agent-dag 3.18.3 → 3.20.0

package/README.md

@@ -165,11 +165,22 @@ ccdeck [options]
 
   -p, --port <number>      Preferred port  (default: 4317; fallback: random 4318–4400)
       --no-open            Don't open the browser automatically
+      --foreground         Hold the terminal, the way every version before 3.20
+                           did (Ctrl+C stops the deck again)
+      --new                Start a second deck even if one is already running
+      --stop               Stop the deck a bare `ccdeck` would open
+                           (--port <n> stops that one; --all stops every deck)
+      --status             What is running on this machine, and on which ports
+      --logs               What a backgrounded deck wrote where a terminal would
+                           have shown it
       --workspace <path>   Only capture sessions whose cwd is inside <path>
       --scope              Restrict to the current working directory
       --all                Capture every session on this machine  (default)
+                           (beside --stop: every deck, not every session)
       --history <path>     Override the events log file
-                           (default: ~/.claude/agent-dag/events.jsonl)
+                           (default: this platform's log directory —
+                           ~/Library/Logs/ccdeck on macOS, %LOCALAPPDATA%\ccdeck\Log
+                           on Windows, $XDG_STATE_HOME/ccdeck on Linux)
       --no-persist         RAM-only mode — don't write or replay the log
       --codex              Force Codex capture even if ~/.codex/ is missing
       --no-codex           Skip Codex capture (Claude only)
@@ -185,6 +196,57 @@ Anything else on the command line is reported as an unknown option and then
 ignored — the deck still starts, so a typo costs you a warning rather than a
 dashboard.
 
+`--foreground` is there for anything that was relying on the old behaviour — a
+wrapper script, a CI step, a supervisor of your own that starts the deck and
+waits on it. On the first run after upgrading you may also see a line about a
+deck from an older version still running: those publish nothing this one can
+check, so it starts beside them rather than attaching to something it cannot
+identify, and `ccdeck --stop --all` clears them.
+
+`ccdeck` runs in the background. The boot report prints in your terminal exactly
+as it always has — the hooks, the port, the URL — and then the prompt comes back
+and the deck stays up: closing the window does not take it with you any more,
+because it is in its own process group and the terminal's hangup never reaches
+it. `ccdeck --stop` ends it, `ccdeck --status` says what is running, and
+`ccdeck --logs` shows what it wrote after you stopped watching. Ctrl+C while the
+boot is still printing cancels the start, which is the one thing it still means.
+
+One Windows exception, and it is `ssh`'s rather than the deck's: OpenSSH puts a
+session's processes in a job object that it kills when the session ends, and
+nothing started from inside one survives it. A deck started from an ordinary
+Windows terminal, or by the login task below, keeps running — measured on a real
+machine, from a second SSH session, still serving.
+
+It also starts when you log in, so a reboot does not cost you the morning's
+events. That is set up once, on the first run, and said out loud when it happens;
+`ccdeck --uninstall-service` undoes it and `ccdeck --uninstall` takes it with the
+hooks. A launchd agent on macOS, a `systemd --user` unit on Linux, a Task
+Scheduler logon task on Windows — none of them carrying a restart policy of its
+own, because the one that decides when a crashed deck stops coming back lives in
+ccdeck and two policies over one process is how a stop becomes a suggestion. An
+`npx` run never installs one: it would name a path inside npm's cache, which npm
+deletes without warning. On Linux, `systemd --user` is torn down at logout unless
+`loginctl enable-linger` is on for your account — the install says so rather than
+changing that for you.
+
+If the deck falls over on its own, it comes back — five times in ten minutes,
+with the wait doubling each time, and then it stops and says so in the log rather
+than spinning on a machine nobody is watching. A clean `--stop` is never answered
+with a restart, and neither is a deck that failed to start in the first place:
+retrying a port the OS will not give you just prints the same refusal six times.
+
+Typing plain `ccdeck` beside a deck that is already running opens **that deck's
+tab** rather than building a second one. It used to build the second one: port
+4317 was busy, so the new deck took a random port out of 4318–4400 and stood
+there beside a perfectly healthy first one, and neither mentioned the other.
+The port fallback is still there — 4317 is also the standard OTLP collector
+port, and Windows reserves whole TCP ranges for Hyper-V, WSL2 and Docker — but
+it now runs only when the thing holding the port is *not* one of your decks. The
+deck on the port has to prove it is yours, with the same token handshake the
+hooks use, before its tab is opened. Any flag that changes what the deck **is**
+— a port, a workspace, a log, either `--codex` or `--claude` pair — still starts
+its own, and `--new` starts one unconditionally.
+
 ccdeck looks for each CLI before it does anything on that CLI's behalf. Claude
 Code counts as present when its binary is on `PATH` (or in one of the places its
 installers put it), or when its config dir carries traces of having been used;

package/bin/agent-dag.js

@@ -37,13 +37,19 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { killTree } from "../src/server/exec.mjs";
 import { invokedAs } from "../src/server/invoked-as.mjs";
+import { isOneShot, parseArgs } from "../src/server/args.mjs";
 import { npxFailureHint, npxFailureSummary, npxLaunch, npxPrefetch } from "../src/server/npx.mjs";
 import {
   bareSpecName, claimRestartFailureKey, clearRestartFailure, installedName, installedVersion,
-  lastKnownLatest, npxRestartSpec, readRestartFailure, recordRestartFailure, successorRoot,
+  isNpxInstall, lastKnownLatest, npxRestartSpec, readRestartFailure, recordRestartFailure,
+  successorRoot,
 } from "../src/server/self-update.mjs";
-import { dieOfSignal, dieWithParent, replacedNote, upgradeAttempt, upgradeRefusalText, workerExitAction } from "../src/server/supervisor.mjs";
-import { colorProfile, glyphs, palette, unicodeOK } from "../src/server/term.mjs";
+import {
+  CRASH_CEILING, CRASH_WINDOW_MS, crashPolicy, dieOfSignal, dieWithParent, isCrash, replacedNote,
+  upgradeAttempt, upgradeRefusalText, workerExitAction,
+} from "../src/server/supervisor.mjs";
+import { colorProfile, glyphs, palette, termColumns, unicodeOK } from "../src/server/term.mjs";
+import { DETACHED_ENV, detachAndWatch, stopCommand } from "../src/server/detach.mjs";
 import { PRODUCT } from "../src/server/brand.mjs";
 
 const BIN_DIR = dirname(fileURLToPath(import.meta.url));
@@ -77,6 +83,72 @@ const G = glyphs(unicodeOK());
 // update reported someone else's failed npx as its own. Our pid is unique among
 // the decks alive on the machine, and putting it in our own environment is what
 // carries it to the worker: launch() spawns with a copy of it.
+// ── the terminal stops being the deck's leash ────────────────────────────────
+//
+// Everything about why is in src/server/detach.mjs. Here is only the decision,
+// and it has exactly two ways out:
+//
+//   ALREADY DETACHED — we ARE the background copy. Carry on as this file always
+//   has: spawn the worker, supervise it, never come back here.
+//
+//   A ONE-SHOT — `--version`, `--stop`, `--status`, `--help`, `--uninstall`.
+//   Those answer and leave, and a one-shot that detached would print its answer
+//   into a log file and hand the terminal back empty. They run in the
+//   foreground exactly as they always have.
+//
+// Anything else is a start, and a start goes to the background.
+const DETACHED = process.env[DETACHED_ENV] === "1";
+// A parent already holding our lifecycle. `process.send` exists only when
+// somebody spawned us with an IPC channel, and that somebody has armed
+// dieWithParent below and is waiting on our exit code — running away from them
+// into our own process group is precisely the wrong answer to being supervised.
+// The suite's spawnSupervised is the caller that does this today.
+const LEASHED = typeof process.send === "function";
+// And the way to ask for the old behaviour out loud.
+//
+// Every version before this one held the terminal, and something out there
+// depends on that: a wrapper script, a CI step, a supervisor of somebody else's
+// that starts `ccdeck` and waits on it, a `ccdeck && open …`. Handing all of
+// those an immediate exit and no way to say otherwise would be a breaking change
+// with no escape hatch — and the marker above is an internal one, not something
+// to tell a user to export.
+const FLAGS = parseArgs(process.argv.slice(2));
+if (!DETACHED && !LEASHED && FLAGS.foreground !== true && !isOneShot(FLAGS)) {
+  const { deckLogDir } = await import("../src/server/deck-home.mjs");
+  const { registeredDecks } = await import("../src/server/running-deck.mjs");
+  const isTTY = Boolean(process.stdout.isTTY);
+  const profile = colorProfile({ isTTY });
+  const tone = palette(profile);
+  const npx = isNpxInstall(PKG_ROOT);
+  const stop = stopCommand({ npx, invokedAs: INVOKED_AS, product: PRODUCT });
+  // THE ONE THING AN NPX RUN CANNOT HAVE, said where it is missing. A login item
+  // must name a path that will still be there tomorrow, and npx runs out of a
+  // cache npm deletes whenever it likes — so an npx deck runs in the background
+  // and cannot come back after a reboot. One line, no disk written, offered
+  // rather than done: `npx` means "run without installing", and a tool that
+  // installs itself anyway is the one people uninstall.
+  const offer = npx
+    ? `     ${tone.muted}\`${INVOKED_AS ?? PRODUCT} --install\` also starts it at login${tone.reset}\n`
+    : "";
+  const outcome = await detachAndWatch({
+    file: fileURLToPath(import.meta.url),
+    argv: process.argv.slice(2),
+    logDir: deckLogDir(),
+    // Only the count, and only to decide whether deck.log is anybody's — see
+    // logMode. No handshake: this is a directory listing and a signal-0 each.
+    liveCount: (await registeredDecks().catch(() => [])).length,
+    isTTY,
+    profile,
+    columns: termColumns(process.stdout),
+    backgroundLine: `  ${tone.muted}${G.dash}  running in the background ${G.bullet} \`${stop}\` ends it${tone.reset}\n${offer}\n`,
+  });
+  // detachAndWatch never returns on the paths that worked. Reaching this line
+  // means the log could not be opened at all — a read-only home, a full disk —
+  // and a deck that will not start over a LOG is a worse answer than one that
+  // stays in the terminal, which is what every version before this did anyway.
+  console.error(`${PRODUCT}: could not open ${PRODUCT}'s log (${outcome.reason}) ${G.dash} staying in the foreground.`);
+}
+
 claimRestartFailureKey();
 
 // The port the worker actually bound, which is not necessarily the one it was
@@ -100,6 +172,11 @@ let attempting = null;
 // worker that was already exiting 75 or 76 when the signal landed reads as a
 // restart request — both resurrect the deck the user just stopped.
 let stopping = false;
+// When this supervisor has put a crashed worker back, pruned to the window the
+// ceiling is counted in. See crashPolicy: a deck that dies once an hour comes
+// back every time; one that dies five times in ten minutes is broken, and the
+// answer to broken is to stop and say so rather than to spin.
+let crashes = [];
 
 function launch(respawn) {
   // Asked on every spawn rather than once at boot: the deletion this catches
@@ -146,6 +223,21 @@ function launch(respawn) {
   worker.on("message", (m) => {
     if (!m || typeof m !== "object") return;
     if (m.type === "listening" && typeof m.port === "number") boundPort = m.port;
+    // The worker saying its boot is finished — every row printed, the browser
+    // launched. Forwarded to whoever detached us, who has been tailing the log
+    // into the user's terminal and is waiting for exactly this to stop.
+    //
+    // GUARDED BY `process.connected`, AND GIVEN A CALLBACK, and it took a real
+    // crash restart to find out why: the launcher disconnects the moment the
+    // first boot finishes, so every LATER boot forwards this down a dead
+    // channel — and `process.send` on a closed channel does not throw where the
+    // call is, it emits 'error' on `process` a tick later. Unhandled, that ends
+    // the supervisor. So a try/catch here was decoration: the guard is the
+    // check, and the callback is what turns the remaining race (disconnect
+    // between the check and the send) into a value nobody has to catch.
+    else if (m.type === "booted" && process.connected) {
+      try { process.send({ type: "booted" }, () => {}); } catch { /* the launcher left */ }
+    }
     // The worker asking to be replaced, while it is still serving. Answered by
     // prefetchUpgrade, which is the whole of this file's new shape: the fetch
     // happens here, and only then does that worker exit — see UPGRADE_CODE.
@@ -173,6 +265,32 @@ function launch(respawn) {
       launchNpx();
       return;
     }
+    // THE DECK FELL OVER, and nobody is watching it any more.
+    //
+    // Before this ran in the background a crash was self-reporting: the terminal
+    // came back with the stack on it. Detached, the first sign is noticing hours
+    // later that a day of work was never recorded — so it goes back up. The
+    // whole of which crashes qualify is in isCrash, and the ceiling that stops
+    // this becoming a spin loop is in crashPolicy.
+    if (isCrash({ code, signal, served: boundPort != null, stopping })) {
+      const verdict = crashPolicy(crashes);
+      if (verdict.restart) {
+        crashes = verdict.history;
+        const how = signal ? `killed by ${signal}` : `exit ${code}`;
+        console.error(`${PRODUCT}: the deck stopped on its own (${how}) ${G.dash} starting it again in ${Math.round(verdict.delayMs / 1000)}s (${verdict.recent}/${CRASH_CEILING}).`);
+        restarts++;
+        // Unref'd would be wrong here: this timer IS the supervisor's reason to
+        // stay alive, and without it the event loop empties and the process
+        // exits before the deck it promised to bring back.
+        setTimeout(() => { if (!stopping) launch(true); }, verdict.delayMs);
+        return;
+      }
+      // Said once, with the two numbers that make it actionable, and then this
+      // process really does end — a supervisor that keeps trying forever is the
+      // failure the ceiling exists to prevent.
+      console.error(`${PRODUCT}: the deck has stopped ${CRASH_CEILING} times in ${Math.round(CRASH_WINDOW_MS / 60000)} minutes ${G.dash} not starting it again. Run \`${INVOKED_AS ?? PRODUCT}\` when you have looked at the log above.`);
+    }
+
     // Anything else is the worker's own verdict and belongs to whoever started
     // us — including the ccdeck wrapper, which exits with our code in turn. A
     // worker killed by a signal is reported by dying of the same one; doing
@@ -492,7 +610,10 @@ for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
 // 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(() => {
+// NOT IN THE DETACHED COPY. There the parent is the launcher, which disconnects
+// and exits the moment the deck is up — by design — and arming this would have
+// the deck kill itself a second after every successful start.
+if (!DETACHED) dieWithParent(() => {
   stopping = true;
   if (fetching) { killTree(fetching, "SIGTERM"); fetching = null; }
   if (child) killTree(child, "SIGTERM");