agent-dag 3.22.0 → 3.22.3

package/src/server/retire-sound-hook.mjs

@@ -1,349 +0,0 @@
-// Takes the deck's old finish-sound hook back off a machine that already has it.
-//
-// Until #704 the deck played its "turn finished" sound by writing a `Stop` entry
-// into the user's settings.json whose command ran `notify.mjs` out of the deck's
-// own install directory. The deck plays that sound itself now, from the `Stop`
-// and `Notification` envelopes it already receives, and the script is gone from
-// the package — so an entry naming it is a hook pointing at a file that does not
-// exist, and Claude Code runs it at the end of every turn. On a machine that was
-// working yesterday. That is what this module exists to prevent, and it is the
-// whole of what is left here: there is no installer, no toggle, no status
-// reporter and no re-assert. Only the removal, and the promise the removal owes.
-//
-// THE PROMISE. Turning the sound on used to PARK any sound hook the user had
-// written themselves — an `afplay` line, a PowerShell one — in
-// ~/.agents-deck/parked-sound-hooks.json, so that "off" produced actual silence
-// and "on" did not play twice. Those hooks are the user's, the deck is the only
-// thing that knows where they went, and this is the last code that will ever be
-// in a position to hand them back. So retirement is not "delete our entry": it
-// is "delete our entry and put theirs back where they wrote it".
-//
-// WHAT COUNTS AS OURS. Two rules, and they cover different machines.
-//
-//   The `__agent-dag-sound` mark is what this deck wrote, and it survives a
-//   settings.json synced from another computer — where every path in the command
-//   belongs to that computer and matches nothing here.
-//
-//   An entry whose command names one of our installed scripts is ours too, mark
-//   or no mark. <claude config dir>/agent-dag/ is a directory this deck creates
-//   and fills; nobody hand-writes a Stop hook that runs `node
-//   ~/.claude/agent-dag/notify.mjs`. The author's own machine is the case: two
-//   Stop entries naming the installed notify.js with the mark missing from both,
-//   which the mark rule alone would have left behind — playing a sound with no
-//   switch anywhere that could stop it, or crashing once the script was swept.
-//
-// Everything else in the file is the user's and is not touched. `afplay …` stays
-// exactly where they put it, and this module has no idea what it does.
-//
-// EXACTLY ONCE, without a stamp. Retirement is triggered by the state it
-// removes: our entry in settings.json, a parked file, or one of our scripts on
-// disk. When it has run there is none of that left, so the next boot asks three
-// `existsSync` questions, gets three noes, and writes nothing — the same answer
-// every boot after it, forever. A "retirement done" marker file would have been
-// the other spelling and is the wrong one: a marker can say done about a machine
-// whose settings.json was later restored from a backup carrying the old entry,
-// and then the broken hook lives there permanently. State that describes itself
-// cannot drift from itself.
-//
-// A DECK THAT CANNOT WRITE. Nothing here is done speculatively and nothing is
-// recorded as done that was not. A settings.json that will not parse stops
-// retirement with the file byte for byte as it was found (see
-// readSettingsForWrite: this rewrites the whole file, so treating a damaged one
-// as `{}` would replace every permission, env var and hook in it with nothing).
-// An unwritable one throws out of the write and the boot reports it. A parked
-// file that will not read leaves the park alone and still removes our entry,
-// because those are two independent repairs and only one of them is urgent.
-// In every one of those cases the trigger state is still on disk, so the next
-// boot tries again. There is nothing to reset.
-//
-// TWO DECKS BOOTING AT ONCE. Both read the same settings, both compute the same
-// result, and both write it through writeFileAtomic — a rename, so the file is
-// one whole payload whichever lands second. The park is the part that could
-// have gone wrong: deck B reading the park before A deleted it and settings
-// after A wrote it would put the user's hooks back a second time, on top of the
-// copy A had just restored. So a parked entry is spliced back only when an
-// identical one is not already in the group. Restoring is idempotent, and the
-// race stops being one.
-import { readFile, rm } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-import { claudeConfigDir } from "./claude-dir.mjs";
-import { readSettingsForWrite, writeFileAtomic } from "./installer.mjs";
-
-const CLAUDE_DIR    = claudeConfigDir();
-const SETTINGS_PATH = join(CLAUDE_DIR, "settings.json");
-const INSTALL_DIR   = join(CLAUDE_DIR, "agent-dag");
-
-// Both names the sound script ever had. `.js` is the pre-#577 spelling, which
-// was CommonJS-by-default in a directory with no package.json above it and so a
-// `SyntaxError: Cannot use import statement` at the end of every turn on the
-// older half of this package's `engines` range; `.mjs` is what replaced it.
-// Retirement has to know both, because a machine that never upgraded past #577
-// is exactly the kind of machine this runs on.
-const NOTIFY_PATH        = join(INSTALL_DIR, "notify.mjs");
-const LEGACY_NOTIFY_PATH = join(INSTALL_DIR, "notify.js");
-const OUR_SCRIPTS = [NOTIFY_PATH, LEGACY_NOTIFY_PATH];
-
-const MARK  = "__agent-dag-sound";
-const EVENT = "Stop";
-// Where the user's own sound hooks were put while the toggle was on. Nothing
-// writes this any more; retirement reads it once and deletes it.
-const PARKED_PATH = join(homedir(), ".agents-deck", "parked-sound-hooks.json");
-
-const commandsOf = (entry) =>
-  (entry?.hooks ?? []).map(h => (typeof h?.command === "string" ? h.command : ""));
-
-/**
- * THE TAIL, NOT THE WHOLE PATH — and this is a data-loss fix, not a tidy-up.
- *
- * The stored command was written by `shellQuoteArg`, whose POSIX branch
- * single-quotes the argument and rewrites every `'` as `'\''`. So on a config
- * dir like `/mnt/Bob's SSD/claude` the command contains `Bob'\''s` and a
- * `cmd.includes(NOTIFY_PATH)` against the raw path is false — on macOS and
- * Linux, for a perfectly ordinary directory name.
- *
- * What follows is unrecoverable. A mark-less `Stop` entry — the case this
- * module exists for — is then not recognised as ours, so it is kept; and
- * `anythingStillNamesOurScripts`, which has no mark to fall back on, also says
- * no, so the sweep deletes `notify.mjs`. Claude Code throws
- * `Cannot find module` at the end of every turn afterwards, forever, with the
- * deck already uninstalled.
- *
- * The last two segments are fixed whatever the prefix is — the install
- * directory is always `<config dir>/agent-dag` — and they contain no character
- * any quoting rewrites. Case is folded where the filesystem folds it, which is
- * the other half: `exec.mjs`'s own `sameCommand` lowercases "because Windows
- * paths are", and this comparison did not.
- */
-const SCRIPT_TAILS = ["agent-dag/notify.mjs", "agent-dag/notify.js"];
-
-export function namesOurScript(cmd, platform = process.platform) {
-  if (typeof cmd !== "string" || cmd === "") return false;
-  // Backslashes become separators only where they ARE separators. On POSIX a
-  // backslash is an ordinary filename character, and rewriting it there could
-  // invent a match that the filesystem does not have.
-  let hay = platform === "win32" ? cmd.replace(/\\/g, "/") : cmd;
-  if (platform === "win32" || platform === "darwin") hay = hay.toLowerCase();
-  return SCRIPT_TAILS.some(tail => hay.includes(tail));
-}
-
-/** An entry this deck put there: by its mark, or by the script it runs. */
-function isOurs(entry) {
-  if (entry?.[MARK] === true) return true;
-  return commandsOf(entry).some(cmd => namesOurScript(cmd));
-}
-
-/** Anywhere in the file — not just `Stop` — that still runs one of our scripts.
- *  The sweep below asks this before deleting them: a stale sound is survivable
- *  and a hook pointing at nothing is not. */
-function anythingStillNamesOurScripts(settings) {
-  const groups = settings?.hooks;
-  if (!groups || typeof groups !== "object") return false;
-  for (const group of Object.values(groups)) {
-    if (!Array.isArray(group)) continue;
-    for (const entry of group) {
-      if (commandsOf(entry).some(cmd => namesOurScript(cmd))) return true;
-    }
-  }
-  return false;
-}
-
-function parkedError(why) {
-  const err = new Error(
-    `${PARKED_PATH} could not be read as JSON (${why}). It holds sound hooks you wrote yourself, so it ` +
-    `is not being treated as empty and it has not been deleted — repair it or move it aside, and the ` +
-    `deck will hand them back on its next start.`,
-  );
-  err.code = "PARKED_UNREADABLE";
-  err.parkedPath = PARKED_PATH;
-  return err;
-}
-
-/**
- * The hooks the toggle set aside, or a refusal.
- *
- * Only ENOENT is genuinely empty. A truncated file — a kill mid-write, a full
- * disk — used to read as "nothing was ever parked", and this is the only copy of
- * hooks a user wrote by hand: answering "restored: 0" about a file with their
- * work in it, and then deleting it, is the one unrecoverable thing in this
- * module. A JSON object rather than an array is a file that is not ours.
- */
-async function readParked() {
-  let raw;
-  try {
-    raw = await readFile(PARKED_PATH, "utf8");
-  } catch (err) {
-    if (err?.code === "ENOENT") return [];
-    throw parkedError(err?.message ?? String(err));
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw parkedError(err?.message ?? String(err));
-  }
-  if (!Array.isArray(parsed)) throw parkedError("top level is not a JSON array");
-  return parsed;
-}
-
-/** Is there anything of the retired mechanism left on this machine? Three
- *  `existsSync` calls and a scan of a settings object the caller already read —
- *  which is the whole cost of retirement on every boot after the first. */
-function anythingToRetire(settings) {
-  const group = settings?.hooks?.[EVENT];
-  if (Array.isArray(group) && group.some(isOurs)) return true;
-  if (existsSync(PARKED_PATH)) return true;
-  return OUR_SCRIPTS.some(existsSync);
-}
-
-/** Nothing here, and nothing for the caller to do afterwards. */
-const NOTHING = Object.freeze({ pending: false, changed: false, removed: 0, restored: 0, parkError: null });
-
-/**
- * Retire the sound hook inside a settings object the caller is about to write.
- *
- * Mutates `settings` and returns what it did; the caller owns the write, so a
- * boot that would otherwise change nothing still changes nothing. Call
- * `completeSoundHookRetirement` with the result AFTER settings.json is on disk —
- * that ordering is the point of the split. Until the new file has landed, the
- * old command is still what a live Claude Code session will run at the end of
- * its next turn, and deleting the script it names turns a stale sound into a
- * "Cannot find module" in the user's session.
- *
- * Never throws over the parked file. A corrupt ~/.agents-deck must not stop the
- * deck from booting, and it must not stop the urgent half either: our entry
- * points at a script that is about to be deleted, and taking it out is worth
- * doing whether or not the user's own hooks can be handed back in the same pass.
- */
-export async function retireSoundHookIn(settings) {
-  if (!anythingToRetire(settings)) return NOTHING;
-
-  let parked = [];
-  let parkError = null;
-  try {
-    parked = await readParked();
-  } catch (err) {
-    if (err?.code !== "PARKED_UNREADABLE") throw err;
-    parkError = { reason: "parked_unreadable", parkedPath: PARKED_PATH, message: err.message };
-  }
-
-  const group = Array.isArray(settings?.hooks?.[EVENT]) ? settings.hooks[EVENT] : [];
-  const theirs = group.filter(g => !isOurs(g));
-  const removed = group.length - theirs.length;
-
-  // Identical entries are not restored twice — see the note on two decks at the
-  // top. `theirs` is what will be in the file, so a hook already back from an
-  // earlier attempt (or from the other deck, a millisecond ago) is recognised.
-  //
-  // And an entry that is OURS is never restored, wherever it was found. The park
-  // is not supposed to contain one — the old toggle set aside hooks that looked
-  // hand-written and skipped its own — but "supposed to" is doing all the work
-  // in that sentence: the file is years old on some machines, it is synced
-  // between them, and the unmarked entries naming our installed script are
-  // exactly the shape a hand-written-hook filter would have swept up. Restoring
-  // one would put back the hook this whole module exists to remove, pointing at
-  // a script this release deletes, on the boot that was supposed to repair it.
-  const seen = new Set(theirs.map(g => JSON.stringify(g)));
-  const putBack = [];
-  for (const entry of parked) {
-    if (isOurs(entry)) continue;
-    const key = JSON.stringify(entry);
-    if (seen.has(key)) continue;
-    seen.add(key);
-    putBack.push(entry);
-  }
-
-  const next = [...putBack, ...theirs];
-  let changed = false;
-  if (removed > 0 || putBack.length > 0) {
-    changed = true;
-    settings.hooks ??= {};
-    if (next.length) settings.hooks[EVENT] = next;
-    else delete settings.hooks[EVENT];        // don't leave an empty array behind
-  }
-
-  return {
-    pending: true,
-    changed,
-    removed,
-    restored: putBack.length,
-    // Only when the whole park was accounted for. A read that refused leaves the
-    // file for repair, and the next boot tries again.
-    clearPark: parkError === null && existsSync(PARKED_PATH),
-    parkError,
-  };
-}
-
-/**
- * The half of retirement that must happen after settings.json is on disk.
- *
- * Deleting the parked file is safe here and only here: its contents are in the
- * file Claude Code reads. If the delete fails — a read-only ~/.agents-deck, a
- * Windows lock — the next boot reads the same park and restores nothing, because
- * the hooks it names are already in the group. That is the whole reason the
- * restore de-duplicates.
- *
- * The scripts go last, and only when nothing in settings.json still names them.
- * Retirement removes every entry that does, so the guard is normally already
- * satisfied; it exists for the file that puts one under some other event, where
- * leaving a stale sound is right and leaving a missing module is not.
- */
-export async function completeSoundHookRetirement(plan, settings) {
-  if (!plan?.pending) return { parkCleared: false, scripts: [] };
-  let parkCleared = false;
-  if (plan.clearPark) {
-    parkCleared = await rm(PARKED_PATH, { force: true }).then(() => true, () => false);
-  }
-  const scripts = [];
-  if (!anythingStillNamesOurScripts(settings)) {
-    for (const path of OUR_SCRIPTS) {
-      if (!existsSync(path)) continue;
-      if (await rm(path, { force: true }).then(() => true, () => false)) scripts.push(path);
-    }
-  }
-  return { parkCleared, scripts };
-}
-
-/**
- * Retirement for a caller that holds no settings object: `agents-deck
- * --uninstall`, which is taking the deck off the machine rather than upgrading
- * it, and where there is no hook install to ride along with.
- *
- * Same three steps in the same order — read, mutate, write, then clean up — so
- * there is one description of what retirement is rather than two that can drift.
- */
-export async function retireSoundHook() {
-  let settings;
-  try {
-    ({ settings } = await readSettingsForWrite(SETTINGS_PATH));
-  } catch (err) {
-    if (err?.code !== "SETTINGS_UNREADABLE") throw err;
-    // A file we cannot parse is a file whose contents we cannot reproduce, and
-    // this rewrites the whole of it. Left exactly as found, parked hooks still
-    // parked, and the user told which file and why.
-    return {
-      ok: false,
-      reason: "settings_unreadable",
-      settingsPath: SETTINGS_PATH,
-      why: err.why ?? err.message,
-      message: err?.message ?? String(err),
-      removed: 0,
-      restored: 0,
-    };
-  }
-
-  const plan = await retireSoundHookIn(settings);
-  if (plan.changed) await writeFileAtomic(SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
-  await completeSoundHookRetirement(plan, settings);
-
-  if (plan.parkError) return { ok: false, ...plan.parkError, removed: plan.removed, restored: plan.restored };
-  return { ok: true, removed: plan.removed, restored: plan.restored };
-}
-
-// Exported so a test can prove it is pointed at a sandbox before it writes
-// anything — the real ones are the user's own settings and the user's own hooks.
-// The script paths are also the only honest way to ask where the retired script
-// ACTUALLY lived: rebuilding `<config dir>/agent-dag/notify.mjs` inside a test
-// would keep passing on the day this module started looking somewhere else.
-export { SETTINGS_PATH, PARKED_PATH, NOTIFY_PATH, LEGACY_NOTIFY_PATH };

package/src/server/running-deck.mjs

@@ -1,234 +0,0 @@
-// Why a second `ccdeck` must not quietly become a second deck.
-//
-// THE DEFECT. `startServer` is handed `portRange: [4318, 4400]` and answers a
-// refused bind on 4317 by taking a random port out of it. That fallback is
-// right and stays: 4317 is also the standard OTLP collector port, and on
-// Windows `winnat` reserves contiguous TCP blocks for Hyper-V, WSL2 and Docker
-// Desktop, so 4317 can be unavailable on a machine with nothing listening on it
-// at all. A deck that comes up on 4322 beats a deck that refuses to come up.
-//
-// What was wrong is that the SAME fallback ran when the thing holding 4317 was
-// another ccdeck. Typing `ccdeck` a second time therefore built a second
-// everything — supervisor, worker, server, hook registration, LAN identity,
-// browser tab — beside a perfectly healthy first one, and neither said a word
-// about the other. Twenty of them were counted on one machine.
-//
-// THE QUESTION IS NOT "IS THE PORT FREE". It is "is one of MY decks already
-// running", and the registry answers that without touching a port: every deck
-// writes ~/.claude/agent-dag/<pid>.json with its pid, port, token and shape.
-//
-// A PID IS NOT EVIDENCE, and that is #695's whole lesson. A record left behind
-// by a deck that is gone — SIGKILL, an OOM kill, a power cut, a console window
-// closed on Windows, none of which run the shutdown that unlinks it — passes a
-// signal-0 probe forever once the OS recycles that number, and the port it
-// names may by then belong to anything. So the port has to prove itself: the
-// record carries the deck's own token in plaintext (mode 0600, same user,
-// written there precisely so another process can challenge with it), and
-// challengeDeck asks that port to hash the token against a nonce it has never
-// seen. A collector, a container, a stranger on a recycled port cannot answer.
-// The deck that wrote the file can.
-//
-// THE DECK FOUND MUST ALSO BE THE DECK WE WOULD HAVE BUILT. Attaching a plain
-// `ccdeck` to a deck started with `--workspace ~/proj` would open a canvas
-// filtered to a directory the user never mentioned, and attaching to a
-// `--no-claude` deck would open one with no accounts panel and no hooks. So the
-// shape is compared field for field, and anything that does not match starts
-// its own deck exactly as before.
-//
-// WHAT THIS FILE DOES NOT IMPORT: src/server/index.mjs. That module is the whole
-// server, and it arms its timers the moment it is loaded — but this one is read
-// on the boot path, and by `ccdeck --stop`, which is a command that talks to a
-// deck and exits. Starting a server to ask a server to stop is absurd on its
-// face and, on a cold start, slower than the thing it is asking for. The
-// handshake and the liveness probe therefore live in deck-probe.mjs, a leaf
-// that imports two node builtins; index.mjs takes them from the same place and
-// re-exports them, so there is still exactly one spelling in the package.
-import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { claudeConfigDir } from "./claude-dir.mjs";
-import { challengeDeck, isProcessAlive } from "./deck-probe.mjs";
-
-/**
- * Where every deck on this machine registers itself.
- *
- * Still under ~/.claude, and deliberately: deck-home.mjs moved the deck's own
- * state out of Claude Code's directory and left exactly two things behind, of
- * which this is one. A deck of any version has to be able to list the others,
- * and an older deck reads this directory by name — move it and two versions
- * running side by side stop seeing each other, which is precisely the blindness
- * this module exists to end.
- */
-export function deckRegistryDir(env = process.env, home = undefined) {
-  return join(home === undefined ? claudeConfigDir(env) : claudeConfigDir(env, home), "agent-dag");
-}
-
-/**
- * The flags that mean "I want a deck of my own", as opposed to "show me the
- * deck".
- *
- * Every one of them changes what the deck IS — which sessions it captures,
- * which log it appends to, which of the two CLIs it serves, which port it
- * binds. A command line carrying any of them is a request that an existing deck
- * cannot satisfy, so it is never answered by attaching to one.
- *
- * `--no-open` is deliberately absent: it changes what the LAUNCHER does once it
- * has a URL, not what the deck is, and it is honoured on the attach path too.
- * `--all` is absent because it has been a no-op since it became the default.
- */
-export const SHAPING_FLAGS = Object.freeze([
-  "port", "workspace", "scope", "history", "noPersist",
-  "codex", "noCodex", "claude", "noClaude",
-]);
-
-/**
- * Is this command line one that must build its own deck?
- *
- * Only a shaping flag, and `--new` — the deliberate escape hatch for the person
- * who really does want two.
- *
- * A TYPO IS NOT ONE, and the first version of this had it the other way round.
- * `unknown` and `incomplete` both forced a new deck, on the argument that an
- * attach prints no startup report and would swallow the warning that names the
- * bad token. The consequence of that argument was `ccdeck --stpo` — a typo in
- * the flag that STOPS a deck — building a second one, which is the exact
- * outcome this whole module exists to prevent, reached through the guard meant
- * to protect it.
- *
- * The warning was the real requirement, not the new process, so the attach path
- * prints it instead: see the call to reportUnknownFlags beside the attach in
- * bin/deck.js. Nothing is swallowed, and no misspelling can leave a rival deck
- * on a random port behind it.
- */
-export function asksForOwnDeck(flags = {}) {
-  if (flags.new === true) return true;
-  return SHAPING_FLAGS.some((k) => flags[k] !== undefined);
-}
-
-/**
- * Would this record's deck serve what we were about to build?
- *
- * Compared field for field rather than by a version or a heuristic. `claude`
- * and `codex` are strict identity against a boolean, so a record written before
- * either field existed carries `undefined`, fails, and its deck is left alone —
- * which is the old behaviour, reached by construction rather than by a version
- * check nobody would remember to update.
- */
-export function sameShape(record, want = {}) {
-  if (!record) return false;
-  return (record.workspace ?? "") === (want.workspace ?? "")
-    && (record.persist ?? null) === (want.persist ?? null)
-    && record.codex === (want.codex !== false)
-    && record.claude === (want.claude !== false);
-}
-
-/** A record complete enough to be worth a challenge. A missing token is a deck
- *  older than the handshake: it cannot prove anything, so it cannot be attached
- *  to, and it keeps the behaviour it has always had. */
-function usable(d) {
-  return Boolean(d)
-    && Number.isInteger(d.pid)
-    && Number.isInteger(d.port) && d.port > 0 && d.port < 65536
-    && typeof d.token === "string" && d.token !== "";
-}
-
-/**
- * Every registered deck whose pid is still there, ordered.
- *
- * NOT PROVED — this is the cheap half, a directory listing and a signal-0 each,
- * and its three callers want different things from it. `detach.mjs` wants only
- * the count, to decide whether deck.log belongs to a deck that is still running
- * or to nobody; a round trip per record to answer that would be absurd. Ordered by port with pid breaking the tie, which is the rule
- * electWriters uses for the log and is here for the same reason: several decks
- * can qualify, and the answer has to be the same one every time it is asked
- * rather than whatever `readdir` happened to return first.
- *
- * A failure to read the directory is "no decks", not an error. This runs on the
- * boot path of a program whose job is to start, and there is no reading of that
- * directory whose failure is worth refusing to start over.
- */
-export async function registeredDecks({
-  dir = deckRegistryDir(),
-  fs = { readdir, readFile },
-  self = process.pid,
-  alive = isProcessAlive,
-} = {}) {
-  let names;
-  try { names = await fs.readdir(dir); } catch { return []; }
-  const out = [];
-  for (const name of names) {
-    if (!name.endsWith(".json")) continue;
-    let d;
-    try { d = JSON.parse(await fs.readFile(join(dir, name), "utf8")); } catch { continue; }
-    if (!usable(d)) continue;
-    if (d.pid === self) continue;
-    if (!alive(d.pid)) continue;
-    out.push(d);
-  }
-  return out.sort((a, b) => a.port - b.port || a.pid - b.pid);
-}
-
-/**
- * The deck already serving what this process was about to serve, or null.
- *
- * Only records that already match the shape are challenged, and the walk stops
- * at the first that proves itself. On the ordinary machine that is one loopback
- * round trip; on a machine with no deck running it is a directory listing and
- * nothing else. That is why this is not `liveDecks().find(…)`: the boot path
- * must not pay a round trip per deck to answer a question the first one settles.
- */
-export async function runningDeck({
-  want = {},
-  dir = deckRegistryDir(),
-  fs = { readdir, readFile },
-  self = process.pid,
-  alive = isProcessAlive,
-  prove = challengeDeck,
-} = {}) {
-  for (const d of await registeredDecks({ dir, fs, self, alive })) {
-    if (!sameShape(d, want)) continue;
-    if (await prove(d.port, d.token)) return d;
-  }
-  return null;
-}
-
-/**
- * Every deck on this machine that answered a challenge, in port order.
- *
- * The list `--status` prints and the list `--stop` chooses from. Everything is
- * challenged here, unlike runningDeck: a list that quietly omitted a deck it
- * could not be bothered to ask about would be worse than no list, because the
- * whole reason to run `--status` is to find the process you did not know was
- * there. The round trips go out together — one deadline for the lot, not one
- * after another — since they are independent and each is bounded at 400ms.
- */
-export async function liveDecks({
-  dir = deckRegistryDir(),
-  fs = { readdir, readFile },
-  self = process.pid,
-  alive = isProcessAlive,
-  prove = challengeDeck,
-} = {}) {
-  const all = await registeredDecks({ dir, fs, self, alive });
-  const proved = await Promise.all(all.map(d => prove(d.port, d.token).then(ok => (ok ? d : null))));
-  return proved.filter(Boolean);
-}
-
-/**
- * What to say about the version of the deck we attached to.
- *
- * A mismatch does NOT stop the attach, and that is the deliberate half. Someone
- * who runs `npx ccdeck@latest` while an older deck is up has asked for the new
- * one, but the way to give it to them is not to stand a rival deck on a random
- * port beside the old one — that is the failure this whole module removes. So
- * they are attached and TOLD, with the one sentence that gets them the version
- * they asked for.
- *
- * Empty when the versions agree, and empty when the running deck is too old to
- * report one: "unknown" beside a number is noise, and there is nothing useful
- * to do about it either way.
- */
-export function versionNote(running, ours) {
-  if (typeof running !== "string" || running === "" || typeof ours !== "string" || ours === "") return "";
-  if (running === ours) return "";
-  return `running v${running}, you launched v${ours} — restart it from the deck to upgrade`;
-}