@zgeoff/atc 0.1.2 → 0.1.4

package/README.md

@@ -52,6 +52,7 @@ 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
@@ -112,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.2",
+  "version": "0.1.4",
   "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

@@ -26,6 +26,7 @@ export interface DaemonContext {
   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;
@@ -215,6 +216,12 @@ 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;

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));
   }
@@ -409,6 +415,14 @@ 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;
@@ -605,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/index.ts

@@ -4,7 +4,7 @@ import { loadConfig } from './config';
 import { collectDirs, findFuzzyScore, formatDir, pickMatches } from './dirs';
 import type { EventMsg } from './protocol';
 import { isRecord } from './report';
-import { countSessionStates, sortSessionViews } from './sessions';
+import { countSessionStates, sortGroupedSessionViews, sortSessionViews } from './sessions';
 import type { SessionState } from './sessions';
 import { ansi, cols, drawHelp, drawHome, drawOverlay, drawPicker, drawStatusBar, rows } from './ui';
 
@@ -81,6 +81,7 @@ function scheduleStatus() {
         focusedName: focused === null ? null : focused.name,
         urgentName: urgent === undefined ? null : urgent.name,
         leaderLabel: leader.label,
+        stale: daemonStale,
       });
     }
   }, 50);
@@ -194,7 +195,7 @@ function applyHelpKey(buf: Buffer) {
 let overlayFilter: string | null = null;
 
 function pickOverlaySessions(): MirrorSession[] {
-  const sorted = sortSessionViews(fleet);
+  const sorted = sortGroupedSessionViews(fleet);
 
   if (overlayFilter === null || overlayFilter === '') {
     return sorted;
@@ -217,6 +218,7 @@ function renderOverlay() {
     selected: overlaySelected,
     confirmKill,
     filter: overlayFilter,
+    stale: daemonStale,
   });
 
   scheduleStatus();
@@ -227,7 +229,7 @@ function openOverlay() {
   confirmKill = false;
   overlayFilter = null;
 
-  const focusedIndex = sortSessionViews(fleet).findIndex((s) => s.id === focusedID);
+  const focusedIndex = sortGroupedSessionViews(fleet).findIndex((s) => s.id === focusedID);
 
   overlaySelected = Math.max(0, focusedIndex);
 
@@ -727,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 = '';
@@ -883,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);
 
@@ -909,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();
 

package/src/mcp-server.ts

@@ -113,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');
 

package/src/sessions.ts

@@ -613,3 +613,30 @@ export function sortSessionViews<
 
   return [...list].toSorted((a, b) => rank[a.state] - rank[b.state] || a.createdAt - b.createdAt);
 }
+
+// Overlay display order: the urgency sort with each group's sessions pulled
+// together at the position of its most urgent member, so the renderer's
+// adjacency-based headers appear once per group and urgent groups still lead.
+export function sortGroupedSessionViews<
+  T extends {
+    readonly state: SessionState;
+    readonly createdAt: number;
+    readonly group?: string;
+    readonly cwd: string;
+  },
+>(list: readonly T[]): T[] {
+  const buckets = new Map<string, T[]>();
+
+  for (const s of sortSessionViews(list)) {
+    const key = s.group ?? s.cwd;
+    const bucket = buckets.get(key);
+
+    if (bucket === undefined) {
+      buckets.set(key, [s]);
+    } else {
+      bucket.push(s);
+    }
+  }
+
+  return [...buckets.values()].flat();
+}

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);
@@ -161,6 +166,7 @@ export interface OverlayView {
   selected: number;
   confirmKill: boolean;
   filter: string | null;
+  stale: boolean;
 }
 
 export function drawOverlay(view: OverlayView) {
@@ -214,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';
   }