aterm: a brand that can change after launch, so a window can say it needs you

coilyco-ops commented

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

Member

Part of #1245. The one that reverses a documented decision, so it is a design change before it is a code change.

docs/warp-host-setup.md states that branding is fixed at launch and that the adapter manages no interactive loop. That is a coherent boundary and it has a cost: a running window cannot signal anything. Six windows are open, one is blocked on a question, and finding it costs six clicks.

Why it is reachable

The _session stage already sits between Alacritty and the harness, which is the whole reason this is possible without a supervisor. It is already holding the window on failure, so it is already a lifecycle participant rather than a passthrough.

Give it a small control socket under the session root, let harness hooks poke a state into it, and repaint over OSC as the session moves between working, waiting on you, and failed. Cursor and background only. Do not touch the ANSI palette, since harness TUIs use those colors semantically, which is the reason the base config leaves them alone.

Pair it with the sound mark

Once #1256 lands, the same state transitions get an audio channel for free: the role's contour played once when a window starts waiting on you, inverted when one fails. No new vocabulary and no new spec, and unlike color it reaches you when the window is not visible.

Design questions to settle first

does this stay inside AOS, or does the state contract belong upstream with the identity
what pokes the socket, and does a harness without hooks degrade to launch-fixed branding silently
what happens to the ownership sentence in docs/warp-host-setup.md

aterm/session.go, docs/warp-host-setup.md, docs/aterm.md.

Part of #1245. The one that reverses a documented decision, so it is a design change before it is a code change. `docs/warp-host-setup.md` states that branding is fixed at launch and that the adapter manages no interactive loop. That is a coherent boundary and it has a cost: a running window cannot signal anything. Six windows are open, one is blocked on a question, and finding it costs six clicks. ## Why it is reachable The `_session` stage already sits between Alacritty and the harness, which is the whole reason this is possible without a supervisor. It is already holding the window on failure, so it is already a lifecycle participant rather than a passthrough. Give it a small control socket under the session root, let harness hooks poke a state into it, and repaint over OSC as the session moves between working, waiting on you, and failed. Cursor and background only. Do not touch the ANSI palette, since harness TUIs use those colors semantically, which is the reason the base config leaves them alone. ## Pair it with the sound mark Once #1256 lands, the same state transitions get an audio channel for free: the role's contour played once when a window starts waiting on you, inverted when one fails. No new vocabulary and no new spec, and unlike color it reaches you when the window is not visible. ## Design questions to settle first - does this stay inside AOS, or does the state contract belong upstream with the identity - what pokes the socket, and does a harness without hooks degrade to launch-fixed branding silently - what happens to the ownership sentence in `docs/warp-host-setup.md` `aterm/session.go`, `docs/warp-host-setup.md`, `docs/aterm.md`.

coilyco-ops referenced this issue

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

EPIC: aterm improvement pass, split into issues #1245

coilyco-ops referenced this issue

2026-08-26 03:14:52 +00:00

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

coilyco-ops commented

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

Author

Member

The implementation proposed here is superseded, and the issue got much cheaper. #1264 landed kitty in #1266 (bc5c9863) after this was filed.

The body proposes "a small control socket under the session root" plus OSC repaints driven from _session. kitty ships that. #1264 verified end to end: a window launched at #211b28, then kitten @ --to unix:... set-colors background='#331116' from an outside process, and a probe inside the window reported the change. So the re-brand channel is the terminal's remote control, not something _session hand-rolls.

What that changes about the design questions in the body:

"does this stay inside AOS, or does the state contract belong upstream" - still open, and now the only genuinely hard question here. The repaint mechanism is settled, the state vocabulary is not.
"what pokes the socket" - becomes what pokes kitten @, and the degradation answer improves: a harness without hooks leaves the launch-fixed brand in place, which is the current behavior, so the fallback is free.
"what happens to the ownership sentence in docs/warp-host-setup.md" - unchanged, still needs answering. That doc was already rewritten by the kitty swap, so check its current wording rather than the wording this issue quotes.

Still true and still worth keeping: the palette caution. kitty's set-colors can reach the ANSI palette, and harness TUIs use those slots semantically. Hold the change to background and cursor as the body says.

Pairing with #1256 also survives, unchanged.

**The implementation proposed here is superseded, and the issue got much cheaper.** #1264 landed kitty in #1266 (`bc5c9863`) after this was filed. The body proposes "a small control socket under the session root" plus OSC repaints driven from `_session`. kitty ships that. #1264 verified end to end: a window launched at `#211b28`, then `kitten @ --to unix:... set-colors background='#331116'` from an outside process, and a probe inside the window reported the change. So the re-brand channel is the terminal's remote control, not something `_session` hand-rolls. **What that changes about the design questions in the body:** * "does this stay inside AOS, or does the state contract belong upstream" - still open, and now the only genuinely hard question here. The repaint mechanism is settled, the state vocabulary is not. * "what pokes the socket" - becomes what pokes `kitten @`, and the degradation answer improves: a harness without hooks leaves the launch-fixed brand in place, which is the current behavior, so the fallback is free. * "what happens to the ownership sentence in `docs/warp-host-setup.md`" - unchanged, still needs answering. That doc was already rewritten by the kitty swap, so check its current wording rather than the wording this issue quotes. **Still true and still worth keeping:** the palette caution. kitty's `set-colors` can reach the ANSI palette, and harness TUIs use those slots semantically. Hold the change to background and cursor as the body says. **Pairing with #1256 also survives**, unchanged.

coilyco-ops referenced this issue

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

EPIC: aterm improvement pass, split into issues #1245

coilyco-ops commented

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

Author

Member

Decided: the state vocabulary goes upstream

Kai settled this 2026-08-25, answering the first of the three design questions in the body.

working / waiting / failed is composed identity, not an aterm-local enum. It lands in the acompose overlay beside annotation and the proposed outro, on the same argument that put agent-compose#358 and #359 upstream: presentation every renderer shares belongs next to native-ui, not inside one terminal launcher. It also makes the #1256 pairing free rather than coincidental, since the audio channel then reads the same vocabulary the color channel does.

Filed upstream as coilyco-flight-deck/agent-compose#360. This issue now depends on it.

The three design questions, current state

where the state contract lives - answered, upstream.
what pokes it - implementer's call. The mechanism is kitten @ set-colors, and a harness without hooks leaves the launch-fixed brand in place, which is today's behavior, so the degradation path costs nothing.
the ownership sentence in docs/warp-host-setup.md - still open, and now the last thing to settle here. That doc was rewritten by the kitty swap, so read its current wording rather than what this issue quotes.

Scope reminder

Background and cursor only. kitty's set-colors can reach the ANSI palette and harness TUIs use those slots semantically.

## Decided: the state vocabulary goes upstream Kai settled this 2026-08-25, answering the first of the three design questions in the body. **working / waiting / failed is composed identity, not an aterm-local enum.** It lands in the acompose overlay beside `annotation` and the proposed `outro`, on the same argument that put agent-compose#358 and #359 upstream: presentation every renderer shares belongs next to `native-ui`, not inside one terminal launcher. It also makes the #1256 pairing free rather than coincidental, since the audio channel then reads the same vocabulary the color channel does. Filed upstream as **coilyco-flight-deck/agent-compose#360**. This issue now depends on it. ### The three design questions, current state * **where the state contract lives** - answered, upstream. * **what pokes it** - implementer's call. The mechanism is `kitten @ set-colors`, and a harness without hooks leaves the launch-fixed brand in place, which is today's behavior, so the degradation path costs nothing. * **the ownership sentence in `docs/warp-host-setup.md`** - still open, and now the last thing to settle here. That doc was rewritten by the kitty swap, so read its current wording rather than what this issue quotes. ### Scope reminder Background and cursor only. kitty's `set-colors` can reach the ANSI palette and harness TUIs use those slots semantically.

coilyco-ops referenced this issue from coilyco-flight-deck/agent-compose

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

Overlay should carry a session-state vocabulary, so a live window can say which state it is in #362

coilyco-ops commented

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

Author

Member

Correction to the comment above: the upstream issue is coilyco-flight-deck/agent-compose#362, not #360. Two numbers were taken between writing and filing.

coilyco-flight-deck/agent-compose#362

Correction to the comment above: the upstream issue is **coilyco-flight-deck/agent-compose#362**, not #360. Two numbers were taken between writing and filing. https://forgejo.coilysiren.me/coilyco-flight-deck/agent-compose/issues/362

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 06:47:38 +00:00

feat(aterm): render --dry-run for a person, and split the exit codes (#1254) #1270

coilyco-ops referenced this issue

2026-08-26 07:41:54 +00:00

feat(aterm): add doctor, one command that answers why no window opened (#1257) #1273

coilyco-ops referenced this issue

2026-08-26 07:42:46 +00:00

docs/ is at 40 of 40 files with five pages inside 20 chars of the char cap, so the aterm tiers have nowhere to document #1274