agent-dag 3.19.0 → 3.21.0

package/bin/deck.js

@@ -12,11 +12,16 @@ import { isPortValue, parseArgs } from "../src/server/args.mjs";
 import {
   CURSOR_HIDE, CURSOR_SHOW, colorProfile, fit, glyphs, labelColumn, link, motionOK, oneLine,
   palette, pulseDot, pulseText, spinnerFrames, statusLine, supportsHyperlinks, termColumns,
-  elapsedSuffix, unicodeOK, unregisteredDetail, visibleWidth, wordmark,
+  elapsedSuffix, sinceLabel, unicodeOK, unregisteredDetail, visibleWidth, wordmark,
 } from "../src/server/term.mjs";
 import { PRODUCT } from "../src/server/brand.mjs";
 import { invokedName, renameNotice } from "../src/server/invoked-as.mjs";
 import { budget, bootDeadlineMs } from "../src/server/boot-deadline.mjs";
+// A leaf — fs, path and claude-dir.mjs, nothing else — so it is imported here
+// with the rest rather than fetched later. Deliberately NOT the other way
+// round: it takes the handshake as a parameter precisely so that it never has
+// to import the server. See the note at the top of that file.
+import { asksForOwnDeck, runningDeck, versionNote } from "../src/server/running-deck.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, "..");
@@ -101,6 +106,32 @@ if (flags.uninstall) {
   // 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.
+  // The login item goes too, and this is the one place the uninstall's
+  // documented narrowness has to bend. "Hook entries only" is right for the
+  // event log and the port registry, which are data somebody may still want —
+  // but a login item left behind after an uninstall is not data, it is a
+  // machine that keeps starting a deck whose hooks were just removed.
+  {
+    const svc = await import(pathToFileURL(join(PKG_ROOT, "src/server/login-service.mjs")).href);
+    const { deckDataDir: dataDir } = await import(pathToFileURL(join(PKG_ROOT, "src/server/deck-home.mjs")).href);
+    if (svc.readServiceRecord(dataDir()) !== null) {
+      const gone = svc.uninstallService();
+      svc.writeServiceRecord(dataDir(), { removed: new Date().toISOString(), version: PKG_VERSION });
+      // Silent when there was nothing on the machine: an uninstall that reports
+      // removing a login item this deck never had is the same lie the explicit
+      // command used to tell, in the place a reader is least able to check it.
+      if (!gone.ok) {
+        // `gDash`, not an em dash: this block runs at module top level, on a
+        // console that may be the legacy Windows one, and #797 is the rule that
+        // a printed string never carries punctuation the terminal may not have.
+        console.error(`${PRODUCT}: could NOT remove the login item ${gDash} ${gone.reason} (${gone.path})`);
+      } else if (gone.existed) {
+        console.log(`${PRODUCT}: no longer starts at login`);
+      }
+      if (!gone.ok) refused = true;
+    }
+  }
+
   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`);
@@ -135,6 +166,284 @@ if (flags.uninstall) {
   process.exit(refused ? 1 : 0);
 }
 
+// ── the two questions that are about another deck, not this one ──────────────
+//
+// One-shot commands in the shape `--uninstall` already established: do the
+// thing, print, exit, and never start a server. They sit ABOVE the migration
+// and well above the heavy imports, because a command that ends a deck has no
+// business moving that deck's files on the way past, and because asking a
+// server to stop should not require starting one.
+//
+// Their own glyphs and palette rather than `G`/`P`, for the reason the bad-port
+// block below gives (#797): those are declared two hundred lines further down
+// and this runs at module top level.
+//
+// WHICH DECK. The shape a bare `ccdeck` would have built — same `sameShape` the
+// attach uses, so `ccdeck` and `ccdeck --stop` name the same deck and there is
+// one model to hold. `--port <n>` names one directly; `--all` takes every deck
+// on the machine. (`--all` is the legacy capture flag, a no-op since it became
+// the default; beside `--stop` it can only mean this, and it is the word a
+// person reaches for.)
+if (flags.stop || flags.status || flags.logs || flags.install || flags.installService || flags.uninstallService) {
+  const { dash, ok: gOk, warn: gWarn, bullet, arrow, ellipsis: gEllipsis } = glyphs(unicodeOK());
+  const tone = palette(colorProfile({ isTTY: Boolean(process.stdout.isTTY) }));
+  const say = (line) => process.stdout.write(`${line}\n`);
+
+  const { deckDataDir, deckLogDir } = await import(pathToFileURL(join(PKG_ROOT, "src/server/deck-home.mjs")).href);
+
+  // ── --install ─────────────────────────────────────────────────────────────
+  //
+  // The one command that turns an npx run into a deck that comes back after a
+  // reboot. `npx ccdeck` cannot start at login — 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 this puts the package on PATH and points the service
+  // at THAT.
+  //
+  // BEHIND A FLAG, because `npx` means "run without installing" and a tool that
+  // installs itself anyway is the tool people uninstall. Somebody typed this.
+  if (flags.install) {
+    const gi = await import(pathToFileURL(join(PKG_ROOT, "src/server/global-install.mjs")).href);
+    const svc = await import(pathToFileURL(join(PKG_ROOT, "src/server/login-service.mjs")).href);
+    const { installedName } = await import(pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href);
+    const { run } = await import(pathToFileURL(join(PKG_ROOT, "src/server/exec.mjs")).href);
+    // The name they typed, not ours. Three packages publish this deck, and
+    // installing `ccdeck` for somebody who ran `npx agent-dag` hands them a
+    // command they did not ask for.
+    const pkg = installedName(PKG_ROOT, PRODUCT);
+
+    say(`\n  ${tone.muted}${dash}  installing ${pkg} globally${gEllipsis}${tone.reset}`);
+    const got = await run("npm", ["i", "-g", pkg], { timeout: gi.INSTALL_TIMEOUT_MS });
+    if (!got?.ok) {
+      say(`  ${tone.err}${gWarn}  ${gi.installFailure(got, { pkg })}${tone.reset}\n`);
+      process.exit(1);
+    }
+    say(`  ${tone.ok}${gOk}${tone.reset}  ${pkg} is on your PATH${tone.muted}  ${bullet}  type \`${pkg}\` to start it${tone.reset}`);
+
+    // WHERE npm PUT IT, asked rather than assumed: a prefix the user set
+    // themselves is common and nothing here can guess it.
+    const root = gi.readGlobalRoot(await run("npm", ["root", "-g"], { timeout: 30_000 }));
+    const script = gi.globalScript(root, pkg);
+    if (!script) {
+      say(`  ${tone.warn}${gWarn}  installed, but npm did not say where ${dash} run \`${pkg} --install-service\` to start it at login${tone.reset}\n`);
+      process.exit(0);
+    }
+    const out = svc.installService({ script, logPath: join(deckLogDir(), "deck.log"), product: PRODUCT });
+    if (!out.ok) {
+      say(`  ${tone.warn}${gWarn}  installed, but it will not start at login ${dash} ${out.reason}${tone.reset}\n`);
+      process.exit(0);
+    }
+    svc.writeServiceRecord(deckDataDir(), { installed: PKG_VERSION, at: new Date().toISOString(), path: out.path });
+    say(`  ${tone.ok}${gOk}${tone.reset}  and starts when you log in${tone.muted}  ${bullet}  ${out.path}${tone.reset}`);
+    if (svc.lingerState() === "off") {
+      say(`  ${tone.warn}${gWarn}  systemd tears your session down at logout, so the deck goes with it.${tone.reset}`);
+      say(`     ${tone.muted}\`sudo loginctl enable-linger $USER\` keeps it running when you are logged out.${tone.reset}`);
+    }
+    say(`     ${tone.muted}\`${pkg} --uninstall-service\` undoes the login part${tone.reset}\n`);
+    process.exit(0);
+  }
+
+  // ── --install-service / --uninstall-service ───────────────────────────────
+  // Answered before the registry is read: neither one is about a deck that is
+  // running, and both are as meaningful on a machine with no deck up as on one
+  // with three.
+  if (flags.installService || flags.uninstallService) {
+    const svc = await import(pathToFileURL(join(PKG_ROOT, "src/server/login-service.mjs")).href);
+    const { isGitCheckout, isNpxInstall } = await import(pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href);
+    if (flags.uninstallService) {
+      const out = svc.uninstallService();
+      // Recorded either way. The record is what stops the next ordinary start
+      // putting back what was just taken away, and a tool that argues with its
+      // user about a login item is a tool that gets uninstalled entirely.
+      svc.writeServiceRecord(deckDataDir(), { removed: new Date().toISOString(), version: PKG_VERSION });
+      // `existed` rather than the record: the record says what THIS tool last
+      // did, and the machine is what actually has a login item on it. Somebody
+      // who removed the plist by hand should be told the truth about the
+      // machine, not about our bookkeeping.
+      say(!out.ok
+        ? `\n  ${tone.err}${gWarn}  could not remove it ${dash} ${out.reason}${tone.reset}\n`
+        : out.existed
+          ? `\n  ${tone.ok}${gOk}${tone.reset}  no longer starts at login${tone.muted}  ${bullet}  ${out.path}${tone.reset}\n`
+          : `\n  ${tone.muted}${dash}  it was not starting at login${tone.reset}\n`);
+      process.exit(out.ok ? 0 : 1);
+    }
+    if (isGitCheckout(PKG_ROOT)) {
+      // Not refused outright — somebody running from a checkout may genuinely
+      // want this — but not done silently either: the item would name a working
+      // tree, and that is worth knowing before it is written.
+      say(`\n  ${tone.warn}${gWarn}  this is a checkout, so the login item would name ${PKG_ROOT}${tone.reset}`);
+      say(`     ${tone.muted}a renamed, moved or deleted working tree leaves a login item pointing at nothing${tone.reset}\n`);
+    }
+    if (isNpxInstall(PKG_ROOT)) {
+      // The item would name a path inside ~/.npm/_npx/<hash>/, which npm deletes
+      // whenever it feels like it — a login item pointing at nothing, forever,
+      // on a machine where nothing was ever installed.
+      say(`\n  ${tone.warn}${gWarn}  an npx run cannot start at login ${dash} its files live in npm's cache and are deleted without warning.${tone.reset}`);
+      say(`     ${tone.muted}install it first: \`npm i -g ${INVOKED_AS ?? PRODUCT}\`${tone.reset}\n`);
+      process.exit(1);
+    }
+    const out = svc.installService({
+      script: join(PKG_ROOT, "bin", "agent-dag.js"),
+      logPath: join(deckLogDir(), "deck.log"),
+      product: PRODUCT,
+    });
+    if (!out.ok) {
+      say(`\n  ${tone.err}${gWarn}  could not set it up ${dash} ${out.reason}${tone.reset}\n`);
+      process.exit(1);
+    }
+    svc.writeServiceRecord(deckDataDir(), { installed: PKG_VERSION, at: new Date().toISOString(), path: out.path });
+    say(`\n  ${tone.ok}${gOk}${tone.reset}  starts when you log in${tone.muted}  ${bullet}  ${out.path}${tone.reset}`);
+    if (out.how === "file-only") {
+      // The file is on disk and both launchd and systemd read their directories
+      // at the next login, so this works from then on. Said rather than hidden:
+      // "it will work tomorrow" is a different promise from "it works now".
+      say(`  ${tone.warn}${gWarn}  not started now ${dash} ${out.reason}. It will come up at your next login.${tone.reset}`);
+    }
+    // The one place the three platforms genuinely differ in what this buys you.
+    if (svc.lingerState() === "off") {
+      say(`  ${tone.warn}${gWarn}  systemd tears your session down at logout, so the deck goes with it.${tone.reset}`);
+      say(`     ${tone.muted}\`sudo loginctl enable-linger $USER\` keeps it running when you are logged out.${tone.reset}`);
+    }
+    say(`     ${tone.muted}\`${INVOKED_AS ?? PRODUCT} --uninstall-service\` undoes it${tone.reset}\n`);
+    process.exit(0);
+  }
+  const { canonicalLogPath } = await import(pathToFileURL(join(PKG_ROOT, "src/server/log-writer.mjs")).href);
+  const { hasCodexInstalled } = await import(pathToFileURL(join(PKG_ROOT, "src/server/installer.mjs")).href);
+  const { hasClaudeInstalled } = await import(pathToFileURL(join(PKG_ROOT, "src/server/claude-dir.mjs")).href);
+  const { liveDecks, sameShape } = await import(pathToFileURL(join(PKG_ROOT, "src/server/running-deck.mjs")).href);
+
+  // The default shape, spelled the same way the boot below spells it. NOT the
+  // shape of the flags on THIS command line: `--stop --no-codex` is not a
+  // request to stop a Codex-less deck, it is a flag that means nothing here,
+  // and reading it as a selector would make `--stop` miss the deck it was
+  // pointed at and say "nothing is running".
+  const mine = {
+    workspace: "",
+    persist: canonicalLogPath(join(deckLogDir(), "events.jsonl")),
+    codex: hasCodexInstalled(),
+    claude: hasClaudeInstalled(),
+  };
+
+  // ── --logs ────────────────────────────────────────────────────────────────
+  // What the deck wrote where a terminal would have shown it. Printed RAW,
+  // escapes and all: the launcher passes its own colour tier down to a detached
+  // deck, so this file is a mirror of the terminal the deck was started from
+  // and re-rendering it is the whole point. The path goes last, because that is
+  // the line somebody copies into `tail -f`.
+  if (flags.logs) {
+    const { readFileSync: readLog, statSync: statLog } = await import("node:fs");
+    const logPath = join(deckLogDir(), "deck.log");
+    let text = null;
+    try { text = readLog(logPath, "utf8"); } catch { /* never started, or swept */ }
+    if (text === null) {
+      say(`\n  ${tone.muted}${dash}  nothing logged yet ${dash} ${logPath}${tone.reset}\n`);
+      process.exit(0);
+    }
+    // The tail, not the file. It is truncated at the first start on an idle
+    // machine, so it is normally small — but an attach appends to a running
+    // deck's log every time, and a long-lived deck's log is somebody's week.
+    const lines = text.split("\n");
+    const shown = lines.slice(Math.max(0, lines.length - 200));
+    if (shown.length < lines.length) {
+      say(`  ${tone.muted}${dash}  showing the last ${shown.length} of ${lines.length} lines${tone.reset}`);
+    }
+    process.stdout.write(shown.join("\n"));
+    if (!text.endsWith("\n")) say("");
+    const size = (() => { try { return statLog(logPath).size; } catch { return 0; } })();
+    say(`  ${tone.muted}${dash}  ${logPath} ${bullet} ${size} bytes${tone.reset}\n`);
+    process.exit(0);
+  }
+
+  const decks = await liveDecks().catch(() => []);
+  const age = (d) => sinceLabel(Date.now() - Date.parse(d.startedAt ?? ""));
+  const where = (d) => (d.workspace ? d.workspace : "(all)");
+  const url = (d) => `http://127.0.0.1:${d.port}`;
+
+  if (flags.status) {
+    if (!decks.length) {
+      say(`\n  ${tone.muted}${dash}  no deck is running ${dash} \`${INVOKED_AS ?? PRODUCT}\` starts one${tone.reset}\n`);
+      process.exit(0);
+    }
+    // The one a bare `ccdeck` would open is marked, because with two decks up
+    // that is the only question this command is really being asked.
+    const opens = decks.find(d => sameShape(d, mine)) ?? null;
+    say("");
+    for (const d of decks) {
+      // The version chunk is dropped rather than printed as "v?" for a deck too
+      // old to publish one — same rule as the attach line, and for the same
+      // reason: a question mark beside two real facts reads as a fault.
+      const head = [d.version ? `v${d.version}` : "", `pid ${d.pid}`, `up ${age(d)}`]
+        .filter(Boolean).join(`  ${bullet}  `);
+      const mark = d === opens ? `${tone.ok}${gOk}${tone.reset}` : `${tone.muted}${bullet}${tone.reset}`;
+      const tail = d === opens ? `${tone.muted}   ${arrow} \`${INVOKED_AS ?? PRODUCT}\` opens this one${tone.reset}` : "";
+      say(`  ${mark}  ${tone.muted}${head}${tone.reset}${tail}`);
+      say(`     ${tone.accent}${tone.bold}${url(d)}${tone.reset}`);
+      say(`     ${tone.muted}${where(d)} ${bullet} ${d.persist ?? "no log (--no-persist)"}${tone.reset}`);
+    }
+    say("");
+    process.exit(0);
+  }
+
+  // ── --stop ────────────────────────────────────────────────────────────────
+  const { stopDeck } = await import(pathToFileURL(join(PKG_ROOT, "src/server/stop-deck.mjs")).href);
+  // `flags.port`, not the `rawPort` computed below: that folds in
+  // AGENT_DAG_PORT, which is how somebody RUNS a deck rather than which deck
+  // they mean to stop — and a deck started on a custom port still has the
+  // default SHAPE, so the matcher finds it without help. It is also declared
+  // below this block, which would make reading it here a ReferenceError (#797).
+  const named = flags.port != null && isPortValue(flags.port) ? Number(flags.port) : null;
+  const wanted = flags.all
+    ? decks
+    : named !== null
+      ? decks.filter(d => d.port === named)
+      : decks.filter(d => sameShape(d, mine)).slice(0, 1);
+
+  if (!wanted.length) {
+    // Three different silences, and saying the wrong one sends the reader
+    // looking in the wrong place. A machine with no deck at all is not a
+    // machine whose deck is scoped differently.
+    const why = !decks.length
+      ? `no deck is running`
+      : named !== null
+        ? `no deck is listening on ${named} ${dash} \`${INVOKED_AS ?? PRODUCT} --status\` lists them`
+        : `no deck of this shape is running ${dash} \`${INVOKED_AS ?? PRODUCT} --status\` lists the ${decks.length} that ${decks.length === 1 ? "is" : "are"}`;
+    say(`\n  ${tone.muted}${dash}  ${why}${tone.reset}\n`);
+    process.exit(0);
+  }
+
+  say("");
+  let refused = false;
+  for (const d of wanted) {
+    const was = age(d);
+    const out = await stopDeck(d);
+    if (!out.ok) {
+      refused = true;
+      say(`  ${tone.err}${gWarn}  could not stop pid ${d.pid} on ${d.port} ${dash} ${out.reason}${tone.reset}`);
+      continue;
+    }
+    // HOW it went out, not just that it did. "asked" means the deck closed its
+    // listener, unlinked its registration and left the LAN cleanly; anything
+    // else means none of that happened and the next boot has litter to sweep.
+    const how = out.how === "asked"
+      ? ""
+      : out.old
+        ? `  ${tone.muted}(${out.how} ${dash} that deck predates \`--stop\`)${tone.reset}`
+        : `  ${tone.muted}(${out.how} ${dash} it did not answer)${tone.reset}`;
+    say(`  ${tone.ok}${gOk}${tone.reset}  stopped${tone.muted}  ${bullet}  pid ${d.pid}  ${bullet}  port ${d.port}  ${bullet}  was up ${was}${tone.reset}${how}`);
+  }
+
+  // What is still up, named. A command that ends one of three decks and says
+  // only "stopped" leaves the reader believing the machine is clear.
+  const left = decks.filter(d => !wanted.includes(d));
+  if (left.length) {
+    say("");
+    say(`  ${tone.muted}${dash}  ${left.length} other deck${left.length === 1 ? "" : "s"} still running:${tone.reset}`);
+    for (const d of left) say(`       ${tone.muted}pid ${d.pid} ${bullet} ${d.port} ${bullet} ${where(d)}${tone.reset}`);
+    say(`     ${tone.muted}\`${INVOKED_AS ?? PRODUCT} --stop --port <n>\` ends one ${bullet} \`--stop --all\` ends every deck${tone.reset}`);
+  }
+  say("");
+  process.exit(refused ? 1 : 0);
+}
+
 // 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
@@ -173,6 +482,36 @@ const openBrowser = flags.noOpen !== true;
 // config dir rather than assuming ~/.claude — see src/server/claude-dir.mjs.
 const { claudeConfigDir, hasClaudeInstalled } =
   await import(pathToFileURL(join(PKG_ROOT, "src/server/claude-dir.mjs")).href);
+
+// ── the deck's own files, brought to their own directory ────────────────────
+//
+// BEFORE ANYTHING READS THEM, which is why it is here and not in the server:
+// index.mjs reads the preferences at module load, so a migration inside it
+// would run after the file it is meant to find had already been looked for in
+// the wrong place. deck-home.mjs owns the reasoning; the shape of it is that
+// nothing is deleted and a destination that exists is never touched, so this is
+// safe to run on every start and does nothing at all on all but the first.
+//
+// A failure here is reported and then ignored. A read-only home or a missing
+// permission is not a reason for the deck not to start — the old paths are
+// still there, and the worst case is a deck that keeps using them.
+const { deckDataDir, deckLogDir, legacyDeckDir, migrateDeckFiles, sweepTempFiles } =
+  await import(pathToFileURL(join(PKG_ROOT, "src/server/deck-home.mjs")).href);
+{
+  const fsp = await import("node:fs/promises");
+  const legacy = legacyDeckDir();
+  const data = deckDataDir();
+  const log = deckLogDir();
+  const { moved } = await migrateDeckFiles({
+    from: legacy, data, log, fs: fsp,
+    onError: (name, err) => console.error(`${PRODUCT}: could not move ${name}:`, err?.message ?? err),
+  });
+  if (moved.length) console.error(`${PRODUCT}: moved ${moved.join(", ")} to ${data}`);
+  // The litter an atomic write leaves when its process is killed between the
+  // write and the rename. Nothing has ever swept it, because the code that
+  // makes it is not running any more when it is made.
+  await sweepTempFiles({ dirs: [legacy, data, log], fs: fsp }).catch(() => 0);
+}
 // CANONICALISED here rather than left as typed: the discovery file publishes
 // this path so the hook can tell which decks share one log and elect a single
 // writer for it, and two spellings of one file would read as two files.
@@ -184,7 +523,12 @@ const { claudeConfigDir, hasClaudeInstalled } =
 const { canonicalLogPath } = await import(pathToFileURL(join(PKG_ROOT, "src/server/log-writer.mjs")).href);
 const persist = flags.noPersist
   ? null
-  : canonicalLogPath(flags.history ?? join(claudeConfigDir(), "agent-dag", "events.jsonl"));
+  // The log follows the deck rather than Claude Code now — a hundred megabytes
+  // of rotating events was never configuration, and it was living in another
+  // application's configuration directory. `--history` still wins, and the
+  // canonical form is still what the discovery file publishes, so decks that
+  // share a path still elect one writer for it.
+  : canonicalLogPath(flags.history ?? join(deckLogDir(), "events.jsonl"));
 
 const { installHooks, keepDiscovery, removeDiscovery, hasCodexInstalled } =
   await import(pathToFileURL(join(PKG_ROOT, "src/server/installer.mjs")).href);
@@ -888,11 +1232,90 @@ dieWithParent(() => shutdown(0));
 // whole report, and a bind that fails in there with nothing attached to it is an
 // unhandledRejection — which Node answers by killing the process over a port it
 // could have named.
+// ── is one of ours already up? ────────────────────────────────────────────────
+// A bare `ccdeck` typed beside a deck that is already running used to build a
+// second everything on a random port, and neither half mentioned the other.
+// src/server/running-deck.mjs carries the whole argument, the registry read and
+// the token handshake that makes the answer trustworthy; this is only where it
+// is asked.
+//
+// ASKED EXACTLY HERE, and the position is the point. Everything the answer
+// depends on is resolved above — the workspace, the canonical log path, which
+// of the two CLIs this deck would serve — and nothing below has run yet: no
+// port bound, no hooks installed, no tool probed, no banner painted, no
+// discovery file written. An attach therefore leaves the machine precisely as
+// it found it, which is what makes it safe to do without asking.
+//
+// A respawn is excluded on its own line rather than left to the flag check.
+// The supervisor relaunches us with `--port <bound>`, which is a shaping flag
+// and would be excluded anyway — but a restart is THIS deck coming back, and
+// having that read as "somebody typed ccdeck twice" is an accident waiting for
+// the day the supervisor stops passing the port.
+if (!RESPAWN && !asksForOwnDeck(flags)) {
+  const live = await runningDeck({
+    want: { workspace, persist, codex: wantCodex, claude: wantClaude },
+  }).catch(() => null);
+  if (live) {
+    const liveUrl = `http://127.0.0.1:${live.port}`;
+    const note = versionNote(live.version, PKG_VERSION);
+    // Not the startup report's rows. That report has a label column because it
+    // has twelve lines to align; this has two, and borrowing the column would
+    // indent a three-line message behind a gutter sized for "Codex sessions".
+    //
+    // The version chunk is dropped rather than printed as "v?" when the running
+    // deck is too old to report one — see versionNote, which says nothing in the
+    // same case for the same reason.
+    const ident = [live.version ? `v${live.version}` : "", `pid ${live.pid}`]
+      .filter(Boolean).join(`  ${G.bullet}  `);
+    write(`\n  ${P.ok}${G.ok}${P.reset}  deck already running${P.muted}  ${G.bullet}  ${ident}${P.reset}\n`);
+    // Its own line, always. The URL is the one detail an ellipsis would destroy
+    // — half an address is not a shorter address — and this message has no
+    // report to hand it to. Same rule as statusLine's `keep`.
+    write(`     ${P.accent}${P.bold}${link(liveUrl, liveUrl, LINKS)}${P.reset}\n`);
+    if (note) write(`  ${P.warn}${G.warn}  ${note}${P.reset}\n`);
+    // THE TYPO'S WARNING, on the path that has no startup report to carry it.
+    //
+    // asksForOwnDeck used to answer `true` for these two so the report would
+    // run and print them, and that is how `ccdeck --stpo` — a misspelling of
+    // the flag that STOPS a deck — came to build a second one. The warning was
+    // the requirement; the extra process never was. Printed here, in the same
+    // rows the report uses, so nothing is lost and nothing is started.
+    reportUnknownFlags(flags.unknown);
+    reportIncompleteFlags(flags.incomplete);
+    // The line that says a second deck was NOT started. Without it the command
+    // looks like it did nothing at all, which is the other way to be confusing
+    // about this — and it names the flag for the person who really did want two.
+    write(`\n  ${P.muted}${G.dash}  no second deck was started ${G.dash} \`${INVOKED_AS ?? PRODUCT} --new\` starts one${P.reset}\n`);
+    if (openBrowser) {
+      write(`\n  ${P.ok}${P.bold}${G.play}  opening browser${G.ellipsis}${P.reset}\n\n`);
+      try {
+        const { openUrl, LAUNCH_GRACE_MS } = await import(pathToFileURL(join(PKG_ROOT, "src/server/open-url.mjs")).href);
+        openUrl(liveUrl);
+        // Held for exactly as long as openUrl needs to fall through to its next
+        // launcher. Every child it spawns is unref'd, so an immediate exit ends
+        // this process before a missing xdg-open has been answered by gio — and
+        // then no browser opens and nothing says why. The boot path never had
+        // to think about this because it stays alive forever.
+        await sleep(LAUNCH_GRACE_MS);
+      } catch { /* the URL is on screen; it can be clicked or pasted */ }
+    } else {
+      write("\n");
+    }
+    process.exit(0);
+  }
+}
+
 const starting = startServer({
   port, persist, workspace, codex: wantCodex, claude: wantClaude,
   // Withheld when nothing is supervising us: without a parent, exiting is just
   // exiting, and /api/restart answers 501 so the UI hides the control.
   onRestart: SUPERVISED ? requestRestart : null,
+  // NOT withheld, unlike the restart above. A restart needs a supervisor to
+  // bring the replacement up on the same port; ending is something any deck can
+  // do on its own, supervised or not, and `ccdeck --stop` must work on both.
+  // shutdown() is a hoisted declaration precisely so it is callable from the
+  // first instruction of this module — see the long note beside it (#448).
+  onStop: () => shutdown(0),
 }).then(s => ({ ok: true, s }), err => ({ ok: false, err }));
 
 // Once-per-session setup — hook install, tool probes, registry lookups, and the
@@ -975,6 +1398,17 @@ discovery = keepDiscovery({
   token: hookToken(),
   persist,
   codex: wantCodex,
+  // Both read by the next `ccdeck` on this machine, not by us: `claude` is half
+  // of the shape it compares before it will attach to us, and `version` is what
+  // it prints when the deck it found is not the one the user just launched. See
+  // src/server/running-deck.mjs.
+  claude: wantClaude,
+  version: PKG_VERSION,
+  // The supervisor above us, for `ccdeck --stop`'s fallback ladder: a worker
+  // killed under a live supervisor is a worker the supervisor puts back, so the
+  // parent has to go first and cannot be found without being told. Null when
+  // nothing is supervising, which is the same question `onRestart` asks.
+  parent: SUPERVISED ? process.ppid : null,
   onState: (state) => {
     const first = registered === null;
     registered = state.ok;
@@ -1001,6 +1435,75 @@ if (openBrowser && !RESPAWN) {
   } catch {}
 }
 
+// ── the deck from before this version that is still running ──────────────────
+//
+// UPGRADE DAY, and without this it is a mystery. A deck older than the attach
+// publishes no `claude` and no `version` in its discovery record, so sameShape
+// cannot match it — deliberately, because a record that cannot be compared is
+// not one to attach to. The consequence is that the first `ccdeck` after an
+// upgrade starts a SECOND deck beside the one already running, opens a tab on
+// it, and says nothing; and `ccdeck --stop` will not find the old one either,
+// because it has the same shape problem.
+//
+// So it is named, once, with the command that actually clears it. Only for
+// decks with no version: a deck started with `--new`, or one scoped to another
+// workspace, is somebody's deliberate second deck and needs no explaining.
+if (!RESPAWN) {
+  try {
+    const { liveDecks } = await import(pathToFileURL(join(PKG_ROOT, "src/server/running-deck.mjs")).href);
+    const older = (await liveDecks()).filter(d => !d.version);
+    if (older.length) {
+      const where = older.map(d => d.port).join(", ");
+      write(`  ${P.warn}${G.warn}${P.reset}  ${P.muted}${older.length === 1 ? "a deck" : `${older.length} decks`} from an older ${PRODUCT} ${older.length === 1 ? "is" : "are"} still running on ${where}${P.reset}\n`);
+      write(`     ${P.muted}too old to be recognised, so this one started beside ${older.length === 1 ? "it" : "them"} ${G.dash} \`${INVOKED_AS ?? PRODUCT} --stop --all\` clears the lot${P.reset}\n\n`);
+    }
+  } catch { /* a question about other decks is never a reason to fail a boot */ }
+}
+
+// ── starting at login ─────────────────────────────────────────────────────────
+//
+// ONCE PER MACHINE, EVER. The record in the deck's own data directory is what
+// makes that true: without it, `--uninstall-service` would be undone by the next
+// start, which is not an uninstall — it is a tool arguing with its user.
+//
+// After the boot rather than during it, and deliberately: a deck that could not
+// come up has no business teaching the machine to start it at every login. By
+// here the port is bound, the hooks are registered and the browser is open.
+//
+// npx is excluded and AGENTS_DECK_NO_INSTALL is honoured — see
+// shouldOfferService, which owns both rules and says why. A failure is one line
+// and nothing else: the deck is already running, and the worst case is the
+// behaviour every version before this one had.
+if (!RESPAWN) {
+  try {
+    const svc = await import(pathToFileURL(join(PKG_ROOT, "src/server/login-service.mjs")).href);
+    const { isGitCheckout, isNpxInstall } = await import(pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href);
+    if (svc.shouldOfferService({
+      record: svc.readServiceRecord(deckDataDir()),
+      npx: isNpxInstall(PKG_ROOT),
+      checkout: isGitCheckout(PKG_ROOT),
+    })) {
+      const out = svc.installService({
+        script: join(PKG_ROOT, "bin", "agent-dag.js"),
+        logPath: join(deckLogDir(), "deck.log"),
+        product: PRODUCT,
+      });
+      svc.writeServiceRecord(deckDataDir(), out.ok
+        ? { installed: PKG_VERSION, at: new Date().toISOString(), path: out.path }
+        : { failed: out.reason ?? "unknown", at: new Date().toISOString(), version: PKG_VERSION });
+      // Said once, on the one run that does it, and never again. A tool that
+      // adds itself to your login items and does not mention it is a tool you
+      // find later, in a settings pane, and stop trusting.
+      write(out.ok
+        ? `  ${P.muted}${G.dash}  ${PRODUCT} will now start when you log in ${G.dash} \`${INVOKED_AS ?? PRODUCT} --uninstall-service\` undoes it${P.reset}\n\n`
+        : `  ${P.muted}${G.dash}  could not set ${PRODUCT} to start at login (${out.reason}) ${G.dash} it still starts when you type it${P.reset}\n\n`);
+    }
+  } catch (err) {
+    // Never fatal. The deck is up; this is a convenience that did not happen.
+    console.error(`${PRODUCT}: could not check the login item:`, err?.message ?? err);
+  }
+}
+
 // ── Pulse indicator ───────────────────────────────────────────────────────────
 // The whole line is rewritten each beat rather than just the dot: anything else
 // on this deck that has something to say writes a newline first, and after that
@@ -1090,6 +1593,13 @@ if (MOTION) {
 // the window opened at the top of this file closes; see requestRestart.
 booted = true;
 markDeckReady();
+// And said out loud, one link up. A launcher that put this deck in the
+// background has been tailing its log into the user's terminal since the spawn
+// and is waiting for exactly this to stop and hand the prompt back — NOT for
+// `listening`, which is sent before the server-ready row, the log row and the
+// browser line are written, and would cut the last three lines off every boot.
+// Inert when nothing is supervising us.
+try { process.send?.({ type: "booted" }); } catch { /* no channel; nothing waiting */ }
 runHeldRestart();
 
 /**
@@ -1250,10 +1760,28 @@ Usage:
 Options:
   -p, --port <number>      Preferred port (default: 4317; falls back to 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.
+                           Without it, a bare \`${PRODUCT}\` beside a deck that is
+                           already up opens that deck's tab instead of building
+                           a rival on another port
+      --stop               Stop the deck a bare \`${PRODUCT}\` would open.
+                           With --port <n>, stop that one; with --all, stop every
+                           deck on this machine
+      --status             What is running on this machine, and on which ports
+      --logs               What the deck wrote where a terminal would have shown
+                           it, and where that file is
+      --install            Put the deck on your PATH and start it at login.
+                           What an \`npx\` run needs to survive a reboot
+      --install-service    Start the deck when you log in. Set up on first run;
+                           this is only for putting it back
+      --uninstall-service  Stop starting at login. \`--uninstall\` does this too
       --workspace <path>   Only capture sessions whose cwd is inside <path>
       --scope              Restrict to current working directory
-      --all                Capture every session (default)
-      --history <path>     Override events log file (default: ~/.claude/agent-dag/events.jsonl)
+      --all                Capture every session (default). Beside --stop it
+                           means every deck rather than every session
+      --history <path>     Override events log file (default: this platform's log directory)
       --no-persist         Don't write or replay events log (RAM-only)
       --codex              Force-enable Codex capture even if ~/.codex/ missing
       --no-codex           Skip Codex capture (Claude only)