agent-dag 3.19.0 → 3.21.0

package/src/server/index.mjs

@@ -10,14 +10,28 @@ import { extname, join, resolve, sep, dirname as pdirname } from "node:path";
 import { homedir, networkInterfaces } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname } from "node:path";
-import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+// Moved out to a leaf so that a one-shot `ccdeck --stop`, the boot-path module
+// that finds a running deck, and the tests that pin the handshake against
+// hook/hook.js can all ask these questions without importing this file and
+// arming everything in it. Re-exported below under the names they have always
+// had — see src/server/deck-probe.mjs.
+import { challengeDeck, challengeProof, isProcessAlive } from "./deck-probe.mjs";
+// The three this file's own callers and tests already name. `sameProof` and the
+// challenge deadline stay private to the leaf: they were private here too, and
+// re-exporting them would be inventing API on the way out of a move.
+export { challengeDeck, challengeProof, isProcessAlive };
 import { promisify } from "node:util";
 import { claudeConfigDir } from "./claude-dir.mjs";
 import { CODEX_HOME, CODEX_SESSIONS_DIR, STOP, walkRolloutDays } from "./codex-dir.mjs";
 import { PRODUCT } from "./brand.mjs";
 import { createBlockNotifier } from "./block-notify.mjs";
-import { DEFAULTS as PREF_DEFAULTS, notificationsOn, notificationsVetoed, publicPrefs, readPrefs, writePrefs } from "./deck-prefs.mjs";
+import { createActivity } from "./activity.mjs";
+import { AWAY_BOOT_GRACE_MS, AWAY_RECHECK_MS, AWAY_TICK_MS, awayGate, awayUpdateStep } from "./auto-update.mjs";
+import { createPresence } from "./presence.mjs";
+import { DEFAULTS as PREF_DEFAULTS, cleanAlias, isAliasKey, notificationsOn, notificationsVetoed, publicPrefs, readPrefs, writePrefs } from "./deck-prefs.mjs";
 import { createEngine, defaultName } from "./lan-engine.mjs";
+import { aboutThisDeck } from "./lan-about.mjs";
 import { PROBE_PS, localAliases, reachability, readProbe } from "./lan-reach.mjs";
 import { run } from "./exec.mjs";
 import { notify as osNotify } from "./browser-react.mjs";
@@ -38,6 +52,13 @@ const RUNNING_VERSION = (() => {
   catch { return null; }
 })();
 
+// The two facts the away-update waits on (awayUpdateTick): whether a turn is
+// running, fed from pushEvent, and whether a tab is being looked at, fed from
+// POST /api/presence. Up here rather than beside the tick because pushEvent
+// can run before the module below it has finished evaluating.
+const activity = createActivity();
+const presence = createPresence();
+
 const MIME = {
   ".html": "text/html; charset=utf-8",
   ".js":   "application/javascript; charset=utf-8",
@@ -2036,10 +2057,6 @@ let codexWorkspace = "";
 // believing a stale "yes" is at most a few unwritten lines, against a directory
 // listing plus an HTTP round trip on every tick of every deck forever.
 const DECK_PROOF_TTL_MS = 5000;
-// The same deadline hook.js gives a challenge, and for the same reason: a
-// bodyless GET to a loopback port is sub-millisecond when a deck is there and an
-// instant ECONNREFUSED when nothing is.
-const DECK_CHALLENGE_TIMEOUT_MS = 400;
 // `${pid}:${port}:${token}` -> { at, ok }. Keyed on the record's own identity so
 // a rewritten record — a deck that restarted onto the same port with a fresh
 // token — is a new question rather than an inherited answer.
@@ -2105,57 +2122,6 @@ async function provesDeck(d) {
   return ok;
 }
 
-/**
- * One challenge round trip, resolving true only on a correct proof.
- *
- * The compare is constant-time for the reason hook.js's sameProof is: whatever
- * is on that port may not be a deck, and it must not be able to walk the
- * expected proof out of us one byte at a time by timing how long we take to hang
- * up. The nonce is fresh per call, so an answer overheard earlier is worth
- * nothing, and the token itself never leaves this process.
- */
-function challengeDeck(port, token) {
-  return new Promise(resolve => {
-    let settled = false;
-    const finish = ok => { if (settled) return; settled = true; resolve(ok); };
-    const nonce = randomBytes(16).toString("hex");
-    const want = challengeProof(token, nonce);
-    const req = httpRequest({
-      hostname: "127.0.0.1",
-      port,
-      path: `/api/hook-challenge?nonce=${nonce}`,
-      method: "GET",
-      timeout: DECK_CHALLENGE_TIMEOUT_MS,
-    }, res => {
-      if (res.statusCode !== 200) { res.resume(); return res.on("end", () => finish(false)); }
-      let answer = "";
-      res.setEncoding("utf8");
-      res.on("data", c => {
-        answer += c;
-        // A deck answers in ~100 bytes. Anything pouring data at us is not one,
-        // and must not be allowed to grow this buffer without bound.
-        if (answer.length > 4096) { req.destroy(); finish(false); }
-      });
-      res.on("end", () => {
-        if (settled) return;
-        let proof;
-        try { proof = JSON.parse(answer).proof; } catch { return finish(false); }
-        finish(sameProof(proof, want));
-      });
-    });
-    req.on("error", () => finish(false));
-    req.on("timeout", () => req.destroy());
-    req.end();
-  });
-}
-
-/** hook.js's sameProof, for the same reason it is constant-time there. */
-function sameProof(got, want) {
-  if (typeof got !== "string") return false;
-  const a = Buffer.from(got, "utf8");
-  const b = Buffer.from(want, "utf8");
-  return a.length === b.length && timingSafeEqual(a, b);
-}
 
 /**
  * Every deck registered right now, as its own discovery record spells it — and
@@ -3231,12 +3197,87 @@ async function handlePrefsWrite(req, res) {
   return send(res, 200, prefsPayload());
 }
 
+// ── updating while nobody is looking ────────────────────────────────────────
+//
+// auto-update.mjs has the why and the rules; this is the timer and the three
+// effects — install, restart, npx relaunch — each through the code a press
+// uses.
+let _awayTry = null;
+let _awayTimer = null;
+let _bootedAt = Date.now();
+// Until when a report that found nothing newer stands — see AWAY_RECHECK_MS.
+let _awayNothingUntil = 0;
+
+/**
+ * One tick of the away-update. Returns what it did, or null.
+ *
+ * Exported so a test can drive it without waiting out the boot grace — the one
+ * input that is a policy rather than a fact, and so the only one it may pass.
+ * Every clock is the real one: presence and activity are stamped with it.
+ */
+export async function awayUpdateTick({ graceMs = AWAY_BOOT_GRACE_MS } = {}) {
+  const now = Date.now();
+  if (!awayGate({
+    enabled: _prefs?.autoUpdate !== false,
+    supervised: _onRestart != null && _canRestart,
+    restarting: _restarting,
+    sinceBootMs: now - _bootedAt,
+    looking: presence.looking(now),
+    busy: activity.busy(now),
+    quietMs: activity.quietMs(now),
+    graceMs,
+  })) return null;
+  // A standing "nothing newer", unless the clock has moved back past it.
+  if (now < _awayNothingUntil && _awayNothingUntil - now <= AWAY_RECHECK_MS) return null;
+  const su = await import(pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href);
+  const report = await su.versionReport({ running: RUNNING_VERSION, pkgRoot: PKG_ROOT });
+  if (!report.notice) {
+    _awayNothingUntil = now + AWAY_RECHECK_MS;
+    return null;
+  }
+  const step = awayUpdateStep({
+    notice: report.notice, mode: report.upgradeMode,
+    installing: report.upgrade?.state === "running", lastTry: _awayTry, now,
+  });
+  if (!step.act) return null;
+  // Asked again, because the lookup above can take seconds on a slow line and
+  // somebody may have sat down, or started a turn, in them.
+  const again = Date.now();
+  if (presence.looking(again) || activity.busy(again) || _restarting) return null;
+  _awayTry = { target: step.target, at: again };
+  if (step.act === "install") {
+    su.startUpgrade({ pkgRoot: PKG_ROOT });
+    return step.act;
+  }
+  // handleRestart's own check for the npx path, for the same reason: the mode
+  // comes from the install on disk, and a spec it cannot name is no relaunch.
+  if (step.act === "npx" && !su.npxRestartSpec(PKG_ROOT)) return null;
+  _restarting = true;
+  handOffRestart(step.act === "npx" ? "npx" : null);
+  return step.act;
+}
+
+/** POST {tab, looking} — a tab saying whether it is being looked at. See
+ *  presence.mjs, and src/web/presence.ts for the sender. */
+async function handlePresence(req, res) {
+  const raw = await readBody(req).catch(() => null);
+  let body = null;
+  try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
+  if (!body || typeof body !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
+  const ok = presence.report(body.tab, body.looking === true, Date.now());
+  return send(res, ok ? 200 : 400, { ok });
+}
+
 // ── LAN sync ────────────────────────────────────────────────────────────────
 //
 // The engine is built once and told the settings; it opens and closes its own
 // sockets as those change. Nothing here touches a credential — see
 // lan-engine.mjs, which passes an opaque blob between two claude-swap commands.
 const lanEngine = createEngine({
+  // This deck's version and machine, for the decks it is paired with and
+  // nobody else. RUNNING_VERSION rather than a fresh read, for the reason it
+  // is read at import: it is what this process actually runs.
+  about: aboutThisDeck({ version: RUNNING_VERSION }),
   readAccounts: async () => {
     const { fetchClaudeAccounts } = await import("./claude-accounts.mjs");
     return fetchClaudeAccounts();
@@ -3246,15 +3287,67 @@ const lanEngine = createEngine({
     const out = await shareAccounts([String(num)]);
     return out?.ok ? out.blob : null;
   },
-  importAccount: async blob => {
-    const { importAccount } = await import("./cswap-admin.mjs");
+  importAccount: async (blob, step) => {
+    const { importAccount, landed } = await import("./cswap-admin.mjs");
     // NO `force`, ever, and this is the line where that promise is kept. A
     // plain import adds an account that is missing and replaces exactly one
     // claude-swap has quarantined; it SKIPS one that is present and healthy.
     // So a peer cannot overwrite a working credential of this deck's even by
     // lying about its own, because the flag that would allow it is not passed.
     const out = await importAccount(blob);
-    return !!out?.ok;
+    if (!out?.ok) return { ok: false, why: out?.reason ?? "import refused" };
+    // A SKIP IS NOT A HEAL, and reading `ok` alone said it was. `cswap import`
+    // exits ZERO when it declines an account it already holds — importAccount's
+    // own comment says so and reports it as `added: false` — so a round that
+    // changed nothing was counted as a successful repair and the panel said the
+    // account had been fixed. Whoever read that then waited for numbers that
+    // were never going to move.
+    //
+    // The decline is narrow and documented on claude-swap's side: a plain
+    // import replaces a slot only when its usage row is quarantined as
+    // refresh-token-dead, and is "never triggered by the live store's
+    // `no credentials` state". So an account whose login expired heals over the
+    // network, and one that has NO stored login does not — which is a true
+    // sentence the panel can now print instead of a false one.
+    if (out.added === true) return { ok: true };
+
+    // THE DECLINE, AND WHY IT MATTERS WHICH ONE IT IS.
+    //
+    // `cswap import` without --force declines for two opposite reasons and says
+    // the same thing about both: the slot is present and HEALTHY, which is the
+    // promise above working exactly as intended — or the slot is EMPTY, which
+    // is the one case pairing exists for and the one a plain import will never
+    // touch. claude-swap is explicit about the second: a plain import replaces
+    // a slot "iff its usage row is quarantined as refresh-token-dead", and is
+    // "never triggered by the live store's `no credentials` state".
+    //
+    // So `login expired` healed over the network and `no stored login` did not,
+    // and the account somebody most needed repaired was the one the feature
+    // could not repair.
+    //
+    // ASKED NOW, NOT READ FROM THE CACHE. The cached verdicts are up to ten
+    // minutes old, which is right for a label and wrong for a decision that
+    // writes a credential: somebody who signed in two minutes ago still reads
+    // as `no_credentials` there, and acting on that would replace the login
+    // they had just created.
+    const { verdictNow } = await import("./claude-accounts.mjs");
+    const [email, org] = String(step?.key ?? "").split("@@");
+    const now = await verdictNow(email, org ?? "");
+    if (now !== "no_credentials") return { ok: false, why: "claude-swap kept the slot it already has" };
+
+    // FILLING AN EMPTY SLOT, WHICH IS NOT OVERWRITING A WORKING ONE — and the
+    // promise above survives word for word. A peer cannot reach this: the
+    // verdict comes from THIS machine's claude-swap, about THIS machine's
+    // store, and nothing a peer sends can make a slot report that it holds
+    // nothing. Narrowed to the one account with `only`, so a bundle carrying
+    // several cannot ride in behind it.
+    const forced = await importAccount(blob, { force: true, only: { email, org: org ?? "" } });
+    if (!forced?.ok) return { ok: false, why: forced?.reason ?? "import refused" };
+    // `added` counts `imported` alone, and a forced replace is `healed` — see
+    // landed, which is the difference between a repair and a repair reported as
+    // a failure.
+    if (!landed(forced.results)) return { ok: false, why: "claude-swap kept the slot it already has" };
+    return { ok: true, filled: true };
   },
   // The deck's own long-term key, kept so a restart is the same deck rather
   // than a stranger to everybody who has paired with it. Written once, on the
@@ -3315,6 +3408,11 @@ async function applyLanPrefs() {
       shared: Array.isArray(lan.shared) ? lan.shared : [],
       trusted: Array.isArray(lan.trusted) ? lan.trusted : [],
       port: lan.port || 0,
+      autoAsk: lan.autoAsk !== false,
+      autoAccept: lan.autoAccept !== false,
+      // Names somebody here gave other decks. The engine only hands them to
+      // the page, so a change never restarts anything.
+      aliases: lan.aliases && typeof lan.aliases === "object" ? lan.aliases : {},
     });
     // Wholesale, so removing an address in the panel really stops it being
     // dialled rather than only taking the row away.
@@ -3452,6 +3550,21 @@ async function handleLanPeer(req, res) {
       return send(res, 200, { ok: lanEngine.allow(fp), ...lanEngine.status() });
     case "unpair":
       return send(res, 200, { ok: lanEngine.unpair(fp), ...lanEngine.status() });
+    // WHAT THIS DECK CALLS THAT ONE, and nobody else sees it. Keyed by the
+    // fingerprint, so it follows the machine across a new address or a new
+    // name of its own choosing. An empty name takes the alias away.
+    //
+    // The whole map is rebuilt from the one on disk rather than sent by the
+    // page, so two tabs renaming two decks cannot undo each other.
+    case "alias": {
+      if (!isAliasKey(fp)) return send(res, 400, { ok: false, reason: "bad_request" });
+      const name = cleanAlias(body.name);
+      const next = { ...(_prefs?.lan?.aliases ?? {}) };
+      if (name) next[fp] = name; else delete next[fp];
+      _prefs = await writePrefs({ lan: { aliases: next } });
+      await lanEngine.apply({ aliases: _prefs.lan.aliases });
+      return send(res, 200, { ok: true, ...lanEngine.status() });
+    }
     default:
       return send(res, 400, { ok: false, reason: "unknown_action" });
   }
@@ -3459,8 +3572,21 @@ async function handleLanPeer(req, res) {
 
 /** Ask every peer now rather than at the next tick — the button beside the
  *  list, for somebody who has just fixed a login on the other machine and does
- *  not want to wait a minute to see it arrive. */
+ *  not want to wait a minute to see it arrive.
+ *
+ *  Or ONE peer, when the body names it: the `check now` in a deck's own
+ *  dialog. A deck that only calls in has no address here, and says so rather
+ *  than reporting a round that asked nobody. */
 async function handleLanSync(req, res) {
+  const raw = await readBody(req).catch(() => null);
+  let body = null;
+  try { body = JSON.parse(raw ?? ""); } catch { /* the whole-list press sends nothing to read */ }
+  const fp = body && typeof body.fp === "string" ? body.fp : null;
+  if (fp) {
+    const done = await lanEngine.roundOne(fp);
+    if (done == null) return send(res, 409, { ok: false, reason: "no_address" });
+    return send(res, 200, { ok: true, done, ...lanEngine.status() });
+  }
   const done = await lanEngine.round();
   return send(res, 200, { ok: true, done, ...lanEngine.status() });
 }
@@ -3615,6 +3741,10 @@ function pushEvent(raw, source, opts = {}) {
   // know the other exists. block-notify.mjs holds the gates and the cooldown.
   blockNotifier.consider(raw, { clients: sseClients.size, replay: !!opts.replay });
 
+  // Whether a turn is running, for the away-update. Not from a replay: the log
+  // is history, and a turn it shows open is one that ended in another process.
+  if (!opts.replay) activity.note(raw, evt.receivedAt);
+
   if (persisting) {
     // Fire-and-forget append. JSONL = newline-delimited JSON, so the whole line
     // has to reach the file as one write — this used to be `appendFile`, which
@@ -4386,6 +4516,16 @@ async function handleRestart(req, res) {
   if (_deckReady) send(res, 200, { ok: true, mode });
   else send(res, 202, { ok: true, mode, booting: true, detail: "the deck is still starting up; the restart runs as soon as it has finished booting" });
   // Let the response flush before the listener goes away.
+  handOffRestart(mode);
+}
+
+/**
+ * Hand a restart the latch has already admitted to the launcher — from a press
+ * (handleRestart, once its answer is on its way) or from the away-update
+ * (awayUpdateTick). The delay is the press's: its response has to leave before
+ * the listener does.
+ */
+function handOffRestart(mode) {
   setTimeout(() => {
     try { _onRestart(mode); }
     catch (err) {
@@ -4429,6 +4569,50 @@ export function markDeckReady() {
   _deckReady = true;
 }
 
+/**
+ * POST /api/shutdown — end this deck, from `ccdeck --stop`.
+ *
+ * THE TOKEN AND NOTHING ELSE. Every other mutating route accepts either the
+ * token or the deck's own page (isAuthorizedMutation), and this one must not:
+ * there is no button for it, so a page asking to end the deck is a page doing
+ * something no part of this product asks it to do. Refusing the browser half
+ * costs nothing and removes the whole class.
+ *
+ * WHY A ROUTE AND NOT A SIGNAL. Windows has none. `process.kill(pid, "SIGTERM")`
+ * there is TerminateProcess: the deck stops mid-instruction, its discovery file
+ * is left for the next boot to sweep, and its LAN beacon never says goodbye — so
+ * every paired colleague watches it time out instead of seeing it leave. One
+ * loopback POST behaves identically on all three platforms and ends in the
+ * deck's own shutdown(), which closes the listener, unlinks the registration and
+ * stops the beacon. The pid ladder still exists in `--stop`, as the fallback for
+ * a deck too wedged to answer this.
+ *
+ * ANSWERED BEFORE ANYTHING IS TORN DOWN. shutdown() calls
+ * server.closeAllConnections(), which would cut this very socket — so the
+ * teardown is hung off the response having left rather than run beside it, and
+ * the caller gets a 200 instead of a dropped connection it has to interpret.
+ */
+async function handleStop(req, res) {
+  if (!presentsDeckToken(req?.headers ?? {})) return send(res, 401, { ok: false, reason: "unauthenticated" });
+  if (!_onStop) return send(res, 501, { ok: false, reason: "no_launcher" });
+  if (_stopping) return send(res, 200, { ok: true, pid: process.pid, already: true });
+  _stopping = true;
+  let left = false;
+  const leave = () => {
+    if (left) return;
+    left = true;
+    // A throw here must still end the process: the caller has already been told
+    // this deck is going, and a deck that answered "ok" and stayed up is worse
+    // than one that never answered.
+    try { _onStop(); } catch { process.exit(0); }
+  };
+  // 'finish' is the response handed to the OS; 'close' covers the caller that
+  // hung up before it got there. Either one means nothing is left to flush.
+  res.once("finish", leave);
+  res.once("close", leave);
+  send(res, 200, { ok: true, pid: process.pid });
+}
+
 async function handleQuota(req, res) {
   const { fetchClaudeQuota } = await import(
     pathToFileURL(join(PKG_ROOT, "src/server/quota.mjs")).href
@@ -5035,17 +5219,6 @@ const HOOK_TOKEN = randomBytes(32).toString("hex");
 /** The token this deck expects to be challenged on. Written by writeDiscovery. */
 export function hookToken() { return HOOK_TOKEN; }
 
-/**
- * The proof of knowing `token`, for a nonce the challenger chose.
- *
- * hook/hook.js spells this out a second time — it is installed outside the
- * package and cannot import from here — and a test pins the two against each
- * other. Changing one without the other silently blinds the deck.
- */
-export function challengeProof(token, nonce) {
-  return createHash("sha256").update(`${token}:${nonce}`).digest("hex");
-}
-
 // GET /api/hook-challenge?nonce=… — answer a hook's challenge.
 //
 // The nonce is the caller's, so the answer proves knowledge of the token
@@ -5070,21 +5243,6 @@ function handleHookChallenge(_req, res, url) {
   send(res, 200, { proof: challengeProof(HOOK_TOKEN, nonce) });
 }
 
-// Signal 0 delivers nothing; it asks whether the pid could be signalled.
-//
-// BOTH ERRNOS, and the second one is the Windows spelling. POSIX `kill(2)`
-// answers EPERM for a process this account may not signal. On Windows
-// `uv_kill` calls `OpenProcess`, a denial is ERROR_ACCESS_DENIED, and libuv
-// maps that to EACCES — so a deck started from an elevated terminal, or under
-// another account, read as DEAD to every probe in this repo. What followed was
-// silent: the live deck's discovery file was unlinked on the next hook fire,
-// rewritten five seconds later by keepDiscovery, and its banner went on
-// claiming it was receiving events it had stopped receiving.
-function isProcessAlive(pid) {
-  try { process.kill(pid, 0); return true; }
-  catch (e) { return !!e && (e.code === "EPERM" || e.code === "EACCES"); }
-}
-
 async function sweepStaleDiscovery() {
   // Same directory the installer writes and the hooks read — see claude-dir.mjs.
   const dir = join(claudeConfigDir(), "agent-dag");
@@ -5590,6 +5748,15 @@ export function listenFailure(err, { host = "", port = 0, platform = process.pla
 // launcher), /api/restart answers 501 and the UI hides the control rather than
 // offering a button that does nothing.
 let _onRestart = null;
+// How this process ends itself, handed down by bin/deck.js for the same reason
+// _onRestart is: the server does not own the process lifecycle and must be told
+// how to leave. Absent when nothing handed one down — running the module
+// directly, or an embedder — and /api/shutdown then answers 501 rather than
+// pretending.
+let _onStop = null;
+// A stop is in flight. Two sockets asking at once must not both start one, and
+// the response's 'finish' and 'close' can both fire for the same request.
+let _stopping = false;
 // A restart is in flight. Several browser tabs watching the same deck will each
 // ask; the second ask must not re-enter the shutdown.
 let _restarting = false;
@@ -5599,8 +5766,10 @@ let _restarting = false;
 // is reachable in and cannot answer for on its own.
 let _deckReady = false;
 
-export async function startServer({ port = 4317, host = "127.0.0.1", persist = null, portRange = [4318, 4400], workspace = "", codex = true, claude = true, onRestart = null } = {}) {
+export async function startServer({ port = 4317, host = "127.0.0.1", persist = null, portRange = [4318, 4400], workspace = "", codex = true, claude = true, onRestart = null, onStop = null } = {}) {
   _onRestart = typeof onRestart === "function" ? onRestart : null;
+  _onStop = typeof onStop === "function" ? onStop : null;
+  _stopping = false;
   _canRestart = _onRestart != null && persist != null;
   // A new listener is a new boot, whatever a previous one had got as far as
   // reporting. Nothing but bin/deck.js ever sets this, and it does so once, at
@@ -5610,6 +5779,22 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
   // `!== false` rather than a cast: a caller that omits the field means "yes",
   // which is how every embedder that predates this option keeps working.
   _providers = { claude: claude !== false, codex: codex !== false };
+  // The away-update's clock. The boot grace counts from here, and the timer is
+  // unref'd so it never keeps a process alive on its own. It does nothing until
+  // the launcher has handed down a restart — see awayGate's `supervised`.
+  _bootedAt = Date.now();
+  clearInterval(_awayTimer);
+  _awayTimer = setInterval(() => { awayUpdateTick().catch(() => {}); }, AWAY_TICK_MS);
+  _awayTimer.unref?.();
+  // The repair a paused Claude account used to wait on a `resume` press for:
+  // handed to the roster read here, by the server that is actually running,
+  // rather than wired at import — see repairStaleCopyWith.
+  if (_providers.claude) {
+    void Promise.all([
+      import(pathToFileURL(join(PKG_ROOT, "src/server/claude-accounts.mjs")).href),
+      cswapAdminModule(),
+    ]).then(([accounts, admin]) => accounts.repairStaleCopyWith(admin.autoRecapture), () => {});
+  }
   const removed = await sweepStaleDiscovery();
   if (removed > 0) console.log(`  swept ${removed} stale discovery file(s)`);
   if (persist) {
@@ -5687,6 +5872,8 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "GET"  && url.pathname === "/api/version")     return guard(handleVersion(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/upgrade")     return guard(handleUpgrade(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/restart")     return guard(handleRestart(req, res), res);
+    if (req.method === "POST" && url.pathname === "/api/presence")    return guard(handlePresence(req, res), res);
+    if (req.method === "POST" && url.pathname === "/api/shutdown")    return guard(handleStop(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/quota")       return guard(handleQuota(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/codex-usage")  return guard(handleCodexUsage(req, res), res);
     // Machine state, not session state: sampled on the server's own timer and

package/src/server/installer.mjs

@@ -709,7 +709,7 @@ async function ensureDiscoveryDir() {
  * the target already had — a first registration, or one left by an earlier run
  * under a recycled pid, would otherwise keep whatever the umask handed it.
  */
-export async function writeDiscovery({ port, workspace, token, persist = null, codex = true }) {
+export async function writeDiscovery({ port, workspace, token, persist = null, codex = true, claude = true, version = "", parent = null }) {
   await ensureDiscoveryDir();
   const file = discoveryPath();
   const data = {
@@ -744,6 +744,27 @@ export async function writeDiscovery({ port, workspace, token, persist = null, c
     // doing the work must be left out of the election rather than win it. An
     // older deck has no such field, so it is excluded by construction.
     watch: true,
+    // Is the Claude side of this deck switched on? Same shape as `codex` above
+    // and there for a second reader: a bare `ccdeck` that finds this deck
+    // running attaches to it instead of starting a rival, and it may only do
+    // that when the deck on the port is the deck it would itself have built. A
+    // `--no-claude` deck has no hooks, no accounts panel and no switcher, and
+    // until this field existed it was indistinguishable from one that has all
+    // three. An older deck has no such field, so it is excluded by
+    // construction — see runningDeck.
+    claude: claude !== false,
+    // What this deck IS, so a launcher that attaches can say whether the deck
+    // it found is the version the user just asked for. Never a decision: a
+    // rival deck on a random port is worse than an older deck said out loud.
+    version: typeof version === "string" ? version : "",
+    // The supervisor above this worker, or null when nothing is supervising.
+    //
+    // Only `ccdeck --stop` reads it, and only on the path where the polite
+    // request failed. A worker killed on its own leaves its supervisor alive,
+    // and a supervisor that puts crashed workers back would answer that kill by
+    // starting the deck again — so the ladder has to end the parent first and
+    // the child second, which it cannot do without being told who the parent is.
+    parent: Number.isInteger(parent) ? parent : null,
     startedAt: new Date().toISOString(),
   };
   await writeFileAtomic(file, JSON.stringify(data, null, 2) + "\n");
@@ -771,13 +792,14 @@ export function discoveryPath() {
  * is cheap (one small read), so the deck checks rather than assumes.
  *
  * A file this process wrote is left alone, mode included. Anything else — no
- * file, unreadable, another pid, a stale port, token, events log or Codex
- * setting — is replaced. Every field another deck decides by is compared, the
+ * file, unreadable, another pid, a stale port, token, events log, Codex or
+ * Claude setting, or a version left by the deck this process replaced — is
+ * replaced. Every field another deck decides by is compared, the
  * log path included: leave one out and a record missing it would pass as ours
  * forever, which for the log path means no deck can tell which of them share a
  * file and they all write their own copy of every event again.
  */
-export async function ensureDiscovery({ port, workspace, token, persist = null, codex = true }) {
+export async function ensureDiscovery({ port, workspace, token, persist = null, codex = true, claude = true, version = "", parent = null }) {
   const file = discoveryPath();
   try {
     const d = JSON.parse(stripBom(await readFile(file, "utf8")));
@@ -787,11 +809,14 @@ export async function ensureDiscovery({ port, workspace, token, persist = null,
       && (d.workspace ?? "") === (workspace ?? "")
       && (d.token ?? "") === (token ?? "")
       && (d.persist ?? null) === persistField(persist)
-      && d.codex === (codex !== false)) {
+      && d.codex === (codex !== false)
+      && d.claude === (claude !== false)
+      && (d.version ?? "") === (typeof version === "string" ? version : "")
+      && (d.parent ?? null) === (Number.isInteger(parent) ? parent : null)) {
       return { file, rewritten: false };
     }
   } catch { /* missing, unreadable or corrupt — rewritten below */ }
-  await writeDiscovery({ port, workspace, token, persist, codex });
+  await writeDiscovery({ port, workspace, token, persist, codex, claude, version, parent });
   return { file, rewritten: true };
 }
 
@@ -822,7 +847,7 @@ export async function ensureDiscovery({ port, workspace, token, persist = null,
  * `run()` never rejects (every failure is a state), so awaiting this cannot
  * throw and cannot outlast one bounded check.
  */
-export function keepDiscovery({ port, workspace, token, persist = null, codex = true, intervalMs = 5000, onState = null } = {}) {
+export function keepDiscovery({ port, workspace, token, persist = null, codex = true, claude = true, version = "", parent = null, intervalMs = 5000, onState = null } = {}) {
   // null until the first outcome, which therefore always differs and is always
   // reported — the caller learns where it stands before anything else happens.
   let healthy = null;
@@ -830,7 +855,7 @@ export function keepDiscovery({ port, workspace, token, persist = null, codex =
   const run = async () => {
     let state;
     try {
-      const { rewritten } = await ensureDiscovery({ port, workspace, token, persist, codex });
+      const { rewritten } = await ensureDiscovery({ port, workspace, token, persist, codex, claude, version, parent });
       state = { ok: true, rewritten, file: discoveryPath(), error: null };
     } catch (err) {
       state = { ok: false, rewritten: false, file: discoveryPath(), error: err };