ccdeck 3.22.8 → 3.22.10

package/src/server/login-service.mjs

@@ -314,6 +314,30 @@ export function lingerState({ platform = process.platform, run = spawnSync, user
   } catch { return "unknown"; }
 }
 
+/**
+ * The variables that decide WHICH deck a start is, for the login item's job.
+ *
+ * A login item runs in the environment the service manager builds, not the
+ * shell's. Somebody who exports CLAUDE_CONFIG_DIR, CCDECK_HOME or CODEX_HOME got
+ * a deck keyed to those directories from the terminal and one keyed to the
+ * defaults at login: two registries that cannot see each other, so two decks
+ * and two LAN keys on one machine — the one-deck rule in running-deck.mjs holds
+ * per registry and cannot reach across. Carried into the job so both starts are
+ * the same deck. Only the ones that are set: an unset variable written into the
+ * job as "" would be a different setting, not the same absent one.
+ *
+ * Windows is not given these. A Task Scheduler job has no environment block in
+ * its XML; it inherits the user's persistent variables, which is where a
+ * Windows user sets them (`setx`) for them to outlive the shell anyway.
+ */
+export const SCOPE_VARS = Object.freeze(["CLAUDE_CONFIG_DIR", "CCDECK_HOME", "CODEX_HOME"]);
+
+export function scopeEnv(env = process.env) {
+  return Object.fromEntries(
+    SCOPE_VARS.filter(k => typeof env?.[k] === "string" && env[k].trim() !== "").map(k => [k, env[k]]),
+  );
+}
+
 /**
  * Write the login item and register it.
  *

package/src/server/running-deck.mjs

@@ -1,4 +1,4 @@
-// Why a second `ccdeck` must not quietly become a second deck.
+// Why a second `ccdeck` must never leave a second deck behind it.
 //
 // 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
@@ -15,7 +15,7 @@
 //
 // 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.
+// writes <config>/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
@@ -28,12 +28,26 @@
 // 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.
+// ONE DECK, WHATEVER THE SHAPE. The first answer to "a deck is up" attached
+// only to a deck that was exactly the one this start would have built, and
+// built a second one beside anything else. So a flag, an older version, or an
+// environment that decided `codex` or the log path differently — a login item
+// runs under the service manager's environment, not the shell's — each left
+// two decks running on one machine, with two LAN keys and two rows on every
+// colleague's panel. It was reported from the field exactly that way. Now a
+// start keeps at most one:
+//
+//   the deck found serves what this start asked for, and is not older  → attach
+//   anything else                                                        → stop it, start
+//
+// The newest start wins, because it is the one somebody just asked for. The
+// rule is secondStart, a function of what is running and what was asked, so it
+// can be pinned without starting a process.
+//
+// PER CLAUDE CONFIG DIRECTORY, which is where the registry lives. For nearly
+// everybody that is one per user; somebody who points CLAUDE_CONFIG_DIR at a
+// second directory has a second registry, and has been getting a second deck
+// with its own identity on purpose since deck-home.mjs was written.
 //
 // 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
@@ -63,67 +77,86 @@ export function deckRegistryDir(env = process.env, home = undefined) {
 }
 
 /**
- * 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.
+ * Would this record's deck serve what we were about to build?
  *
- * `--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.
+ * 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` and fails — and a deck that old is
+ * replaced rather than attached to, which is what a start does with any deck
+ * it cannot vouch for.
  */
-export const SHAPING_FLAGS = Object.freeze([
-  "port", "workspace", "scope", "history", "noPersist",
-  "codex", "noCodex", "claude", "noClaude",
-]);
+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);
+}
 
 /**
- * Is this command line one that must build its own deck?
+ * Is `running` a version older than `ours`?
  *
- * 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.
+ * Numeric, field by field, because "3.9.0" sorts after "3.22.0" as a string. A
+ * running deck that publishes no version at all predates the field, which makes
+ * it older than anything that does. Our own version unreadable is the one case
+ * with nothing to compare, and it answers no: a start that cannot say what it
+ * is has no grounds to replace anything.
+ */
+export function olderVersion(running, ours) {
+  const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(v ?? ""));
+    return m ? m.slice(1).map(Number) : null;
+  };
+  const o = parse(ours);
+  if (!o) return false;
+  const r = parse(running);
+  if (!r) return true;
+  for (let i = 0; i < 3; i++) if (r[i] !== o[i]) return r[i] < o[i];
+  return false;
+}
+
+/**
+ * Does this running deck already serve what this start asked for?
  *
- * 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.
+ * The shape, the port when one was named, and a version no older than ours.
+ * `port` is the one `--port` asked for, or null when none was; 0 is "any free
+ * port", which every running deck satisfies.
  */
-export function asksForOwnDeck(flags = {}) {
-  if (flags.new === true) return true;
-  return SHAPING_FLAGS.some((k) => flags[k] !== undefined);
+export function serves(record, { want = {}, port = null, ours = "" } = {}) {
+  return sameShape(record, want)
+    && (port == null || port === 0 || record.port === port)
+    && !olderVersion(record.version, ours);
 }
 
 /**
- * Would this record's deck serve what we were about to build?
+ * What a start does about the decks already running.
  *
- * 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.
+ *   { act: "start",   stop: [] }        nothing is running
+ *   { act: "attach",  deck, stop }      open `deck`; stop the rest — leftovers
+ *                                       from before this rule
+ *   { act: "replace", stop }            stop every one of them, then start
+ *   { act: "yield",   deck, stop: [] }  a respawn found somebody else's deck
+ *
+ * `fresh` is `--new`: replace even a deck that would have served. `respawn` is
+ * the supervisor bringing a crashed or restarted worker back — that is THIS
+ * deck returning, so anything already running got there in the gap, was asked
+ * for more recently, and keeps its place.
+ *
+ * The deck kept on an attach is the first that serves, in the registry's port
+ * order, so the answer is the same every time it is asked.
  */
-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);
+export function secondStart({ live = [], want = {}, port = null, ours = "", fresh = false, respawn = false } = {}) {
+  if (!live.length) return { act: "start", stop: [] };
+  if (respawn) return { act: "yield", deck: live[0], stop: [] };
+  const keep = fresh ? null : live.find(d => serves(d, { want, port, ours })) ?? null;
+  if (keep) return { act: "attach", deck: keep, stop: live.filter(d => d !== keep) };
+  return { act: "replace", stop: [...live] };
 }
 
 /** 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. */
+ *  older than the handshake: it cannot prove anything, so it can be neither
+ *  attached to nor stopped by token, and it keeps the behaviour it has always
+ *  had. */
 function usable(d) {
   return Boolean(d)
     && Number.isInteger(d.pid)
@@ -134,13 +167,13 @@ function usable(d) {
 /**
  * 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.
+ * NOT PROVED — this is the cheap half, a directory listing and a signal-0 each.
+ * `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
@@ -167,39 +200,16 @@ export async function registeredDecks({
   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.
+ * What a start decides by, the list `--status` prints and the list `--stop`
+ * ends. Everything is challenged: a start that is about to stop a deck must
+ * know it is one, and 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(),
@@ -216,19 +226,18 @@ export async function liveDecks({
 /**
  * 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.
+ * An attach only ever keeps a deck at least as new as the one launched — an
+ * older one is replaced — so a difference here is somebody running an older
+ * copy, an npx cache or a second install, beside a newer deck. That deck is
+ * kept and they are told, because the newer one is what they would have wanted.
  *
- * 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.
+ * Empty when the versions agree, and empty when either side is too old to
+ * report one: "unknown" beside a number is noise.
  */
 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`;
+  return olderVersion(running, ours)
+    ? `running v${running}, older than the v${ours} you launched`
+    : `running v${running}, newer than the v${ours} you launched — kept it`;
 }

package/src/server/self-update.mjs

@@ -274,7 +274,7 @@ export function bareSpecName(spec) {
  *  the answer is null instead, which is what invoked-as.mjs needs: it asks which
  *  name the user typed, and there the package name is not a lesser answer, it is
  *  a wrong one. */
-export function npxSpecFromMeta(meta, fallback = "agents-deck") {
+export function npxSpecFromMeta(meta, fallback = PUBLISHED_NAME) {
   const list = meta && meta._npx && Array.isArray(meta._npx.packages) ? meta._npx.packages : [];
   for (const entry of list) {
     const name = bareSpecName(entry);
@@ -286,7 +286,7 @@ export function npxSpecFromMeta(meta, fallback = "agents-deck") {
 /** The same, answered against the filesystem. Null when this is not an npx run,
  *  and — for a caller that passed no fallback — when the metadata cannot be
  *  read. */
-export function npxRestartSpec(pkgRoot, name = "agents-deck") {
+export function npxRestartSpec(pkgRoot, name = PUBLISHED_NAME) {
   const root = npxRoot(pkgRoot);
   if (!root) return null;
   let meta = null;
@@ -331,18 +331,32 @@ export function npxRestartSpec(pkgRoot, name = "agents-deck") {
 // other. What both of them do carry is their own package.json, which npm's
 // rename made authoritative: see installedName.
 
-/** Every name this deck is published under.
+/** Every name an install of this deck can have been REACHED under.
  *
- *  `agents-deck` and `agent-dag` are one tarball published twice — see
- *  .github/workflows/publish.yml, which renames it between the two — and since
- *  #340 `ccdeck` is a third rename of the same tarball rather than a launcher
- *  package in front of it. The same three strings as
+ *  Only `ccdeck` is published now. `agents-deck` and `agent-dag` were this
+ *  tarball published twice more, then (from 3.22.3) small packages that
+ *  depended on ccdeck, and both stay on the registry at their last version — so
+ *  a deck can still be running inside one of them, or out of an npx run of one
+ *  of them, and this list is what lets it recognise that. It is not the list of
+ *  names to ask npm about: see PUBLISHED_NAME. The same three strings as
  *  invoked-as.mjs's COMMANDS, and deliberately not that list: this is the set
- *  of npm PACKAGES a `npm i -g` may name, that is the set of bin commands a
- *  user may type. They are equal only because the rename made them so, and a
- *  test pins them against each other rather than either side assuming it. */
+ *  of npm PACKAGES an install may belong to, that is the set of commands a user
+ *  may have typed. A test pins them against each other rather than either side
+ *  assuming it. */
 export const ALIAS_PACKAGES = ["agents-deck", "agent-dag", "ccdeck"];
 
+/** The one name the deck is published under, and so the only package whose
+ *  dist-tag still moves. */
+export const PUBLISHED_NAME = "ccdeck";
+
+/** The names it is no longer published under. */
+export const RETIRED_NAMES = ["agents-deck", "agent-dag"];
+
+/** The published name in place of a retired one; any other name unchanged. */
+export function currentName(name) {
+  return RETIRED_NAMES.includes(name) ? PUBLISHED_NAME : name;
+}
+
 /** Which of those three THIS build was published as, out of its own manifest.
  *
  *  The other half of the same bug, and the easier half. `agent-dag` is not a
@@ -373,7 +387,7 @@ export const ALIAS_PACKAGES = ["agents-deck", "agent-dag", "ccdeck"];
  *  `fallback` is what to answer when the manifest is missing, unreadable, or
  *  names something that is not one of ours — the caller's own `name`, so every
  *  shape that cannot prove which alias it is keeps the behaviour it had. */
-export function installedName(pkgRoot, fallback = "agents-deck") {
+export function installedName(pkgRoot, fallback = PUBLISHED_NAME) {
   const self = readManifest(pkgRoot)?.name;
   return typeof self === "string" && ALIAS_PACKAGES.includes(self) ? self : fallback;
 }
@@ -405,7 +419,7 @@ export function hostRoot(pkgRoot) {
  *  `npm i -g their-app@latest`: a package it has no business installing, and on
  *  a private name one that does not exist. Confining the answer to the three
  *  published names leaves every such install with the fallback it has today. */
-export function hostNameFromMeta(meta, name = "agents-deck") {
+export function hostNameFromMeta(meta, name = PUBLISHED_NAME) {
   const host = typeof meta?.name === "string" ? meta.name : null;
   if (!host || !ALIAS_PACKAGES.includes(host)) return null;
   return typeof meta?.dependencies?.[name] === "string" ? host : null;
@@ -413,7 +427,7 @@ export function hostNameFromMeta(meta, name = "agents-deck") {
 
 /** The same, answered against the filesystem: `{ root, name }` for the alias
  *  package this copy was installed as a dependency of, or null. */
-export function hostPackage(pkgRoot, name = "agents-deck") {
+export function hostPackage(pkgRoot, name = PUBLISHED_NAME) {
   const root = hostRoot(pkgRoot);
   if (!root) return null;
   const host = hostNameFromMeta(readManifest(root), name);
@@ -457,8 +471,8 @@ export function successorRoot(pkgRoot) {
   return typeof name === "string" && ALIAS_PACKAGES.includes(name) ? root : null;
 }
 
-/** The package an upgrade would actually install here — the only package worth
- *  asking npm about.
+/** The package an upgrade would actually install here — and, but for a retired
+ *  name, the one worth asking npm about (see registryName).
  *
  *  The check used to ask about `agents-deck` no matter what the upgrade
  *  command installed, so a deck started with `npx ccdeck` compared its version
@@ -475,7 +489,7 @@ export function successorRoot(pkgRoot) {
  *  shape carries that answer somewhere different — npx in the spec it recorded,
  *  a stub install in the layout npm built, a plain global install in the
  *  manifest of the package it is. All three are read; none is assumed. */
-export function upgradeName(pkgRoot, name = "agents-deck") {
+export function upgradeName(pkgRoot, name = PUBLISHED_NAME) {
   // The published name this build actually carries, which outranks `name` in
   // every branch below because `name` is a default at every call site in the
   // deck and the manifest on disk is not a guess. It replaces the parameter
@@ -483,17 +497,20 @@ export function upgradeName(pkgRoot, name = "agents-deck") {
   // registry-shaped answers meet — the dist-tag that is fetched, the marker it
   // is cached in, the command the user is shown, and the argv npm is spawned
   // with — so resolving the name once here is what keeps those four naming one
-  // package, which is the property the whole function exists to hold.
+  // package. registryName is the one exception, for a retired name, and it
+  // starts from this answer.
   const self = installedName(pkgRoot, name);
   // A checkout installs nothing at all, so the published name is the only
   // sensible subject for the version question — and the only one whose
   // dist-tag says anything about the branch the maintainer is sitting on.
   if (isGitCheckout(pkgRoot)) return self;
   // npx recorded the spec the user typed, which is a better answer than the
-  // manifest: `npx ccdeck` unpacks a deck whose manifest says `agents-deck`,
-  // and re-running the name they did not type would move them off the stub.
-  // The manifest is what is left when that record cannot be read.
-  if (isNpxInstall(pkgRoot)) return bareSpecName(npxRestartSpec(pkgRoot, self)) ?? self;
+  // manifest — except that a retired name answers `ccdeck`. npx reinstalls only
+  // when a spec resolves to a different version, and `agents-deck@latest`
+  // resolves to the same last-published package forever, so re-running it
+  // would reuse the cached copy, and the ccdeck inside it, and never move. The
+  // manifest is what is left when the record cannot be read.
+  if (isNpxInstall(pkgRoot)) return currentName(bareSpecName(npxRestartSpec(pkgRoot, self)) ?? self);
   // Left: a global install, where the answer is whichever package owns the
   // directory npm would rewrite. That is the stub for `npm i -g ccdeck`, where
   // the deck is nested one level down inside a package it is not named after,
@@ -517,7 +534,7 @@ export function upgradeName(pkgRoot, name = "agents-deck") {
 }
 
 /** The exact line the user can paste, for the way THIS copy was installed. */
-export function upgradeCommand(pkgRoot, name = "agents-deck") {
+export function upgradeCommand(pkgRoot, name = PUBLISHED_NAME) {
   // A checkout is updated by pulling, and the bundle is built, not shipped —
   // so `npm run build` is part of the answer rather than an afterthought.
   if (isGitCheckout(pkgRoot)) return "git pull && npm run build";
@@ -529,6 +546,21 @@ export function upgradeCommand(pkgRoot, name = "agents-deck") {
   return `npm i -g ${upgradeName(pkgRoot, name)}@latest`;
 }
 
+/** The package to ask npm about: the one an upgrade installs, except that a
+ *  retired name is asked about as `ccdeck`.
+ *
+ *  One install reaches that exception. A deck sitting inside the old
+ *  `agents-deck` or `agent-dag` package upgrades by reinstalling THAT package —
+ *  installing `ccdeck` would write a tree this process never reads, #358 again —
+ *  but that package's dist-tag stopped moving when it stopped being published.
+ *  The reinstall is still the right act: the old package depends on
+ *  `ccdeck@^3`, and npm resolves that to the newest ccdeck on every reinstall,
+ *  even of the same version. So the version asked about is ccdeck's and the
+ *  command names the old package — the one place the two differ, on purpose. */
+export function registryName(pkgRoot, name = PUBLISHED_NAME) {
+  return currentName(upgradeName(pkgRoot, name));
+}
+
 // ── what npm has ─────────────────────────────────────────────────────────────
 
 // The dist-tags endpoint answers with ~20 bytes ({"latest":"1.30.7"}); the full
@@ -597,7 +629,7 @@ async function isPublished(name, version) {
  *  common case reads plainly, and the tail is trimmed so a pathological name
  *  cannot produce a path the OS refuses. An unusable name falls back to the
  *  default rather than to the shared file this fix exists to get rid of. */
-export function markerFileName(name = "agents-deck") {
+export function markerFileName(name = PUBLISHED_NAME) {
   return `.self-update-check-${safeNamePart(name)}`;
 }
 
@@ -613,7 +645,7 @@ function safeNamePart(name) {
     // trailing dot from a file name, so a name that ends in one would write to
     // a path that is not the path we would later read.
     .replace(/^[-.]+|[-.]+$/g, "");
-  return safe || "agents-deck";
+  return safe || PUBLISHED_NAME;
 }
 
 function markerPath(name) {
@@ -664,7 +696,7 @@ function readMarker(name) {
  *  between a click and a fetch, and the reason the fetch is about to fail may
  *  well be that there is no network — and it has to be the same number the
  *  banner offered, which is precisely what the marker holds. */
-export function lastKnownLatest(name = "agents-deck") {
+export function lastKnownLatest(name = PUBLISHED_NAME) {
   const v = readMarker(name)?.version;
   return typeof v === "string" && v ? v : null;
 }
@@ -1026,7 +1058,7 @@ export function claimRestartFailureKey(env = process.env, pid = process.pid) {
 
 /** `ccdeck` under supervisor 4821 → `.restart-failed-ccdeck-4821`, or null when
  *  there is no supervisor, which is not a deck any note can be about. */
-export function restartFailureFileName(name = "agents-deck", key = restartFailureKey()) {
+export function restartFailureFileName(name = PUBLISHED_NAME, key = restartFailureKey()) {
   const owner = safeOwner(key);
   return owner ? `${NOTE_PREFIX}${safeNamePart(name)}-${owner}` : null;
 }
@@ -1041,7 +1073,7 @@ function restartFailurePath(name, key) {
  *  already failed here and is not being tried again. Best-effort: a read-only
  *  home costs the report, not the deck. */
 export function recordRestartFailure({
-  name = "agents-deck", command = null, error = null, version = null,
+  name = PUBLISHED_NAME, command = null, error = null, version = null,
   target = null, attempts = 1, at = Date.now(), failedAt = at, key = restartFailureKey(),
 } = {}) {
   const file = restartFailureFileName(name, key);
@@ -1072,13 +1104,13 @@ export function recordRestartFailure({
 
 /** Called before each attempt, so a retry is answered by its own outcome rather
  *  than by the last one's. */
-export function clearRestartFailure(name = "agents-deck", key = restartFailureKey()) {
+export function clearRestartFailure(name = PUBLISHED_NAME, key = restartFailureKey()) {
   const path = restartFailurePath(name, key);
   if (!path) return;
   try { rmSync(path, { force: true }); } catch { /* ignore */ }
 }
 
-export function readRestartFailure(name = "agents-deck", key = restartFailureKey()) {
+export function readRestartFailure(name = PUBLISHED_NAME, key = restartFailureKey()) {
   const path = restartFailurePath(name, key);
   if (!path) return null;
   try {
@@ -1162,7 +1194,7 @@ export function upgradeStatus() {
  * assembled from request input: the only thing that varies is which alias, and
  * that is read off the install on disk and confined to ALIAS_PACKAGES.
  */
-export function startUpgrade({ pkgRoot, name = "agents-deck" }) {
+export function startUpgrade({ pkgRoot, name = PUBLISHED_NAME }) {
   if (_upgrade.state === "running") return { ok: true, already: true, command: _upgrade.command };
   const blocked = upgradeBlock(pkgRoot);
   if (blocked) return { ok: false, reason: blocked, command: upgradeCommand(pkgRoot, name) };
@@ -1314,13 +1346,15 @@ export function lastMeaningfulLine(text) {
  *  yet — the installability probe (see runCheck), each carrying its own
  *  AbortSignal timeout. That second request costs its timeout at most once per
  *  release; a deck sitting on the current release stays inside one. */
-export async function versionReport({ running, pkgRoot, name = "agents-deck", now = Date.now(), force = false }) {
+export async function versionReport({ running, pkgRoot, name = PUBLISHED_NAME, now = Date.now(), force = false }) {
   const installed = installedVersion(pkgRoot);
   // Asked about the package the command installs, not about the one this build
-  // happens to be named after — see upgradeName. Everything registry-shaped in
-  // this report is about `target`: the version, the marker it is cached in, and
-  // the name the report gives for it.
+  // happens to be named after — see upgradeName — except that a retired name
+  // is asked about as ccdeck, the only dist-tag that still moves (registryName).
+  // `target` is what the command installs and what the failure note is filed
+  // under; `asked` is whose version this reports and the marker it is cached in.
   const target = upgradeName(pkgRoot, name);
+  const asked = registryName(pkgRoot, name);
   // Only an explicit opt-out silences the registry.
   //
   // A checkout used to be excluded here too, on the reasoning that its version
@@ -1334,8 +1368,8 @@ export async function versionReport({ running, pkgRoot, name = "agents-deck", no
   const skipRegistry =
     process.env.AGENTS_DECK_NO_UPDATE_CHECK === "1" ||
     process.env.AGENTS_DECK_NO_INSTALL === "1";
-  const latest = skipRegistry ? null : await latestOnNpm(target, now, force);
-  const marker = skipRegistry ? null : readMarker(target);
+  const latest = skipRegistry ? null : await latestOnNpm(asked, now, force);
+  const marker = skipRegistry ? null : readMarker(asked);
   const blocked = upgradeBlock(pkgRoot);
   // An install started in THIS process outranks the note on disk: it is newer
   // by construction, and a running one must not be reported as a past failure.