ccdeck 3.36.9 → 3.37.1

package/README.md

@@ -119,7 +119,7 @@ log in. **`ccdeck --stop` is the off switch**; `Ctrl+C` only cancels a start tha
 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. Nothing about your sessions is reported anywhere — the deck does send usage reports (its version, your system, your IP address and a device fingerprint, the errors it hits), on by default, and `AGENTS_DECK_NO_REPORTS=1` turns them off.
+No config file. No account. What your sessions contain — your prompts, the replies, the files they touch — is never reported anywhere. The deck does send usage reports, on by default: its version, your system, your IP address and a device fingerprint, rough counts such as how many sessions ran in a day, and the errors it hits. It has no switch for them; `AGENTS_DECK_NO_REPORTS=1` keeps them off from the first start.
 
 **The deck cannot steer your agent.** The hook it installs is a one-way forwarder: it POSTs the event, exits `0`, and writes nothing to stdout. Those are the two channels Claude Code's hook protocol gives a hook for allowing, denying, deferring or rewriting the tool call it was told about, and this one uses neither — it has no way to answer at all. `src/web/__tests__/hook-read-only.test.ts` pins both halves, over the source and by running the real script.
 
@@ -129,7 +129,7 @@ Step by step: [Install ccdeck with npx and see your first session](https://ccdec
 
 ### Desktop app
 
-The same deck as an app: it starts the deck itself and puts an icon in the menu bar (the tray on Windows and Linux) that counts the Claude Code sessions stopped on a permission prompt or a question — the number sits beside the icon on macOS, and in the icon's tooltip and menu on Windows and Linux. With **Notifications while closed** ticked in that menu, which starts off, it also sends a notification while the window is closed wherever an open page would have played a sound, with the deck's own tone on macOS. It needs no Node.js. If a deck from `npx ccdeck` is already running, the app uses that one rather than starting a second, and replaces it only when it is older than the one the app carries.
+The same deck as an app: it starts the deck itself and puts an icon in the menu bar (the tray on Windows and Linux) that counts the Claude Code sessions stopped on a permission prompt or a question — the number sits beside the icon on macOS, and in the icon's tooltip and menu on Windows and Linux. With **Notifications while closed** ticked in that menu, which starts off, it also sends a notification while the window is closed wherever an open page would have played a sound, with the deck's own tone on macOS. It needs no Node.js. The deck it starts is given whichever of the variables in the environment table further down your login shell sets — `AGENTS_DECK_NO_REPORTS` and `CLAUDE_CONFIG_DIR` among them — however the app was opened, as a deck started from a terminal would be. If a deck from `npx ccdeck` is already running, the app uses that one rather than starting a second, and replaces it only when it is older than the one the app carries.
 
 | System | Download |
 | --- | --- |
@@ -208,13 +208,13 @@ Quota is the one thing that is not just reading. It needs a live token, so when
 
 It never steers an agent or edits your code, but it is not read-only either — besides the hook entry and its own event log, it manages the two tools it leans on, and it refreshes the Codex token it reads quota with, rewriting `~/.codex/auth.json` the way `codex` itself does. It also reads your browser's history, because Browser Watch is on unless you switch it off; that is its own section below, because it is the one thing here that is about you rather than about an agent.
 
-What does go out is short and ordinary: a ~20-byte version check against the npm registry (plus one small request to confirm a version it has not seen before), installs and daily version checks for the two tools the deck manages (claude-swap from PyPI, ccusage from npm), on an Apple Silicon Mac whose sensors stay silent one release lookup and one binary download from GitHub for `macmon`, and, while the page is open, quota reads to Anthropic and OpenAI signed with your own credentials — that is where those numbers live. While the page is open, and while the desktop app has a session running or waiting, it also reads Anthropic's and OpenAI's public status pages (`status.claude.com`, `status.openai.com`), unsigned, about every three minutes, and once a minute at most while a page is not answering, so an outage on their side shows as a chip in the topbar instead of looking like a fault on yours. The [desktop app](#desktop-app) also asks this repository's GitHub releases for its own updates. With **Local network** on, which it is unless you switch it off, the deck also announces itself to other decks on your local network over UDP (port 45317) and pairs with the ones that answer — see [Local network](#local-network). The deck also sends usage reports to `api.ccdeck.dev`: an install event, an update event, one "active" a day, one "uninstall" when you run `ccdeck --uninstall` (which asks, at a terminal, one skippable question about why, from a short list), one "activated" when a new install's first session arrives (how long after the install, in rough buckets such as "under five minutes", and whether it was a Claude or a Codex session), and the errors it runs into with folders, addresses and keys scrubbed out. Each carries the version, your OS and CPU architecture, the channel (desktop, npm or a source checkout), the runtime, your IP address and a device fingerprint (a stable hashed machine id), and the machine's rough shape — the number of CPU cores, the amount of RAM, the locale, the shell, the terminal, and the Claude Code and Codex versions — and whether the Claude hooks went in and Codex is being watched, with the daily "active" also carrying how many sessions, subagents and projects you ran on the last day you used the deck, that day's date, and which of the deck's own features you used that day — fixed names such as "usage history" or "account switch", a yes for each and nothing about what you did with them. The fingerprint is a one-way hash of stable machine traits, never those traits in the clear; everything else is coarse counts and short tokens — no path, no project name, no free text. These reports are no longer anonymous: the install id is random, but the fingerprint follows this machine and the server records the IP the report arrives from. What still never leaves is your sessions, prompts, files, project names and paths. The deck has no switch for them; `AGENTS_DECK_NO_REPORTS=1` keeps them off from the first start. While the deck runs it also sends a tiny heartbeat every few minutes, the install id and nothing else, so the count of decks running right now can be seen. **Send feedback** (the topbar's Feedback button) sends what you write, and any screenshots you add, to the same place, where the people who make ccdeck read it and may open a public issue from it, never with the contact you gave or your screenshots. `AGENTS_DECK_NO_INSTALL=1` turns off everything but the quota reads; `AGENTS_DECK_NO_DOWNLOAD=1` is the narrower version — no `uv` binary is fetched, the managed installs stay.
+What does go out is short and ordinary: a ~20-byte version check against the npm registry (plus one small request to confirm a version it has not seen before), installs and daily version checks for the two tools the deck manages (claude-swap from PyPI, ccusage from npm), on an Apple Silicon Mac whose sensors stay silent one release lookup and one binary download from GitHub for `macmon`, and, while the page is open, quota reads to Anthropic and OpenAI signed with your own credentials — that is where those numbers live. While the page is open, and while the desktop app has a session running or waiting, it also reads Anthropic's and OpenAI's public status pages (`status.claude.com`, `status.openai.com`), unsigned, about every three minutes, and once a minute at most while a page is not answering, so an outage on their side shows as a chip in the topbar instead of looking like a fault on yours. While the machine panel is open, on a machine with Claude Code, it times the way to Claude every thirty seconds — a DNS lookup of `api.anthropic.com` and a TCP handshake on port 443, with nothing sent over it — for the panel's latency reading. While the Browser Watch panel is open, it looks up the address of Claude's browser relay, `bridge.claudeusercontent.com`, about every thirty seconds — a DNS query to your resolver — to tell whether a running browser holds a connection to it. The [desktop app](#desktop-app) also asks this repository's GitHub releases for its own updates. With **Local network** on, which it is unless you switch it off, the deck also announces itself to other decks on your local network over UDP (port 45317) and pairs with the ones that answer — see [Local network](#local-network). The deck also sends usage reports to `api.ccdeck.dev`: an install event (naming the ccdeck.dev page the command was copied from, when the command says so with `--ref`, which the site's copy buttons add; a page name and nothing else, sent once), an update event (saying how the new version arrived: the deck's own update, the desktop app's updater, npx, npm or a source checkout), one "active" a day, one "uninstall" when you run `ccdeck --uninstall` (which asks, at a terminal, one skippable question about why, from a short list), one "activated" when a new install's first session arrives (how long after the install, in rough buckets such as "under five minutes", and whether it was a Claude or a Codex session), one "rated" if you answer the one question the deck asks about itself after about a week of use — "How useful is ccdeck to you?", 0 to 10, which you can skip — with the number you picked and how many days you had used the deck, as a range (nothing is sent for a question you put off or leave), and the errors it runs into, with every path outside ccdeck's own code, project folder names, the machine name in every web address, every IP address and the machine name a network error carries (the loopback, such as `127.0.0.1:4317`, stays, so a local port error still reads as one), email addresses and keys scrubbed out (a line of ccdeck's own code keeps its place in the package, such as `ccdeck/src/server/tail.mjs:42`, or in the page, such as `<deck>/assets/index-abc.js:1:2345`, so the error still says where it happened). Each carries the version, your OS and CPU architecture, the channel (desktop, npm or a source checkout), the runtime, your IP address and a device fingerprint (a stable hashed machine id), and the machine's rough shape — the number of CPU cores, the amount of RAM, the locale, the shell, the terminal, and the Claude Code and Codex versions — and whether the Claude hooks went in and Codex is being watched, with the daily "active" also carrying how many sessions, subagents and projects you ran on the last day you used the deck, that day's date, and which of the deck's own features you used that day — fixed names such as "usage history" or "account switch", a yes for each and nothing about what you did with them — plus how the deck held up and what it runs with: how long this run took to start, that day's peak memory and how many events it took in, each as a rough bucket such as "under two seconds" or "256–512 MB", the Claude and Codex plan as its category only (such as "Max 5x" or "Plus", read from the file each CLI keeps beside its login, and nothing else from it), and how many Claude accounts and paired machines the deck holds, as counts. The fingerprint is a one-way hash of stable machine traits, never those traits in the clear; everything else is coarse counts and short tokens — no path, no project name, no free text. These reports are no longer anonymous: the install id is random, but the fingerprint follows this machine and the server records the IP the report arrives from. What still never leaves is your sessions, prompts, files, project names and paths. The deck has no switch for them; `AGENTS_DECK_NO_REPORTS=1` keeps them off from the first start. While the deck runs it also sends a tiny heartbeat every few minutes, the install id and nothing else, so the count of decks running right now, and how many hours a day a deck stays open, can be seen. **Send feedback** (the topbar's Feedback button) sends what you write, and any screenshots you add, to the same place, where the people who make ccdeck read it and may open a public issue from it, never with the contact you gave or your screenshots. `AGENTS_DECK_NO_INSTALL=1` turns off everything but the quota reads; `AGENTS_DECK_NO_DOWNLOAD=1` is the narrower version — no `uv` binary is fetched, the managed installs stay.
 
 ## Browser Watch
 
 The panel behind the eye icon answers one question: **did something drive your browser while you were away?** An agent with browser control opens pages through an API, and Chromium records that — `visits.transition` says `FROM_API` rather than `LINK` or `TYPED`. So a run of those, in a stretch when you were not touching the machine, is a finding worth showing.
 
-To answer it the deck reads the browsers' own history. That means, on each poll: it finds every Chromium profile (Chrome, Brave, Edge, Vivaldi), **copies each profile's `History` database** to a temp file — a live database cannot be opened safely — queries the visits newer than the moment this deck started, and deletes the copy. Nothing leaves the machine, and the copy exists for as long as one query takes.
+To answer it the deck reads the browsers' own history. That means, on each poll: it finds every Chromium profile (Chrome, Brave, Edge, Vivaldi), **copies each profile's `History` database** to a temp file — a live database cannot be opened safely — queries the visits newer than the moment this deck started, and deletes the copy. None of what it reads leaves the machine, and the copy exists for as long as one query takes. The one thing the watch sends out is a DNS query: while the panel is open, it looks up the address of Claude's browser relay (`bridge.claudeusercontent.com`) about every thirty seconds, to show whether a running browser is connected to it. The background poll does not.
 
 **The switch decides whether any of that happens in the background, and it starts on.** With Browser Watch off, the deck's five-minute poll reads no browser at all; with it on, the poll reads, keeps what it finds in `~/.claude/agent-dag/browser-watch/state.json`, writes a line per finding to `watch.log` beside it, and performs whatever reaction you chose. Opening the panel always reads live, on either setting — that is you looking, and it is the only way the panel can tell you what is there.
 
@@ -228,6 +228,8 @@ The Accounts panel reads the store [claude-swap](https://github.com/realiti4/cla
 
 The deck installs that package itself, so it installs it **bounded**: `claude-swap~=0.26`, which is `>= 0.26, == 0.*`, and when PyPI can be reached the exact version it resolved rather than the range. What `cswap --version` reports afterwards has to be that version, or the deck says so and leaves the panel dark rather than driving a copy it cannot account for — this is the tool that holds your Claude logins. The daily upgrade is bounded by the same specifier, and what it left behind is written to `~/.agents-deck/cswap-upgrade.json`.
 
+**Switch** on an account's row makes it the active one. New sessions start on it; sessions already running are not restarted, and pick it up on their next message — up to about 30 seconds later on macOS. **Auto-switch**, off until you turn it on, does the same without a press: about once a minute the deck runs claude-swap's own engine, which, once the active account passes your threshold (90% unless you choose another) of its 5-hour or 7-day window, moves Claude Code to the account with the most room left. Every account keeps its own limits; when no other account is under the threshold, nothing switches.
+
 **`+` → Sign in** runs `claude auth login`, shows you the link, and hands the result to `cswap add`. The sign-in usually completes by itself once you approve it in the browser; only when the page shows a code — as it does on a deck opened from another machine — is there one to paste back into the dialog. The account you were using **stays active** — signing in replaces the live credentials, so the previous one is switched back the moment the new one is recorded. A pasted code goes straight into the CLI's stdin on this machine; it is never stored, logged, or sent anywhere else.
 
 **`share`** on an account produces a `ccdeck2:…` blob to paste into another deck's **`+` → Paste a share**.
@@ -274,7 +276,7 @@ Four pictures, which are also the guide the section opens from `See how it works
 
 **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 a machine that is asked waits for somebody there to press `accept` — unless its `Say yes to every deck that asks` switch, in the same dialog, is on. 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.
+**What is shared, and with whom.** Nothing until you tick a login, and then only that login, and only with paired decks — the deck asks the machines it finds, and a machine that is asked waits for somebody there to press `accept` unless its `Say yes to every deck that asks` switch, in the same dialog, is on. That switch starts on, so your own machines pair without a press; what still takes a person is the tick, because a paired deck is handed nothing until somebody ticks a login here. On a network you do not own, turn the switch off. A login that arrives from a deck somebody here accepted or paired by invite is ticked here too, so this machine can repair the next one; a deck the switch paired is handed only the logins a person ticked, so untick and tick that one again to hand it to those decks as well. 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.
 
 On a Mac, **cannot share here** is different from **expired here**. It means this ccdeck process cannot read the Keychain copy, so that machine is not used as a credential source and another deck does not keep trying to “repair” the same healthy slot every minute. A LAN import is checked after it lands too; if the receiving Mac still cannot read the Keychain, the round reports that problem instead of claiming the login was repaired.
 
@@ -316,6 +318,8 @@ ccdeck [options]
       --claude             Force Claude capture even if Claude Code wasn't found
       --no-claude          Skip Claude entirely — no hooks, no claude-swap,
                            no Accounts panel (Codex only)
+      --ref <name>         The ccdeck.dev page this command was copied from;
+                           sent once, with the first install report
       --uninstall          Remove ccdeck's hooks from settings files, and name
                            the files that still hold this deck's private key
       --purge              With --uninstall: delete those files too
@@ -354,7 +358,9 @@ Scheduler logon task on Windows — none of them carrying a restart policy of it
 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
+deletes without warning — nor does a `pnpm dlx`, `bunx` or `yarn dlx` run, for the
+same reason. A Linux machine that does not run systemd gets none either, and the
+first start says so. 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.
 
@@ -381,7 +387,8 @@ so unconditionally. Two starts at the same moment, such as the login item and a
 terminal opened at login, wait for each other instead of both starting. The rule
 holds per Claude config directory: pointing `CLAUDE_CONFIG_DIR` somewhere else
 is a second deck with its own identity, as it always was, and the login item is
-given the same directory as the shell that installed it.
+given the same directory as the shell that installed it, along with every other
+variable in the table below that the shell had set.
 
 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
@@ -486,6 +493,7 @@ What the banner offers depends on how this copy was installed:
 |---|---|
 | global npm install | **Update now** — runs `npm install -g` on the package you installed, then restarts once nothing is running |
 | `npx` | **Update & restart** — re-runs the spec through npx, which fetches a fresh copy and takes over the same port |
+| `pnpm dlx`, `bunx` or `yarn dlx` | the command — a one-off copy cannot be upgraded in place, so the global install is what is shown |
 | git checkout | the command, because your working copy leads npm: `git pull && npm run build` |
 | directory not writable | the command — a root-owned prefix is declined up front rather than failing inside npm |
 | `AGENTS_DECK_NO_INSTALL=1` | the command only; you asked for no installs |

package/bin/agent-dag.js

@@ -43,7 +43,7 @@ import { parseArgs } from "../src/server/args.mjs";
 import { holdOutput, npxFailureHint, npxFailureSummary, npxLaunch, npxPrefetch } from "../src/server/npx.mjs";
 import {
   bareSpecName, claimRestartFailureKey, clearRestartFailure, currentName, installedName, installedVersion,
-  isNpxInstall, lastKnownLatest, npxRestartSpec, readRestartFailure, recordRestartFailure,
+  lastKnownLatest, npxRestartSpec, oneOffRunner, readRestartFailure, recordRestartFailure,
   successorRoot,
 } from "../src/server/self-update.mjs";
 import {
@@ -98,22 +98,27 @@ const LEASHED = typeof process.send === "function";
 const FLAGS = parseArgs(process.argv.slice(2));
 if (shouldDetach({ detached: DETACHED, leashed: LEASHED, flags: FLAGS })) {
   const { deckLogDir } = await import("../src/server/deck-home.mjs");
-  const { registeredDecks } = await import("../src/server/running-deck.mjs");
+  const { deckRegistryDir, registeredDecks } = await import("../src/server/running-deck.mjs");
+  const { BOOT_LOCK_FILE } = await import("../src/server/boot-lock.mjs");
   const isTTY = Boolean(process.stdout.isTTY);
   const profile = colorProfile({ isTTY });
   const tone = palette(profile);
-  const npx = isNpxInstall(PKG_ROOT);
+  // npx, pnpm dlx, bunx or yarn dlx: the runner the background line's two
+  // commands go through, since none of them leaves the command on PATH.
+  const runner = oneOffRunner(PKG_ROOT);
   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.
+    // Only the count and the boot lock, and only to decide whether deck.log is
+    // anybody's — see startsFresh. No handshake: this is a directory listing
+    // and a signal-0 each.
     liveCount: (await registeredDecks().catch(() => [])).length,
+    booting: existsSync(join(deckRegistryDir(), BOOT_LOCK_FILE)),
     isTTY,
     profile,
     columns: termColumns(process.stdout),
-    backgroundLine: backgroundNote({ npx, invokedAs: INVOKED_AS, product: PRODUCT, tone, g: G }),
+    backgroundLine: backgroundNote({ runner, invokedAs: INVOKED_AS, product: PRODUCT, tone, g: G }),
   });
   // 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 —
@@ -136,6 +141,10 @@ claimRestartFailureKey();
 // Re-launching without this is how a restart silently moves the deck out from
 // under an open tab.
 let boundPort = null;
+// What the last worker said about the Claude hooks ("ok", "failed", "off"),
+// handed to the next one: a respawn on the same version installs nothing, so
+// this is the only way it can say what the session's hooks are (activation.mjs).
+let bootHooks = "";
 let restarts = 0;
 let child = null;
 // The npx process fetching a replacement, while the worker above keeps serving.
@@ -212,6 +221,9 @@ function launch(respawn) {
       // different one installs them again. Empty for "we could not tell",
       // which the worker reads as different.
       AGENTS_DECK_BOOT_VERSION: VERSION === "?" ? "" : VERSION,
+      // And how the hooks went, as the last worker said. Empty for "nobody has
+      // said", which the worker reports as nothing rather than a guess.
+      AGENTS_DECK_BOOT_HOOKS: bootHooks,
       AGENTS_DECK_RESTARTS: String(restarts),
       // Empty for "we could not tell", which knownCommand reads as unknown just
       // like an absent one. Set on the worker's environment only: the npx
@@ -227,6 +239,7 @@ function launch(respawn) {
   worker.on("message", (m) => {
     if (!m || typeof m !== "object") return;
     if (m.type === "listening" && typeof m.port === "number") boundPort = m.port;
+    else if (m.type === "setup" && ["ok", "failed", "off"].includes(m.claudeHooks)) bootHooks = m.claudeHooks;
     // 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.

package/bin/cli/help.js

@@ -45,6 +45,7 @@ Options:
       --no-codex           Skip Codex capture (Claude only)
       --claude             Force-enable Claude capture even if Claude Code wasn't found
       --no-claude          Skip Claude entirely: no hooks, no claude-swap, no accounts panel
+      --ref <name>         The site page this command was copied from (first run)
       --uninstall          Remove ${PRODUCT}'s hooks from ~/.claude/settings.json and
                            ~/.codex/hooks.json, and restore any sound hooks of yours it parked.
                            Hook entries only: the forwarder script under

package/bin/cli/login-item.js

@@ -29,6 +29,18 @@ const loginJob = (script, deckLogDir) => ({ script, logPath: join(deckLogDir(),
 const installedRecord = (path) => ({ installed: PKG_VERSION, at: new Date().toISOString(), path });
 export const removedRecord = () => ({ removed: new Date().toISOString(), version: PKG_VERSION });
 
+/**
+ * A Linux unit written and not enabled, said as what it is. systemd starts at
+ * login only an enabled user unit, so a refused `systemctl --user enable` is a
+ * file nothing reads until somebody runs the command the verdict carries —
+ * unlike a refused `launchctl load`, whose plist launchd still loads at the
+ * next login. Two lines, the way every warning here is said.
+ */
+function sayNotEnabled(out, { say, tone, gWarn, dash }) {
+  say(`  ${tone.warn}${gWarn}  the login item is written but not enabled ${dash} ${out.reason}${tone.reset}`);
+  say(`     ${tone.muted}systemd starts only an enabled unit at login ${dash} \`${out.enable}\` turns it on${tone.reset}`);
+}
+
 /** The one place the three platforms genuinely differ in what a login item buys you. */
 function warnWhenLingerOff(svc, { say, tone, gWarn }) {
   if (svc.lingerState() === "off") {
@@ -79,7 +91,8 @@ export async function installGlobally({ say, tone, dash, gOk, gWarn, bullet, gEl
     return 0;
   }
   svc.writeServiceRecord(deckDataDir(), installedRecord(out.path));
-  say(`  ${tone.ok}${gOk}${tone.reset}  and starts when you log in${tone.muted}  ${bullet}  ${out.path}${tone.reset}`);
+  if (out.enable) sayNotEnabled(out, { say, tone, gWarn, dash });
+  else say(`  ${tone.ok}${gOk}${tone.reset}  and starts when you log in${tone.muted}  ${bullet}  ${out.path}${tone.reset}`);
   warnWhenLingerOff(svc, { say, tone, gWarn });
   say(`     ${tone.muted}\`${pkg} --uninstall-service\` undoes the login part${tone.reset}\n`);
   return 0;
@@ -91,7 +104,7 @@ export async function installGlobally({ say, tone, dash, gOk, gWarn, bullet, gEl
 // with three.
 export async function loginItemCommand(flags, { say, tone, dash, gOk, gWarn, bullet, deckDataDir, deckLogDir }) {
   const svc = await import(pathToFileURL(join(PKG_ROOT, "src/server/login-service.mjs")).href);
-  const { isGitCheckout, isNpxInstall } = await import(pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href);
+  const { isGitCheckout, isNpxInstall, isOneOffRun } = await import(pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href);
   if (flags.uninstallService) {
     const out = svc.uninstallService();
     // Recorded either way. The record is what stops the next ordinary start
@@ -116,11 +129,14 @@ export async function loginItemCommand(flags, { say, tone, dash, gOk, gWarn, bul
     say(`\n  ${tone.warn}${gWarn}  this is a checkout, so the login item would name ${PKG_ROOT}${tone.reset}`);
     say(`     ${tone.muted}a renamed, moved or deleted working tree leaves a login item pointing at nothing${tone.reset}\n`);
   }
-  if (isNpxInstall(PKG_ROOT)) {
+  if (isOneOffRun(PKG_ROOT)) {
     // The item would name a path inside ~/.npm/_npx/<hash>/, which npm deletes
     // whenever it feels like it — a login item pointing at nothing, forever,
-    // on a machine where nothing was ever installed.
-    say(`\n  ${tone.warn}${gWarn}  an npx run cannot start at login ${dash} its files live in npm's cache and are deleted without warning.${tone.reset}`);
+    // on a machine where nothing was ever installed. pnpm dlx, bunx and yarn
+    // dlx keep theirs in a cache or a temp folder the same way.
+    say(isNpxInstall(PKG_ROOT)
+      ? `\n  ${tone.warn}${gWarn}  an npx run cannot start at login ${dash} its files live in npm's cache and are deleted without warning.${tone.reset}`
+      : `\n  ${tone.warn}${gWarn}  a pnpm dlx, bunx or yarn dlx run cannot start at login ${dash} its files live in a cache or temp folder and are deleted without warning.${tone.reset}`);
     say(`     ${tone.muted}install it first: \`npm i -g ${COMMAND}\`${tone.reset}\n`);
     return 1;
   }
@@ -130,12 +146,17 @@ export async function loginItemCommand(flags, { say, tone, dash, gOk, gWarn, bul
     return 1;
   }
   svc.writeServiceRecord(deckDataDir(), installedRecord(out.path));
-  say(`\n  ${tone.ok}${gOk}${tone.reset}  starts when you log in${tone.muted}  ${bullet}  ${out.path}${tone.reset}`);
-  if (out.how === "file-only") {
-    // The file is on disk and both launchd and systemd read their directories
-    // at the next login, so this works from then on. Said rather than hidden:
-    // "it will work tomorrow" is a different promise from "it works now".
-    say(`  ${tone.warn}${gWarn}  not started now ${dash} ${out.reason}. It will come up at your next login.${tone.reset}`);
+  if (out.enable) {
+    say("");
+    sayNotEnabled(out, { say, tone, gWarn, dash });
+  } else {
+    say(`\n  ${tone.ok}${gOk}${tone.reset}  starts when you log in${tone.muted}  ${bullet}  ${out.path}${tone.reset}`);
+    if (out.how === "file-only") {
+      // The plist is on disk and launchd loads its directory at the next
+      // login, so this works from then on. Said rather than hidden: "it will
+      // work tomorrow" is a different promise from "it works now".
+      say(`  ${tone.warn}${gWarn}  not started now ${dash} ${out.reason}. It will come up at your next login.${tone.reset}`);
+    }
   }
   warnWhenLingerOff(svc, { say, tone, gWarn });
   say(`     ${tone.muted}\`${COMMAND} --uninstall-service\` undoes it${tone.reset}\n`);
@@ -148,20 +169,21 @@ export async function loginItemCommand(flags, { say, tone, dash, gOk, gWarn, bul
 // makes that true: without it, `--uninstall-service` would be undone by the next
 // start, which is not an uninstall — it is a tool arguing with its user.
 //
-// npx is excluded and AGENTS_DECK_NO_INSTALL is honoured — see
-// shouldOfferService, which owns both rules and says why. A failure is one line
-// and nothing else: the deck is already running, and the worst case is the
-// behaviour every version before this one had.
+// npx and the other one-off runners are excluded and AGENTS_DECK_NO_INSTALL is
+// honoured — see shouldOfferService, which owns both rules and says why. A
+// failure is one line and nothing else: the deck is already running, and the
+// worst case is the behaviour every version before this one had.
 //
 // Called by the boot, not by a one-shot, so it writes the boot's way: `P`, `G`
 // and `write`, straight from bin/cli/screen.js.
 export async function offerLoginItem({ deckDataDir, deckLogDir }) {
   try {
     const svc = await import(pathToFileURL(join(PKG_ROOT, "src/server/login-service.mjs")).href);
-    const { isGitCheckout, isNpxInstall } = await import(pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href);
+    const { isGitCheckout, isOneOffRun } = await import(pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href);
     if (svc.shouldOfferService({
       record: svc.readServiceRecord(deckDataDir()),
-      npx: isNpxInstall(PKG_ROOT),
+      // npx, pnpm dlx, bunx and yarn dlx alike: none has a path to name.
+      npx: isOneOffRun(PKG_ROOT),
       checkout: isGitCheckout(PKG_ROOT),
     })) {
       const out = svc.installService(loginJob(OWN_SCRIPT, deckLogDir));
@@ -171,9 +193,11 @@ export async function offerLoginItem({ deckDataDir, deckLogDir }) {
       // Said once, on the one run that does it, and never again. A tool that
       // adds itself to your login items and does not mention it is a tool you
       // find later, in a settings pane, and stop trusting.
-      write(out.ok
-        ? `  ${P.muted}${G.dash}  ${PRODUCT} will now start when you log in ${G.dash} \`${COMMAND} --uninstall-service\` undoes it${P.reset}\n\n`
-        : `  ${P.muted}${G.dash}  could not set ${PRODUCT} to start at login (${out.reason}) ${G.dash} it still starts when you type it${P.reset}\n\n`);
+      write(!out.ok
+        ? `  ${P.muted}${G.dash}  could not set ${PRODUCT} to start at login (${out.reason}) ${G.dash} it still starts when you type it${P.reset}\n\n`
+        : out.enable
+          ? `  ${P.muted}${G.dash}  ${PRODUCT}'s login item is written but systemd did not enable it (${out.reason}) ${G.dash} \`${out.enable}\` turns it on${P.reset}\n\n`
+          : `  ${P.muted}${G.dash}  ${PRODUCT} will now start when you log in ${G.dash} \`${COMMAND} --uninstall-service\` undoes it${P.reset}\n\n`);
     }
   } catch (err) {
     // Never fatal. The deck is up; this is a convenience that did not happen.

package/bin/cli/one-shot.js

@@ -16,7 +16,7 @@ import { pathToFileURL } from "node:url";
 import { isPortValue } from "../../src/server/args.mjs";
 import { sinceLabel } from "../../src/server/term.mjs";
 import { installGlobally, loginItemCommand } from "./login-item.js";
-import { COMMAND, PKG_ROOT } from "./package.js";
+import { COMMAND, PKG_ROOT, PKG_VERSION } from "./package.js";
 import { G, P } from "./screen.js";
 
 /**
@@ -124,7 +124,7 @@ function printLogs(deckLogDir, { say, tone, dash, bullet }) {
     say(`\n  ${tone.muted}${dash}  nothing logged yet ${dash} ${logPath}${tone.reset}\n`);
     return 0;
   }
-  // The tail, not the file. It is truncated at the first start on an idle
+  // The tail, not the file. It starts afresh at the first start on an idle
   // machine, so it is normally small — but an attach appends to a running
   // deck's log every time, and a long-lived deck's log is somebody's week.
   const lines = text.split("\n");
@@ -170,7 +170,7 @@ async function defaultShape(deckLogDir) {
 
 /** `--status`: every deck on this machine, and which one a bare start would open. */
 async function printStatus(decks, mine, { say, tone, dash, gOk, bullet, arrow }) {
-  const { sameShape } = await import(pathToFileURL(join(PKG_ROOT, "src/server/running-deck.mjs")).href);
+  const { olderVersion, sameShape, serves } = await import(pathToFileURL(join(PKG_ROOT, "src/server/running-deck.mjs")).href);
   if (!decks.length) {
     say(`\n  ${tone.muted}${dash}  no deck is running ${dash} \`${COMMAND}\` starts one${tone.reset}\n`);
     return 0;
@@ -178,7 +178,13 @@ async function printStatus(decks, mine, { say, tone, dash, gOk, bullet, arrow })
   // The one a bare `ccdeck` would open is marked, because with two decks up
   // that is the only question this command is really being asked. Never a
   // deck between workers: a start typed now finds nothing to open there.
-  const opens = decks.find(d => !d.restarting && sameShape(d, mine)) ?? null;
+  //
+  // By the start's own rule, serves — the shape AND a version no older than
+  // this one. The shape alone marked an older deck, the one still up after an
+  // upgrade, as the deck the next `ccdeck` opens, and that `ccdeck` replaced
+  // it. With nothing to open, an older deck of the start's shape says so.
+  const opens = decks.find(d => !d.restarting && serves(d, { want: mine, ours: PKG_VERSION })) ?? null;
+  const replaced = (d) => !opens && !d.restarting && sameShape(d, mine) && olderVersion(d.version, PKG_VERSION);
   say("");
   for (const d of decks) {
     // The version chunk is dropped rather than printed as "v?" for a deck too
@@ -191,7 +197,11 @@ async function printStatus(decks, mine, { say, tone, dash, gOk, bullet, arrow })
     const head = [d.version ? `v${d.version}` : "", `pid ${pidOf(d)}`, d.restarting ? "restarting after a crash" : `up ${age(d)}`]
       .filter(Boolean).join(`  ${bullet}  `);
     const mark = d === opens ? `${tone.ok}${gOk}${tone.reset}` : `${tone.muted}${bullet}${tone.reset}`;
-    const tail = d === opens ? `${tone.muted}   ${arrow} \`${COMMAND}\` opens this one${tone.reset}` : "";
+    const tail = d === opens
+      ? `${tone.muted}   ${arrow} \`${COMMAND}\` opens this one${tone.reset}`
+      : replaced(d)
+        ? `${tone.muted}   ${arrow} \`${COMMAND}\` replaces this one ${dash} older than v${PKG_VERSION}${tone.reset}`
+        : "";
     say(`  ${mark}  ${tone.muted}${head}${tone.reset}${tail}`);
     say(`     ${tone.accent}${tone.bold}${url(d)}${tone.reset}`);
     say(`     ${tone.muted}${where(d)} ${bullet} ${d.persist ?? "no log (--no-persist)"}${tone.reset}`);

package/bin/cli/screen.js

@@ -56,13 +56,18 @@ export const showCursor = () => {
 export function takeCursor() {
   if (MOTION) { cursorHidden = true; write(CURSOR_HIDE); }
   process.on("exit", showCursor);
-  // SIGHUP is the one signal this process does not otherwise handle, so its
-  // default action would end us before 'exit' could run. Handled only to put the
-  // cursor back and then die of it exactly as before — the supervisor reads the
-  // signal, not an exit code.
-  process.on("SIGHUP", () => { showCursor(); dieOfSignal("SIGHUP"); });
+  // SIGHUP's default action would end us before 'exit' could run. Handled to
+  // put the cursor back and then die of it exactly as before — the supervisor
+  // reads the signal, not an exit code — until the boot hands it to its
+  // shutdown with onHangup.
+  process.on("SIGHUP", () => { showCursor(); hangup(); });
 }
 
+let hangup = () => dieOfSignal("SIGHUP");
+/** What a hangup does once the boot can do better than die of it: bin/deck.js
+ *  routes it into the same shutdown SIGINT and SIGTERM run. */
+export const onHangup = (fn) => { hangup = fn; };
+
 // ── rows ──────────────────────────────────────────────────────────────────────
 // The status column is computed from the longest label. It used to be counted
 // into each string as trailing spaces, so any new row, or any label a character

package/bin/cli/startup.js

@@ -162,15 +162,19 @@ export function startupWork({ wantClaude, installHooks, leftoverCodexHooks }) {
  *
  * A failure is one line and the restart goes on: the deck is serving, and the
  * previous forwarder, which is still in place, still reaches it.
+ *
+ * Answers like startupWork's hook job — `{ ok: true, v }` or `{ ok: false, err }`
+ * — when it installed, and null when it did not try, so the usage reports can
+ * say what this respawn saw (respawnHooksJob in activation.mjs).
  */
 export async function respawnHooks({ wantClaude, installHooks, bootVersion }) {
   if (!wantClaude || bootVersion === PKG_VERSION) return null;
   try {
-    return await installHooks({ provider: "claude" });
+    return { ok: true, v: await installHooks({ provider: "claude" }) };
   } catch (err) {
     const why = String(err?.message ?? err).split("\n")[0];
     console.error(`${PRODUCT}: Claude hooks not updated to v${PKG_VERSION} ${G.dash} ${why}`);
-    return null;
+    return { ok: false, err };
   }
 }
 

package/bin/cli/uninstall.js

@@ -6,6 +6,7 @@
 // well before the heavy imports, exactly where the block used to sit. Every
 // module the uninstall touches is still imported off PKG_ROOT at the moment it
 // is needed, so `--uninstall` loads only what it uses and starts nothing.
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { PRODUCT } from "../../src/server/brand.mjs";
@@ -124,6 +125,14 @@ export async function uninstall(flags) {
   // HERE, and the position is the point: after every hook is out, and before
   // --purge takes the key files, so no deck is left running to write them back.
   if (!(await stopLiveDecks())) refused = true;
+  // The reporter the goodbye at the end goes out through, loaded HERE rather
+  // than where it is used. Importing reports.mjs is what reads prefs.json into
+  // memory, install id and all, and `--purge` just below deletes that file:
+  // read after it, the reporter found no id, decided nothing would go out, and
+  // the uninstall that most meant it was the one never counted or asked why.
+  // Null when no goodbye can go out — see goodbyeReporter for why that is
+  // decided before the import rather than by it.
+  const reporter = await goodbyeReporter();
   // ── THE PRIVATE KEY ────────────────────────────────────────────────────────
   //
   // The one thing left on the disk that is a CREDENTIAL rather than data. Every
@@ -181,16 +190,43 @@ export async function uninstall(flags) {
 
   // Last, once everything above is done, and only while reports are on: the
   // usage reports hear that this install left, with a reason if the person at
-  // the terminal picks one. See bin/cli/leaving.js.
-  {
-    const { reporter } = await import(pathToFileURL(join(PKG_ROOT, "src/server/reports.mjs")).href);
-    await sayGoodbye({ reporter });
-  }
+  // the terminal picks one. See bin/cli/leaving.js, and the reporter's own
+  // comment above the key section for why it was loaded there.
+  await sayGoodbye({ reporter });
   // Non-zero when any half of it refused, so `ccdeck --uninstall && …` and every
   // CI step that runs this stops on the failure instead of continuing past it.
   return refused ? 1 : 0;
 }
 
+/**
+ * The usage reporter the goodbye goes out through, with the install id already
+ * read into memory — or null, when no goodbye can go out.
+ *
+ * NOT A BARE IMPORT. Importing reports.mjs reads prefs.json with the deck's own
+ * boot read (prefs-state.mjs), and that read MOVES ASIDE a file it cannot parse
+ * or that another user owns, and announces that the deck is starting with fresh
+ * settings. In an uninstall that is a rename, under the user, of the very file
+ * the key section names as the one to remove, by a command that promises to
+ * leave their data where it is. So with reports vetoed nothing is read at all,
+ * and otherwise the file is read here first, touching nothing: a file the boot
+ * read would not take as it is has no install id to say goodbye under either.
+ */
+async function goodbyeReporter() {
+  const { normalise, prefsPath, reportsVetoed } =
+    await import(pathToFileURL(join(PKG_ROOT, "src/server/deck-prefs.mjs")).href);
+  if (reportsVetoed(process.env)) return null;
+  const { stripBom } = await import(pathToFileURL(join(PKG_ROOT, "src/server/atomic-write.mjs")).href);
+  try {
+    normalise(JSON.parse(stripBom(await readFile(prefsPath(), "utf8"))));
+  } catch {
+    return null;
+  }
+  const { reporter } = await import(pathToFileURL(join(PKG_ROOT, "src/server/reports.mjs")).href);
+  // willReport() waits for the import's read, so the id is held from here on.
+  await reporter.willReport();
+  return reporter;
+}
+
 /**
  * Stop every live deck on this machine, one line per deck, and answer whether
  * all of them went.

package/bin/deck.js

@@ -13,7 +13,7 @@
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { existsSync } from "node:fs";
-import { RESTART_CODE, UPGRADE_CODE, dieWithParent } from "../src/server/supervisor.mjs";
+import { RESTART_CODE, UPGRADE_CODE, dieWithParent, signalExitAction } from "../src/server/supervisor.mjs";
 import { parseArgs, startPort, wantsCli } from "../src/server/args.mjs";
 import { unregisteredDetail } from "../src/server/pulse-line.mjs";
 import { PRODUCT } from "../src/server/brand.mjs";
@@ -33,7 +33,7 @@ import { offerLoginItem } from "./cli/login-item.js";
 import { oneShot } from "./cli/one-shot.js";
 // The terminal the boot draws in: palette, glyphs, rows, the wordmark and the spinner.
 import {
-  G, P, fileLink, printBanner, showCursor, step, takeCursor, tty, write,
+  G, P, fileLink, onHangup, printBanner, showCursor, step, takeCursor, tty, write,
 } from "./cli/screen.js";
 // The once-per-session work and the rows that report it.
 import { reportReady, reportRestarted, reportStartup, respawnHooks, startupWork } from "./cli/startup.js";
@@ -200,7 +200,11 @@ const { installHooks, keepDiscovery, removeDiscovery, hasCodexInstalled, leftove
 const { startServer, hookToken, releaseRestart, markDeckReady, CODEX_SESSIONS_DIR, canonicalWorkspace } =
   await import(pathToFileURL(join(PKG_ROOT, "src/server/index.mjs")).href);
 // What this boot set up, for the usage reports — see activation.mjs.
-const { noteSetup } = await import(pathToFileURL(join(PKG_ROOT, "src/server/activation.mjs")).href);
+const { noteSetup, respawnHooksJob } = await import(pathToFileURL(join(PKG_ROOT, "src/server/activation.mjs")).href);
+// And the site page the command came from, which only a new install's first
+// report carries — see install-ref.mjs.
+const { noteRef } = await import(pathToFileURL(join(PKG_ROOT, "src/server/install-ref.mjs")).href);
+noteRef(flags.ref);
 
 // Resolved here rather than left as typed, for the reason the events log above
 // is: the discovery file publishes this path, and the hook that reads it runs in
@@ -398,15 +402,33 @@ const starting = startServer({
 // the one the session started on — see respawnHooks.
 if (!RESPAWN) {
   const jobs = startupWork({ wantClaude, installHooks, leftoverCodexHooks });
-  noteSetup({ claude: jobs.hooks, codex: wantCodex });
+  handDownSetup(noteSetup({ claude: jobs.hooks, codex: wantCodex }));
   jobs.cswapQuiet.then(settleCswap);
   await printBanner();
   await reportStartup(jobs, { workspace, wantClaude, wantCodex, CODEX_SESSIONS_DIR });
 } else {
   settleCswap();
-  // The session's first boot installed the hooks; a respawn says the same.
-  noteSetup({ claude: wantClaude ? { ok: true } : null, codex: wantCodex });
-  await respawnHooks({ wantClaude, installHooks, bootVersion: process.env.AGENTS_DECK_BOOT_VERSION });
+  // What a respawn says about the hooks is what it saw: its own re-install when
+  // the package changed under the session, else the first boot's answer as the
+  // supervisor handed it down — never an "ok" it assumed. See respawnHooksJob.
+  const reinstall = respawnHooks({ wantClaude, installHooks, bootVersion: process.env.AGENTS_DECK_BOOT_VERSION });
+  handDownSetup(noteSetup({
+    claude: respawnHooksJob({ wantClaude, reinstall, carried: process.env.AGENTS_DECK_BOOT_HOOKS }),
+    codex: wantCodex,
+  }));
+  await reinstall;
+}
+
+/** The hooks' answer, told to the supervisor, which hands it to the next
+ *  respawn in AGENTS_DECK_BOOT_HOOKS: a respawn on the same version installs
+ *  nothing, and this is how it can still say what the session's hooks are.
+ *  Guarded, and given a callback, like every send down a channel the other end
+ *  may have closed. */
+function handDownSetup(said) {
+  said.then(({ claudeHooks }) => {
+    if (!claudeHooks || !process.connected) return;
+    try { process.send({ type: "setup", claudeHooks }, () => {}); } catch { /* nobody supervising */ }
+  }).catch(() => {});
 }
 
 // Usually settled long ago by the time we get here, which is the point: `step`
@@ -558,7 +580,9 @@ async function shutdown(code = 0) {
     // Before anything that can take time: a Ctrl+C the user has to watch for a
     // second and a half is a second and a half without a cursor.
     showCursor();
-    if (tty && code !== RESTART_CODE && code !== UPGRADE_CODE) {
+    // Nothing for a terminal that hung up (onHangup, below): it is not there.
+    const hungUp = code === hangupCode();
+    if (tty && code !== RESTART_CODE && code !== UPGRADE_CODE && !hungUp) {
       write(`\n\n  ${P.warn}${G.stop}  shutting down${G.ellipsis}${P.reset}\n`);
     }
     // WHAT THIS DECK STARTED, ENDED WITH IT. Every deadline in exec.mjs lives
@@ -626,6 +650,17 @@ async function shutdown(code = 0) {
 }
 process.on("SIGINT", () => shutdown(0));
 process.on("SIGTERM", () => shutdown(0));
+// A terminal closed under a `--foreground` deck, or a console window closed on
+// Windows, which Node reports as SIGHUP. Dying of it on the spot dropped every
+// append already acknowledged, left the discovery record for the hooks and
+// gave the LAN no goodbye, so it takes the way out the other two take. With
+// the hangup's own exit code, so the supervisor reads what it read before; and
+// with nothing written to the terminal that is gone — a write there fails, and
+// an unhandled 'error' on stdout would end the shutdown halfway.
+onHangup(() => {
+  for (const out of [process.stdout, process.stderr]) out.on("error", () => {});
+  shutdown(hangupCode());
+});
 process.on("beforeExit", () => { discovery?.stop(); if (discoveryFile) removeDiscovery(discoveryFile); });
 // The boot lock's `exit` handler is NOT here with its siblings. It is armed up
 // beside `let bootLock = null;`, above the start gate, because the three ways
@@ -634,6 +669,13 @@ process.on("beforeExit", () => { discovery?.stop(); if (discoveryFile) removeDis
 
 // ── helpers ───────────────────────────────────────────────────────────────────
 
+/** The code a death by SIGHUP is reported as, 129: what a hangup that runs
+ *  shutdown instead of dying of it exits with. A function, like shutdown, so
+ *  it is there at any instant of the boot. */
+function hangupCode() {
+  return signalExitAction("SIGHUP").code;
+}
+
 // The deck is up and the discovery file could not be written. Said in full —
 // the path, the reason — because the alternative is what this replaced: an
 // ordinary-looking deck that simply never shows a session.