@zgeoff/atc 0.1.1 → 0.1.3

package/README.md

@@ -38,12 +38,13 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 | Key             | Where          | Action                                                                                         |
 | --------------- | -------------- | ---------------------------------------------------------------------------------------------- |
 | leader          | anywhere       | toggle session overlay — `Ctrl-Space` by default, configurable (see Config)                    |
-| `n`             | home/overlay   | spawn: pick dir (zoxide + history, fuzzy) → name → optional first prompt                       |
+| `n`             | home/overlay   | spawn: pick dir (zoxide + history, fuzzy) → name → optional group → optional first prompt      |
 | `r`             | home/overlay   | adopt: pick dir → name → `claude --resume` (Claude's session picker opens in the new PTY)      |
 | `R`             | home           | restore last fleet after a daemon death — respawns every session via `claude --resume <id>`    |
 | `j`/`k`/`↑`/`↓` | overlay/picker | move                                                                                           |
 | `Enter`         | overlay        | attach (auto-acks)                                                                             |
-| `/`             | overlay        | fzf-style filter: type to narrow by name/dir, `⏎` attach top match, `esc` clear                |
+| `Tab`           | overlay        | attach the most urgent needs-you session                                                       |
+| `/`             | overlay        | fuzzy filter by name/dir (chars in order), `⏎` attach top match, `esc` clear                   |
 | `a`             | overlay        | ack notification without attaching                                                             |
 | `H`             | overlay        | eject to headless: the terminal dies, a headless Agent SDK run resumes the same session        |
 | `P`             | overlay        | revive: a fresh terminal resumes a headless or killed session in place                         |
@@ -51,8 +52,14 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 | `Y`             | overlay        | eject: yank the resume command, then kill the session here — paste it in any pane to take over |
 | `K`             | overlay        | kill selected (confirm with `y`) — the entry stays revivable with `P`; a second `K` forgets it |
 | `?`             | overlay        | full key reference — the hint row only shows actions valid for the selected session            |
+| `u`             | overlay        | restart an outdated daemon and restore the fleet — offered only while `⟳ update ready` shows   |
 | `q`             | home/overlay   | quit the client — sessions keep running in the daemon                                          |
 
+The overlay clusters sessions under dim headers when more than one group exists: a session's
+explicit group wins, and sessions without one fall back to the directory they were spawned from.
+Groups also come from outside — the `atc_session_update` MCP tool renames and regroups sessions, so
+an agent can organise the fleet for you.
+
 Revive (`P`) and headless eject (`H`) resume the session from its saved transcript, so both need one
 to exist: a session killed before its first exchange has nothing on disk yet, and the overlay says
 so in its message column instead of resuming.
@@ -92,8 +99,8 @@ Pick a different leader when `Ctrl-Space` is taken on your machine — Raycast o
 `ctrl-]` is a solid replacement that no common terminal, multiplexer, or OS shortcut wants. An
 unknown or reserved value falls back to the default.
 
-`atc mcp` exposes the fleet as MCP tools (list, spawn, drive) to any MCP client, wrangled sessions
-included:
+`atc mcp` exposes the fleet as MCP tools (list, spawn, drive, organise) to any MCP client, wrangled
+sessions included:
 
 ```sh
 claude mcp add --scope user atc -- atc mcp
@@ -106,8 +113,11 @@ daemon's pid file sits in `$XDG_RUNTIME_DIR/atc-daemon.pid`, beside its sockets.
 ## Crash safety
 
 A client crash or closed window costs nothing: the daemon keeps hosting the fleet, and the next
-`atc` reconnects. The daemon continuously writes the live fleet (name, cwd, Claude session id) to
-its SQLite store. If the daemon itself dies — crash, SIGKILL, reboot — the child claude processes
-die with it, but every session's transcript is already on disk. Start atc and press `R`: the whole
-fleet respawns via `claude --resume`. Only deliberate kills (`K`, `Y` eject) remove entries from the
-fleet, so it stays restorable.
+`atc` reconnects. After an update, a client meeting an older daemon keeps talking to it — killing it
+would kill every hosted session — and shows `⟳ update ready` in the status bar; `u` in the overlay
+restarts the daemon and restores the fleet at a moment you choose. Only a protocol mismatch, where
+the two could miscommunicate, forces the restart immediately. The daemon continuously writes the
+live fleet (name, cwd, Claude session id) to its SQLite store. If the daemon itself dies — crash,
+SIGKILL, reboot — the child claude processes die with it, but every session's transcript is already
+on disk. Start atc and press `R`: the whole fleet respawns via `claude --resume`. Only deliberate
+kills (`K`, `Y` eject) remove entries from the fleet, so it stays restorable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Terminal control tower for Claude Code sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/boot-daemon.ts

@@ -4,37 +4,51 @@ import { basename, join } from 'node:path';
 import { daemonPidFile, daemonSocketPath } from './config';
 import { DaemonClient } from './daemon-client';
 import { getBuild } from './get-build';
+import { isRecord } from './report';
+
+export interface DaemonBoot {
+  readonly client: DaemonClient;
+  readonly stale: boolean;
+}
 
 /**
  * Opens a handshaken client to the daemon, booting the daemon first when its
- * socket is absent. A daemon left running from an older build is restarted,
- * so a fresh client never talks to stale daemon code — the fleet stays
- * restorable afterwards through the usual cold-boot recovery. The expected
+ * socket is absent. A daemon from an older build stays in service — killing
+ * it would kill every hosted session — and is reported as stale so the
+ * caller can offer a deliberate restart. Only a protocol mismatch, where
+ * talking would misbehave, forces the restart immediately. The expected
  * build is read from disk on every attempt: a long-lived caller holding a
- * build string from its own boot would otherwise restart daemons that are
+ * build string from its own boot would otherwise flag daemons that are
  * already current.
  */
-export async function bootDaemonClient(): Promise<DaemonClient> {
+export async function bootDaemonClient(): Promise<DaemonBoot> {
   for (let attempt = 0; attempt < 2; attempt++) {
     const build = getBuild();
 
     const client = await openOrBootDaemon();
-    const hello = await client.sendHello(build);
 
-    const daemonBuild = hello['daemon'];
+    try {
+      const hello = await client.sendHello(build);
 
-    if (daemonBuild === build || attempt > 0) {
-      return client;
-    }
+      return { client, stale: hello['daemon'] !== build };
+    } catch (error) {
+      client.stop();
 
-    client.stop();
+      if (attempt > 0 || !isProtocolMismatch(error)) {
+        throw error;
+      }
 
-    await stopStaleDaemon();
+      await stopStaleDaemon();
+    }
   }
 
   throw new Error('the atc daemon could not be restarted');
 }
 
+function isProtocolMismatch(error: unknown): boolean {
+  return isRecord(error) && error['code'] === 'protocol_mismatch';
+}
+
 async function openOrBootDaemon(): Promise<DaemonClient> {
   let opened = await tryOpenDaemon();
 

package/src/cli.ts

@@ -61,6 +61,7 @@ const main = defineCommand({
             legacyFleetPath: config.legacyFleetFile,
             pidPath: config.daemonPidFile,
             ...(Number.isFinite(queueBytes) && queueBytes > 0 ? { queueBytes } : {}),
+            onQuit: () => process.exit(0),
           });
 
           process.on('SIGTERM', () => {

package/src/daemon-connection.ts

@@ -15,6 +15,7 @@ interface SpawnParams {
   readonly rows: number;
   readonly resume: boolean | string;
   readonly namedBy: 'user' | 'auto';
+  readonly group?: string;
 }
 
 export interface DaemonContext {
@@ -24,6 +25,8 @@ export interface DaemonContext {
   readonly collectFleet: () => FleetEntry[];
   readonly spawnSession: (p: SpawnParams) => SessionDescriptor;
   readonly killSession: (id: string) => boolean;
+  readonly updateSession: (id: string, name?: string, group?: string) => boolean;
+  readonly quitDaemon: () => void;
   readonly ackSession: (id: string) => boolean;
   readonly buildResumeCommand: (id: string) => string | null;
   readonly answerPermission: (request: string, decision: string) => AnswerResult;
@@ -213,6 +216,25 @@ export class DaemonConnection {
 
         return;
       }
+      case 'daemon.quit': {
+        this.sendOk(req.id, {});
+        this.ctx.quitDaemon();
+
+        return;
+      }
+      case 'session.update': {
+        const sessionID = typeof req.p?.['session'] === 'string' ? req.p['session'] : '';
+        const name = typeof req.p?.['name'] === 'string' ? req.p['name'] : undefined;
+        const group = typeof req.p?.['group'] === 'string' ? req.p['group'] : undefined;
+
+        if (this.ctx.updateSession(sessionID, name, group)) {
+          this.sendOk(req.id, {});
+        } else {
+          this.sendErr(req.id, 'no_such_session', `no session '${sessionID}'`);
+        }
+
+        return;
+      }
       case 'session.kill': {
         this.applySessionVerb(req, this.ctx.killSession);
 
@@ -348,6 +370,8 @@ export class DaemonConnection {
       resume = rawResume;
     }
 
+    const group = typeof req.p?.['group'] === 'string' ? req.p['group'] : '';
+
     const session = this.ctx.spawnSession({
       cwd,
       name: name === '' ? basename(cwd) : name,
@@ -356,6 +380,7 @@ export class DaemonConnection {
       rows: typeof req.p?.['rows'] === 'number' ? req.p['rows'] : 24,
       resume,
       namedBy: name === '' ? 'auto' : 'user',
+      ...(group === '' ? {} : { group }),
     });
 
     this.sendOk(req.id, { session });

package/src/daemon.ts

@@ -43,6 +43,10 @@ export interface DaemonOptions {
   // How long an eject waits for the dying terminal to report SessionEnd
   // before starting the headless run anyway.
   readonly ejectSettleMs?: number;
+
+  // Called after a client-requested quit has stopped the daemon; the real
+  // entrypoint exits the process, tests leave it unset.
+  readonly onQuit?: () => void;
 }
 
 interface HeadlessRunRequest {
@@ -77,6 +81,8 @@ export interface DaemonHandle {
  * or hostile peer.
  */
 export function startDaemon(opts: DaemonOptions): DaemonHandle {
+  let stopDaemon: (() => void) | null = null;
+
   if (opts.pidPath !== undefined) {
     writeFileSync(opts.pidPath, String(process.pid));
   }
@@ -367,6 +373,7 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
         kind: s.kind,
         alive: s.pty !== null || (s.kind === 'jsonl' && s.state !== 'exited'),
         ...(s.claudeId === undefined ? {} : { claudeId: s.claudeId }),
+        ...(s.group === undefined ? {} : { group: s.group }),
       }),
       renamed: () => ({
         v: PROTOCOL_V,
@@ -399,7 +406,7 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
     collectSpawnDirs: () => store.collectSpawnDirs(),
     collectFleet: () => store.loadFleet(),
     spawnSession: (p) => {
-      const s = mgr.spawn(p.cwd, p.name, p.prompt, p.cols, p.rows, p.resume, p.namedBy);
+      const s = mgr.spawn(p.cwd, p.name, p.prompt, p.cols, p.rows, p.resume, p.namedBy, p.group);
 
       ptyDims.set(s.id, { cols: p.cols, rows: p.rows });
       screens.set(s.id, new ScreenModel(p.cols, p.rows));
@@ -407,6 +414,15 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
 
       return getDescriptor(mgr, s.id);
     },
+    updateSession: (id, name, group) => mgr.updateSession(id, name, group),
+    quitDaemon: () => {
+      // The ok response for the quit request must flush before the sockets
+      // close under it.
+      setTimeout(() => {
+        stopDaemon?.();
+        opts.onQuit?.();
+      }, 80);
+    },
     killSession: (id) => {
       if (!mgr.sessions.some((s) => s.id === id)) {
         return false;
@@ -556,7 +572,16 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
           continue;
         }
 
-        const s = mgr.spawn(entry.cwd, entry.name, '', cols, rows, entry.claudeId);
+        const s = mgr.spawn(
+          entry.cwd,
+          entry.name,
+          '',
+          cols,
+          rows,
+          entry.claudeId,
+          'auto',
+          entry.group,
+        );
 
         ptyDims.set(s.id, { cols, rows });
         screens.set(s.id, new ScreenModel(cols, rows));
@@ -594,33 +619,33 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
     },
   });
 
-  return {
-    stop() {
-      for (const timer of resizeTimers.values()) {
-        clearTimeout(timer);
-      }
+  stopDaemon = () => {
+    for (const timer of resizeTimers.values()) {
+      clearTimeout(timer);
+    }
 
-      for (const timer of detectTimers.values()) {
-        clearTimeout(timer);
-      }
+    for (const timer of detectTimers.values()) {
+      clearTimeout(timer);
+    }
 
-      server.stop(true);
-      reporter.stop(true);
-      mgr.killAll();
+    server.stop(true);
+    reporter.stop(true);
+    mgr.killAll();
 
-      for (const model of screens.values()) {
-        model.stop();
-      }
+    for (const model of screens.values()) {
+      model.stop();
+    }
 
-      store.stop();
+    store.stop();
 
-      if (opts.pidPath !== undefined) {
-        try {
-          unlinkSync(opts.pidPath);
-        } catch {}
-      }
-    },
+    if (opts.pidPath !== undefined) {
+      try {
+        unlinkSync(opts.pidPath);
+      } catch {}
+    }
   };
+
+  return { stop: stopDaemon };
 }
 
 // A session reporting a transcript path that does not exist on disk yet has

package/src/dirs.ts

@@ -38,26 +38,21 @@ export function pickMatches(items: readonly string[], filter: string): string[]
     return [...items];
   }
 
-  const f = filter.toLowerCase();
-
-  const scored = items
-    .map((item) => {
-      const base = basename(item).toLowerCase();
-      let score = -1;
-
-      if (base.startsWith(f)) {
-        score = 0;
-      } else if (base.includes(f)) {
-        score = 1;
-      } else if (item.toLowerCase().includes(f)) {
-        score = 2;
-      }
-
-      return { item, score };
-    })
-    .filter((x) => x.score >= 0);
-
-  return scored.toSorted((a, b) => a.score - b.score).map((x) => x.item);
+  const scored: { item: string; score: number }[] = [];
+
+  for (const item of items) {
+    // Basename hits beat full-path hits, so `vers` ranks ~/projects/vers
+    // above every path that merely passes through a vers directory.
+    const baseScore = findFuzzyScore(basename(item), filter);
+    const pathScore = findFuzzyScore(item, filter);
+    const score = baseScore === null ? pathScore : baseScore + 100;
+
+    if (score !== null) {
+      scored.push({ item, score });
+    }
+  }
+
+  return scored.toSorted((a, b) => b.score - a.score).map((x) => x.item);
 }
 
 export function formatDir(d: string): string {
@@ -65,3 +60,44 @@ export function formatDir(d: string): string {
 
   return d.startsWith(home) ? `~${d.slice(home.length)}` : d;
 }
+
+const SEPARATORS = new Set(['/', '-', '_', '.', ' ']);
+
+/**
+ * Scores how well a filter fuzzy-matches a candidate: every filter
+ * character must appear in order, consecutive characters and characters
+ * starting a word score higher, and a miss is null rather than zero so
+ * non-matches are distinguishable from weak matches.
+ */
+export function findFuzzyScore(candidate: string, filter: string): number | null {
+  const hay = candidate.toLowerCase();
+  const needle = filter.toLowerCase();
+  let score = 0;
+  let pos = 0;
+  let prevHit = -2;
+
+  for (const ch of needle) {
+    const hit = hay.indexOf(ch, pos);
+
+    if (hit === -1) {
+      return null;
+    }
+
+    score += 1;
+
+    if (hit === prevHit + 1) {
+      score += 2;
+    }
+
+    const before = hay[hit - 1];
+
+    if (hit === 0 || (before !== undefined && SEPARATORS.has(before))) {
+      score += 2;
+    }
+
+    prevHit = hit;
+    pos = hit + 1;
+  }
+
+  return score;
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 import { basename } from 'node:path';
 import { bootDaemonClient } from './boot-daemon';
 import { loadConfig } from './config';
-import { collectDirs, formatDir, pickMatches } from './dirs';
+import { collectDirs, findFuzzyScore, formatDir, pickMatches } from './dirs';
 import type { EventMsg } from './protocol';
 import { isRecord } from './report';
 import { countSessionStates, sortSessionViews } from './sessions';
@@ -15,6 +15,7 @@ type Mode =
   | 'help'
   | 'picker-dir'
   | 'picker-name'
+  | 'picker-group'
   | 'picker-prompt'
   | 'picker-eject';
 
@@ -22,6 +23,7 @@ interface MirrorSession {
   id: string;
   name: string;
   cwd: string;
+  group?: string;
   state: SessionState;
   unread: boolean;
   lastMsg: string;
@@ -46,6 +48,7 @@ let pickerInput = '';
 let pickerSelected = 0;
 let spawnDir = '';
 let spawnName = '';
+let spawnGroup = '';
 let spawnResume = false;
 const stdout = process.stdout;
 
@@ -78,6 +81,7 @@ function scheduleStatus() {
         focusedName: focused === null ? null : focused.name,
         urgentName: urgent === undefined ? null : urgent.name,
         leaderLabel: leader.label,
+        stale: daemonStale,
       });
     }
   }, 50);
@@ -197,9 +201,11 @@ function pickOverlaySessions(): MirrorSession[] {
     return sorted;
   }
 
-  const f = overlayFilter.toLowerCase();
+  const f = overlayFilter;
 
-  return sorted.filter((s) => `${s.name} ${formatDir(s.cwd)}`.toLowerCase().includes(f));
+  return sorted.filter(
+    (s) => findFuzzyScore(`${s.name} ${s.group ?? ''} ${formatDir(s.cwd)}`, f) !== null,
+  );
 }
 
 function renderOverlay() {
@@ -212,6 +218,7 @@ function renderOverlay() {
     selected: overlaySelected,
     confirmKill,
     filter: overlayFilter,
+    stale: daemonStale,
   });
 
   scheduleStatus();
@@ -255,6 +262,18 @@ function renderPicker() {
       placeholder: basename(spawnDir),
       hint: `session name for ${formatDir(spawnDir)} · ⏎ accept · esc back`,
     });
+  } else if (mode === 'picker-group') {
+    const groups = [...new Set(fleet.map((s) => s.group).filter((g) => g !== undefined))];
+    const known = groups.length === 0 ? '' : ` · existing: ${groups.slice(0, 4).join(', ')}`;
+
+    drawPicker({
+      title: `${verb}: group`,
+      items: [],
+      selected: -1,
+      input: pickerInput,
+      placeholder: 'optional — ⏎ to skip',
+      hint: `group for the overlay hierarchy${known} · ⏎ accept · esc back`,
+    });
   } else if (mode === 'picker-eject') {
     drawPicker({
       title: 'eject: headless instruction',
@@ -280,6 +299,7 @@ function renderPicker() {
 
 async function openDirPicker(resume = false) {
   spawnResume = resume;
+  spawnGroup = '';
 
   let recent: string[] = [];
 
@@ -327,6 +347,7 @@ async function spawnFromPicker(prompt: string) {
       cols: cols(),
       rows: ptyRows(),
       ...(spawnResume ? { resume: true } : {}),
+      ...(spawnGroup === '' ? {} : { group: spawnGroup }),
     });
 
     const spawned = toMirrorSession(ok['session']);
@@ -382,6 +403,7 @@ function toMirrorSession(value: unknown): MirrorSession | null {
     id: value['id'],
     name: value['name'],
     cwd: value['cwd'],
+    ...(typeof value['group'] === 'string' ? { group: value['group'] } : {}),
     state,
     unread: value['unread'],
     lastMsg: value['lastMsg'],
@@ -463,6 +485,14 @@ function applyDaemonEvent(e: EventMsg) {
           s.kind = e['kind'];
         }
 
+        if (typeof e['group'] === 'string') {
+          if (e['group'] === '') {
+            delete s.group;
+          } else {
+            s.group = e['group'];
+          }
+        }
+
         if (typeof e['unread'] === 'boolean') {
           s.unread = e['unread'];
         }
@@ -529,6 +559,7 @@ function copyToClipboard(text: string) {
 const leader = loadConfig().leader;
 
 const KEY = {
+  tab: 0x09,
   ctrlC: 0x03,
   ctrlU: 0x15,
   esc: 0x1b,
@@ -663,6 +694,16 @@ function applyOverlayKey(buf: Buffer) {
 
   const ch = buf.toString();
 
+  if (buf[0] === KEY.tab) {
+    const needy = sortSessionViews(fleet).find((s) => s.state === 'needs_you' && s.alive);
+
+    if (needy !== undefined) {
+      void attach(needy.id);
+    }
+
+    return;
+  }
+
   if (buf[0] === KEY.enter && sel !== undefined && sel.alive) {
     void attach(sel.id);
 
@@ -688,6 +729,12 @@ function applyOverlayKey(buf: Buffer) {
     return;
   }
 
+  if (ch === 'u' && daemonStale) {
+    void restartDaemon();
+
+    return;
+  }
+
   if (ch === 'H' && sel !== undefined && sel.kind === 'pty' && sel.alive) {
     ejectTarget = sel.id;
     pickerInput = '';
@@ -844,16 +891,23 @@ function applyTextKey(buf: Buffer, onSubmit: () => void, onCancel: () => void) {
   }
 }
 
-const client = await bootDaemonClient();
+const boot = await bootDaemonClient();
+
+let client = boot.client;
+let daemonStale = boot.stale;
 
 client.onEvent = applyDaemonEvent;
 
-{
+await refreshMirror();
+
+async function refreshMirror() {
   const list = await client.sendRequest('session.list');
 
   const sessions = list['sessions'];
 
   if (Array.isArray(sessions)) {
+    fleet = [];
+
     for (const raw of sessions) {
       const d = toMirrorSession(raw);
 
@@ -870,6 +924,42 @@ client.onEvent = applyDaemonEvent;
   fleetCount = Array.isArray(entries) ? entries.length : 0;
 }
 
+/**
+ * The deliberate half of the stale-daemon story: quits the old daemon,
+ * boots one from the current build, and restores the whole fleet, so an
+ * update never interrupts sessions until the user picks the moment.
+ */
+async function restartDaemon() {
+  try {
+    await client.sendRequest('daemon.quit');
+  } catch {}
+
+  client.stop();
+
+  const deadline = Date.now() + 8000;
+
+  let next = await bootDaemonClient();
+
+  while (next.stale && Date.now() < deadline) {
+    next.client.stop();
+
+    await new Promise((resolve) => {
+      setTimeout(resolve, 200);
+    });
+
+    next = await bootDaemonClient();
+  }
+
+  client = next.client;
+  daemonStale = next.stale;
+  client.onEvent = applyDaemonEvent;
+
+  await sendQuiet('fleet.restore', { cols: cols(), rows: ptyRows() });
+  await refreshMirror().catch(() => {});
+
+  openOverlay();
+}
+
 process.stdin.setRawMode(true);
 process.stdin.resume();
 
@@ -975,6 +1065,30 @@ process.stdin.on('data', (buf: Buffer) => {
         () => {
           spawnName = pickerInput.trim();
           pickerInput = '';
+          mode = 'picker-group';
+
+          stdout.write(ansi.clear);
+
+          renderPicker();
+        },
+        () => {
+          pickerInput = '';
+          mode = 'picker-dir';
+
+          stdout.write(ansi.clear);
+
+          renderPicker();
+        },
+      );
+
+      return;
+    }
+    case 'picker-group': {
+      applyTextKey(
+        buf,
+        () => {
+          spawnGroup = pickerInput.trim();
+          pickerInput = '';
 
           // Adopt skips the prompt step: claude --resume opens its own
           // session picker inside the new PTY.
@@ -992,7 +1106,7 @@ process.stdin.on('data', (buf: Buffer) => {
         },
         () => {
           pickerInput = '';
-          mode = 'picker-dir';
+          mode = 'picker-name';
 
           stdout.write(ansi.clear);
 
@@ -1010,7 +1124,7 @@ process.stdin.on('data', (buf: Buffer) => {
         },
         () => {
           pickerInput = '';
-          mode = 'picker-name';
+          mode = 'picker-group';
 
           stdout.write(ansi.clear);
 

package/src/mcp-server.ts

@@ -69,6 +69,21 @@ const TOOLS: readonly MCPTool[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'atc_session_update',
+    description:
+      'Rename and/or regroup a session. Renames stick against auto-summaries; an empty group clears the grouping. Use this to organise the fleet: name sessions after their task and group related work.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session: { type: 'string', description: 'The atc session id' },
+        name: { type: 'string', description: 'New display name; omit to keep' },
+        group: { type: 'string', description: 'New group; empty string clears, omit to keep' },
+      },
+      required: ['session'],
+      additionalProperties: false,
+    },
+  },
   {
     name: 'atc_session_kill',
     description: 'Kill a session. A second kill on a dead session removes it from the list.',
@@ -98,7 +113,9 @@ const TOOLS: readonly MCPTool[] = [
  * stdout carries only JSON-RPC lines; the daemon is booted on demand.
  */
 export async function runMCPServer(build: string): Promise<void> {
-  const client = await bootDaemonClient();
+  const boot = await bootDaemonClient();
+
+  const client = boot.client;
 
   const decoder = new TextDecoder('utf-8');
 
@@ -237,6 +254,15 @@ async function runTool(
 
       return 'sent';
     }
+    case 'atc_session_update': {
+      await client.sendRequest('session.update', {
+        session: args['session'],
+        ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
+        ...(typeof args['group'] === 'string' ? { group: args['group'] } : {}),
+      });
+
+      return 'updated';
+    }
     case 'atc_session_kill': {
       await client.sendRequest('session.kill', { session: args['session'] });
 

package/src/sessions.ts

@@ -23,6 +23,7 @@ export interface SessionDescriptor {
   readonly lastMsg: string;
   readonly lastDetail?: string;
   readonly claudeId?: string;
+  readonly group?: string;
   readonly namedBy: 'user' | 'auto' | 'agent';
   readonly createdAt: number;
   readonly kind: 'pty' | 'jsonl';
@@ -41,6 +42,7 @@ export interface Session {
   lastDetail?: string;
   claudeId?: string;
   transcriptSource?: string;
+  group?: string;
 
   // who last named this session: the agent's own rename beats everything, a
   // user-typed spawn name beats auto-summaries.
@@ -54,6 +56,7 @@ export interface FleetEntry {
   readonly name: string;
   readonly cwd: string;
   readonly claudeId: string;
+  readonly group?: string;
 }
 
 const fleetFile = join(stateDir, 'fleet.json');
@@ -187,6 +190,42 @@ export class SessionManager {
   }
 
   // Reports a headless run's lifecycle into the session state machine.
+  /**
+   * Renames and/or regroups 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. An empty group clears the grouping.
+   */
+  updateSession(id: string, name?: string, group?: string): boolean {
+    const s = this.sessions.find((x) => x.id === id);
+
+    if (s === undefined) {
+      return false;
+    }
+
+    if (name !== undefined && name !== '' && s.namedBy !== 'agent') {
+      s.name = name;
+      s.namedBy = 'user';
+
+      this.onEvent('renamed', s);
+    }
+
+    if (group !== undefined) {
+      if (group === '') {
+        delete s.group;
+      } else {
+        s.group = group;
+      }
+
+      this.onEvent('state', s);
+    }
+
+    this.writeFleet();
+    this.writeStatus();
+    this.emitChange();
+
+    return true;
+  }
+
   updateSurfaceState(id: string, state: SessionState, msg: string) {
     const s = this.sessions.find((x) => x.id === id);
 
@@ -240,6 +279,7 @@ export class SessionManager {
     rows: number,
     resume: boolean | string = false,
     namedBy: 'user' | 'auto' = 'auto',
+    group?: string,
   ): Session {
     const id = `s${++counter}-${Date.now().toString(36)}`;
     const plan = this.adapter.planSpawn({ prompt, resume });
@@ -268,6 +308,7 @@ export class SessionManager {
       unread: false,
       lastMsg: initialMsg,
       ...(typeof resume === 'string' ? { claudeId: resume } : {}),
+      ...(group === undefined ? {} : { group }),
       namedBy,
       createdAt: Date.now(),
     };
@@ -309,6 +350,7 @@ export class SessionManager {
       lastMsg: s.lastMsg,
       ...(s.lastDetail === undefined ? {} : { lastDetail: s.lastDetail }),
       ...(s.claudeId === undefined ? {} : { claudeId: s.claudeId }),
+      ...(s.group === undefined ? {} : { group: s.group }),
       namedBy: s.namedBy,
       createdAt: s.createdAt,
       kind: s.kind,
@@ -525,7 +567,12 @@ export class SessionManager {
       const live = s.pty !== null || (s.kind === 'jsonl' && s.state !== 'exited');
 
       if (live && s.claudeId !== undefined) {
-        fleet.push({ name: s.name, cwd: s.cwd, claudeId: s.claudeId });
+        fleet.push({
+          name: s.name,
+          cwd: s.cwd,
+          claudeId: s.claudeId,
+          ...(s.group === undefined ? {} : { group: s.group }),
+        });
       }
     }
 

package/src/state-store.ts

@@ -23,7 +23,8 @@ export class StateStore {
       CREATE TABLE IF NOT EXISTS fleet (
         claude_id TEXT PRIMARY KEY,
         name TEXT NOT NULL,
-        cwd TEXT NOT NULL
+        cwd TEXT NOT NULL,
+        grp TEXT
       );
       CREATE TABLE IF NOT EXISTS events (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -39,6 +40,17 @@ export class StateStore {
       );
     `);
 
+    // Stores created before groups existed lack the column; the create
+    // above only applies to fresh databases.
+    const fleetColumns = this.db
+      .query<{ name: string }, []>('PRAGMA table_info(fleet)')
+      .all()
+      .map((c) => c.name);
+
+    if (!fleetColumns.includes('grp')) {
+      this.db.run('ALTER TABLE fleet ADD COLUMN grp TEXT');
+    }
+
     if (legacyFleetPath !== undefined) {
       this.adoptLegacyFleet(legacyFleetPath);
     }
@@ -46,12 +58,23 @@ export class StateStore {
 
   loadFleet(): FleetEntry[] {
     const rows = this.db
-      .query<{ claude_id: string; name: string; cwd: string }, []>(
-        'SELECT claude_id, name, cwd FROM fleet',
+      .query<{ claude_id: string; name: string; cwd: string; grp: string | null }, []>(
+        'SELECT claude_id, name, cwd, grp FROM fleet',
       )
       .all();
 
-    return rows.map((row) => ({ claudeId: row.claude_id, name: row.name, cwd: row.cwd }));
+    const entries: FleetEntry[] = [];
+
+    for (const row of rows) {
+      const entry: FleetEntry =
+        row.grp === null
+          ? { claudeId: row.claude_id, name: row.name, cwd: row.cwd }
+          : { claudeId: row.claude_id, name: row.name, cwd: row.cwd, group: row.grp };
+
+      entries.push(entry);
+    }
+
+    return entries;
   }
 
   writeFleet(entries: readonly FleetEntry[]): void {
@@ -59,11 +82,11 @@ export class StateStore {
       this.db.run('DELETE FROM fleet');
 
       const insert = this.db.query(
-        'INSERT OR REPLACE INTO fleet (claude_id, name, cwd) VALUES (?1, ?2, ?3)',
+        'INSERT OR REPLACE INTO fleet (claude_id, name, cwd, grp) VALUES (?1, ?2, ?3, ?4)',
       );
 
       for (const entry of all) {
-        insert.run(entry.claudeId, entry.name, entry.cwd);
+        insert.run(entry.claudeId, entry.name, entry.cwd, entry.group ?? null);
       }
     });
 

package/src/ui.ts

@@ -67,6 +67,7 @@ export interface StatusView {
   readonly focusedName: string | null;
   readonly urgentName: string | null;
   readonly leaderLabel: string;
+  readonly stale: boolean;
 }
 
 export function drawStatusBar(view: StatusView) {
@@ -93,6 +94,10 @@ export function drawStatusBar(view: StatusView) {
     parts.push(`✗ ${c.exited}`);
   }
 
+  if (view.stale) {
+    parts.push('⟳ update ready');
+  }
+
   const joined = parts.join(' ▏');
   const right = ` ${joined === '' ? 'idle' : joined} ▏${view.leaderLabel} `;
   const pad = Math.max(1, width - left.length - right.length);
@@ -153,6 +158,7 @@ export interface OverlaySessionView extends SessionView {
   readonly alive: boolean;
   readonly kind: 'pty' | 'jsonl';
   readonly resumable: boolean;
+  readonly group?: string;
 }
 
 export interface OverlayView {
@@ -160,6 +166,7 @@ export interface OverlayView {
   selected: number;
   confirmKill: boolean;
   filter: string | null;
+  stale: boolean;
 }
 
 export function drawOverlay(view: OverlayView) {
@@ -172,15 +179,29 @@ export function drawOverlay(view: OverlayView) {
     rowsList.push(dimRow(width, empty));
   }
 
+  // Sessions cluster under dim headers when more than one group exists: an
+  // explicit group wins, sessions without one fall back to their spawn
+  // directory. The rows keep the sorted order, so urgent groups lead.
+  const grouped = new Set(view.sessions.map((s) => s.group ?? s.cwd)).size > 1;
+  let lastKey: string | null = null;
+
   for (const [i, s] of view.sessions.entries()) {
+    const key = s.group ?? s.cwd;
+
+    if (grouped && key !== lastKey) {
+      lastKey = key;
+
+      rowsList.push(dimRow(width, `▸ ${s.group ?? formatDir(s.cwd)}`));
+    }
+
     const sel = i === view.selected;
     const name = truncate(s.name, 16).padEnd(16);
     const state = STATE_LABEL[s.state].padEnd(9);
-    const dir = truncate(formatDir(s.cwd), 18).padEnd(18);
-    const msgWidth = Math.max(4, width - 4 - 2 - 17 - 10 - 19);
+    const dir = grouped ? '' : ` ${truncate(formatDir(s.cwd), 18).padEnd(18)}`;
+    const msgWidth = Math.max(4, width - 4 - 2 - 17 - 10 - (grouped ? 0 : 19));
     const msg = truncate(s.lastMsg, msgWidth).padEnd(msgWidth);
     const unread = s.unread ? `${ESC}[1;33m!${ESC}[0m` : ' ';
-    const body = `${name} ${state} ${dir} ${msg}`;
+    const body = `${name} ${state}${dir} ${msg}`;
     const styledBody = sel ? `${ESC}[7m${body}${ESC}[0m` : body;
 
     rowsList.push(boxRow(width, `${GLYPH[s.state]}${unread}${styledBody}`, 2 + body.length));
@@ -199,6 +220,10 @@ export function drawOverlay(view: OverlayView) {
 
   let hint = buildOverlayHint(view.sessions[view.selected]);
 
+  if (view.stale) {
+    hint += ' · u update daemon';
+  }
+
   if (view.filter !== null) {
     hint = 'type to filter · ↑↓ move · ⏎ attach · esc clear';
   }
@@ -249,6 +274,7 @@ export function drawHelp() {
 
   const lines = [
     '⏎  attach the selected session',
+    '⇥  attach the most urgent needs-you session',
     'a  ack its notification without attaching',
     'H  eject to a headless run',
     'P  revive a dead or headless session',