agent-dag 3.19.0 → 3.21.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# ccdeck
+# ccdeck — a live dashboard for Claude Code and Codex
 
 **Know which agent is waiting on you, and for how long.**
 
@@ -22,7 +22,7 @@ npx ccdeck
 
 who is blocked on you · tool calls · one canvas · cost · quota · local · no telemetry
 
-[What you get](#what-you-get) · [Quick start](#quick-start) · [How it works](#how-it-works) · [What it touches](#what-it-touches) · [Accounts](#accounts) · [Options](#options)
+[What you get](#what-you-get) · [Quick start](#quick-start) · [How it works](#how-it-works) · [What it touches](#what-it-touches) · [Accounts](#accounts) · [Local network](#local-network) · [Options](#options) · [FAQ](#questions-people-ask)
 
 
 </div>
@@ -43,6 +43,43 @@ ccdeck draws the tree instead. It is local and needs no configuration: it regist
 
 One canvas. No tabs. No kanban.
 
+The deck opens on these eight pictures the first time it runs — they are the whole tour, and `Take the tour` on an empty canvas brings them back.
+
+<table>
+<tr>
+<td><img src="assets/guide/welcome-1.svg" width="440" alt="Sessions waiting on you rise to the top, longest wait first."></td>
+<td><img src="assets/guide/welcome-2.svg" width="440" alt="Every agent and subagent is a node. Tool calls light up as they run."></td>
+</tr>
+<tr>
+<td align="center"><sub>Sessions waiting on you rise to the top, longest wait first.</sub></td>
+<td align="center"><sub>Every agent and subagent is a node. Tool calls light up as they run.</sub></td>
+</tr>
+<tr>
+<td><img src="assets/guide/welcome-3.svg" width="440" alt="Click any node: its prompt, every tool call, tokens and timing."></td>
+<td><img src="assets/guide/welcome-4.svg" width="440" alt="What each session costs, and how much quota is left."></td>
+</tr>
+<tr>
+<td align="center"><sub>Click any node: its prompt, every tool call, tokens and timing.</sub></td>
+<td align="center"><sub>What each session costs, and how much quota is left.</sub></td>
+</tr>
+<tr>
+<td><img src="assets/guide/welcome-5.svg" width="440" alt="Cores, memory and heat while the agents run, and what is hogging them."></td>
+<td><img src="assets/guide/welcome-6.svg" width="440" alt="Several Claude accounts: switch, add one, share one to another machine."></td>
+</tr>
+<tr>
+<td align="center"><sub>Cores, memory and heat while the agents run, and what is hogging them.</sub></td>
+<td align="center"><sub>Several Claude accounts: switch, add one, share one to another machine.</sub></td>
+</tr>
+<tr>
+<td><img src="assets/guide/welcome-7.svg" width="440" alt="Your machines repair each other's expired logins over the local network."></td>
+<td><img src="assets/guide/welcome-8.svg" width="440" alt="Run claude or codex in any folder. It shows up here on its own."></td>
+</tr>
+<tr>
+<td align="center"><sub>Your machines repair each other's expired logins over the local network.</sub></td>
+<td align="center"><sub>Run <code>claude</code> or <code>codex</code> in any folder. It shows up here on its own.</sub></td>
+</tr>
+</table>
+
 | | |
 |---|---|
 | **Blocked on you** | A permission prompt, or a finished turn waiting for your next instruction, sorts that session to the top of the sidebar with how long it has been stuck — longest wait first, so the oldest block is the first row. A permission prompt also puts a count in the topbar that jumps straight to it. Claude Code only — Codex emits no such signal. |
@@ -52,6 +89,7 @@ One canvas. No tabs. No kanban.
 | **Click to inspect** | Any node opens its prompt, tool calls, token usage and timing. |
 | **Survives restarts** | Events are appended to `~/.claude/agent-dag/events.jsonl` and replayed on open. |
 | **Accounts without a terminal** | Sign a new Claude account in, move one or your whole set to another machine, rename, reorder, remove — from the panel. |
+| **Logins that repair each other** | A Claude login that expires on one of your machines is copied back from another machine on the same network that still has it — see [Local network](#local-network). |
 | **Knows when it is stale** | Node caches modules at startup, so an upgraded-while-running deck keeps executing old code. This one says so, and can restart itself when nothing is running. |
 | **Workspace scoping** | `--scope` for the current directory, `--workspace <path>` for any subtree — for Claude Code and Codex alike. |
 
@@ -61,7 +99,12 @@ One canvas. No tabs. No kanban.
 npx ccdeck          # or: npx agents-deck · npx agent-dag — same deck
 ```
 
-Opens **http://127.0.0.1:4317** and registers the Claude Code hook on first run. If something else already holds 4317, the deck takes a port between 4318 and 4400 instead and prints the address it ended up on — that line in the terminal is the one to trust. Start any Claude Code or Codex session and the graph fills in live. `Ctrl+C` stops it.
+Opens **http://127.0.0.1:4317**, shows an eight-picture tour the first time, and registers the Claude Code hook on first run. If something else already holds 4317, the deck takes a port between 4318 and 4400 instead and prints the address it ended up on — that line in the terminal is the one to trust. Start any Claude Code or Codex session and the graph fills in live.
+
+The deck keeps running after you close the terminal, and starts again when you
+log in. **`ccdeck --stop` is the off switch**; `Ctrl+C` only cancels a start that
+is still printing. `ccdeck --status` says what is running, and `--foreground`
+holds the terminal the way every version before 3.20 did.
 
 No config file. No account. No telemetry — nothing about your sessions is reported anywhere.
 
@@ -158,6 +201,37 @@ An import adds what is missing and leaves a working account exactly as it is. Th
 
 Renaming, reordering and removing are on the same row menu. Removal takes two clicks and cannot be undone.
 
+## Local network
+
+A Claude login expires on the machine that has not used it for a while, and stays alive on the one that has. With two or three machines that is a `claude login` a week, each time on the machine you are not sitting at. **Local network** is the last section of the Claude accounts panel, and it is that chore done for you: decks on one network find each other, pair, and a login that has expired on one is copied back from another that still has it.
+
+Four pictures, which are also the guide the section opens from `See how it works`:
+
+<table>
+<tr>
+<td><img src="assets/guide/lan-1.svg" width="440" alt="A login can expire on one machine while it still works on another."></td>
+<td><img src="assets/guide/lan-2.svg" width="440" alt="Turn this on, on both machines. They find each other and pair."></td>
+</tr>
+<tr>
+<td align="center"><sub><b>1.</b> A login can expire on one machine while it still works on another.</sub></td>
+<td align="center"><sub><b>2.</b> Turn this on, on both machines. They find each other and pair.</sub></td>
+</tr>
+<tr>
+<td><img src="assets/guide/lan-3.svg" width="440" alt="Tick which logins this machine may hand out. Nothing is shared until you do."></td>
+<td><img src="assets/guide/lan-4.svg" width="440" alt="An expired login is copied from a paired machine within a minute."></td>
+</tr>
+<tr>
+<td align="center"><sub><b>3.</b> Tick which logins this machine may hand out. Nothing is shared until you do.</sub></td>
+<td align="center"><sub><b>4.</b> An expired login is copied from a paired machine within a minute.</sub></td>
+</tr>
+</table>
+
+**On each machine, in order:** open the Claude accounts panel (`A`), switch **Local network** on, and in the dialog that opens tick the logins this machine may hand out. That is all — the two decks find each other over a UDP beacon on port 45317, pair on their own, and from then on every paired deck is asked once a minute for anything this deck's expired logins need.
+
+**When they do not find each other** — a VPN, a guest network, two subnets — `+` at the top of the section reaches a deck by address, or with an invite the other deck minted. An invite is the route when the machine that cannot be seen is this one.
+
+**What is shared, and with whom.** Nothing until you tick a login, and then only that login, and only with decks somebody at this machine accepted — the deck asks the machines it finds and says yes to the ones that ask, and both switches are in the same dialog if you would rather press `accept` yourself. A paired deck can fill an *expired* slot of this deck's and nothing else: it cannot overwrite a login that still works here. What crosses the wire is the same live credential a share carries, sealed to the deck it is addressed to, so treat the pairing decision as the moment that matters. Unpairing stops future rounds; a login already copied stays where it went.
+
 ## Options
 
 ```
@@ -165,11 +239,22 @@ ccdeck [options]
 
   -p, --port <number>      Preferred port  (default: 4317; fallback: random 4318–4400)
       --no-open            Don't open the browser automatically
+      --foreground         Hold the terminal, the way every version before 3.20
+                           did (Ctrl+C stops the deck again)
+      --new                Start a second deck even if one is already running
+      --stop               Stop the deck a bare `ccdeck` would open
+                           (--port <n> stops that one; --all stops every deck)
+      --status             What is running on this machine, and on which ports
+      --logs               What a backgrounded deck wrote where a terminal would
+                           have shown it
       --workspace <path>   Only capture sessions whose cwd is inside <path>
       --scope              Restrict to the current working directory
       --all                Capture every session on this machine  (default)
+                           (beside --stop: every deck, not every session)
       --history <path>     Override the events log file
-                           (default: ~/.claude/agent-dag/events.jsonl)
+                           (default: this platform's log directory —
+                           ~/Library/Logs/ccdeck on macOS, %LOCALAPPDATA%\ccdeck\Log
+                           on Windows, $XDG_STATE_HOME/ccdeck on Linux)
       --no-persist         RAM-only mode — don't write or replay the log
       --codex              Force Codex capture even if ~/.codex/ is missing
       --no-codex           Skip Codex capture (Claude only)
@@ -185,6 +270,57 @@ Anything else on the command line is reported as an unknown option and then
 ignored — the deck still starts, so a typo costs you a warning rather than a
 dashboard.
 
+`--foreground` is there for anything that was relying on the old behaviour — a
+wrapper script, a CI step, a supervisor of your own that starts the deck and
+waits on it. On the first run after upgrading you may also see a line about a
+deck from an older version still running: those publish nothing this one can
+check, so it starts beside them rather than attaching to something it cannot
+identify, and `ccdeck --stop --all` clears them.
+
+`ccdeck` runs in the background. The boot report prints in your terminal exactly
+as it always has — the hooks, the port, the URL — and then the prompt comes back
+and the deck stays up: closing the window does not take it with you any more,
+because it is in its own process group and the terminal's hangup never reaches
+it. `ccdeck --stop` ends it, `ccdeck --status` says what is running, and
+`ccdeck --logs` shows what it wrote after you stopped watching. Ctrl+C while the
+boot is still printing cancels the start, which is the one thing it still means.
+
+One Windows exception, and it is `ssh`'s rather than the deck's: OpenSSH puts a
+session's processes in a job object that it kills when the session ends, and
+nothing started from inside one survives it. A deck started from an ordinary
+Windows terminal, or by the login task below, keeps running — measured on a real
+machine, from a second SSH session, still serving.
+
+It also starts when you log in, so a reboot does not cost you the morning's
+events. That is set up once, on the first run, and said out loud when it happens;
+`ccdeck --uninstall-service` undoes it and `ccdeck --uninstall` takes it with the
+hooks. A launchd agent on macOS, a `systemd --user` unit on Linux, a Task
+Scheduler logon task on Windows — none of them carrying a restart policy of its
+own, because the one that decides when a crashed deck stops coming back lives in
+ccdeck and two policies over one process is how a stop becomes a suggestion. An
+`npx` run never installs one: it would name a path inside npm's cache, which npm
+deletes without warning. On Linux, `systemd --user` is torn down at logout unless
+`loginctl enable-linger` is on for your account — the install says so rather than
+changing that for you.
+
+If the deck falls over on its own, it comes back — five times in ten minutes,
+with the wait doubling each time, and then it stops and says so in the log rather
+than spinning on a machine nobody is watching. A clean `--stop` is never answered
+with a restart, and neither is a deck that failed to start in the first place:
+retrying a port the OS will not give you just prints the same refusal six times.
+
+Typing plain `ccdeck` beside a deck that is already running opens **that deck's
+tab** rather than building a second one. It used to build the second one: port
+4317 was busy, so the new deck took a random port out of 4318–4400 and stood
+there beside a perfectly healthy first one, and neither mentioned the other.
+The port fallback is still there — 4317 is also the standard OTLP collector
+port, and Windows reserves whole TCP ranges for Hyper-V, WSL2 and Docker — but
+it now runs only when the thing holding the port is *not* one of your decks. The
+deck on the port has to prove it is yours, with the same token handshake the
+hooks use, before its tab is opened. Any flag that changes what the deck **is**
+— a port, a workspace, a log, either `--codex` or `--claude` pair — still starts
+its own, and `--new` starts one unconditionally.
+
 ccdeck looks for each CLI before it does anything on that CLI's behalf. Claude
 Code counts as present when its binary is on `PATH` (or in one of the places its
 installers put it), or when its config dir carries traces of having been used;
@@ -225,7 +361,7 @@ Being told to restart after an upgrade is local only — no network involved —
 npx ccdeck --uninstall
 ```
 
-Removes every hook entry ccdeck injected from `~/.claude/settings.json`, and `~/.codex/hooks.json` if present.
+Removes every hook entry ccdeck injected from `~/.claude/settings.json`, and `~/.codex/hooks.json` if present — and the login item, if this machine had one. That one exception to the narrowness below is deliberate: a login item left behind would keep starting a deck whose hooks had just been removed.
 
 It removes the hook entries and nothing else. The forwarder script
 (`~/.claude/agent-dag/hook.js`), the discovery directory around it, the events
@@ -253,7 +389,7 @@ Nothing is ever installed unless you click, the argument vector is fixed in the
 
 ### Restarting
 
-ccdeck runs as a two-process pair: a supervisor that owns nothing but the lifecycle, and the deck itself. When newer code is found, the deck exits with code 75 and the supervisor brings it back **on the port it actually bound**, which is not always the one it asked for. Ctrl+C, stdout and exit codes behave exactly as before — same terminal, same process group.
+ccdeck runs as a two-process pair: a supervisor that owns nothing but the lifecycle, and the deck itself. When newer code is found, the deck exits with code 75 and the supervisor brings it back **on the port it actually bound**, which is not always the one it asked for. Both live in their own process group since 3.20, so stdout goes to `deck.log` rather than to the terminal you started from — `ccdeck --logs` reads it back. The supervisor also puts the deck back after a crash, five times in ten minutes with the wait doubling, and then stops and says why rather than spinning.
 
 It restarts on its own only after 30 seconds with nothing running, because hook events are fire-and-forget and anything fired during the gap is lost. The toggle in the banner turns that off; the preference is per-browser. Under `--no-persist` a restart is refused outright — with no event log there is nothing to replay, and the canvas would be gone.
 
@@ -287,6 +423,40 @@ It is now the same build as the other two.
 The repository was previously named `agents-deck`; the old URL redirects here,
 so existing clones, links and bookmarks keep working.
 
+## Questions people ask
+
+**Does it work with Codex, or only Claude Code?**
+Both, on one canvas. Claude Code arrives through a hook, Codex through its
+rollout log, and the model chip tells them apart. The *blocked on you* queue is
+Claude Code only — Codex emits no signal for it.
+
+**Does anything leave my machine?**
+Your sessions, never. The deck binds `127.0.0.1` and has no telemetry. The only
+outbound requests are a ~20-byte version check to the npm registry at most once
+an hour, and whatever the usage panels ask Anthropic and OpenAI for about your
+own quota. [What it touches](#what-it-touches) lists all of it.
+
+**Can it interfere with what my agent does?**
+No. The hook it installs is a one-way forwarder: it POSTs the event, exits `0`,
+and writes nothing to stdout — the two channels Claude Code's hook protocol
+gives a hook for allowing, denying or rewriting a tool call. It uses neither, so
+it has no way to answer at all, and a test pins both halves.
+
+**Does it need an account, an API key or a config file?**
+None of the three. `npx ccdeck` and it runs.
+
+**macOS, Linux, Windows?**
+All three, and each release is tested on all three.
+
+**What is the difference between `ccdeck`, `agents-deck` and `agent-dag`?**
+One deck, three names on npm. `ccdeck` is the one to use; the other two are the
+names it shipped under before, kept working so nobody's command breaks. See
+[Names](#names).
+
+**Do I have to keep a terminal open?**
+No. Since 3.20 the deck runs in the background, survives the terminal closing,
+and starts again when you log in. `ccdeck --stop` ends it.
+
 ## License
 
 MIT © [Bargan Constantin](https://github.com/BarganConstantin)

package/bin/agent-dag.js

@@ -37,13 +37,19 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { killTree } from "../src/server/exec.mjs";
 import { invokedAs } from "../src/server/invoked-as.mjs";
+import { isOneShot, parseArgs } from "../src/server/args.mjs";
 import { npxFailureHint, npxFailureSummary, npxLaunch, npxPrefetch } from "../src/server/npx.mjs";
 import {
   bareSpecName, claimRestartFailureKey, clearRestartFailure, installedName, installedVersion,
-  lastKnownLatest, npxRestartSpec, readRestartFailure, recordRestartFailure, successorRoot,
+  isNpxInstall, lastKnownLatest, npxRestartSpec, readRestartFailure, recordRestartFailure,
+  successorRoot,
 } from "../src/server/self-update.mjs";
-import { dieOfSignal, dieWithParent, replacedNote, upgradeAttempt, upgradeRefusalText, workerExitAction } from "../src/server/supervisor.mjs";
-import { colorProfile, glyphs, palette, unicodeOK } from "../src/server/term.mjs";
+import {
+  CRASH_CEILING, CRASH_WINDOW_MS, crashPolicy, dieOfSignal, dieWithParent, isCrash, replacedNote,
+  upgradeAttempt, upgradeRefusalText, workerExitAction,
+} from "../src/server/supervisor.mjs";
+import { colorProfile, glyphs, palette, termColumns, unicodeOK } from "../src/server/term.mjs";
+import { DETACHED_ENV, detachAndWatch, stopCommand } from "../src/server/detach.mjs";
 import { PRODUCT } from "../src/server/brand.mjs";
 
 const BIN_DIR = dirname(fileURLToPath(import.meta.url));
@@ -77,6 +83,72 @@ const G = glyphs(unicodeOK());
 // update reported someone else's failed npx as its own. Our pid is unique among
 // the decks alive on the machine, and putting it in our own environment is what
 // carries it to the worker: launch() spawns with a copy of it.
+// ── the terminal stops being the deck's leash ────────────────────────────────
+//
+// Everything about why is in src/server/detach.mjs. Here is only the decision,
+// and it has exactly two ways out:
+//
+//   ALREADY DETACHED — we ARE the background copy. Carry on as this file always
+//   has: spawn the worker, supervise it, never come back here.
+//
+//   A ONE-SHOT — `--version`, `--stop`, `--status`, `--help`, `--uninstall`.
+//   Those answer and leave, and a one-shot that detached would print its answer
+//   into a log file and hand the terminal back empty. They run in the
+//   foreground exactly as they always have.
+//
+// Anything else is a start, and a start goes to the background.
+const DETACHED = process.env[DETACHED_ENV] === "1";
+// A parent already holding our lifecycle. `process.send` exists only when
+// somebody spawned us with an IPC channel, and that somebody has armed
+// dieWithParent below and is waiting on our exit code — running away from them
+// into our own process group is precisely the wrong answer to being supervised.
+// The suite's spawnSupervised is the caller that does this today.
+const LEASHED = typeof process.send === "function";
+// And the way to ask for the old behaviour out loud.
+//
+// Every version before this one held the terminal, and something out there
+// depends on that: a wrapper script, a CI step, a supervisor of somebody else's
+// that starts `ccdeck` and waits on it, a `ccdeck && open …`. Handing all of
+// those an immediate exit and no way to say otherwise would be a breaking change
+// with no escape hatch — and the marker above is an internal one, not something
+// to tell a user to export.
+const FLAGS = parseArgs(process.argv.slice(2));
+if (!DETACHED && !LEASHED && FLAGS.foreground !== true && !isOneShot(FLAGS)) {
+  const { deckLogDir } = await import("../src/server/deck-home.mjs");
+  const { registeredDecks } = await import("../src/server/running-deck.mjs");
+  const isTTY = Boolean(process.stdout.isTTY);
+  const profile = colorProfile({ isTTY });
+  const tone = palette(profile);
+  const npx = isNpxInstall(PKG_ROOT);
+  const stop = stopCommand({ npx, invokedAs: INVOKED_AS, product: PRODUCT });
+  // THE ONE THING AN NPX RUN CANNOT HAVE, said where it is missing. A login item
+  // must name a path that will still be there tomorrow, and npx runs out of a
+  // cache npm deletes whenever it likes — so an npx deck runs in the background
+  // and cannot come back after a reboot. One line, no disk written, offered
+  // rather than done: `npx` means "run without installing", and a tool that
+  // installs itself anyway is the one people uninstall.
+  const offer = npx
+    ? `     ${tone.muted}\`${INVOKED_AS ?? PRODUCT} --install\` also starts it at login${tone.reset}\n`
+    : "";
+  const outcome = await detachAndWatch({
+    file: fileURLToPath(import.meta.url),
+    argv: process.argv.slice(2),
+    logDir: deckLogDir(),
+    // Only the count, and only to decide whether deck.log is anybody's — see
+    // logMode. No handshake: this is a directory listing and a signal-0 each.
+    liveCount: (await registeredDecks().catch(() => [])).length,
+    isTTY,
+    profile,
+    columns: termColumns(process.stdout),
+    backgroundLine: `  ${tone.muted}${G.dash}  running in the background ${G.bullet} \`${stop}\` ends it${tone.reset}\n${offer}\n`,
+  });
+  // detachAndWatch never returns on the paths that worked. Reaching this line
+  // means the log could not be opened at all — a read-only home, a full disk —
+  // and a deck that will not start over a LOG is a worse answer than one that
+  // stays in the terminal, which is what every version before this did anyway.
+  console.error(`${PRODUCT}: could not open ${PRODUCT}'s log (${outcome.reason}) ${G.dash} staying in the foreground.`);
+}
+
 claimRestartFailureKey();
 
 // The port the worker actually bound, which is not necessarily the one it was
@@ -100,6 +172,11 @@ let attempting = null;
 // worker that was already exiting 75 or 76 when the signal landed reads as a
 // restart request — both resurrect the deck the user just stopped.
 let stopping = false;
+// When this supervisor has put a crashed worker back, pruned to the window the
+// ceiling is counted in. See crashPolicy: a deck that dies once an hour comes
+// back every time; one that dies five times in ten minutes is broken, and the
+// answer to broken is to stop and say so rather than to spin.
+let crashes = [];
 
 function launch(respawn) {
   // Asked on every spawn rather than once at boot: the deletion this catches
@@ -146,6 +223,21 @@ function launch(respawn) {
   worker.on("message", (m) => {
     if (!m || typeof m !== "object") return;
     if (m.type === "listening" && typeof m.port === "number") boundPort = m.port;
+    // The worker saying its boot is finished — every row printed, the browser
+    // launched. Forwarded to whoever detached us, who has been tailing the log
+    // into the user's terminal and is waiting for exactly this to stop.
+    //
+    // GUARDED BY `process.connected`, AND GIVEN A CALLBACK, and it took a real
+    // crash restart to find out why: the launcher disconnects the moment the
+    // first boot finishes, so every LATER boot forwards this down a dead
+    // channel — and `process.send` on a closed channel does not throw where the
+    // call is, it emits 'error' on `process` a tick later. Unhandled, that ends
+    // the supervisor. So a try/catch here was decoration: the guard is the
+    // check, and the callback is what turns the remaining race (disconnect
+    // between the check and the send) into a value nobody has to catch.
+    else if (m.type === "booted" && process.connected) {
+      try { process.send({ type: "booted" }, () => {}); } catch { /* the launcher left */ }
+    }
     // The worker asking to be replaced, while it is still serving. Answered by
     // prefetchUpgrade, which is the whole of this file's new shape: the fetch
     // happens here, and only then does that worker exit — see UPGRADE_CODE.
@@ -173,6 +265,32 @@ function launch(respawn) {
       launchNpx();
       return;
     }
+    // THE DECK FELL OVER, and nobody is watching it any more.
+    //
+    // Before this ran in the background a crash was self-reporting: the terminal
+    // came back with the stack on it. Detached, the first sign is noticing hours
+    // later that a day of work was never recorded — so it goes back up. The
+    // whole of which crashes qualify is in isCrash, and the ceiling that stops
+    // this becoming a spin loop is in crashPolicy.
+    if (isCrash({ code, signal, served: boundPort != null, stopping })) {
+      const verdict = crashPolicy(crashes);
+      if (verdict.restart) {
+        crashes = verdict.history;
+        const how = signal ? `killed by ${signal}` : `exit ${code}`;
+        console.error(`${PRODUCT}: the deck stopped on its own (${how}) ${G.dash} starting it again in ${Math.round(verdict.delayMs / 1000)}s (${verdict.recent}/${CRASH_CEILING}).`);
+        restarts++;
+        // Unref'd would be wrong here: this timer IS the supervisor's reason to
+        // stay alive, and without it the event loop empties and the process
+        // exits before the deck it promised to bring back.
+        setTimeout(() => { if (!stopping) launch(true); }, verdict.delayMs);
+        return;
+      }
+      // Said once, with the two numbers that make it actionable, and then this
+      // process really does end — a supervisor that keeps trying forever is the
+      // failure the ceiling exists to prevent.
+      console.error(`${PRODUCT}: the deck has stopped ${CRASH_CEILING} times in ${Math.round(CRASH_WINDOW_MS / 60000)} minutes ${G.dash} not starting it again. Run \`${INVOKED_AS ?? PRODUCT}\` when you have looked at the log above.`);
+    }
+
     // Anything else is the worker's own verdict and belongs to whoever started
     // us — including the ccdeck wrapper, which exits with our code in turn. A
     // worker killed by a signal is reported by dying of the same one; doing
@@ -492,7 +610,10 @@ for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
 // worker's exit is not read as a request to bring it back; the kill is the
 // signal on POSIX and, through killTree, `taskkill /T /F` on Windows, which has
 // neither SIGTERM nor a process group to aim at.
-dieWithParent(() => {
+// NOT IN THE DETACHED COPY. There the parent is the launcher, which disconnects
+// and exits the moment the deck is up — by design — and arming this would have
+// the deck kill itself a second after every successful start.
+if (!DETACHED) dieWithParent(() => {
   stopping = true;
   if (fetching) { killTree(fetching, "SIGTERM"); fetching = null; }
   if (child) killTree(child, "SIGTERM");