aterm doctor: one command that answers why no window opened #1257

New issue

Closed

opened 2026-08-26 02:50:00 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-26 02:50:00 +00:00

Member

Part of #1245.

Every other AOS surface has a doctor and aterm does not, so a launch that produces nothing sends you probing the chain by hand.

Preflight the whole path in one command:

agent-compose on PATH, and on a supported contract (agent-compose.catalog.v1, agent-compose.overlay.v1 schema 1)
Alacritty on PATH, and its base config importable
aos _native-shadow --probe, reporting whether the launch will be leased or unleased rather than only pass or fail
harness launch profiles resolvable, and every role in them present on the live roster
roster fetches and parses, with the count of roles carrying a launchable native seat
the configured font present
$PROJECTS_ROOT set and a real directory

The unleased-shadow case matters most here. nativeShadowAvailable silently degrades to an unleased launch, which is correct behavior and invisible, so doctor is where that becomes legible.

aterm/main.go, aterm/launch_profiles.go, aterm/plan.go.

Part of #1245. Every other AOS surface has a doctor and aterm does not, so a launch that produces nothing sends you probing the chain by hand. Preflight the whole path in one command: - `agent-compose` on PATH, and on a supported contract (`agent-compose.catalog.v1`, `agent-compose.overlay.v1` schema 1) - Alacritty on PATH, and its base config importable - `aos _native-shadow --probe`, reporting whether the launch will be leased or unleased rather than only pass or fail - harness launch profiles resolvable, and every role in them present on the live roster - roster fetches and parses, with the count of roles carrying a launchable native seat - the configured font present - `$PROJECTS_ROOT` set and a real directory The unleased-shadow case matters most here. `nativeShadowAvailable` silently degrades to an unleased launch, which is correct behavior and invisible, so doctor is where that becomes legible. `aterm/main.go`, `aterm/launch_profiles.go`, `aterm/plan.go`.

coilyco-ops referenced this issue

2026-08-26 02:53:23 +00:00

EPIC: aterm improvement pass, split into issues #1245

coilyco-ops commented

2026-08-26 05:21:33 +00:00

Author

Member

Two corrections before this is handed to an agent. Both are consequences of the kitty swap landing in #1266 as bc5c9863, after this was filed.

1. The terminal check is wrong as written. The body asks doctor to check "Alacritty on PATH, and its base config importable". aterm no longer opens Alacritty. defaultTerminalBin = "kitty" in main.go:24, the flag is --terminal-bin reading ATERM_TERMINAL_BIN or KITTY_BIN, and the baseline config is now kitty/kitty.conf. The check should be against the resolved --terminal-bin rather than a hardcoded terminal name, so this issue stops needing an edit every time the terminal turns over.

2. aterm/launch_profiles.go does not exist. The file list at the bottom names it. Harness launch profiles are read by aos-cli/harness_launch_profile.go, which resolves .agents/harness-launch-profiles.yaml. aterm asks aos for the default seat rather than parsing the file itself, which is the no-second-parser property docs/aterm.md sells. So doctor checks that path through aos, and the file list should read aterm/main.go, aterm/plan.go, and aos-cli/harness_launch_profile.go.

Everything else in the checklist verified as still real. nativeShadowAvailable still degrades silently to an unleased launch, and aterm platform claude --dry-run reports "shadowed": true only inside the plan JSON, which nothing surfaces to a person. That is still the highest-value line in the doctor output.

Blocked-on note. The Windows terminal question from #1264 is unanswered, and it decides whether doctor reports one terminal or a per-platform one. Worth settling that before implementing, or scoping this to unix and saying so.

**Two corrections before this is handed to an agent.** Both are consequences of the kitty swap landing in #1266 as `bc5c9863`, after this was filed. **1. The terminal check is wrong as written.** The body asks doctor to check "Alacritty on PATH, and its base config importable". aterm no longer opens Alacritty. `defaultTerminalBin = "kitty"` in `main.go:24`, the flag is `--terminal-bin` reading `ATERM_TERMINAL_BIN` or `KITTY_BIN`, and the baseline config is now `kitty/kitty.conf`. The check should be against the resolved `--terminal-bin` rather than a hardcoded terminal name, so this issue stops needing an edit every time the terminal turns over. **2. `aterm/launch_profiles.go` does not exist.** The file list at the bottom names it. Harness launch profiles are read by `aos-cli/harness_launch_profile.go`, which resolves `.agents/harness-launch-profiles.yaml`. aterm asks `aos` for the default seat rather than parsing the file itself, which is the no-second-parser property `docs/aterm.md` sells. So doctor checks that path through `aos`, and the file list should read `aterm/main.go`, `aterm/plan.go`, and `aos-cli/harness_launch_profile.go`. **Everything else in the checklist verified as still real.** `nativeShadowAvailable` still degrades silently to an unleased launch, and `aterm platform claude --dry-run` reports `"shadowed": true` only inside the plan JSON, which nothing surfaces to a person. That is still the highest-value line in the doctor output. **Blocked-on note.** The Windows terminal question from #1264 is unanswered, and it decides whether doctor reports one terminal or a per-platform one. Worth settling that before implementing, or scoping this to unix and saying so.

coilyco-ops referenced this issue

2026-08-26 05:22:57 +00:00

EPIC: aterm improvement pass, split into issues #1245

coilyco-ops referenced this issue

2026-08-26 06:07:08 +00:00

Terminal showdown: Kitty beats Ghostty for aterm, and the deciding factor is the process model, not the features #1264

coilyco-ops referenced this issue

2026-08-26 06:08:00 +00:00

EPIC: aterm improvement pass, split into issues #1245

coilyco-ops referenced this issue

2026-08-26 07:03:35 +00:00

feat(aterm): drop the Windows build and its Scoop packaging (#1264) #1271