@zgeoff/atc 2.0.0 → 2.2.0

package/README.md

@@ -1,11 +1,8 @@
 <div align="center">
-  <h1>atc</h1>
-
-  <p>
-    Control tower for coding-agent sessions: stock <code>claude</code>, <code>grok</code>, and
-    <code>codex</code> instances in PTYs behind a keyboard-driven session list with hook-driven
-    attention routing — no panes, no tiling, no mouse.
-  </p>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/atc-dark.png">
+    <img src="./docs/assets/atc-light.png" alt="atc" width="256">
+  </picture>
 
   <p>
     <a href="https://www.npmjs.com/package/@zgeoff/atc"><img src="https://img.shields.io/npm/v/%40zgeoff%2Fatc" alt="npm version"></a>
@@ -19,100 +16,102 @@
   </p>
 </div>
 
+**atc** lets you run several coding agents at once in a single terminal pane and keep track of which
+are waiting on you.
+
+`claude`, `grok`, and `codex` sessions all run in a background daemon, with a session list in front
+of them. There are no panes. One session fills the terminal, `Ctrl-Space` opens the list, a session
+that needs an answer turns red, and `Tab` takes you to it. Quit atc and the sessions keep running.
+
+<img src="./docs/assets/demo.gif" alt="atc: spawn a session, open the session list, jump back in" width="1100">
+
 ## Install
 
 ```sh
 bun add -g @zgeoff/atc
+```
+
+atc needs [Bun](https://bun.sh) and at least one of the `claude`, `grok`, or `codex` CLIs on your
+PATH. The agent picker lists the ones it finds.
+
+## Use
+
+```sh
 atc
 ```
 
-atc needs [Bun](https://bun.sh) and the `claude` CLI on your PATH. Grok sessions need the `grok`
-CLI, and Codex sessions the `codex` CLI — the agent picker lists only the agents whose binary it can
-find. With [zoxide](https://github.com/ajeetdsouza/zoxide) installed, the spawn directory picker
-feeds on its frecency list, so every directory you visit is two keystrokes from a session; without
-it, the picker falls back to atc's own spawn history.
-
-The first invocation auto-spawns the daemon; the TUI is a thin client, so quitting or crashing it
-leaves every session running. atc runs fine nested inside zellij or tmux — give the pane locked mode
-so the leader key reaches atc.
-
-## Keys
-
-| Key             | Where          | Action                                                                                         |
-| --------------- | -------------- | ---------------------------------------------------------------------------------------------- |
-| leader          | anywhere       | toggle session overlay — `Ctrl-Space` by default, configurable                                 |
-| `n`             | home/overlay   | spawn: pick agent → dir → name → optional first prompt                                         |
-| `r`             | home/overlay   | adopt an existing session: pick agent → dir → name                                             |
-| `R`             | home           | restore the last fleet after a daemon death                                                    |
-| `j`/`k`/`↑`/`↓` | overlay/picker | move                                                                                           |
-| `Enter`         | overlay        | attach (auto-acks)                                                                             |
-| `Tab`           | overlay        | attach the most urgent needs-you session, else the latest turn-done one                        |
-| `/`             | overlay        | fuzzy filter by name/dir, `⏎` attach top match, `esc` clear                                    |
-| `a`             | overlay        | ack a notification without attaching                                                           |
-| `p`             | overlay        | pin or unpin — pinned sessions stay at the top of the list                                     |
-| `g`             | overlay        | toggle the grouped view: sessions cluster under repository headers                             |
-| `H`             | overlay        | eject to headless — hidden on agents with no headless handoff                                  |
-| `P`             | overlay        | revive: a fresh terminal resumes a headless or killed session in place                         |
-| `y`             | overlay        | yank the resume command for the session's agent                                                |
-| `Y`             | overlay        | eject: yank the resume command, then kill the session here                                     |
-| `K`             | overlay        | kill selected (confirm with `y`) — the entry stays revivable with `P`; a second `K` forgets it |
-| `u`             | overlay        | restart an outdated daemon and restore the fleet — offered while `⟳ update ready` shows        |
-| `?`             | overlay        | full key reference — the hint row only shows actions valid for the selected session            |
-| `q`             | home/overlay   | quit the client — sessions keep running in the daemon                                          |
-
-The overlay orders sessions by pinned first, then attention state, then most recently attached, so
-the session you want is nearly always near the top. Session states: red `●` needs you, cyan `◐`
-running, green `✓` turn done, gray `✗` exited. Everything else passes through to the focused
-session, which owns the full screen; while attached, atc appends a fleet segment
-(`▏● 2 need you: auth-bug`) to your own Claude Code statusline.
-
-## Attention hooks
-
-Claude sessions report attention automatically: atc injects its hooks through a generated
-`--settings` file per spawn and never touches your own Claude config. Grok and Codex hooks are a
-one-time self-install — atc prints them and never writes into your agent config either:
+The first run starts the daemon. Press `n` to spawn a session: pick an agent, pick a directory, give
+it a name, and type a first prompt if you have one. The session takes the whole screen and you work
+in it as you would in a plain terminal.
+
+`Ctrl-Space` opens the session list over whatever you are attached to. Each row carries a state
+mark:
+
+| Mark | State                                 |
+| ---- | ------------------------------------- |
+| `●`  | needs you: a prompt or question waits |
+| `◐`  | running                               |
+| `✓`  | turn done                             |
+| `✗`  | exited                                |
+
+Sessions that need you sort to the top, so the one you want is nearly always first.
+
+| Key          | Action                                       |
+| ------------ | -------------------------------------------- |
+| `Ctrl-Space` | open or close the list                       |
+| `Tab`        | attach the session that needs you most       |
+| `Enter`      | attach the selected session                  |
+| `/`          | filter by name or directory                  |
+| `a`          | acknowledge a notification without attaching |
+| `K`          | kill the selected session                    |
+| `q`          | quit the client; sessions keep running       |
+| `?`          | every other key                              |
+
+The directory picker reads your [zoxide](https://github.com/ajeetdsouza/zoxide) list when zoxide is
+installed, and atc's own spawn history otherwise. Inside a Claude session your statusline gains a
+fleet segment, so `● 2 need you: auth-bug` is visible without opening the list.
+
+If the daemon dies, press `R` on the home screen and every session respawns from its transcript.
+After you upgrade atc, the status bar shows `⟳ update ready`, and `u` restarts the daemon and
+restores the fleet when you are ready.
+
+atc runs inside zellij or tmux. Give the pane locked mode so the leader key reaches atc.
+
+## Grok and Codex
+
+Claude sessions report attention on their own: atc passes a generated settings file at spawn time
+and never edits your Claude config. Grok and Codex take a one-time hook install. atc prints the
+hooks and leaves the install to you:
 
 ```sh
-# Grok: install the hook file
+# Grok
 mkdir -p ~/.grok/hooks
 atc grok-hooks > ~/.grok/hooks/atc-reporter.json
 
-# Codex: print the entries, merge them into ~/.codex/hooks.json,
-# then trust them once in the codex TUI
+# Codex: merge the output into ~/.codex/hooks.json, then trust it once in the codex TUI
 atc codex-hooks
 ```
 
-The [configuration guide](./docs/guides/configuration.md#attention-hooks-grok-and-codex) covers the
-detail; [agent integration](./docs/architecture/overview.md#agent-integration) covers how the
-reporting works.
-
-## Configuration
+The [configuration guide](./docs/guides/configuration.md#attention-hooks-grok-and-codex) covers both
+installs in detail.
 
-`~/.config/atc/config.json` is created with defaults on first run. The
-[configuration guide](./docs/guides/configuration.md) covers every field:
+## Beyond the keyboard
 
-- [Agent binaries](./docs/guides/configuration.md) — the binary and prepended arguments per agent,
-  e.g. `"claudeArgs": ["--model", "opus"]`.
-- [Leader key](./docs/guides/configuration.md#leader) — rebind the overlay toggle when `Ctrl-Space`
-  is taken on your machine.
-- [Gateways](./docs/guides/configuration.md#gateways) — run the Claude CLI against Claude-compatible
-  backends (GLM and friends), each as its own agent in one fleet.
-- [Daemon hooks](./docs/guides/configuration.md#daemon-hooks) — run your own commands on fleet
-  events, or pipe the full NDJSON event stream from `atc events`.
-- [Attention hooks](./docs/guides/configuration.md#attention-hooks-grok-and-codex) — the Grok and
-  Codex self-install in detail.
+- `atc mcp` exposes the fleet as MCP tools, so an agent can spawn, drive, and read other agents. A
+  session spawned this way lists under the session that spawned it and is killed with it. Register
+  it with `claude mcp add --scope user atc -- atc mcp`.
+- `atc events` prints every fleet event as one NDJSON line. The same stream is on a unix socket, and
+  `config.json` hooks run your own commands on events. The [events guide](./docs/guides/events.md)
+  covers all three.
+- A Claude-compatible backend runs as its own agent in the same fleet. The
+  [gateways](./docs/guides/configuration.md#gateways) section covers the setup.
 
-`atc mcp` exposes the fleet as MCP tools (list, spawn, drive, organise) to any MCP client, wrangled
-sessions included:
+## Configuration
 
-```sh
-claude mcp add --scope user atc -- atc mcp
-```
+atc creates `~/.config/atc/config.json` on first run. The
+[configuration guide](./docs/guides/configuration.md) covers every field: agent binaries and
+arguments, the leader key, gateways, and hooks.
 
-## Crash safety
+## Documentation
 
-A client crash or closed window costs nothing: the daemon keeps hosting the fleet, and the next
-`atc` reconnects. If the daemon itself dies, every session's transcript is already on disk — press
-`R` and the whole fleet respawns with the matching CLI. After an update, the status bar shows
-`⟳ update ready`, and `u` restarts the daemon and restores the fleet at a moment you choose. The
-[recovery model](./docs/architecture/overview.md#recovery-model) covers the detail.
+[docs/](./docs/README.md) covers the architecture, the daemon, and the wire protocol.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.0.0",
-  "description": "Terminal control tower for Claude Code sessions",
+  "version": "2.2.0",
+  "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
   "license": "MIT",
@@ -59,5 +59,9 @@
     "type-fest": "5.8.0",
     "typescript": "7.0.2"
   },
+  "overrides": {
+    "fast-uri": "3.1.6",
+    "qs": "6.16.0"
+  },
   "packageManager": "bun@1.3.10"
 }

package/src/cli.ts

@@ -8,7 +8,7 @@ const main = defineCommand({
   meta: {
     name: 'atc',
     version: pkg.version,
-    description: 'Terminal control tower for Claude Code sessions',
+    description: 'Terminal control tower for coding-agent sessions',
   },
   default: 'tui',
   subCommands: {

package/src/client/index.ts

@@ -191,7 +191,16 @@ function pickOverlaySessions(): MirrorSession[] {
 
   const f = overlayFilter;
 
-  return sorted.filter((s) => findFuzzyScore(`${s.name} ${formatDir(s.cwd)}`, f) !== null);
+  const matched = new Set(
+    sorted
+      .filter((s) => findFuzzyScore(`${s.name} ${formatDir(s.cwd)}`, f) !== null)
+      .map((s) => s.id),
+  );
+
+  // A matching sub-session keeps its parent row, so it stays nested.
+  return sorted.filter(
+    (s) => matched.has(s.id) || sorted.some((c) => c.parent === s.id && matched.has(c.id)),
+  );
 }
 
 function renderOverlay() {
@@ -588,10 +597,13 @@ function applyOverlayKey(buf: Buffer) {
   }
 
   if (ch === 'p' && sel !== undefined) {
-    // Flipped locally too so the repaint is immediate; the daemon's state
-    // event confirms it.
-    sel.pinned = !sel.pinned;
-    void sendQuiet('session.update', { session: sel.id, pinned: sel.pinned });
+    // A sub-session pins with its parent. Flipped locally too so the
+    // repaint is immediate; the daemon's state event confirms it.
+    const target =
+      (sel.parent === null ? undefined : fleet.find((x) => x.id === sel.parent)) ?? sel;
+
+    target.pinned = !target.pinned;
+    void sendQuiet('session.update', { session: target.id, pinned: target.pinned });
     renderOverlay();
 
     return;

package/src/client/pick-tab-target.ts

@@ -3,6 +3,7 @@ import { sortSessionViews } from '../daemon/sessions';
 
 interface TabCandidate {
   readonly id: string;
+  readonly parent: string | null;
   readonly state: SessionState;
   readonly pinned: boolean;
   readonly lastAttachedAt: number;

package/src/client/to-mirror-session.ts

@@ -19,6 +19,7 @@ export interface MirrorSession {
   resumable: boolean;
   canEject: boolean;
   agent: AgentID;
+  parent: string | null;
 }
 
 // Only the fields a mirror can't function without; an unparseable descriptor
@@ -61,5 +62,6 @@ export function toMirrorSession(value: unknown): MirrorSession | null {
     resumable: typeof record['agentSessionID'] === 'string',
     canEject: record['canEject'] === true,
     agent: toAgentID(record['agent']),
+    parent: typeof record['parent'] === 'string' ? record['parent'] : null,
   };
 }

package/src/client/ui.ts

@@ -174,6 +174,8 @@ function dimRow(width: number, text: string): Row {
 
 // Selection-dependent hints need the liveness facts of each row.
 export interface OverlaySessionView extends SessionView {
+  readonly id: string;
+  readonly parent: string | null;
   readonly alive: boolean;
   readonly kind: 'pty' | 'headless';
   readonly resumable: boolean;
@@ -208,20 +210,22 @@ export function drawOverlay(view: OverlayView) {
 
   // The grouped view clusters sessions under dim repository headers, with
   // pinned sessions leading in their own cluster; the flat view shows a
-  // directory column instead. The rows keep the sorted order either way.
+  // directory column instead. The rows keep the sorted order either way. A
+  // sub-session row follows its parent indented, and never opens a header.
   let lastKey: string | null = null;
 
   for (const [i, s] of view.sessions.entries()) {
+    const sub = s.parent !== null && view.sessions.some((x) => x.id === s.parent);
     const key = s.pinned ? PINNED_GROUP_KEY : s.repoRoot;
 
-    if (view.grouped && key !== lastKey) {
+    if (view.grouped && !sub && key !== lastKey) {
       lastKey = key;
 
       rowsList.push(dimRow(width, `▸ ${s.pinned ? 'pinned' : formatDir(s.repoRoot)}`));
     }
 
     const sel = i === view.selected;
-    const name = truncate(s.name, 16).padEnd(16);
+    const name = (sub ? `↳ ${truncate(s.name, 14)}` : truncate(s.name, 16)).padEnd(16);
     const state = STATE_LABEL[s.state].padEnd(9);
     const dir = view.grouped ? '' : ` ${truncate(formatDir(s.cwd), 18).padEnd(18)}`;
     const msgWidth = Math.max(4, width - 4 - 4 - 17 - 10 - (view.grouped ? 0 : 19));
@@ -249,7 +253,8 @@ export function drawOverlay(view: OverlayView) {
     );
   }
 
-  let hint = buildOverlayHint(view.sessions[view.selected]);
+  const selected = view.sessions[view.selected];
+  let hint = buildOverlayHint(selected, view.sessions);
 
   if (view.stale) {
     hint += ' · u update daemon';
@@ -260,7 +265,7 @@ export function drawOverlay(view: OverlayView) {
   }
 
   if (view.confirmKill) {
-    hint = 'kill selected session? y / n';
+    hint = formatKillConfirm(selected, view.sessions);
   }
 
   rowsList.push(dimRow(width, hint), boxBottom(width));
@@ -268,11 +273,33 @@ export function drawOverlay(view: OverlayView) {
   drawBox(rowsList);
 }
 
+// A kill acts on the selected session's whole set, so the confirm counts
+// the live sub-sessions that go with it; a forget counts the dead ones.
+function formatKillConfirm(
+  s: OverlaySessionView | undefined,
+  list: readonly OverlaySessionView[],
+): string {
+  const children = s === undefined ? [] : list.filter((x) => x.parent === s.id);
+  const affected = children.filter((x) => x.alive === (s?.alive ?? false));
+
+  if (affected.length === 0) {
+    return 'kill selected session? y / n';
+  }
+
+  const noun = affected.length === 1 ? 'sub-session' : 'sub-sessions';
+
+  return `kill selected session and its ${affected.length} ${noun}? y / n`;
+}
+
 const GLOBAL_HINT = 'g groups · n new · ? keys';
 
 // Only the actions valid for the selected row appear; the full reference
-// lives behind ?. Grok has no headless handoff, so H is omitted there.
-export function buildOverlayHint(s: OverlaySessionView | undefined): string {
+// lives behind ?. Grok has no headless handoff, so H is omitted there. A
+// sub-session's pin action targets its parent.
+export function buildOverlayHint(
+  s: OverlaySessionView | undefined,
+  list: readonly OverlaySessionView[] = [],
+): string {
   if (s === undefined) {
     return GLOBAL_HINT;
   }
@@ -301,7 +328,9 @@ export function buildOverlayHint(s: OverlaySessionView | undefined): string {
     actions.push('K forget');
   }
 
-  const pinAction = s.pinned ? 'p unpin' : 'p pin';
+  const owner = (s.parent === null ? undefined : list.find((x) => x.id === s.parent)) ?? s;
+  const pinVerb = owner.pinned ? 'p unpin' : 'p pin';
+  const pinAction = owner === s ? pinVerb : `${pinVerb} parent`;
 
   actions.push(pinAction);
 
@@ -321,6 +350,7 @@ export function drawHelp() {
     'Y  yank the resume command, then kill here',
     'K  kill (K again on a dead session forgets it)',
     'p  pin or unpin — pinned sessions stay on top',
+    '    a sub-session pins with its parent',
     'g  toggle grouping by repository',
     '    Grok rows show a dim g after the pin mark',
     'n  new session',
@@ -390,7 +420,7 @@ export function drawHome(fleetCount = 0, leaderLabel = '^Space') {
   out(ansi.clear + ansi.hideCursor);
 
   const msgs = [
-    'atc — control tower for Claude and Grok sessions',
+    'atc — control tower for coding-agent sessions',
     '',
     'n       spawn a session',
     'r       adopt an existing session',

package/src/daemon/daemon-connection.ts

@@ -15,6 +15,7 @@ import type { SessionID } from '../shared/session-id';
 import type { FleetEntry } from '../store/fleet-entry';
 import type { Dims } from './attach-registry';
 import type { AnswerResult } from './permission-registry';
+import type { ScreenText } from './screen-model';
 import type { SessionDescriptor } from './sessions';
 
 interface SpawnParams {
@@ -26,6 +27,7 @@ interface SpawnParams {
   readonly resume: SpawnOptions['resume'];
   readonly namedBy: 'user' | 'auto';
   readonly agent: AgentID;
+  readonly parent: SessionID | null;
 }
 
 export interface DaemonContext {
@@ -37,10 +39,11 @@ export interface DaemonContext {
   readonly findAdapter: (id: AgentID) => AgentAdapter | null;
   readonly spawnSession: (p: SpawnParams) => SessionDescriptor;
   readonly killSession: (id: SessionID) => Promise<boolean>;
-  readonly updateSession: (id: SessionID, name?: string, pinned?: boolean) => boolean;
+  readonly updateSession: (id: SessionID, name?: string, pinned?: boolean) => boolean | 'child_pin';
   readonly quitDaemon: () => void;
   readonly ackSession: (id: SessionID) => boolean;
   readonly buildResumeCommand: (id: SessionID) => string | null;
+  readonly readSessionScreen: (id: SessionID) => Promise<ScreenText | 'missing' | 'no_screen'>;
   readonly answerPermission: (request: string, decision: string) => AnswerResult;
   readonly restoreFleet: (cols: number, rows: number) => Promise<number>;
   readonly attachSession: (
@@ -265,8 +268,15 @@ export class DaemonConnection {
         }
 
         const sessionID = parsed.data.session;
+        const updated = this.ctx.updateSession(sessionID, parsed.data.name, parsed.data.pinned);
 
-        if (this.ctx.updateSession(sessionID, parsed.data.name, parsed.data.pinned)) {
+        if (updated === 'child_pin') {
+          this.sendErr(
+            req.id,
+            'bad_args',
+            `session '${sessionID}' is a sub-session and takes its pin from its parent`,
+          );
+        } else if (updated) {
           this.sendOk(req.id, {});
         } else {
           this.sendErr(req.id, 'no_such_session', `no session '${sessionID}'`);
@@ -304,6 +314,29 @@ export class DaemonConnection {
 
         return;
       }
+      case 'session.screen': {
+        const parsed = parseRequestParams('session.screen', req.p);
+
+        if (!parsed.ok) {
+          this.sendErr(req.id, 'bad_args', parsed.message);
+
+          return;
+        }
+
+        const id = parsed.data.session;
+
+        const screen = await this.ctx.readSessionScreen(id);
+
+        if (screen === 'missing') {
+          this.sendErr(req.id, 'no_such_session', `no session '${id}'`);
+        } else if (screen === 'no_screen') {
+          this.sendErr(req.id, 'session_dead', `session '${id}' has no captured screen`);
+        } else {
+          this.sendOk(req.id, { ...screen });
+        }
+
+        return;
+      }
       case 'session.eject': {
         const parsed = parseRequestParams('session.eject', req.p);
 
@@ -440,6 +473,22 @@ export class DaemonConnection {
       return;
     }
 
+    let parent: SessionID | null = null;
+
+    if (parsed.data.parent !== undefined) {
+      const owner = this.ctx.collectSessions().find((s) => s.id === parsed.data.parent);
+
+      if (owner === undefined) {
+        this.sendErr(req.id, 'no_such_session', `no session '${parsed.data.parent}'`);
+
+        return;
+      }
+
+      // A sub-session spawning a sub-session of its own lands beside it,
+      // so a set stays one level deep.
+      parent = owner.parent ?? owner.id;
+    }
+
     const session = this.ctx.spawnSession({
       cwd,
       name: name === '' ? basename(cwd) : name,
@@ -449,6 +498,7 @@ export class DaemonConnection {
       resume: parsed.data.resume,
       namedBy: name === '' ? 'auto' : 'user',
       agent,
+      parent,
     });
 
     this.sendOk(req.id, { session });

package/src/daemon/daemon.ts

@@ -415,7 +415,18 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     loadLastUsedAgent: () => store.loadLastUsedAgent(),
     findAdapter: (kind) => mgr.findAdapter(kind),
     spawnSession: (p) => {
-      const s = mgr.spawn(p.cwd, p.name, p.prompt, p.cols, p.rows, p.resume, p.namedBy, p.agent);
+      const s = mgr.spawn(
+        p.cwd,
+        p.name,
+        p.prompt,
+        p.cols,
+        p.rows,
+        p.resume,
+        p.namedBy,
+        p.agent,
+        p.parent,
+      );
+
       const runtime = runtimes.get(s.id);
 
       if (runtime !== undefined) {
@@ -446,6 +457,10 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         return false;
       }
 
+      for (const child of mgr.collectChildren(id)) {
+        runtimes.get(child.id)?.stopHeadlessRun();
+      }
+
       runtimes.get(id)?.stopHeadlessRun();
 
       await mgr.kill(id);
@@ -525,6 +540,18 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       return true;
     },
     buildResumeCommand: (id) => mgr.buildResumeCommand(id),
+
+    // A killed session keeps its last screen until a second kill removes
+    // it, so a reader can still see what the agent printed before it died.
+    readSessionScreen: (id) => {
+      if (!mgr.sessions.some((x) => x.id === id)) {
+        return Promise.resolve('missing');
+      }
+
+      const screen = runtimes.get(id)?.screen ?? null;
+
+      return screen === null ? Promise.resolve('no_screen') : screen.renderText();
+    },
     answerPermission: (request, decision) => registry.answer(request, decision),
     attachSession: (client, sessionID, dims) => {
       const s = mgr.sessions.find((x) => x.id === sessionID);

package/src/daemon/restore-fleet.ts

@@ -51,7 +51,7 @@ export async function restoreFleet(params: RestoreFleetParams): Promise<number>
   // reported an event keep their stored order at the end. Exited entries
   // dedupe against every listed session, so repeated restores never double
   // up the killed archive.
-  const entries = stored
+  const kept = stored
     .filter((entry) =>
       entry.exited === true
         ? !hasAnySession(entry.agentSessionID)
@@ -61,6 +61,14 @@ export async function restoreFleet(params: RestoreFleetParams): Promise<number>
       (recency.get(b.agentSessionID) ?? '').localeCompare(recency.get(a.agentSessionID) ?? ''),
     );
 
+  // Sub-sessions register after every top-level entry, so each one links
+  // to a parent that is already listed; the wrangling session also boots
+  // before the sessions it wrangles.
+  const entries = [
+    ...kept.filter((entry) => entry.parent === undefined),
+    ...kept.filter((entry) => entry.parent !== undefined),
+  ];
+
   // The whole fleet registers as terminal-less sessions up front, so the
   // list shows every incoming session immediately instead of revealing them
   // one boot at a time. Exited entries only register — they stay killed

package/src/daemon/screen-model.ts

@@ -2,6 +2,12 @@ import { SerializeAddon } from '@xterm/addon-serialize';
 import { Terminal } from '@xterm/headless';
 import { RESET_INPUT_MODES } from '../shared/reset-input-modes';
 
+export interface ScreenText {
+  readonly text: string;
+  readonly cols: number;
+  readonly rows: number;
+}
+
 // The serializer already re-emits the modes the vt engine models (mouse
 // tracking, bracketed paste, focus events); these are the ones it drops.
 const REPLAYED_DEC_MODES = new Set([1006, 1007, 2031]);
@@ -84,21 +90,34 @@ export class ScreenModel {
     });
   }
 
-  // The terminal parses asynchronously, and bytes recorded while a flush is
-  // awaited re-arm it — so the replay drains until no newer write is
-  // pending. Serializing earlier would omit bytes already streamed live to
-  // clients, and the replay's leading clear would erase them from the
-  // client's screen for good.
+  // Serializing before the flush drains would omit bytes already streamed
+  // live to clients, and the replay's leading clear would erase them from
+  // the client's screen for good.
   async renderReplay(): Promise<string> {
-    let pending: Promise<void>;
+    await this.waitForFlush();
 
-    do {
-      pending = this.flushed;
+    return RESET_INPUT_MODES + this.renderVisibleScreen() + this.renderInputModes();
+  }
 
-      await pending;
-    } while (pending !== this.flushed);
+  // The visible rows of whichever buffer the session is showing, as plain
+  // text with no escape sequences: one line per row, trailing blanks
+  // trimmed from each row, trailing blank rows dropped. Drains pending
+  // writes first, so text recorded just before the read is never missing.
+  async renderText(): Promise<ScreenText> {
+    await this.waitForFlush();
 
-    return RESET_INPUT_MODES + this.renderVisibleScreen() + this.renderInputModes();
+    const buffer = this.term.buffer.active;
+    const lines: string[] = [];
+
+    for (let y = 0; y < this.term.rows; y++) {
+      lines.push((buffer.getLine(buffer.baseY + y)?.translateToString(true) ?? '').trimEnd());
+    }
+
+    while (lines.length > 0 && lines.at(-1) === '') {
+      lines.pop();
+    }
+
+    return { text: lines.join('\n'), cols: this.term.cols, rows: this.term.rows };
   }
 
   updateDims(cols: number, rows: number): void {
@@ -109,6 +128,18 @@ export class ScreenModel {
     this.term.dispose();
   }
 
+  // The terminal parses asynchronously, and bytes recorded while a flush is
+  // awaited re-arm it — so this drains until no newer write is pending.
+  private async waitForFlush(): Promise<void> {
+    let pending: Promise<void>;
+
+    do {
+      pending = this.flushed;
+
+      await pending;
+    } while (pending !== this.flushed);
+  }
+
   // A session on the alternate screen serializes as the normal buffer, a
   // buffer switch, then the alternate buffer. The switch clears nothing on a
   // terminal already in alternate mode — and the client always is, since its

package/src/daemon/sessions.ts

@@ -38,6 +38,10 @@ export interface SessionDescriptor {
   // Whether this session's agent can run a headless turn, so the client can
   // offer the eject action without knowing which agent it is.
   readonly canEject: boolean;
+
+  // The session this one is a sub-session of, when it has one: it lists
+  // under that session and takes its pin from it.
+  readonly parent?: SessionID;
 }
 
 export interface Session {
@@ -67,6 +71,10 @@ export interface Session {
   // user-typed spawn name beats auto-summaries.
   namedBy: 'user' | 'auto' | 'agent';
   createdAt: number;
+
+  // The session that spawned this one as a sub-session; null for a
+  // top-level session. One level deep: a sub-session never owns another.
+  parent: SessionID | null;
 }
 
 export class SessionManager {
@@ -171,6 +179,7 @@ export class SessionManager {
       repoRoot: resolveRepoRoot(entry.cwd),
       namedBy: 'auto',
       createdAt: Date.now(),
+      parent: this.findByAgentSessionID(entry.parent)?.id ?? null,
     };
 
     this.sessions.push(session);
@@ -180,6 +189,14 @@ export class SessionManager {
     return session;
   }
 
+  private findByAgentSessionID(agentSessionID: AgentSessionID | undefined): Session | undefined {
+    if (agentSessionID === undefined) {
+      return undefined;
+    }
+
+    return this.sessions.find((s) => s.agentSessionID === agentSessionID);
+  }
+
   // Adopts a headless session back into a terminal: a fresh PTY resumes the
   // same agent session id.
   adoptTerminal(id: SessionID, cols: number, rows: number): Session | null {
@@ -237,15 +254,20 @@ export class SessionManager {
   /**
    * Renames and/or pins a session on a caller's behalf. A rename lands at
    * user strength, so auto-summaries stop overwriting it while an
-   * in-session rename still wins. Pinned sessions lead every list.
+   * in-session rename still wins. Pinned sessions lead every list. A
+   * sub-session takes its pin from its parent, so pinning one is refused.
    */
-  updateSession(id: SessionID, name?: string, pinned?: boolean): boolean {
+  updateSession(id: SessionID, name?: string, pinned?: boolean): boolean | 'child_pin' {
     const s = this.sessions.find((x) => x.id === id);
 
     if (s === undefined) {
       return false;
     }
 
+    if (pinned !== undefined && s.parent !== null) {
+      return 'child_pin';
+    }
+
     if (name !== undefined && name !== '' && s.namedBy !== 'agent') {
       s.name = name;
       s.namedBy = 'user';
@@ -310,7 +332,8 @@ export class SessionManager {
   }
 
   // resume: true opens the agent's own session picker; an agent session id
-  // resumes that specific session (fleet restore).
+  // resumes that specific session (fleet restore). parent makes the new
+  // session a sub-session of that one.
   spawn(
     cwd: string,
     name: string,
@@ -320,6 +343,7 @@ export class SessionManager {
     resume: boolean | AgentSessionID = false,
     namedBy: 'user' | 'auto' = 'auto',
     agent: AgentID = 'claude',
+    parent: SessionID | null = null,
   ): Session {
     const adapter = this.findAdapter(agent);
 
@@ -360,6 +384,7 @@ export class SessionManager {
       repoRoot: resolveRepoRoot(cwd),
       namedBy,
       createdAt: Date.now(),
+      parent,
     };
 
     pty.onData((d) => {
@@ -408,9 +433,15 @@ export class SessionManager {
       kind: s.kind,
       alive: s.pty !== null || (s.kind === 'headless' && s.state !== 'exited'),
       canEject: (this.findAdapter(s.agent)?.headlessRunner ?? null) !== null,
+      ...(s.parent === null ? {} : { parent: s.parent }),
     }));
   }
 
+  // The live and dead sub-sessions of a session, in list order.
+  collectChildren(id: SessionID): Session[] {
+    return this.sessions.filter((s) => s.parent === id);
+  }
+
   // Returns the normalized event kind so the caller can key lifecycle
   // bookkeeping on it, or null when no session or adapter matches.
   applyHook(e: HookEvent): AdapterEvent['kind'] | null {
@@ -585,7 +616,9 @@ export class SessionManager {
 
   // A kill's response is the caller's cue that the session is safely
   // archived, so the write it depends on must land before that response
-  // goes out.
+  // goes out. A kill acts on the whole set: killing a session kills its
+  // live sub-sessions with it, and forgetting a dead one forgets its dead
+  // sub-sessions and promotes any live ones to top level.
   async kill(id: SessionID): Promise<void> {
     const s = this.sessions.find((x) => x.id === id);
 
@@ -594,21 +627,23 @@ export class SessionManager {
     }
 
     if (s.pty) {
-      s.pty.kill();
-
-      s.pty = null;
-      s.state = 'exited';
-      s.lastMsg = 'killed';
+      for (const child of this.collectChildren(id)) {
+        this.killTerminal(child);
+      }
 
-      this.onEvent('state', s);
+      this.killTerminal(s);
     } else {
-      this.sessions = this.sessions.filter((x) => x.id !== id);
+      for (const child of this.collectChildren(id)) {
+        if (child.pty === null && !(child.kind === 'headless' && child.state !== 'exited')) {
+          this.remove(child);
+        } else {
+          child.parent = null;
 
-      if (this.focusedId === id) {
-        this.focusedId = null;
+          this.onEvent('state', child);
+        }
       }
 
-      this.onEvent('removed', s);
+      this.remove(s);
     }
 
     await this.writeFleet();
@@ -616,6 +651,33 @@ export class SessionManager {
     this.emitChange();
   }
 
+  // Ends a live session, terminal or headless, leaving a dead entry; a
+  // session already dead is left as it is.
+  private killTerminal(s: Session) {
+    if (s.pty !== null) {
+      s.pty.kill();
+
+      s.pty = null;
+    } else if (s.kind !== 'headless' || s.state === 'exited') {
+      return;
+    }
+
+    s.state = 'exited';
+    s.lastMsg = 'killed';
+
+    this.onEvent('state', s);
+  }
+
+  private remove(s: Session) {
+    this.sessions = this.sessions.filter((x) => x.id !== s.id);
+
+    if (this.focusedId === s.id) {
+      this.focusedId = null;
+    }
+
+    this.onEvent('removed', s);
+  }
+
   killAll() {
     for (const s of this.sessions) {
       s.pty?.kill();
@@ -653,6 +715,13 @@ export class SessionManager {
 
       const live = s.pty !== null || (s.kind === 'headless' && s.state !== 'exited');
 
+      // The link persists by the parent's agent session id, since atc ids
+      // are minted afresh on restore.
+      const parent =
+        s.parent === null
+          ? undefined
+          : this.sessions.find((x) => x.id === s.parent)?.agentSessionID;
+
       fleet.push({
         name: s.name,
         cwd: s.cwd,
@@ -661,6 +730,7 @@ export class SessionManager {
         ...(s.pinned ? { pinned: true } : {}),
         lastAttachedAt: s.lastAttachedAt,
         ...(live ? {} : { exited: true }),
+        ...(parent === undefined ? {} : { parent }),
       });
     }
 
@@ -689,6 +759,8 @@ export function countSessionStates(
 }
 
 interface SortableSessionView {
+  readonly id: string;
+  readonly parent: string | null;
   readonly state: SessionState;
   readonly pinned: boolean;
   readonly lastAttachedAt: number;
@@ -697,7 +769,10 @@ interface SortableSessionView {
 
 // Overlay order: pinned sessions first in most-recently-attached order, then
 // everyone else by urgency — who needs you, finished turns, busy, dead —
-// with most-recently-attached breaking ties inside each state.
+// with most-recently-attached breaking ties inside each state. A
+// sub-session sits directly under its parent, ranked among its siblings
+// alone, so its attention never moves the parent's row; a sub-session whose
+// parent is not listed ranks as a top-level row.
 export function sortSessionViews<T extends SortableSessionView>(list: readonly T[]): T[] {
   const rank: Record<SessionState, number> = {
     needs_you: 0,
@@ -706,7 +781,7 @@ export function sortSessionViews<T extends SortableSessionView>(list: readonly T
     exited: 3,
   };
 
-  return [...list].toSorted((a, b) => {
+  const ranked = [...list].toSorted((a, b) => {
     if (a.pinned !== b.pinned) {
       return a.pinned ? -1 : 1;
     }
@@ -715,6 +790,20 @@ export function sortSessionViews<T extends SortableSessionView>(list: readonly T
 
     return a.pinned ? recency : rank[a.state] - rank[b.state] || recency;
   });
+
+  const listed = new Set(ranked.map((s) => s.id));
+
+  const sorted: T[] = [];
+
+  for (const s of ranked) {
+    if (s.parent !== null && listed.has(s.parent)) {
+      continue;
+    }
+
+    sorted.push(s, ...ranked.filter((child) => child.parent === s.id));
+  }
+
+  return sorted;
 }
 
 // Never a filesystem path, so a repository can't collide with it.
@@ -723,14 +812,17 @@ export const PINNED_GROUP_KEY = ' pinned';
 // Overlay display order for the grouped view: the flat sort with each
 // repository's sessions pulled together at the position of its best-ranked
 // member, so the renderer's adjacency-based headers appear once per group.
-// Pinned sessions form their own leading group.
+// Pinned sessions form their own leading group. A sub-session keys by its
+// parent, so a set never splits across groups.
 export function sortGroupedSessionViews<
   T extends SortableSessionView & { readonly repoRoot: string },
 >(list: readonly T[]): T[] {
+  const byID = new Map(list.map((s) => [s.id, s]));
   const buckets = new Map<string, T[]>();
 
   for (const s of sortSessionViews(list)) {
-    const key = s.pinned ? PINNED_GROUP_KEY : s.repoRoot;
+    const owner = (s.parent === null ? undefined : byID.get(s.parent)) ?? s;
+    const key = owner.pinned ? PINNED_GROUP_KEY : owner.repoRoot;
     const bucket = buckets.get(key);
 
     if (bucket === undefined) {

package/src/mcp-server.ts

@@ -43,6 +43,12 @@ const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
     agent: SPAWN_SCHEMA.shape.agent.describe(
       'Which registered agent id to spawn; defaults to claude',
     ),
+    detached: z
+      .boolean()
+      .optional()
+      .describe(
+        'Spawn a top-level session. By default a spawn from inside an atc session becomes a sub-session of it: listed under it, pinned with it, killed with it.',
+      ),
   }),
   { io: 'input' },
 );
@@ -57,7 +63,7 @@ const TOOLS: readonly MCPTool[] = [
   {
     name: 'atc_session_spawn',
     description:
-      'Spawn a new session in a directory. Optional agent is an agent id the daemon has registered, such as claude, grok, or codex; omitted agent is always Claude, never the TUI last-used value. An unregistered id is rejected. Returns the new session descriptor. Give it a prompt to start it working immediately.',
+      'Spawn a new session in a directory. Optional agent is an agent id the daemon has registered, such as claude, grok, or codex; omitted agent is always Claude, never the TUI last-used value. An unregistered id is rejected. Called from inside an atc session, the new session is a sub-session of the caller unless detached is true. Returns the new session descriptor. Give it a prompt to start it working immediately.',
     inputSchema: SPAWN_INPUT,
   },
   {
@@ -74,10 +80,16 @@ const TOOLS: readonly MCPTool[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'atc_session_screen',
+    description:
+      'Read the current terminal screen of a session as plain text, without attaching to it. Use it to see what a session printed or what it is waiting on before answering it with atc_session_input. A killed session keeps its last screen.',
+    inputSchema: SESSION_INPUT,
+  },
   {
     name: 'atc_session_update',
     description:
-      'Rename and/or pin a session. Renames stick against auto-summaries; pinned sessions lead every list. Use this to organise the fleet: name sessions after their task.',
+      'Rename and/or pin a session. Renames stick against auto-summaries; pinned sessions lead every list. A sub-session pins with its parent, so pin the parent instead. Use this to organise the fleet: name sessions after their task.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -243,14 +255,23 @@ async function runTool(
     case 'atc_session_spawn': {
       const rawAgent = args['agent'];
 
-      const ok = await client.sendRequest('session.spawn', {
+      // The server inherits the calling session's id from its environment,
+      // so a spawn from inside a session nests under it by default.
+      const caller = process.env['ATC_SESSION_ID'];
+      const nested = args['detached'] !== true && caller !== undefined && caller !== '';
+
+      const params = {
         cwd: args['cwd'],
         ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
         ...(typeof args['prompt'] === 'string' ? { prompt: args['prompt'] } : {}),
         ...(rawAgent === undefined ? {} : { agent: rawAgent }),
         cols: 100,
         rows: 30,
-      });
+      };
+
+      const ok = nested
+        ? await sendNestedSpawn(client, params, caller)
+        : await client.sendRequest('session.spawn', params);
 
       return JSON.stringify(ok['session'], null, 2);
     }
@@ -262,6 +283,11 @@ async function runTool(
 
       return 'sent';
     }
+    case 'atc_session_screen': {
+      const ok = await client.sendRequest('session.screen', { session: args['session'] });
+
+      return typeof ok['text'] === 'string' ? ok['text'] : JSON.stringify(ok);
+    }
     case 'atc_session_update': {
       await client.sendRequest('session.update', {
         session: args['session'],
@@ -304,3 +330,22 @@ function sendResult(id: string | number, result: Readonly<Record<string, unknown
 function sendError(id: string | number, code: number, message: string): void {
   process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } })}\n`);
 }
+
+// The inherited id can point at a session another daemon hosts, or one
+// this daemon no longer lists; the spawn then lands top-level instead of
+// failing the tool call.
+async function sendNestedSpawn(
+  client: FleetCaller,
+  params: Readonly<Record<string, unknown>>,
+  parent: string,
+): Promise<Readonly<Record<string, unknown>>> {
+  try {
+    return await client.sendRequest('session.spawn', { ...params, parent });
+  } catch (error) {
+    if (error instanceof DaemonError && error.code === 'no_such_session') {
+      return client.sendRequest('session.spawn', params);
+    }
+
+    throw error;
+  }
+}

package/src/protocol/request-param-schemas.ts

@@ -42,6 +42,13 @@ export const REQUEST_PARAM_SCHEMAS = {
       .string({ error: 'session.spawn agent must be a non-empty agent id' })
       .min(1, 'session.spawn agent must be a non-empty agent id')
       .optional(),
+
+    // The session the new one is a sub-session of; absent or empty spawns a
+    // top-level session.
+    parent: z.preprocess(
+      (v) => (typeof v === 'string' && v !== '' ? v : undefined),
+      z.string().transform(toSessionID).optional(),
+    ),
   }),
   'session.kill': SESSION_DEFAULTED,
   'session.ack': SESSION_DEFAULTED,
@@ -64,6 +71,7 @@ export const REQUEST_PARAM_SCHEMAS = {
     message: 'session.resize requires positive cols and rows',
   }),
   'session.resumeCommand': SESSION_DEFAULTED,
+  'session.screen': SESSION_DEFAULTED,
   'session.eject': SESSION_DEFAULTED.extend({
     prompt: buildDefaultedNonEmptyString(EJECT_DEFAULT_PROMPT),
   }),

package/src/store/fleet-entry.ts

@@ -3,6 +3,7 @@ import { toAgentID } from '../agents/agent-adapter';
 import type { AgentID } from '../agents/agent-adapter';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import { buildOptionalBoolean } from '../shared/build-optional-boolean';
+import { buildOptionalString } from '../shared/build-optional-string';
 import { isRecord } from '../shared/report';
 import { toAgentSessionID } from '../shared/to-agent-session-id';
 
@@ -14,6 +15,9 @@ export interface FleetEntry {
   readonly pinned?: boolean;
   readonly lastAttachedAt?: number;
   readonly exited?: boolean;
+
+  // The agent session id of the session this one is a sub-session of.
+  readonly parent?: AgentSessionID;
 }
 
 export interface FleetStore {
@@ -43,6 +47,7 @@ const FLEET_ENTRY_SCHEMA = z.preprocess(
     pinned: buildOptionalBoolean(),
     lastAttachedAt: buildOptionalNumber(),
     exited: buildOptionalBoolean(),
+    parent: buildOptionalString(),
   }),
 );
 
@@ -64,6 +69,9 @@ export function parseFleetEntry(raw: unknown): FleetEntry | undefined {
       ? {}
       : { lastAttachedAt: parsed.data.lastAttachedAt }),
     ...(parsed.data.exited === true ? { exited: true } : {}),
+    ...(parsed.data.parent === undefined || parsed.data.parent === ''
+      ? {}
+      : { parent: toAgentSessionID(parsed.data.parent) }),
   };
 }
 

package/src/store/run-migrations.ts

@@ -11,6 +11,7 @@ interface FleetTable {
   last_attached: number | null;
   agent: string;
   exited: number;
+  parent: string | null;
 }
 
 interface EventsTable {
@@ -119,6 +120,11 @@ const MIGRATIONS: Record<string, Migration> = {
         .execute();
     },
   },
+  '007_add_fleet_parent': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema.alterTable('fleet').addColumn('parent', 'text').execute();
+    },
+  },
 };
 
 const PROVIDER: MigrationProvider = {
@@ -238,5 +244,9 @@ function pickBaselineSteps(columns: ReadonlySet<string>): readonly string[] {
     steps.push('006_add_fleet_exited');
   }
 
+  if (columns.has('parent')) {
+    steps.push('007_add_fleet_parent');
+  }
+
   return steps;
 }

package/src/store/state-store.ts

@@ -63,7 +63,16 @@ export class StateStore {
   async loadFleet(): Promise<FleetEntry[]> {
     const rows = await this.db
       .selectFrom('fleet')
-      .select(['agent_session_id', 'name', 'cwd', 'pinned', 'last_attached', 'agent', 'exited'])
+      .select([
+        'agent_session_id',
+        'name',
+        'cwd',
+        'pinned',
+        'last_attached',
+        'agent',
+        'exited',
+        'parent',
+      ])
       .execute();
 
     const entries: FleetEntry[] = [];
@@ -77,6 +86,7 @@ export class StateStore {
         ...(row.pinned === 0 ? {} : { pinned: true }),
         ...(row.last_attached === null ? {} : { lastAttachedAt: row.last_attached }),
         ...(row.exited === 0 ? {} : { exited: true }),
+        ...(row.parent === null ? {} : { parent: toAgentSessionID(row.parent) }),
       });
     }
 
@@ -121,6 +131,7 @@ export class StateStore {
             last_attached: entry.lastAttachedAt ?? null,
             agent: entry.agent,
             exited: entry.exited === true ? 1 : 0,
+            parent: entry.parent ?? null,
           })
           .orReplace()
           .execute();