agent-dag 1.44.1 → 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:
 

package/bin/agent-dag.js

@@ -42,7 +42,7 @@ import {
   bareSpecName, claimRestartFailureKey, clearRestartFailure, installedName, installedVersion,
   lastKnownLatest, npxRestartSpec, readRestartFailure, recordRestartFailure, successorRoot,
 } from "../src/server/self-update.mjs";
-import { dieOfSignal, replacedNote, 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";
 
@@ -478,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,
@@ -89,22 +89,34 @@ if (flags.uninstall) {
       : `${PRODUCT}: no ${label} hooks to remove`);
   };
   report(await uninstallHooks({ provider: "claude" }), "Claude");
-  // The sound toggle is a second entry in the same file, marked
+  // 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) {
     refused = true;
-    console.error(named.has(sound.settingsPath)
-      ? `${PRODUCT}: the sound hook is still in that file too.`
-      : `${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)`);
+    // 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()) {
     report(await uninstallHooks({ provider: "codex" }), "Codex");
@@ -119,7 +131,27 @@ if (flags.uninstall) {
   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.
@@ -241,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);
 
@@ -645,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
@@ -725,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
@@ -736,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.
@@ -937,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
 
@@ -964,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.
 `);
 }