agent-dag 1.43.0 → 1.45.0

package/README.md

@@ -135,7 +135,9 @@ them, the other one's hooks, installs and panels are skipped rather than shown
 empty — the boot banner says which way it went, and `--claude` / `--codex`
 override it if the guess is wrong.
 
-`--workspace` is a filter this deck applies to itself, not a claim on the sessions it matches: **every** running deck whose workspace contains a session's directory draws that session, so a machine-wide deck and one scoped to `~/proj` both show the agents working inside `~/proj`. It reads the same way on both capture paths — Claude Code's hook and Codex's rollout files — and the events log still gets exactly one copy of each event, whichever decks are up. A relative path is resolved against the directory you start the deck in, and once, so both paths scope to the same tree.
+`--workspace` is a filter this deck applies to itself, not a claim on the sessions it matches: **every** running deck whose workspace contains a session's directory draws that session, so a machine-wide deck and one scoped to `~/proj` both show the agents working inside `~/proj`. It reads the same way on all three paths a session can reach the canvas by — Claude Code's hook, Codex's rollout files, and the boot replay of the events log — and the events log still gets exactly one copy of each event, whichever decks are up. A relative path is resolved against the directory you start the deck in, and once, so every path scopes to the same tree. The log is machine-wide by default and shared by every deck on the box, so a scoped deck replays only the part of it that is inside its own workspace: it comes up showing what it will go on to capture, and nothing else.
+
+That one events log is also the reason Clear is not quite the per-deck button it looks like. The decks elect a single writer for each log file, and only that deck may empty it: Clear on any other deck wipes its own canvas and leaves the file to the deck that writes it. The confirmation says which of the two you are about to do, and how many decks share the log when it is yours to empty — so `--history` or `--no-persist` gives a deck a log of its own if you want Clear to answer to nobody else.
 
 Environment:
 
@@ -180,7 +182,7 @@ What the banner offers depends on how this copy was installed:
 
 | Installed as | Offer |
 |---|---|
-| global npm install | **Update now** — runs `npm install -g agents-deck@latest`, then restarts once nothing is running |
+| global npm install | **Update now** — runs `npm install -g` on the name you installed (`ccdeck`, `agents-deck` or `agent-dag`), 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 |
 | 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 |
@@ -208,14 +210,18 @@ under three, and `npx` runs the same deck from any of them.
 
 ```bash
 npx ccdeck        # this repo's name — the short one
-npx agents-deck   # the canonical npm package (in-app updates install this one)
+npx agents-deck   # the name it shipped under before the rename
 npx agent-dag     # the original name; existing installs and scripts keep working
 ```
 
-A global install is the one place the three differ. `agents-deck` and
-`agent-dag` are one build published twice, so `npm i -g` on either puts all
-three commands on your `PATH`. `ccdeck` is a thin package that depends on
-`agents-deck` and ships only the `ccdeck` command.
+The three are one build published three times, so they behave identically:
+`npx` on any of them fetches a single package, and `npm i -g` on any of them
+puts all three commands on your `PATH`.
+
+`ccdeck` was the exception until recently — a thin package that depended on
+`agents-deck` and spawned its binary. It worked, but `npx ccdeck` downloaded two
+packages instead of one and a global `ccdeck` ran under the old package's name.
+It is now the same build as the other two.
 
 The repository was previously named `agents-deck`; the old URL redirects here,
 so existing clones, links and bookmarks keep working.

package/bin/agent-dag.js

@@ -31,6 +31,7 @@
 // Everything else the deck does still lives in bin/deck.js. This file must stay
 // boring: it is the one process that is never replaced.
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { connect } from "node:net";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -38,10 +39,10 @@ import { killTree } from "../src/server/exec.mjs";
 import { invokedAs } from "../src/server/invoked-as.mjs";
 import { npxFailureHint, npxFailureSummary, npxLaunch, npxPrefetch } from "../src/server/npx.mjs";
 import {
-  bareSpecName, claimRestartFailureKey, clearRestartFailure, installedVersion, lastKnownLatest,
-  npxRestartSpec, readRestartFailure, recordRestartFailure,
+  bareSpecName, claimRestartFailureKey, clearRestartFailure, installedName, installedVersion,
+  lastKnownLatest, npxRestartSpec, readRestartFailure, recordRestartFailure, successorRoot,
 } from "../src/server/self-update.mjs";
-import { dieOfSignal, upgradeAttempt, upgradeRefusalText, workerExitAction } from "../src/server/supervisor.mjs";
+import { dieOfSignal, dieWithParent, replacedNote, upgradeAttempt, upgradeRefusalText, workerExitAction } from "../src/server/supervisor.mjs";
 import { colorProfile, glyphs, palette, unicodeOK } from "../src/server/term.mjs";
 import { PRODUCT } from "../src/server/brand.mjs";
 
@@ -101,6 +102,19 @@ let attempting = null;
 let stopping = false;
 
 function launch(respawn) {
+  // Asked on every spawn rather than once at boot: the deletion this catches
+  // happens while the deck is running, so a constant read at import time would
+  // be the one answer that cannot see it. See supervisor.mjs for the whole case.
+  const replaced = replacedNote({
+    workerExists: existsSync(WORKER),
+    moved: successorRoot(PKG_ROOT),
+    product: PRODUCT,
+    command: INVOKED_AS ?? PRODUCT,
+  });
+  if (replaced) {
+    console.error(replaced);
+    process.exit(1);
+  }
   const args = [WORKER, ...process.argv.slice(2)];
   // Appended last so it wins: the worker's parser keeps the final --port.
   if (respawn && boundPort != null) args.push("--port", String(boundPort));
@@ -188,6 +202,43 @@ function withoutPortAndOpen(args) {
   return out;
 }
 
+/**
+ * Which package an npx upgrade here names, and the spec that installs it — or
+ * null when this deck was not started by npx and there is nothing to re-run.
+ *
+ * One function because there is one answer, and the worker above us reaches it
+ * independently: `upgradeName` in self-update.mjs resolves the npx case as
+ * `bareSpecName(npxRestartSpec(pkgRoot, installedName(pkgRoot)))`, and
+ * everything registry-shaped on that side — the dist-tag it fetched, the marker
+ * it cached the answer in, the failure note the browser reads — is keyed by it.
+ * This supervisor keyed the same four things off `npxRestartSpec(PKG_ROOT)`
+ * with the module's own default, which is the literal string "agents-deck".
+ *
+ * Both read `_npx/<hash>/package.json`, so they agreed for as long as that
+ * metadata was readable, and #340 made the disagreement matter when it is not:
+ * the three names are one tarball now, so the manifest under a `npx ccdeck` run
+ * genuinely says `ccdeck` where it once always said `agents-deck`. A cache
+ * directory written by an npm whose `_npx.packages` layout differs — or a
+ * truncated file — split the two apart: the worker asked npm about `ccdeck` and
+ * read `.restart-failed-ccdeck-<pid>` while this process wrote
+ * `.restart-failed-agents-deck-<pid>`, took `lastKnownLatest("agents-deck")`
+ * off a marker nobody had written — so `target` was null and upgradeAttempt's
+ * per-target cap degraded to "any failure counts" — and relaunched
+ * `npx -y agents-deck@latest`, moving a `npx ccdeck` user onto a different
+ * published name. The note went where the browser never looks, which is the
+ * exact class of bug NOTE_PREFIX's naming exists to prevent.
+ *
+ * So the fallback is the name npm's rename wrote into this build's own manifest,
+ * which is what the worker falls back to as well. Read on each call rather than
+ * once at import for the reason installedVersion gives: the manifest is a file
+ * on disk, and this process outlives more than one of them.
+ */
+function npxUpgrade() {
+  const self = installedName(PKG_ROOT);
+  const spec = npxRestartSpec(PKG_ROOT, self);
+  return spec ? { spec, pkgName: bareSpecName(spec) ?? self } : null;
+}
+
 /** The note the browser reads, written by the only process that knows why an
  *  upgrade did not happen. `failedAt` is when the FETCH failed, which a refusal
  *  restating an earlier failure carries forward — see upgradeAttempt. */
@@ -227,11 +278,11 @@ async function prefetchUpgrade(worker) {
   if (stopping || fetching || attempting) return;
   const reply = (msg) => { try { worker.send?.(msg); } catch { /* the worker is gone */ } };
 
-  const spec = npxRestartSpec(PKG_ROOT);
+  const upgrade = npxUpgrade();
   // Not an npx run after all, so there is nothing to fetch and the files on
   // disk are already the newest this deck can reach.
-  if (!spec) { reply({ type: "upgrade-refused", error: "this deck was not started by npx" }); return; }
-  const pkgName = bareSpecName(spec) ?? "agents-deck";
+  if (!upgrade) { reply({ type: "upgrade-refused", error: "this deck was not started by npx" }); return; }
+  const { spec, pkgName } = upgrade;
   // What the banner offered, straight off the marker the version check writes.
   // The note is keyed by it so that "this exact version already failed here" is
   // a question anything can answer — and so a newer release clears the slate.
@@ -284,8 +335,12 @@ async function prefetchUpgrade(worker) {
  * down), and someone has to bring the working copy back when it does.
  */
 function launchNpx() {
-  const spec = npxRestartSpec(PKG_ROOT);
-  if (!spec) { launch(true); return; } // not an npx run after all
+  const upgrade = npxUpgrade();
+  if (!upgrade) { launch(true); return; } // not an npx run after all
+  // The same package prefetchUpgrade fetched and the worker asked npm about —
+  // one answer, so the spec that is run, the note that records it and the
+  // marker its target came from all name one package. See npxUpgrade.
+  const { spec, pkgName } = upgrade;
   // Our two are appended, so the originals are dropped rather than left to be
   // overridden — `--port 4317 --no-open --port 4317 --no-open` works, but it is
   // what the next person reads in `ps`.
@@ -298,7 +353,6 @@ function launchNpx() {
   // A retry answers for itself: whatever the last attempt left on disk is about
   // to be replaced by this attempt's outcome, and leaving it there would keep
   // the browser showing an old failure over a running fetch.
-  const pkgName = bareSpecName(spec) ?? "agents-deck";
   clearRestartFailure(pkgName);
 
   // No "fetching…" line here any more: prefetchUpgrade printed it and the
@@ -424,4 +478,28 @@ for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
   });
 }
 
+// And the same leash the worker is on, one link up (#702).
+//
+// Inert for every published way of starting the deck: `ccdeck`, `npx ccdeck` and
+// the npx relaunch in launchNpx all spawn this file with no IPC channel, so
+// dieWithParent declines to arm and this line costs nothing. It is armed by a
+// harness that DOES hand one over — the suite's spawnSupervised — and what it
+// buys there is the case no teardown can cover, because the teardown is not
+// running: a vitest worker killed outright leaves this supervisor orphaned, and
+// an orphaned supervisor keeps a worker alive under it.
+//
+// Taking the worker with us is the whole of the stop. `stopping` first, so the
+// worker's exit is not read as a request to bring it back; the kill is the
+// signal on POSIX and, through killTree, `taskkill /T /F` on Windows, which has
+// neither SIGTERM nor a process group to aim at.
+dieWithParent(() => {
+  stopping = true;
+  if (fetching) { killTree(fetching, "SIGTERM"); fetching = null; }
+  if (child) killTree(child, "SIGTERM");
+  // Long enough for the worker to unregister its discovery file and let the
+  // port go, short enough that nothing is waiting on us. Unref'd: if the worker
+  // leaves first its exit handler ends this process and the timer never fires.
+  setTimeout(() => process.exit(0), 3000).unref();
+});
+
 launch(false);

package/bin/deck.js

@@ -7,8 +7,8 @@
 import { resolve, dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { existsSync, readFileSync } from "node:fs";
-import { dieOfSignal } from "../src/server/supervisor.mjs";
-import { parseArgs } from "../src/server/args.mjs";
+import { dieOfSignal, dieWithParent } from "../src/server/supervisor.mjs";
+import { isPortValue, parseArgs } from "../src/server/args.mjs";
 import {
   CURSOR_HIDE, CURSOR_SHOW, colorProfile, fit, glyphs, labelColumn, link, motionOK, oneLine,
   palette, pulseText, spinnerFrames, statusLine, supportsHyperlinks, termColumns, unicodeOK,
@@ -64,34 +64,94 @@ if (flags.version) {
 
 if (flags.uninstall) {
   const { uninstallHooks, hasCodexInstalled } = await import(pathToFileURL(join(PKG_ROOT, "src/server/installer.mjs")).href);
-  const claude = await uninstallHooks({ provider: "claude" });
-  console.log(claude.changed
-    ? `${PRODUCT}: hooks removed from ${claude.settingsPath}`
-    : `${PRODUCT}: no Claude hooks to remove`);
-  // The sound toggle is a second entry in the same file, marked
+  // Anything that could not be taken out. An uninstall that removed nothing
+  // because it could not read the file has not uninstalled anything, and both
+  // the wording and the exit code have to say so: a user who is told it worked
+  // and still has our hooks firing on every event is worse off than one who is
+  // told it failed, because they have stopped looking.
+  let refused = false;
+  // Files already reported as unparseable. The Claude hooks and the sound hook
+  // live in the SAME settings.json, so a stray comma refuses both, and printing
+  // the whole path-plus-parser-error twice buries the one line that differs —
+  // which of our two installations is still in there.
+  const named = new Set();
+  /** Report one provider's outcome. `ok` first — see uninstallHooks. */
+  const report = (res, label) => {
+    if (res.ok === false) {
+      refused = true;
+      named.add(res.settingsPath);
+      console.error(`${PRODUCT}: ${label} hooks NOT removed — ${res.settingsPath} could not be read as JSON (${res.why}).`);
+      console.error(`${PRODUCT}: the __agent-dag hook entries are still in that file and keep firing on every ${label} event.`);
+      return;
+    }
+    console.log(res.changed
+      ? `${PRODUCT}: hooks removed from ${res.settingsPath}`
+      : `${PRODUCT}: no ${label} hooks to remove`);
+  };
+  report(await uninstallHooks({ provider: "claude" }), "Claude");
+  // The old finish sound was a second entry in the same file, marked
   // __agent-dag-sound rather than __agent-dag, and uninstallHooks does not know
   // that mark — so it used to be left behind, playing on every turn after the
-  // deck was supposedly gone. It also parks the user's own afplay/PowerShell
-  // Stop hooks while it is on, and once the deck is uninstalled nothing else can
-  // put them back, so this restores them too.
-  const { uninstallSoundHook } = await import(pathToFileURL(join(PKG_ROOT, "src/server/sound-hook.mjs")).href);
-  const sound = await uninstallSoundHook();
+  // deck was supposedly gone. #704 retired the mechanism outright, but the entry
+  // is still on every machine that had it, so removing it is still this
+  // command's job. So is the other half: turning the sound on parked the user's
+  // own afplay/PowerShell Stop hooks, and once the deck is uninstalled nothing
+  // else on the machine knows where they went.
+  const { retireSoundHook } = await import(pathToFileURL(join(PKG_ROOT, "src/server/retire-sound-hook.mjs")).href);
+  const sound = await retireSoundHook();
+  if (sound.removed) console.log(`${PRODUCT}: sound hook removed`);
+  if (sound.restored) console.log(`${PRODUCT}: restored ${sound.restored} of your own sound hook(s)`);
   if (sound.ok === false) {
-    console.error(`${PRODUCT}: sound hook left in place — ${sound.message}`);
-  } else {
-    if (sound.removed) console.log(`${PRODUCT}: sound hook removed`);
-    if (sound.restored) console.log(`${PRODUCT}: restored ${sound.restored} of your own sound hook(s)`);
+    refused = true;
+    // Two different refusals, and saying the wrong one sends the user to the
+    // wrong file. `settings_unreadable` means nothing was touched at all — and
+    // when the forwarders already named that same file, the whole path and
+    // parser error would only bury the one line that differs. `parked_unreadable`
+    // is the other file: our entry IS out (the lines above said so), and what is
+    // still owed is the user's own hooks, which stay parked until they repair it.
+    if (sound.reason === "settings_unreadable") {
+      console.error(named.has(sound.settingsPath)
+        ? `${PRODUCT}: the sound hook is still in that file too.`
+        : `${PRODUCT}: sound hook left in place — ${sound.message}`);
+      named.add(sound.settingsPath);
+    } else {
+      console.error(`${PRODUCT}: your own sound hooks were NOT restored — ${sound.message}`);
+    }
   }
   if (hasCodexInstalled()) {
-    const codex = await uninstallHooks({ provider: "codex" });
-    console.log(codex.changed
-      ? `${PRODUCT}: hooks removed from ${codex.settingsPath}`
-      : `${PRODUCT}: no Codex hooks to remove`);
+    report(await uninstallHooks({ provider: "codex" }), "Codex");
   }
-  process.exit(0);
+  // The remedy last and once, after every symptom above it, rather than once
+  // per refusal in the middle of the list.
+  if (named.size > 0) {
+    console.error(`${PRODUCT}: repair the JSON (or move the file aside), then run \`${PRODUCT} --uninstall\` again.`);
+  }
+  // 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.
+  process.exit(refused ? 1 : 0);
 }
 
-const port = Number(flags.port ?? process.env.AGENT_DAG_PORT ?? 4317);
+// The port, and the one piece of argv the deck really does refuse to boot over.
+//
+// It refused before too — `--port banana` and `--port --no-open` both became
+// `Number(…)` → `NaN`, which survived the whole startup (hooks installed,
+// claude-swap installed, ccusage probed) and then killed the process from inside
+// `listen` with Node's own wording: "options.port should be >= 0 and < 65536.
+// Received type number (NaN)." That names neither the flag nor the value the
+// user typed, and arrives after a page of green ticks. Same outcome, said here:
+// early, in the deck's own voice, quoting the flag and the value back.
+//
+// An empty `AGENT_DAG_PORT` is an unset one — a variable that did not expand is
+// not a request for port zero. `--port ""` never reaches this, because the
+// parser records an empty value as `incomplete` and leaves the flag unset.
+const envPort = process.env.AGENT_DAG_PORT?.trim();
+const rawPort = flags.port ?? (envPort ? envPort : null);
+if (rawPort != null && !isPortValue(rawPort)) {
+  const named = flags.port != null ? "--port" : "AGENT_DAG_PORT";
+  console.error(`${PRODUCT}: ${named} ${rawPort}: not a port number — expected 0–65535.`);
+  process.exit(1);
+}
+const port = rawPort == null ? 4317 : Number(rawPort);
 // Default = machine-wide (capture every CC session on this box). Pass
 // `--workspace <path>` (or `--scope`) to restrict to a single tree. Canonicalized
 // just below, once the module that owns that rule is loaded.
@@ -213,6 +273,7 @@ process.on("SIGHUP", () => { showCursor(); dieOfSignal("SIGHUP"); });
 const LABELS = [
   "workspace", "Claude hooks", "Codex sessions", "claude-swap", "accounts",
   "ccusage", "update", "name", "server ready", "log", "unknown option",
+  "missing value",
 ];
 const LABEL_W = labelColumn(LABELS);
 
@@ -617,6 +678,22 @@ let server = null;
 let discovery = null;
 let discoveryFile = null;
 
+// This worker does not outlive the supervisor that started it (#702).
+//
+// Armed HERE rather than beside the signal handlers at the bottom of the file,
+// for the reason the three `let`s above are where they are: this is the first
+// line from which `shutdown` can be called without dying of a temporal dead
+// zone, and the window that matters is the boot — the supervisor can be killed
+// while the report is still printing, and a worker orphaned in there is a
+// worker that binds its port a moment later and then holds it for a day.
+//
+// A no-op with nothing supervising us, which is `node bin/deck.js` run by hand:
+// dieWithParent arms only when there is a channel, the same question SUPERVISED
+// asks above. Shutdown code 0 because there is nobody left to read it — the
+// point is only that discovery is unregistered and the port let go of on the
+// way out, rather than left for the next boot's stale sweep.
+dieWithParent(() => shutdown(0));
+
 // The listen, begun HERE and awaited below the startup report rather than after
 // it. The report is a narration; the port is the product, and it was queued
 // behind three tool probes for no reason but the order these two statements
@@ -697,6 +774,7 @@ if (RESPAWN) {
   // and then went quiet for every restart afterwards is back to hiding it from
   // anyone who was not watching the first boot.
   reportUnknownFlags(flags.unknown);
+  reportIncompleteFlags(flags.incomplete);
 } else {
   // The URL is the one detail an ellipsis would destroy — half an address is
   // not a shorter address — so it keeps its own line when the terminal is too
@@ -708,6 +786,7 @@ if (RESPAWN) {
   if (persist) write(row({ label: "log", detail: fileLink(persist) }));
   // Last of the rows, on purpose — see reportUnknownFlags.
   reportUnknownFlags(flags.unknown);
+  reportIncompleteFlags(flags.incomplete);
   // Only when one is actually being opened. Under --no-open — which is how an
   // npx update relaunches, with a tab already waiting — this was announcing
   // something that never happened.
@@ -909,6 +988,33 @@ function reportUnknownFlags(unknown) {
   }
 }
 
+/**
+ * Every value-taking flag that was given no value it could use, named, one row
+ * each — and printed beside the unknown ones because it is the same failure
+ * wearing a different hat.
+ *
+ * #697: `--workspace`, `--history` and `--port` used to consume the following
+ * token whatever it was, so `ccdeck --workspace $PROJ --no-persist` with `PROJ`
+ * unset scoped the deck to a directory called `--no-persist`, kept persisting to
+ * the shared log, and reported neither. Nothing landed in `unknown`, because the
+ * token that belonged there had been eaten. The parser refuses that value now
+ * and lists the flag here instead.
+ *
+ * Said rather than acted on, under exactly the argument reportUnknownFlags makes
+ * above: the flag falls back to its documented default and the deck still boots.
+ * The row is what makes the fallback a decision the user can see, and the rows
+ * around it show its consequence — `workspace (all)` and the `log` line are
+ * printed by the same report.
+ */
+function reportIncompleteFlags(incomplete) {
+  for (const { flag, expects } of incomplete ?? []) {
+    write(row({
+      mark: G.warn, tone: P.warn, label: "missing value",
+      detail: `${flag} ${G.dash} expected ${expects}; using the default`,
+    }));
+  }
+}
+
 function printHelp() {
   process.stdout.write(`${PRODUCT} — live deck of Claude Code + Codex agents
 
@@ -936,5 +1042,10 @@ Options:
 
 Anything else on the command line is reported as an unknown option and then
 ignored: the deck still starts.
+
+A flag that takes a value never swallows the next flag. If the value is missing,
+empty, or itself looks like a flag — \`${PRODUCT} --workspace \$UNSET --no-persist\`
+after the shell has dropped an unset variable — the flag is reported, left on its
+default, and the token it would have eaten is parsed as the flag it is.
 `);
 }