claude-garage 0.3.4 → 0.4.1

package/README.md

@@ -3,16 +3,18 @@
 <img src="docs/banner.png" alt="claude-garage: a pit wall for your Claude Code agents" width="100%" />
 
 **Multiple Claude agents driving you crazy? Park them all in one
-garage.** A needs-input queue that follows you across every project (`a`
-jumps to whoever's waiting), file-by-file diff review, and tmux-owned
-sessions that outlive the tool — reboot the Mac, `tmux attach` still works.
+garage.** A full-screen terminal wall that shows every session at once, a
+needs-input queue that follows you across every project (`a` jumps to
+whoever's waiting), and tmux-owned sessions that outlive the tool — reboot
+the Mac, `tmux attach` still works. A browser wall with file-by-file diff
+review comes along for the ride.
 
 [![npm](https://img.shields.io/npm/v/claude-garage?color=e2a75e&label=npm)](https://www.npmjs.com/package/claude-garage)
 [![license](https://img.shields.io/badge/license-MIT-79b26e)](LICENSE)
 [![node](https://img.shields.io/badge/node-%E2%89%A5%2020-6e9ecc)](package.json)
 [![local](https://img.shields.io/badge/100%25-local-c6cfdb)](#local-only-by-design)
 
-<img src="docs/hero.png" alt="The web wall: two workspaces, a session asking for permission (amber), a finished worktree session, and the diff pane" width="100%" />
+<img src="docs/hero-tui.png" alt="The terminal wall: two workspaces in the rail, four live Claude sessions, one asking for permission (amber), and the status strip with the blocked count" width="100%" />
 
 </div>
 
@@ -70,7 +72,7 @@ and every tmux session running. It's also light: ~5ms input latency, ~2%
 CPU, and a 2.4MB binary (measured on the ratatui port — see
 [`openspec/changes/archive/2026-08-31-p9-ratatui-port/verification.md`](openspec/changes/archive/2026-08-31-p9-ratatui-port/verification.md)).
 
-Since p10–p12, the TUI also groups sessions into views (`d` detaches the
+The TUI also groups sessions into views (`d` detaches the
 focused one into its own view or rejoins it to the default, `D` moves it to
 a chosen group, `Tab` cycles views), shows a dim auto-subtitle under each
 session's label straight from Claude Code's own terminal-title updates (zero
@@ -78,7 +80,9 @@ config), and tracks context pressure: a per-tile meter plus a `5h`/`7-day`
 usage chip in the strip, fed by a one-keypress `I` install of a chaining
 statusline wrapper (any statusline you already have keeps running). Closing
 a plain session tears it down; closing a worktree session keeps its branch
-and points you at the web wall to merge or discard it.
+and points you at the web wall to merge or discard it. `w` adds a project:
+type a path, paste one, drag a folder in from Finder, or press `^O` for the
+macOS folder picker.
 
 **Prefer a browser?**
 
@@ -189,6 +193,39 @@ gets a line like *"water. now. i'm not asking."* (Arthur), *"acceptable."*
 nights, and a usage window running hot, and they never interrupt a session
 that needs you. Set `GARAGE_PET_ASCII=1` if your font lacks `ᴥ`.
 
+## Restarting
+
+Two things go stale under a running wall: the garage daemon itself (after
+a `npm` upgrade) and the `claude` binary inside every session (after
+Anthropic ships a release — Claude Code shows "update available", but a
+running session keeps the old process until it's restarted).
+
+```bash
+claude-garage restart
+```
+
+Restarts the daemon only. Sessions are untouched; the TUI and web wall
+reconnect on their own through the existing SSE reconnect.
+
+```bash
+claude-garage restart --sessions
+```
+
+Restarts the daemon, then respawns every idle/done session in place —
+`tmux respawn-pane -k` running `claude --resume <id>` in the same tmux
+session, so the tile, its title and the conversation all survive. Sessions
+that are `working` or `needs-input` are skipped and listed rather than
+losing an in-flight turn; `--all` restarts those too.
+
+**In the TUI:** `r r` restarts the focused session (press twice — the
+first press warns if it's busy), `r a` restarts every idle/done session
+in the focused workspace, `r d` restarts the daemon. `?` lists all three.
+
+**In the web wall:** the `↻` in a cell's hover controls restarts that
+session, with the same two-click confirmation.
+
+Upgrading the garage package itself is still `npx claude-garage@latest tui`.
+
 ## Keybindings
 
 The TUI's full keymap (`claude-garage tui`, also shown in-app with `?`).
@@ -216,11 +253,15 @@ key mapping (Settings → Profiles → Keyboard) for Shift+Return that sends
 | `R` | restore all restorable sessions in workspace |
 | `I` | install statusline feed for context meters |
 | `x x` | close focused session (press twice) |
+| `r r` | restart focused session — resumes on the current claude binary |
+| `r a` | restart idle/done sessions in workspace |
+| `r d` | restart the daemon (sessions untouched) |
 | `X X` | remove focused workspace (sessions keep running) |
 | `X K` | remove focused workspace AND kill its sessions |
-| `w` | add workspace |
+| `w` | add workspace — type, paste or drag a path in, `^O` opens the folder picker |
 | `d` | detach focused session to its own view, or rejoin main |
 | `D` | move focused session to another view / new group |
+| `P` | cycle the pit pet: Arthur / Papito / Segan / off |
 | `Tab` | cycle the focused workspace's views |
 | `?` | toggle this help |
 | `q` | quit (tmux sessions keep running) |
@@ -258,7 +299,9 @@ npm run build:tui    # cargo build --release; copies the binary into wall/dist
 ```
 
 `wall/` is a separate Rust workspace with its own unit and e2e suites
-(`cd wall && cargo test`; e2e harnesses under `wall/test/e2e`).
+(`cd wall && cargo test --lib --bins` for the unit tests; e2e harnesses under
+`wall/test/e2e`). Plain `cargo test` also runs `tests/injection.rs`, which
+creates and kills scratch sessions on your real tmux server.
 
 Built through spec-driven phases ([`openspec/`](openspec/)), each verified
 end-to-end on a real system.

package/bin/garage.js

@@ -491,8 +491,121 @@ async function tuiMain() {
   });
 }
 
-if (process.argv[2] === "tui") {
+// ---------------------------------------------------------------------------
+// `claude-garage restart` (p16-restart)
+// ---------------------------------------------------------------------------
+
+const JSON_HEADERS = { "content-type": "application/json" };
+
+// D4: same 15s-cap/250ms-poll shape as waitForHealth above, but also
+// requires the answering pid to differ from `previousPid` (undefined counts
+// as "no prior daemon", so any live match immediately satisfies it) AND the
+// version to match this launcher's own — a daemon that hasn't actually
+// swapped yet (still the old process, mid-handoff) must not read as done.
+async function waitForHealthChanged(previousPid, deadlineMs = 15000) {
+  const start = Date.now();
+  while (Date.now() - start < deadlineMs) {
+    const health = await fetchHealth(500);
+    if (health && health.version === VERSION && health.pid !== previousPid) return health;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return null;
+}
+
+// D4/D5: `claude-garage restart --sessions` — POSTs /api/sessions/restart
+// with `{all: true, force: <--all>}` and prints one line per restarted,
+// skipped and failed session, then a summary line.
+async function restartSessionsCLI(force) {
+  const res = await fetch(`http://127.0.0.1:${PORT}/api/sessions/restart`, {
+    method: "POST",
+    headers: JSON_HEADERS,
+    body: JSON.stringify({ all: true, force }),
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    console.error(body.error || `session restart failed (${res.status})`);
+    process.exit(1);
+  }
+
+  for (const r of body.restarted ?? []) {
+    console.log(
+      r.resumed
+        ? `restarted ${r.id} (resumed)`
+        : `restarted ${r.id} (fresh — no conversation to resume)`
+    );
+  }
+  for (const s of body.skipped ?? []) {
+    console.log(`skipped ${s.id} — ${s.status} (use --all to include)`);
+  }
+  for (const f of body.failed ?? []) {
+    console.log(`failed ${f.id} — ${f.error}`);
+  }
+
+  const restartedN = body.restarted?.length ?? 0;
+  const skippedN = body.skipped?.length ?? 0;
+  const failedN = body.failed?.length ?? 0;
+  console.log(`${restartedN} restarted, ${skippedN} skipped, ${failedN} failed`);
+}
+
+// D3/D4: restarts the daemon — via its own self-restart endpoint when one
+// is already healthy (so the in-process successor logic is exercised the
+// same way the TUI's stale-daemon gate exercises stopStaleDaemon), else
+// there's nothing to hand off from, so just start one detached the same way
+// `tui` does when no daemon answers. `--sessions` then restarts every live
+// Claude Code session in place; `--all` also includes busy ones.
+async function restartMain() {
+  const args = process.argv.slice(3);
+  const sessions = args.includes("--sessions");
+  const all = args.includes("--all");
+
+  const before = await fetchHealth();
+  if (before) {
+    const res = await fetch(`http://127.0.0.1:${PORT}/api/daemon/restart`, { method: "POST" });
+    if (!res.ok) {
+      console.error(
+        `daemon restart request failed (${res.status}) — the running daemon ` +
+          `(v${before.version ?? "?"}, pid ${before.pid ?? "?"}) may predate this endpoint; ` +
+          `stop it yourself (lsof -ti tcp:${PORT} | xargs kill) and re-run "claude-garage"`
+      );
+      process.exit(1);
+    }
+    if (!(await waitForHealthChanged(before.pid))) {
+      console.error(
+        `garage daemon did not come back up on port ${PORT} within 15s of restarting`
+      );
+      process.exit(1);
+    }
+  } else {
+    console.log(`no daemon on port ${PORT} — starting one`);
+    startDetachedDaemon();
+    if (!(await waitForHealth())) {
+      console.error(`claude-garage daemon did not come up on port ${PORT}`);
+      process.exit(1);
+    }
+  }
+
+  const after = await fetchHealth();
+  console.log(`garage daemon restarted → v${after.version} (pid ${after.pid})`);
+
+  if (sessions) {
+    // p16-restart follow-up: the daemon now awaits one fresh poll before
+    // planning restart targets whenever any of them has no status entry
+    // yet (exactly the case right after this handoff) — say why there's a
+    // short pause instead of leaving the user staring at silence.
+    console.log("daemon restarted — refreshing session status before restarting sessions");
+    await restartSessionsCLI(all);
+  }
+}
+
+const subcommand = process.argv[2];
+if (subcommand === undefined) {
+  main();
+} else if (subcommand === "tui") {
   tuiMain();
+} else if (subcommand === "restart") {
+  restartMain();
 } else {
-  main();
+  console.error(`unknown subcommand: ${subcommand}`);
+  console.error(`usage: claude-garage [tui|restart [--sessions] [--all]]`);
+  process.exit(1);
 }

package/daemon/src/daemon-restart.js

@@ -0,0 +1,87 @@
+// p16-restart D3: daemon self-restart. POST /api/daemon/restart spawns a
+// detached successor running this same daemon/src/index.js, replies 202
+// with the successor's pid, then closes this daemon and exits — the
+// successor takes the port once this process is gone (see index.js's
+// boot-time waitForPredecessor call and D6's port-handoff-without-a-race
+// requirement).
+import { spawn } from "node:child_process";
+import { mkdirSync, openSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Same daemon.log the launcher's startDetachedDaemon uses (bin/garage.js) —
+// honors GARAGE_DIR (the p8.1 scratch-dir override) so a scratch-port test
+// run never writes into the real ~/.garage.
+function daemonLogPath() {
+  const logDir = process.env.GARAGE_DIR ?? path.join(os.homedir(), ".garage");
+  mkdirSync(logDir, { recursive: true });
+  return path.join(logDir, "daemon.log");
+}
+
+// probe() answers true while the predecessor is still reachable on `port`,
+// false once its /api/health stops answering (port free). A short per-probe
+// timeout keeps a single failed connect from stretching the 200ms poll
+// interval a caller passes below.
+async function defaultProbe(port) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
+      signal: AbortSignal.timeout(500),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+// D3/D6: called at daemon boot when GARAGE_PREDECESSOR_PID is set (see
+// index.js) — polls until the predecessor's health stops answering (the
+// port is free, safe to bind) or `deadlineMs` passes, in which case it
+// throws so the successor fails loud and exits non-zero rather than racing
+// the predecessor for the port. `probe`/`now`/`sleep` are injectable so this
+// is unit-testable without a real daemon or real time (daemon/test/).
+export async function waitForPredecessor({
+  port,
+  pid,
+  probe = () => defaultProbe(port),
+  now = Date.now,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  deadlineMs = 10000,
+} = {}) {
+  const start = now();
+  while (now() - start < deadlineMs) {
+    if (!(await probe())) return;
+    await sleep(200);
+  }
+  throw new Error(
+    `predecessor daemon (pid ${pid}) did not release port ${port} within ${deadlineMs}ms`
+  );
+}
+
+export default async function daemonRestartRoutes(app) {
+  app.post("/api/daemon/restart", async (req, reply) => {
+    // daemon/src/daemon-restart.js -> daemon/src/index.js, same directory.
+    const daemonEntry = path.resolve(
+      path.dirname(fileURLToPath(import.meta.url)),
+      "index.js"
+    );
+    const out = openSync(daemonLogPath(), "a");
+    const child = spawn(process.execPath, [daemonEntry], {
+      detached: true,
+      stdio: ["ignore", out, out],
+      // GARAGE_PREDECESSOR_PID tells the successor which pid to wait out
+      // before it binds the port (see waitForPredecessor / index.js).
+      env: { ...process.env, GARAGE_PREDECESSOR_PID: String(process.pid) },
+    });
+    child.unref();
+
+    await reply.code(202).send({ pid: child.pid });
+    // The reply must flush to the socket before this process tears itself
+    // down — deferred to the next tick so Fastify's write actually reaches
+    // the client first (D3).
+    setImmediate(async () => {
+      await app.close();
+      process.exit(0);
+    });
+  });
+}

package/daemon/src/index.js

@@ -13,6 +13,7 @@ import notifyRoutes from "./notify.js";
 import diffRoutes from "./diff.js";
 import editorRoutes from "./editor.js";
 import worktreeRoutes from "./worktrees.js";
+import daemonRestartRoutes, { waitForPredecessor } from "./daemon-restart.js";
 import { attachTermServer } from "./term.js";
 import { rejectForeignOrigins } from "./security.js";
 import { startPoller } from "./poller.js";
@@ -45,6 +46,7 @@ app.register(notifyRoutes);
 app.register(diffRoutes);
 app.register(editorRoutes);
 app.register(worktreeRoutes);
+app.register(daemonRestartRoutes);
 attachTermServer(app);
 
 // D-packaging: flag-gated so dev mode (Vite on :5173 proxying to this
@@ -71,15 +73,38 @@ app.addHook("onClose", async () => {
   stopPoller();
 });
 
-app.listen({ host: HOST, port: PORT }).catch((err) => {
-  if (err.code === "EADDRINUSE") {
-    app.log.error(
-      `port ${PORT} is already in use — set GARAGE_PORT to choose a different port`
-    );
-  } else {
+// p16-restart D3/D6: a successor spawned by POST /api/daemon/restart carries
+// GARAGE_PREDECESSOR_PID — wait for that pid's /api/health to stop answering
+// (port free) before binding it, so the handoff never races two daemons for
+// one port. Fails loud (non-zero exit, listen() never called) if the
+// predecessor doesn't let go within 10s, naming the port and pid — see
+// daemon-restart.js. `readyToListen` (rather than exiting straight from the
+// catch below) keeps this a single, unambiguous control-flow path down to
+// exactly one of listen() or process.exit(1) — never both.
+let readyToListen = true;
+if (process.env.GARAGE_PREDECESSOR_PID) {
+  await waitForPredecessor({
+    port: PORT,
+    pid: Number(process.env.GARAGE_PREDECESSOR_PID),
+  }).catch((err) => {
     app.log.error(err);
-  }
+    readyToListen = false;
+  });
+}
+
+if (readyToListen) {
+  app.listen({ host: HOST, port: PORT }).catch((err) => {
+    if (err.code === "EADDRINUSE") {
+      app.log.error(
+        `port ${PORT} is already in use — set GARAGE_PORT to choose a different port`
+      );
+    } else {
+      app.log.error(err);
+    }
+    process.exit(1);
+  });
+} else {
   process.exit(1);
-});
+}
 
 export { app };

package/daemon/src/poller.js

@@ -127,7 +127,15 @@ export function diffSessionState(sessions, panePids, hostname, prevIds, prevTitl
   return { changed, ids: currentIds, titles };
 }
 
-async function tick() {
+// p16-restart follow-up: renamed from `tick` (body unchanged) and split so
+// a route (POST /api/sessions/restart) can `await pollOnce(app)` for one
+// fresh poll — e.g. right after a restarted daemon boots with an empty
+// status store, planning off getStatus's "idle" default would be wrong
+// (status.js's hasStatus). `pollOnce` catches internally and logs via
+// `app` exactly like startPoller's interval always has, so it never
+// rejects — a caller awaiting it never needs its own try/catch, and
+// startPoller's own error-logging shape is preserved unchanged below.
+async function pollBody() {
   const sessions = await listSessions().catch(() => []);
 
   if (sessions.length === 0) {
@@ -192,9 +200,17 @@ async function tick() {
   }
 }
 
+export async function pollOnce(app) {
+  try {
+    await pollBody();
+  } catch (err) {
+    app?.log?.warn?.({ err }, "poller tick failed");
+  }
+}
+
 export function startPoller(app) {
   const timer = setInterval(() => {
-    tick().catch((err) => app?.log?.warn?.({ err }, "poller tick failed"));
+    pollOnce(app);
   }, POLL_MS);
   timer.unref?.();
   return () => clearInterval(timer);

package/daemon/src/sessions.js

@@ -11,6 +11,7 @@ import {
   hasSession,
   createSession,
   killSession,
+  respawnPane,
 } from "./tmux.js";
 import {
   getWorkspace,
@@ -19,13 +20,91 @@ import {
   upsertSessionMeta,
   removeSessionMeta,
 } from "./registry.js";
-import { getStatusEntry } from "./status.js";
+import { getStatusEntry, getStatus, hasStatus, dropSession as dropStatus } from "./status.js";
+import { dropSession as dropStatuslineContext } from "./statusline.js";
+import { pollerEvents, pollOnce } from "./poller.js";
 import { createWorktree } from "./worktrees.js";
 import { getStatuslineContext, getRateLimits } from "./statusline.js";
 import { getCachedContext, refreshContext } from "./transcript.js";
 
 const CLAUDE_CMD = process.env.GARAGE_CLAUDE_CMD ?? "claude";
 
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// D-restore-flow / p16-restart D1: shared by restore (spawn === createSession,
+// a fresh tmux session) and restart (spawn === respawnPane, the SAME tmux
+// session) — both need "start `claude --resume <claudeSessionId>`, then
+// confirm it didn't immediately die". `claude --resume` exits (after
+// printing "No conversation found") when the conversation was never
+// persisted — a session with no submitted exchange — killing the pane/
+// session it just started. The exit isn't instant, so confirm twice before
+// trusting the resume; if it died, or there was no claudeSessionId to resume
+// in the first place (p16-restart out-of-scope note: a fresh session that
+// never wrote a transcript), fall back to a plain `claude` and report
+// `resumed: false` rather than silently defaulting a required value.
+// `spawn` takes the same (id, dir, command, extraArgs) shape createSession
+// and respawnPane already share.
+// Exported alongside planRestartTargets so the missing-claudeSessionId
+// branch (no tmux call at all — it never reaches hasSession) is
+// unit-testable with a fake `spawn`, same discipline as the target-
+// selection tests below (daemon/test/restart.test.js).
+export async function spawnClaudeResumed(spawn, id, dir, claudeSessionId) {
+  if (!claudeSessionId) {
+    await spawn(id, dir, CLAUDE_CMD);
+    return false;
+  }
+
+  await spawn(id, dir, CLAUDE_CMD, ["--resume", claudeSessionId]);
+
+  await sleep(1500);
+  if (await hasSession(id)) {
+    await sleep(2000);
+  }
+  if (await hasSession(id)) {
+    return true;
+  }
+
+  await spawn(id, dir, CLAUDE_CMD);
+  return false;
+}
+
+// p16-restart D2: pure target-selection step for POST /api/sessions/restart
+// — no tmux/IO, so it's exhaustively unit-testable without a live tmux
+// server (daemon/test/restart.test.js). `sessions` is the already-scoped
+// candidate list ({id, status} — either the one requested id or every live
+// session for {all:true}); busy sessions (`working`/`needs-input`) are
+// skipped unless `force`. p16-restart follow-up: a status of "unknown"
+// (the route's stand-in for "the poller has never observed this id" — see
+// hasStatus/needsPollBeforePlan below) is treated the same way — never
+// silently planned as if it were idle (D6: never default a required
+// value). Exported for the test suite.
+export function planRestartTargets(sessions, force) {
+  const targets = [];
+  const skipped = [];
+  for (const s of sessions) {
+    const busy = s.status === "working" || s.status === "needs-input" || s.status === "unknown";
+    if (!force && busy) {
+      skipped.push({ id: s.id, status: s.status });
+    } else {
+      targets.push(s.id);
+    }
+  }
+  return { targets, skipped };
+}
+
+// p16-restart follow-up: pure decision — should the restart route await one
+// fresh poll (pollOnce) before planning? Yes whenever ANY id in `ids` has no
+// status entry yet (`hasStatusFn` is status.js's `hasStatus`, injected so
+// this is unit-testable without the real store). This is exactly the
+// window right after `claude-garage restart` hands off to a fresh successor
+// daemon: its status store is empty, so getStatus(id) would silently read
+// "idle" for a session that is actually mid-turn (status.js docs this
+// default deliberately) — planning off that default would restart a
+// `working` session without `force`.
+export function needsPollBeforePlan(ids, hasStatusFn) {
+  return ids.some((id) => !hasStatusFn(id));
+}
+
 export default async function sessionRoutes(app) {
   app.get("/api/sessions", async () => {
     const sessions = await listSessions();
@@ -220,8 +299,6 @@ export default async function sessionRoutes(app) {
       targets = [meta];
     }
 
-    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-
     // Targets are independent — restore them concurrently so the
     // died-on-resume confirmation waits below don't serialize restore-all.
     const results = await Promise.all(
@@ -247,25 +324,12 @@ export default async function sessionRoutes(app) {
           return { failed: { id: meta.id, reason: "session already running" } };
         }
 
-        await createSession(meta.id, spawnDir, CLAUDE_CMD, [
-          "--resume",
-          meta.claudeSessionId,
-        ]);
-
-        // `claude --resume` exits (after printing "No conversation found")
-        // when the conversation was never persisted — a session with no
-        // submitted exchange — killing the new tmux session and leaving a
-        // restore loop. The exit isn't instant, so confirm twice before
-        // trusting the resume; if it died, fall back to a fresh claude.
-        let resumed = true;
-        await sleep(1500);
-        if (await hasSession(meta.id)) {
-          await sleep(2000);
-        }
-        if (!(await hasSession(meta.id))) {
-          resumed = false;
-          await createSession(meta.id, spawnDir, CLAUDE_CMD);
-        }
+        const resumed = await spawnClaudeResumed(
+          createSession,
+          meta.id,
+          spawnDir,
+          meta.claudeSessionId
+        );
 
         return {
           restored: {
@@ -287,6 +351,103 @@ export default async function sessionRoutes(app) {
     return reply.code(status).send({ restored, failed });
   });
 
+  // p16-restart: restart every LIVE session matching {id}, or every live
+  // session for {all:true}, in place — tmux respawn-pane (D1), not
+  // kill+restore, so the tmux session identity (and everything keyed off
+  // it: the wall tile, dockview panel, title) survives. Restorable
+  // (non-live) sessions are never targets — they have no pane to respawn;
+  // restore them via /api/sessions/restore instead. `force` restarts a
+  // working/needs-input session anyway; without it those land in `skipped`
+  // (D2) rather than losing an in-flight turn.
+  app.post("/api/sessions/restart", async (req, reply) => {
+    const { id, all, force } = req.body ?? {};
+    if (!id && !all) {
+      return reply.code(400).send({ error: "must provide id or all:true" });
+    }
+
+    const liveSessions = await listSessions();
+    if (id && !liveSessions.some((s) => s.id === id)) {
+      return reply.code(404).send({ error: `no live session: ${id}` });
+    }
+    const scoped = id ? liveSessions.filter((s) => s.id === id) : liveSessions;
+
+    // p16-restart follow-up: getStatus defaults an unobserved id to "idle"
+    // (by design — every other caller wants that safe default), which is
+    // wrong here right after a fresh successor daemon boots with an empty
+    // status store (claude-garage restart, D3) — every session would look
+    // idle and a `working` one would restart without `force`. Await one
+    // real poll first whenever that's the situation, so planning below
+    // reads real signal instead of the default.
+    if (needsPollBeforePlan(scoped.map((s) => s.id), hasStatus)) {
+      await pollOnce(app);
+    }
+
+    const candidates = scoped.map((s) => ({
+      id: s.id,
+      // Still unobserved even after the poll (claude CLI missing, pid join
+      // failed, ...) — "unknown", never silently defaulted to idle; see
+      // planRestartTargets.
+      status: hasStatus(s.id) ? getStatus(s.id) : "unknown",
+    }));
+
+    const { targets, skipped } = planRestartTargets(candidates, Boolean(force));
+
+    const liveById = new Map(liveSessions.map((s) => [s.id, s]));
+    const metas = await listSessionMetas();
+    const metaById = new Map(metas.map((m) => [m.id, m]));
+
+    // Targets are independent — restart them concurrently, same discipline
+    // as restore-all above. A tmux failure (respawnPane rejects with tmux's
+    // stderr) is caught here and reported per-target in `failed`, rather
+    // than letting one bad target take down the rest of the batch.
+    const results = await Promise.all(
+      targets.map(async (targetId) => {
+        const live = liveById.get(targetId);
+        const meta = metaById.get(targetId);
+        try {
+          // Same dir resolution restore uses (D-wt-meta): the worktree
+          // path when this is a worktree session, else the registered
+          // workspace dir — falling back to the live tmux dir only when
+          // the session predates any registry meta (a fresh session the
+          // poller hasn't observed yet).
+          const registered = await getWorkspace(live.workspace);
+          const dir = meta?.worktree?.path ?? registered?.dir ?? live.dir;
+
+          const resumed = await spawnClaudeResumed(
+            respawnPane,
+            targetId,
+            dir,
+            meta?.claudeSessionId ?? null
+          );
+
+          // The pane now runs a fresh claude process (a new pid) — the
+          // status the poller had for the OLD process (working/done/
+          // needs-input) no longer describes anything. Clear it the same
+          // way the poller's own dropSession does for a dead session, so
+          // the next tick's pid-join re-derives the real state instead of
+          // carrying stale signal forward.
+          dropStatus(targetId);
+          dropStatuslineContext(targetId);
+
+          return { restarted: { id: targetId, resumed } };
+        } catch (err) {
+          return { failed: { id: targetId, error: err.message } };
+        }
+      })
+    );
+
+    const restarted = results.filter((r) => r.restarted).map((r) => r.restarted);
+    const failed = results.filter((r) => r.failed).map((r) => r.failed);
+
+    // respawn-pane never changes the tmux session-id set the poller diffs
+    // on (same session, new process), so the poller's own "sessions-changed"
+    // detection never fires for a restart — push it explicitly so the wall
+    // refetches promptly instead of waiting on an unrelated event.
+    if (restarted.length > 0) pollerEvents.emit("sessions-changed");
+
+    return reply.code(200).send({ restarted, skipped, failed });
+  });
+
   // id contains slashes — capture the whole tail as a wildcard.
   app.delete("/api/sessions/*", async (req, reply) => {
     const id = decodeURIComponent(req.params["*"]);