EPIC: aterm improvement pass, split into issues #1245

Open
opened 2026-08-26 01:17:16 +00:00 by coilyco-ops · 2 comments
Member

Design pass over aterm/, reviewed, decided, and split. This issue is now the index.

Rendered version with live before/after toggles: https://claude.ai/code/artifact/8339fd5d-56bd-420d-92f3-5ba024cd61b5

The finding that reframed the pass

Every overlay aterm already consumes carries a complete sensory identity per personality: motif, emblem{name,emoji,glyph}, form{silhouette,geometry,motion}, sound_mark{timbre,contour,pulse}. Measured against live agent-compose v2.47.0:

leaf fields shipped in one overlay   38
of which personality sensory spec    24
sensory fields aterm reads            1   (emblem.glyph)

The vocabulary is fully distinct across all 10 personalities: 10 timbres, 10 contours, 10 pulses, 9 motions. The identity system was specified across five modalities and built in one.

Easy

  • #1251 - overlayPersonality decodes 3 of 11 shipped fields and one of the 3 is dead. Do first, unlocks #1255 and #1256.
  • #1252 - window titles are ordered so truncation eats the only part that differs
  • #1253 - shell completion for roles and seats, plus a JSON twin for --list
  • #1254 - render --dry-run for a person, and split failure exit codes

Medium

Hard

  • #1260 - session shadows are leased and never released. 378 branches, 195 worktrees, 9.2 GB. Not an aterm issue. Largest thing this pass found.
  • #1256 - play the sound mark, from pre-rendered samples
  • #1258 - a brand that can change after launch, so a window can say it needs you
  • #1259 - contract-test against the live roster, assert no shipped overlay field is discarded

Terminal

  • #1261 - imagery is blocked on Alacritty having no background image and no graphics protocol
  • #1264 - terminal showdown: Kitty beats Ghostty, decided on process model rather than features. Ghostty cannot be spawned detached the way spawnWindow does. Kitty delivers #1258 outright, verified. The open question is Windows, which only Alacritty serves.

Closed

  • Seat in the window title. Cut. Two windows of the same role and different harness produce a byte-identical title, verified, but the title space is better spent on the workspace. Seat lands in the identity card.
  • Terminal adapters. Cut, and partly reopened by #1264 since a kitty move would leave Windows without a terminal.
  • Crews. Withdrawn. Presumed a tiled multi-window workflow with no evidence and no measurement behind it.
  • Picker on /dev/tty. Folded into #1254 as opportunistic. Real bug, roughly 8 lines, almost never fires.
  • Caching the roster. Dead across both passes. Whole aterm --dry-run is 30 ms, and a cache would cost the freshness the stale-role refusal depends on.
  • WezTerm. Previously evaluated on tabs against Warp and lost. The archived fork is recorded in agentic-os-kai/data/repo-split-decisions.yaml. Not reconsidered.

Correction

An earlier revision of this issue claimed platform_windows.go meant Windows was "a target with no terminal it can open." That was wrong, an over-read of detachAttr returning nil there. Alacritty ships Windows builds and aterm builds for Windows. Returning nil only means there is no setsid equivalent, not that no window opens.

Ownership split

agent-compose owns #358 and #359. aos owns #1260. Everything else is aterm's.

Design pass over `aterm/`, reviewed, decided, and split. This issue is now the index. Rendered version with live before/after toggles: https://claude.ai/code/artifact/8339fd5d-56bd-420d-92f3-5ba024cd61b5 ## The finding that reframed the pass Every overlay `aterm` already consumes carries a complete sensory identity per personality: `motif`, `emblem{name,emoji,glyph}`, `form{silhouette,geometry,motion}`, `sound_mark{timbre,contour,pulse}`. Measured against live `agent-compose v2.47.0`: ``` leaf fields shipped in one overlay 38 of which personality sensory spec 24 sensory fields aterm reads 1 (emblem.glyph) ``` The vocabulary is fully distinct across all 10 personalities: 10 timbres, 10 contours, 10 pulses, 9 motions. The identity system was specified across five modalities and built in one. ## Easy - #1251 - overlayPersonality decodes 3 of 11 shipped fields and one of the 3 is dead. **Do first**, unlocks #1255 and #1256. - #1252 - window titles are ordered so truncation eats the only part that differs - #1253 - shell completion for roles and seats, plus a JSON twin for `--list` - #1254 - render `--dry-run` for a person, and split failure exit codes ## Medium - coilyco-flight-deck/agent-compose#358 - role colors solved per role in isolation, 18 of 21 pairs perceptually identical - #1255 - draw the identity card from `form.geometry`, animate it on `form.motion` - #1257 - `aterm doctor` - coilyco-flight-deck/agent-compose#359 - overlay should carry an outro line ## Hard - #1260 - **session shadows are leased and never released.** 378 branches, 195 worktrees, 9.2 GB. Not an aterm issue. Largest thing this pass found. - #1256 - play the sound mark, from pre-rendered samples - #1258 - a brand that can change after launch, so a window can say it needs you - #1259 - contract-test against the live roster, assert no shipped overlay field is discarded ## Terminal - #1261 - imagery is blocked on Alacritty having no background image and no graphics protocol - #1264 - **terminal showdown: Kitty beats Ghostty**, decided on process model rather than features. Ghostty cannot be spawned detached the way `spawnWindow` does. Kitty delivers #1258 outright, verified. The open question is Windows, which only Alacritty serves. ## Closed - **Seat in the window title.** Cut. Two windows of the same role and different harness produce a byte-identical title, verified, but the title space is better spent on the workspace. Seat lands in the identity card. - **Terminal adapters.** Cut, and partly reopened by #1264 since a kitty move would leave Windows without a terminal. - **Crews.** Withdrawn. Presumed a tiled multi-window workflow with no evidence and no measurement behind it. - **Picker on `/dev/tty`.** Folded into #1254 as opportunistic. Real bug, roughly 8 lines, almost never fires. - **Caching the roster.** Dead across both passes. Whole `aterm --dry-run` is 30 ms, and a cache would cost the freshness the stale-role refusal depends on. - **WezTerm.** Previously evaluated on tabs against Warp and lost. The archived fork is recorded in `agentic-os-kai/data/repo-split-decisions.yaml`. Not reconsidered. ## Correction An earlier revision of this issue claimed `platform_windows.go` meant Windows was "a target with no terminal it can open." That was wrong, an over-read of `detachAttr` returning nil there. Alacritty ships Windows builds and aterm builds for Windows. Returning nil only means there is no setsid equivalent, not that no window opens. ## Ownership split agent-compose owns #358 and #359. `aos` owns #1260. Everything else is aterm's.
coilyco-ops changed title from aterm improvement backlog: sixteen items, easy to hard, with the brand separation finding measured to aterm improvement backlog (decided): 16 in, 2 cut, 1 open, and a five-modality identity spec built in one modality 2026-08-26 02:44:44 +00:00
coilyco-ops changed title from aterm improvement backlog (decided): 16 in, 2 cut, 1 open, and a five-modality identity spec built in one modality to EPIC: aterm improvement pass, split into issues 2026-08-26 02:53:22 +00:00
Author
Member

Batch re-verified for dispatch, 2026-08-25

Every issue in this index re-checked against main at d24e5d5a and live agent-compose v2.54.0, seven minor versions past the v2.47.0 the pass measured on. Each issue carries its own verification comment. No open PRs in either repo, so the batch starts clean.

Two things moved since this index was written, and both change what an agent should do:

  1. kitty landed (#1266, bc5c9863). #1264's decision is taken. That makes #1258 much cheaper, moots #1261's premise, and dates the Alacritty check in #1257.
  2. Completion already shipped. #1253 is half done on main.

Ready now, no decision needed

  • #1251 - re-measured, still exactly true, Color still dead. Do first, unlocks #1255 and #1256.
  • #1252 - finding holds in buildTitle. Sample titles in the body are stale, re-derive from the live roster.
  • #1253 - reduced to --list --json alone. Completion is on main at aterm/completion.go.
  • #1254 - both halves hold. --dry-run still raw JSON, every launcher error still exits 1.
  • #1259 - unchanged, and worth noting it is the check that would have caught #1252's fixtures going stale.
  • agent-compose#358 - confirmed no derived background upstream, aterm still tints in brand.go.
  • agent-compose#359 - confirmed no outro key upstream. aterm side is a two-line substitution.

Ready, but read the correction first

  • #1255 - unchanged, still needs #1251. kitty's graphics protocol means the figure is no longer restricted to text cells, so decide half-blocks against real pixels rather than inheriting #1261's old constraint.
  • #1256 - unchanged.
  • #1257 - two corrections: the Alacritty check is now the resolved --terminal-bin, and aterm/launch_profiles.go does not exist. Profiles live in aos-cli/harness_launch_profile.go.
  • #1258 - the control-socket design is superseded by kitten @ set-colors. The remaining hard question is where the state vocabulary lives, not how the repaint happens.

Blocked on a decision, not on code

  • #1261 - premise gone. Retitle and re-ask after agent-compose#358 rather than implementing the half-block conclusion.
  • #1264 - the Windows question is unanswered and currently shipping broken: the release still publishes aterm-windows-amd64.exe into the Scoop manifest while --terminal-bin speaks only kitty's dialect. Details in the comment there. This decides scope for #1257 and #1259.

Missing from this index

coilyco-flight-deck/agent-compose#348 belongs in this batch and is not listed. It was filed separately by the tpm seat, and its entire user-visible symptom is aterm: aterm eval claude from inside a composed session refuses with native role launch cannot start inside another agent-compose launch. It is an upstream acompose fix to an aterm behavior, same shape as #358 and #359, and it has acceptance criteria already written.

Ownership split, restated

  • agent-compose owns #358, #359, #348
  • aos owns #1260, which remains out of aterm's scope
  • everything else is aterm's
## Batch re-verified for dispatch, 2026-08-25 Every issue in this index re-checked against `main` at `d24e5d5a` and live `agent-compose v2.54.0`, seven minor versions past the v2.47.0 the pass measured on. Each issue carries its own verification comment. No open PRs in either repo, so the batch starts clean. **Two things moved since this index was written**, and both change what an agent should do: 1. **kitty landed** (#1266, `bc5c9863`). #1264's decision is taken. That makes #1258 much cheaper, moots #1261's premise, and dates the Alacritty check in #1257. 2. **Completion already shipped.** #1253 is half done on `main`. ### Ready now, no decision needed * **#1251** - re-measured, still exactly true, `Color` still dead. **Do first**, unlocks #1255 and #1256. * **#1252** - finding holds in `buildTitle`. Sample titles in the body are stale, re-derive from the live roster. * **#1253** - **reduced to `--list --json` alone.** Completion is on `main` at `aterm/completion.go`. * **#1254** - both halves hold. `--dry-run` still raw JSON, every launcher error still exits 1. * **#1259** - unchanged, and worth noting it is the check that would have caught #1252's fixtures going stale. * **agent-compose#358** - confirmed no derived background upstream, aterm still tints in `brand.go`. * **agent-compose#359** - confirmed no `outro` key upstream. aterm side is a two-line substitution. ### Ready, but read the correction first * **#1255** - unchanged, still needs #1251. kitty's graphics protocol means the figure is no longer restricted to text cells, so decide half-blocks against real pixels rather than inheriting #1261's old constraint. * **#1256** - unchanged. * **#1257** - two corrections: the Alacritty check is now the resolved `--terminal-bin`, and `aterm/launch_profiles.go` does not exist. Profiles live in `aos-cli/harness_launch_profile.go`. * **#1258** - the control-socket design is superseded by `kitten @ set-colors`. The remaining hard question is where the state vocabulary lives, not how the repaint happens. ### Blocked on a decision, not on code * **#1261** - premise gone. Retitle and re-ask after agent-compose#358 rather than implementing the half-block conclusion. * **#1264** - the Windows question is unanswered **and currently shipping broken**: the release still publishes `aterm-windows-amd64.exe` into the Scoop manifest while `--terminal-bin` speaks only kitty's dialect. Details in the comment there. This decides scope for #1257 and #1259. ### Missing from this index **coilyco-flight-deck/agent-compose#348** belongs in this batch and is not listed. It was filed separately by the tpm seat, and its entire user-visible symptom is aterm: `aterm eval claude` from inside a composed session refuses with `native role launch cannot start inside another agent-compose launch`. It is an upstream acompose fix to an aterm behavior, same shape as #358 and #359, and it has acceptance criteria already written. ### Ownership split, restated * **agent-compose** owns #358, #359, #348 * **aos** owns #1260, which remains out of aterm's scope * everything else is aterm's
Author
Member

Dispatch plan, decided 2026-08-25

Kai settled the four open decisions. The batch is 15 issues across three repos-worth of ownership, dispatched as one goal per dependency tier. Everything rides along, including #1260 and #1261.

Decisions taken

  • Windows - drop the aterm Windows build and its Scoop packaging. The two-terminal adapter stays cut. Recorded in #1264.
  • #1258 state vocabulary - goes upstream into the acompose overlay. Filed as agent-compose#362.
  • Scope - all four adjacent issues ride along: agent-compose#348, #1256, #1260, #1261.
  • Dispatch - one goal per tier, below.

Tier 1, no dependencies, all parallel

issue repo note
#1251 agentic-os precondition for tier 2. Widen the overlay struct, no behavior change
#1252 agentic-os title order. Re-derive the samples, the ones in the body are stale
#1253 agentic-os reduced to --list --json. Completion already shipped
#1254 agentic-os --dry-run render plus split exit codes. Keep check-aos-release.sh green
#1264 agentic-os drop the Windows build and packaging. Closes on that landing
#1260 agentic-os aos _native-shadow release and reap. Separate subsystem, no aterm overlap
#348 agent-compose nested launch refusal. Acceptance criteria already written
#358 agent-compose separation-solved background
#359 agent-compose outro key
#362 agent-compose session-state vocabulary

Tier 2, after tier 1

  • #1255 - identity card from form.geometry, animated on form.motion. Needs #1251. kitty's graphics protocol means real pixels are now an option, so decide half-blocks against that rather than inheriting #1261's old ceiling.
  • #1256 - sound mark from pre-rendered samples. Needs #1251.
  • #1257 - aterm doctor. Needs #1264 landed so it is unix-only, and reads better after #1254's exit codes. Two file-path corrections in its own comment.

Tier 3, after tier 2

  • #1258 - live re-brand. Needs agent-compose#362 for the vocabulary. Mechanism is kitten @ set-colors, background and cursor only.
  • #1261 - imagery. Needs agent-compose#358. Retitle and re-ask rather than implement, the half-block conclusion is no longer forced.
  • #1259 - contract tests, deliberately last. It asserts no shipped overlay field is discarded, which is only meaningful once tiers 1 and 2 have consumed them.

Note for whoever takes a tier

agent-compose is a separate checkout at /Users/kai/projects/coilyco-flight-deck/agent-compose and lands on its own lane. Do not try to carry an acompose issue from inside the agentic-os worktree.

## Dispatch plan, decided 2026-08-25 Kai settled the four open decisions. The batch is 15 issues across three repos-worth of ownership, dispatched as **one goal per dependency tier**. Everything rides along, including #1260 and #1261. ### Decisions taken * **Windows** - drop the aterm Windows build and its Scoop packaging. The two-terminal adapter stays cut. Recorded in #1264. * **#1258 state vocabulary** - goes upstream into the acompose overlay. Filed as **agent-compose#362**. * **Scope** - all four adjacent issues ride along: agent-compose#348, #1256, #1260, #1261. * **Dispatch** - one goal per tier, below. ### Tier 1, no dependencies, all parallel | issue | repo | note | | --- | --- | --- | | #1251 | agentic-os | **precondition for tier 2.** Widen the overlay struct, no behavior change | | #1252 | agentic-os | title order. Re-derive the samples, the ones in the body are stale | | #1253 | agentic-os | **reduced to `--list --json`.** Completion already shipped | | #1254 | agentic-os | `--dry-run` render plus split exit codes. Keep `check-aos-release.sh` green | | #1264 | agentic-os | drop the Windows build and packaging. Closes on that landing | | #1260 | agentic-os | `aos _native-shadow` release and reap. Separate subsystem, no aterm overlap | | #348 | agent-compose | nested launch refusal. Acceptance criteria already written | | #358 | agent-compose | separation-solved background | | #359 | agent-compose | `outro` key | | #362 | agent-compose | session-state vocabulary | ### Tier 2, after tier 1 * **#1255** - identity card from `form.geometry`, animated on `form.motion`. Needs #1251. kitty's graphics protocol means real pixels are now an option, so decide half-blocks against that rather than inheriting #1261's old ceiling. * **#1256** - sound mark from pre-rendered samples. Needs #1251. * **#1257** - `aterm doctor`. Needs #1264 landed so it is unix-only, and reads better after #1254's exit codes. Two file-path corrections in its own comment. ### Tier 3, after tier 2 * **#1258** - live re-brand. Needs agent-compose#362 for the vocabulary. Mechanism is `kitten @ set-colors`, background and cursor only. * **#1261** - imagery. Needs agent-compose#358. **Retitle and re-ask rather than implement**, the half-block conclusion is no longer forced. * **#1259** - contract tests, deliberately last. It asserts no shipped overlay field is discarded, which is only meaningful once tiers 1 and 2 have consumed them. ### Note for whoever takes a tier `agent-compose` is a separate checkout at `/Users/kai/projects/coilyco-flight-deck/agent-compose` and lands on its own lane. Do not try to carry an acompose issue from inside the agentic-os worktree.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
coilyco-flight-deck/agentic-os#1245
No description provided.