agent-dag 3.18.3 → 3.20.0

package/src/server/running-deck.mjs

@@ -0,0 +1,234 @@
+// 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`;
+}

package/src/server/self-update.mjs

@@ -211,7 +211,10 @@ export function isNpxInstall(pkgRoot) {
  *  ahead of npm, and telling someone to `npm i -g` over their working copy is
  *  actively wrong, so the registry side of the check is skipped there.
  *
- *  Not exported (#383). It gates three answers and each of the three is already
+ *  Exported for one caller outside this file: the login item, which must not be
+ *  installed from a checkout for the same reason it must not be installed from
+ *  an npx run — the path is not one anybody promised to keep. Everything else it
+ *  gates stays internal, and each of those is already
  *  asserted against a directory with a real `.git` in it — `upgradeCommand`
  *  returning "git pull && npm run build", `upgradeName` refusing to move a
  *  checkout onto a published alias, and `startUpgrade` refusing with
@@ -226,7 +229,7 @@ export function isNpxInstall(pkgRoot) {
  *  carries a drive letter and backslashes. Both shapes are covered in
  *  worktree-git-file-587.test.ts and beside every checkout fixture in the
  *  suite — narrowing this to `.isDirectory()` fails them. */
-function isGitCheckout(pkgRoot) {
+export function isGitCheckout(pkgRoot) {
   try { return existsSync(join(pkgRoot, ".git")); } catch { return false; }
 }
 

package/src/server/stop-deck.mjs

@@ -0,0 +1,171 @@
+// Ending a deck that is not our child.
+//
+// `ccdeck --stop` holds a pid and a port out of a discovery file and nothing
+// else — no ChildProcess, no IPC channel, no shell job. That rules out
+// exec.mjs's killTree, which takes a ChildProcess and calls `child.kill`, and it
+// is why the Windows half of that function is spelled a second time here rather
+// than shared: the two have the same shape and different inputs.
+//
+// THREE RUNGS, and each one exists for a failure the one above it cannot cover:
+//
+//   THE POST. /api/shutdown, with the token out of the record, ending in the
+//   deck's own shutdown(): the listener closes, the registration is unlinked,
+//   the LAN beacon says goodbye so paired colleagues see it LEAVE rather than
+//   time out. This is the rung that behaves identically on all three platforms,
+//   which is the whole reason the route exists — Windows has no signals.
+//
+//   SIGTERM, POSIX only. Not a fallback for a wedged deck — a wedged deck is
+//   wedged for this too — but the only way to end a deck OLDER than the route,
+//   which answers the POST with a 404 and would otherwise be unstoppable by its
+//   own command. bin/deck.js has handled SIGTERM with shutdown(0) for years, so
+//   this is still a clean exit on every version that has ever shipped.
+//
+//   THE HARD KILL. SIGKILL, or `taskkill /T /F` on Windows. Leaves the discovery
+//   file behind for the next boot to sweep and gives the LAN no goodbye, and is
+//   still better than a process the user cannot end with the tool that started
+//   it — which is the outcome this whole file is written against.
+//
+// THE PARENT GOES FIRST on both kill rungs. A worker killed under a live
+// supervisor is a worker the supervisor puts back: that is what it is for. So
+// the supervisor is ended first and the worker second, which is also what the
+// record's `parent` field is written for.
+import { request as httpRequest } from "node:http";
+import { spawn } from "node:child_process";
+import { isProcessAlive } from "./deck-probe.mjs";
+
+/** Long enough for a loopback POST and the deck's own teardown to begin; short
+ *  enough that a wedged deck does not hold the terminal. */
+export const STOP_ASK_MS = 2000;
+/** How long a deck gets to actually disappear after each rung. A clean shutdown
+ *  drains SSE connections and closes the listener; 1500ms of that is the
+ *  fallback timer in bin/deck.js's shutdown(), so this has to outlast it. */
+export const STOP_GONE_MS = 3000;
+
+/**
+ * Ask one deck to end itself, politely.
+ *
+ * Never rejects: every failure is a verdict the caller has a next rung for. A
+ * 404 is a deck too old to know the route, a refused connection is a record
+ * whose port is already gone, a timeout is a deck that is not answering — and
+ * all three lead to the same place.
+ */
+export function askDeckToStop(rec, { timeoutMs = STOP_ASK_MS, request = httpRequest } = {}) {
+  return new Promise(resolve => {
+    let settled = false;
+    const finish = (v) => { if (settled) return; settled = true; resolve(v); };
+    let req;
+    try {
+      req = request({
+        hostname: "127.0.0.1",
+        port: rec.port,
+        path: "/api/shutdown",
+        method: "POST",
+        timeout: timeoutMs,
+        headers: {
+          // The one spelling the server reads. The token came out of a file
+          // only this user can open, which is the whole of the access control.
+          "x-ccdeck-token": String(rec.token ?? ""),
+          "content-length": "0",
+        },
+      }, res => {
+        // The body is drained rather than read: the verdict is the status, and
+        // a response left unconsumed keeps the socket open past our exit.
+        res.resume();
+        res.on("end", () => finish({
+          ok: res.statusCode === 200,
+          status: res.statusCode ?? 0,
+          // A route that is not there is a deck older than this feature, and
+          // the caller says so rather than reporting a mysterious refusal.
+          old: res.statusCode === 404,
+        }));
+      });
+    } catch (err) {
+      return finish({ ok: false, status: 0, old: false, reason: err?.code ?? "request_failed" });
+    }
+    req.on("error", (err) => finish({ ok: false, status: 0, old: false, reason: err?.code ?? "unreachable" }));
+    req.on("timeout", () => { req.destroy(); finish({ ok: false, status: 0, old: false, reason: "timeout" }); });
+    req.end();
+  });
+}
+
+/**
+ * End a pid and everything under it.
+ *
+ * exec.mjs's killTree with a pid where its ChildProcess goes — see the note at
+ * the top of this file. `/T` is the half that matters: the supervisor's worker
+ * is a child of the pid being ended, and on Windows there is no process group
+ * to signal as one.
+ *
+ * On Windows a "polite" rung does not exist. `taskkill` without `/F` posts
+ * WM_CLOSE to a window, and the deck has none, so the only thing to do there is
+ * the forceful one — which is why the caller skips the SIGTERM rung on win32
+ * rather than running it twice under a different name.
+ */
+export function killPidTree(pid, signal = "SIGTERM", {
+  platform = process.platform, spawnFn = spawn, kill = (p, s) => process.kill(p, s),
+} = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  const plain = () => { try { kill(pid, signal); } catch { /* already gone */ } };
+  if (platform !== "win32") return plain();
+  try {
+    const root = process.env.SystemRoot || process.env.systemroot;
+    const exe = root ? `${root}\\System32\\taskkill.exe` : "taskkill";
+    const killer = spawnFn(exe, ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+    killer.on("error", plain);
+    killer.on("exit", (code) => { if (code !== 0) plain(); });
+    killer.unref?.();
+  } catch {
+    plain();
+  }
+}
+
+/** Has this pid actually gone, within the deadline? Polled rather than waited
+ *  on: this process is not the parent, so there is no exit to listen for. */
+async function gone(pid, { alive, deadlineMs, sleep, now }) {
+  const until = now() + deadlineMs;
+  for (;;) {
+    if (!alive(pid)) return true;
+    if (now() >= until) return false;
+    await sleep(50);
+  }
+}
+
+/**
+ * Stop one deck, and say how it went out.
+ *
+ * `how` is not decoration. "asked" means the deck closed its listener, unlinked
+ * its registration and left the LAN cleanly; "killed" means none of that
+ * happened and the next boot has litter to sweep. A command that reported both
+ * as "stopped" would hide the one case worth knowing about.
+ */
+export async function stopDeck(rec, {
+  ask = askDeckToStop,
+  alive = isProcessAlive,
+  kill = killPidTree,
+  platform = process.platform,
+  now = Date.now,
+  sleep = (ms) => new Promise(r => setTimeout(r, ms)),
+  askMs = STOP_ASK_MS,
+  goneMs = STOP_GONE_MS,
+} = {}) {
+  const wait = () => gone(rec.pid, { alive, deadlineMs: goneMs, sleep, now });
+  const parent = Number.isInteger(rec.parent) ? rec.parent : null;
+
+  const answer = await ask(rec, { timeoutMs: askMs });
+  if (answer.ok && await wait()) return { ok: true, how: "asked" };
+
+  if (platform !== "win32") {
+    // Parent first: see the note at the top. A supervisor left alive over a
+    // killed worker is a supervisor doing its job, which here means undoing
+    // ours.
+    if (parent !== null) kill(parent, "SIGTERM", { platform });
+    kill(rec.pid, "SIGTERM", { platform });
+    if (await wait()) return { ok: true, how: "signalled", old: answer.old === true };
+  }
+
+  if (parent !== null) kill(parent, "SIGKILL", { platform });
+  kill(rec.pid, "SIGKILL", { platform });
+  if (await wait()) return { ok: true, how: "killed", old: answer.old === true };
+
+  return { ok: false, how: "stuck", reason: answer.reason ?? `http ${answer.status}` };
+}

package/src/server/supervisor.mjs

@@ -53,6 +53,96 @@ export function workerExitAction(code, stopping) {
   return { relaunch: null, code: ours ? 0 : code ?? 0 };
 }
 
+// ── putting a crashed deck back ──────────────────────────────────────────────
+//
+// Before the deck ran in the background, a crash was self-reporting: the
+// terminal came back, the stack was on screen, and you knew within a second.
+// Detached, nothing says anything. The deck stops receiving hook events, stops
+// answering the LAN beacon, stops watching the quota — and the first sign is
+// noticing, hours later, that a day of work was never recorded.
+//
+// So the supervisor puts it back. WITH A CEILING, because the other failure is
+// worse than the one being fixed: a deck that dies on its own boot, respawned
+// forever, is a process spinning on a machine nobody is watching, writing the
+// same stack into the same log a thousand times an hour.
+//
+// The window is what makes the ceiling mean "is this broken" rather than "how
+// long has this machine been up". Five crashes in ten minutes is a deck that
+// cannot run; five crashes over three weeks is a machine that went to sleep
+// oddly three times, and putting it back each time is exactly right.
+
+/** Five, then stop and say why. */
+export const CRASH_CEILING = 5;
+/** The window those five are counted in. */
+export const CRASH_WINDOW_MS = 10 * 60 * 1000;
+/** The first wait, doubling per crash inside the window. */
+export const CRASH_BACKOFF_MS = 1000;
+/** …and where the doubling stops. Past this the delay is no longer protecting
+ *  anything: five attempts at 30s already span most of the window. */
+export const CRASH_BACKOFF_MAX_MS = 30_000;
+
+/**
+ * Should this crash be answered with another deck, and after how long?
+ *
+ * `history` is the timestamps of the crashes already answered; the caller adds
+ * this one only if the answer is yes, so a refusal does not push the count
+ * further out of reach.
+ *
+ * The backoff doubles rather than waiting a fixed beat, because the two shapes
+ * of crash want opposite things. A deck that falls over once an hour should
+ * come back immediately — a second of downtime is a second of unrecorded work.
+ * A deck that dies in its own first instruction should be tried slowly enough
+ * that the log is readable and the CPU is idle between attempts.
+ */
+export function crashPolicy(history = [], {
+  now = Date.now(),
+  ceiling = CRASH_CEILING,
+  windowMs = CRASH_WINDOW_MS,
+  backoffMs = CRASH_BACKOFF_MS,
+  maxMs = CRASH_BACKOFF_MAX_MS,
+} = {}) {
+  const recent = history.filter(t => now - t < windowMs);
+  if (recent.length >= ceiling) {
+    return { restart: false, delayMs: 0, recent: recent.length, history: recent };
+  }
+  return {
+    restart: true,
+    delayMs: Math.min(backoffMs * 2 ** recent.length, maxMs),
+    recent: recent.length + 1,
+    // The pruned list, so a caller that keeps it does not carry crashes from
+    // last Tuesday into this decision forever.
+    history: [...recent, now],
+  };
+}
+
+/**
+ * Was this a deck falling over, as opposed to one leaving?
+ *
+ * THREE THINGS HAVE TO BE TRUE, and each one removes a way this could respawn
+ * something nobody asked for:
+ *
+ *   It was UP. `served` is the supervisor having seen the worker bind a port. A
+ *   worker that never got that far did not crash, it failed to start — a port
+ *   the OS will not give us, a `dist/` that was never built — and retrying that
+ *   five times prints the same refusal six times and fixes nothing.
+ *
+ *   We are not STOPPING. Ctrl+C, a SIGTERM, and `--stop`'s fallback ladder all
+ *   set it, and every one of them is somebody asking for this deck to be gone.
+ *
+ *   It did not exit ZERO. That is the deck ending itself — the shutdown that
+ *   /api/shutdown runs, which is what `ccdeck --stop` asks for. Answering a
+ *   clean stop with a restart would make the off switch a no-op.
+ *
+ * A signal counts as a crash. `kill -9` on the worker alone is an OOM killer or
+ * a stray hand, not a request to end the deck: `--stop` ends the supervisor
+ * FIRST precisely so that this rule and that ladder do not fight.
+ */
+export function isCrash({ code, signal, served, stopping } = {}) {
+  if (!served || stopping) return false;
+  if (signal) return true;
+  return code !== 0 && code !== null && code !== undefined;
+}
+
 /**
  * How to report a worker that did not exit at all but was killed by a signal.
  *

package/src/server/term.mjs

@@ -240,6 +240,32 @@ export function elapsedSuffix(ms, after = SPINNER_ELAPSED_AFTER_MS) {
   return ms < after ? "" : `  ${Math.floor(ms / 1000)}s`;
 }
 
+/**
+ * How long a deck has been up, in the two units that matter and no more.
+ *
+ * `--status` and `--stop` both print this, and the question behind it is always
+ * "is this the deck I started, or one I forgot about" — which "3h 12m" answers
+ * and "11543s" does not. Two units, because the second one stops being
+ * interesting as soon as the first is large: nobody reading "2d" wants the
+ * minutes.
+ *
+ * Seconds under a minute, because that is the unit a deck started moments ago
+ * is measured in and "up just now" is not an answer to "how long". A clock that
+ * went backwards, or a `startedAt` from a machine whose time has since been
+ * corrected, reads as `0s` rather than as a negative duration.
+ */
+export function sinceLabel(ms) {
+  const s = Math.floor(Number(ms) / 1000);
+  if (!Number.isFinite(s) || s < 0) return "0s";
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return h > 0 && m % 60 > 0 ? `${h}h ${m % 60}m` : `${h}h`;
+  const d = Math.floor(h / 24);
+  return h % 24 > 0 ? `${d}d ${h % 24}h` : `${d}d`;
+}
+
 // ── motion ───────────────────────────────────────────────────────────────────
 
 /**
@@ -275,9 +301,16 @@ export function visibleWidth(s) {
 /** How wide the terminal is, or 80 when it will not say — a pipe, a CI runner,
  *  a terminal that never sent SIGWINCH. 80 is the assumption every one of them
  *  is already built around, and the layout below never needs more than 40. */
-export function termColumns(stream = process.stdout) {
+export function termColumns(stream = process.stdout, env = process.env) {
   const c = stream?.columns;
-  return Number.isInteger(c) && c > 0 ? c : 80;
+  if (Number.isInteger(c) && c > 0) return c;
+  // COLUMNS, the POSIX spelling of this question, and the only answer a DETACHED
+  // deck has. Its stdout is the log file, so the stream knows nothing about a
+  // width — but the launcher is watching that file from a real terminal and
+  // passes its own width down, so the boot report is laid out for the terminal
+  // a person is actually reading it in rather than for the 80 below.
+  const n = Number.parseInt(String(env?.COLUMNS ?? "").trim(), 10);
+  return Number.isInteger(n) && n > 0 ? n : 80;
 }
 
 /** The status column, computed from the labels rather than counted into each