agent-dag 1.42.0 → 1.44.1

package/src/server/quota.mjs

@@ -29,7 +29,7 @@
 // cooldown; 1 is not, because it is a local file read.
 import { activeAccountUsage, requestCollection } from "./claude-accounts.mjs";
 import { claudeCliCandidates, claudeConfigDir } from "./claude-dir.mjs";
-import { run } from "./exec.mjs";
+import { pathLookup, run } from "./exec.mjs";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -174,6 +174,11 @@ let _cacheAt  = 0;
 let _inflight = null;   // deduplicates concurrent CLI probes
 let _lastGood = null;   // last result that had real quota percentages
 let _lastSelfPollAt = 0;
+// Which account the readings below are about — as a counter, because the
+// account's identity is not something this module holds. invalidateQuotaCache
+// bumps it; every write in _doFetch is stamped with the value that was current
+// when that read STARTED. See publish().
+let _generation = 0;
 
 const CACHE_MS = 60_000;
 
@@ -356,15 +361,69 @@ function parseUsageText(raw) {
  *
  *  Exported, with everything it touches injectable, so the Windows branch is
  *  testable from the platforms this repo is actually developed on.
+ *
+ *  WHY THE BARE NAME HAS TO EARN ITS PLACE (#553). This used to be a `.find`
+ *  over `!c.includes(sep) || exists(c)`, which reads as "a bare name always
+ *  answers, a full path only when it is there". On Windows that is harmless —
+ *  the bare name is LAST in the list — but on POSIX it is FIRST, so the `||`
+ *  short-circuited on candidate one and `exists` was never called even once:
+ *  `~/.local/bin/claude`, `/usr/local/bin/claude` and `/opt/homebrew/bin/claude`
+ *  were in a list nothing ever read. The user this broke is the one
+ *  claude-dir.mjs names out loud: Claude Code installed by the official
+ *  installer, so the binary is at `~/.local/bin/claude`, and the deck launched
+ *  from something whose PATH never sourced a shell rc — a LaunchAgent, a
+ *  systemd user unit, pm2, a desktop shortcut. `hasClaudeInstalled()` stats the
+ *  absolute paths and says yes, so hooks install and the Claude surface turns
+ *  on; every `claude --print /usage` spawn is then a bare-name ENOENT logged as
+ *  `quota: claude CLI failed`. On macOS there is no `.credentials.json` to fall
+ *  back to (the token is in the Keychain, #360), so the quota panel simply stays
+ *  dark on a machine that plainly has Claude Code. The identical install on
+ *  Windows worked, because there the ordering already said what this now says.
+ *
+ *  WHICH WINS. The candidate list's own order decides, unchanged on both
+ *  platforms — PATH first on POSIX, the two known install directories first on
+ *  Windows — because the ordering question here is the one getRunner in
+ *  ccusage.mjs already answered: preferring a different copy would silently
+ *  change which binary runs on every machine that has two, and a deck that
+ *  works today must not start running a `claude` it has never run. A user with
+ *  a current claude on PATH via nvm/mise/volta and a stale one left in
+ *  `~/.local/bin` keeps getting the one their own shell gives them. All that
+ *  changes is that a bare name is now only ANSWERED WITH when PATH actually
+ *  holds it, which is the same rule claudeCliOnDisk in claude-dir.mjs has
+ *  always applied to this very list — the two readers of one list can no longer
+ *  disagree about whether the deck can run what it says is installed.
+ *
+ *  WHAT IT COSTS. One PATH walk, stopping at the first hit, and only for the
+ *  bare candidate; the absolute paths are stat'ed only once PATH has come up
+ *  empty. That is the trade ccusage.mjs already priced for the same shape of
+ *  question — "a handful of stats, once per uncached fetch, against a process
+ *  spawn that follows it" — and here the spawn that follows is a whole Claude
+ *  Code process measured at ~3s, behind the SELF_POLL_MS floor.
+ *
+ *  `pathLookup` is used as a yes/no gate rather than for the path it found, on
+ *  purpose: answering with the bare name keeps spawn's own resolution (and, on
+ *  Windows, exec.mjs's PATHEXT candidate walk) in charge of the PATH case
+ *  exactly as before, so a PATH entry that merely LOOKS like a hit — a
+ *  directory named `claude` — cannot become the answer.
  */
 export function quotaClaudeBin(platform = process.platform, env = process.env,
                                home = homedir(), exists = existsSync) {
   const sep = platform === "win32" ? "\\" : "/";
-  // A bare name is left to spawn's own PATH lookup (and, on Windows, to the
-  // PATHEXT walk exec.mjs does by hand); a full path is only worth naming when
-  // it is actually there.
-  return claudeCliCandidates(platform, env, home)
-    .find(c => !c.includes(sep) || exists(c)) ?? "claude";
+  // process.env is case-insensitive on Windows; an injected plain object in a
+  // test is not, and %Path% is how the variable is actually spelled there.
+  const pathEnv = env.PATH ?? env.Path ?? env.path ?? "";
+  for (const c of claudeCliCandidates(platform, env, home)) {
+    // A full path is worth a single stat; a bare name means "ask PATH", which
+    // is pathLookup's walk — PATHEXT included, since `claude` on Windows is
+    // spelled `claude.exe` or `claude.cmd` and never the bare word.
+    if (c.includes(sep)) { if (exists(c)) return c; }
+    else if (pathLookup(c, platform, { pathEnv, exists })) return c;
+  }
+  // Nothing on PATH and nothing at any known install directory. The bare name
+  // is still the right last resort — POSIX `execvp` and cmd.exe's own search
+  // both deserve their turn at a layout no list here knows — and the ENOENT it
+  // produces is what `quota: claude CLI failed` reports.
+  return "claude";
 }
 
 export async function fetchClaudeQuota({ force = false } = {}) {
@@ -376,8 +435,44 @@ export async function fetchClaudeQuota({ force = false } = {}) {
   // good result with 0%).
   if (_inflight) return _inflight;
 
-  _inflight = _doFetch(now, force).finally(() => { _inflight = null; });
-  return _inflight;
+  // `_inflight === mine` rather than a bare clear: invalidateQuotaCache drops
+  // `_inflight` so the next caller starts a read that knows the account moved,
+  // and that read installs its own promise here. A read from before the switch
+  // finishing afterwards would otherwise clear the NEW one on its way out,
+  // letting a third caller spawn a second concurrent probe — which is the very
+  // thing this slot exists to prevent.
+  const mine = _doFetch(now, force, _generation)
+    .finally(() => { if (_inflight === mine) _inflight = null; });
+  _inflight = mine;
+  return mine;
+}
+
+/**
+ * Write a reading into the caches, unless the account moved while it was being
+ * taken.
+ *
+ * Every one of _doFetch's writes happens after at least one await — a store
+ * read, a 15-second HTTPS call, up to three `claude --print /usage` spawns with
+ * 1.2s between them — and invalidateQuotaCache clears variables, which does
+ * nothing to a function that is already running and still holds the old
+ * account's answer in a local. So a switch landing mid-flight was followed,
+ * milliseconds later, by the pre-switch reading being written straight back over
+ * the cleared cache: the invalidation looked like it worked and was undone
+ * before anyone could observe it.
+ *
+ * The fetch is deliberately NOT cancelled. Whoever asked for it is still owed an
+ * answer, and the reading is not wrong — it is simply about an account that is
+ * no longer active, which makes it a fine return value and a bad cached one.
+ * `_lastGood` gets the same guard, and needs it more: it is the half that
+ * survives the result cache's minute and comes back under a "stale" label for as
+ * long as the store has nothing to say about the new account.
+ */
+function publish(gen, result, at, { good = false } = {}) {
+  if (gen !== _generation) return result;
+  _cache   = result;
+  _cacheAt = at;
+  if (good) _lastGood = result;
+  return result;
 }
 
 /**
@@ -456,7 +551,7 @@ async function _execOnce(bin) {
   return { cliOk, parsed: parseUsageText(combined) };
 }
 
-async function _doFetch(now, force = false) {
+async function _doFetch(now, force = false, gen = _generation) {
   // Source 1: claude-swap's store. Free, and already paid for.
   let store = await storeQuota();
 
@@ -473,9 +568,7 @@ async function _doFetch(now, force = false) {
     // throttle inside is shared with the accounts panel, so two open panels
     // ask no more often than one.
     if (!force) requestCollection().catch(() => {});
-    _cache = store; _cacheAt = now;
-    _lastGood = store;
-    return store;
+    return publish(gen, store, now, { good: true });
   }
 
   // Nothing usable in the store. Everything below spends the user's budget, so
@@ -488,24 +581,16 @@ async function _doFetch(now, force = false) {
     // and then reverted to 23% (from a 48-minute-old store row) on the very
     // next poll, because the store had not moved.
     const held = freshest(store, _lastGood);
-    if (held) {
-      const result = { ...held, stale: true };
-      _cache = result; _cacheAt = now;
-      return result;
-    }
+    if (held) return publish(gen, { ...held, stale: true }, now);
     const result = { ok: false, reason: now < _rateLimitedUntil ? "rate_limited" : "waiting", fetchedAt: now };
-    _cache = result; _cacheAt = now - (CACHE_MS - 5_000);
-    return result;
+    return publish(gen, result, now - (CACHE_MS - 5_000));
   }
   _lastSelfPollAt = now;
 
   // Source 2: OAuth usage API — instant, exact, no cold-start gap.
   const api = await fetchOAuthUsage();
   if (api) {
-    const result = { ok: true, ...api, source: "api", fetchedAt: now };
-    _cache = result; _cacheAt = now;
-    _lastGood = result;
-    return result;
+    return publish(gen, { ok: true, ...api, source: "api", fetchedAt: now }, now, { good: true });
   }
 
   // Source 3: parse `claude --print /usage` CLI output.
@@ -526,10 +611,7 @@ async function _doFetch(now, force = false) {
 
   // Got real quota lines — cache normally and remember as last-known-good.
   if (parsed) {
-    const result = { ok: true, ...parsed, source: "cli", fetchedAt: now };
-    _cache = result; _cacheAt = now;
-    _lastGood = result;
-    return result;
+    return publish(gen, { ok: true, ...parsed, source: "cli", fetchedAt: now }, now, { good: true });
   }
 
   // No quota lines after retries. If we've ever seen real values, keep showing
@@ -540,10 +622,7 @@ async function _doFetch(now, force = false) {
   // vouches for numbers this branch already knows are stale. Short-cache so we
   // retry the CLI again soon.
   if (_lastGood) {
-    const result = { ..._lastGood, stale: true };
-    _cache = result;
-    _cacheAt = now - (CACHE_MS - 5_000);
-    return result;
+    return publish(gen, { ..._lastGood, stale: true }, now - (CACHE_MS - 5_000));
   }
 
   // Never had good data. CLI ran but lines absent → treat as genuine <1%.
@@ -552,9 +631,7 @@ async function _doFetch(now, force = false) {
     ? { ok: true, session5hPct: 0, session5hWindowSec: 18000,
         week7dPct: 0, week7dWindowSec: 604800, fetchedAt: now }
     : { ok: false, fetchedAt: now };
-  _cache = result;
-  _cacheAt = now - (CACHE_MS - 5_000);
-  return result;
+  return publish(gen, result, now - (CACHE_MS - 5_000));
 }
 
 /**
@@ -579,9 +656,29 @@ async function _doFetch(now, force = false) {
  * the shared request budget, and one that reset it would make switching a way to
  * hammer it. Until the store answers for the new account, "no reading yet" is
  * the honest thing to serve.
+ *
+ * Clearing the three variables is not enough on its own, because a fetch that is
+ * already running is not a variable. `_doFetch` writes `_cache` and `_lastGood`
+ * AFTER its awaits, so one that read the store before the switch and resolves
+ * after it put the previous account's numbers back into both, undoing this call
+ * from the other side of an await — and callers arriving in that window were
+ * handed the same in-flight promise rather than a read that knows the account
+ * moved. The window is real: a forced fetch goes through nudgeAndReread, which
+ * sleeps REREAD_TRIES * REREAD_GAP_MS = 2.4 seconds by construction, comfortably
+ * longer than a `cswap switch`.
+ *
+ * So the generation counter moves too. Every write in `_doFetch` is stamped with
+ * the generation that was current when that read started, and publish() drops
+ * any write whose stamp is stale — the fetch still resolves, and whoever asked
+ * for it still gets its answer, but that answer no longer becomes this module's.
+ * `_inflight` is released for the same reason: the next caller must start a read
+ * of its own rather than join one that is describing the account the deck just
+ * left.
  */
 export function invalidateQuotaCache() {
   _cache = null;
   _cacheAt = 0;
   _lastGood = null;
+  _generation++;
+  _inflight = null;
 }

package/src/server/self-update.mjs

@@ -26,7 +26,7 @@ import { accessSync, constants as FS, existsSync, mkdirSync, readdirSync, readFi
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { killTree } from "./exec.mjs";
+import { killTree, shimPath, spawnSpec } from "./exec.mjs";
 
 // Once an hour, not once a day.
 //
@@ -67,6 +67,68 @@ const LEGACY_MARKER = join(MARKER_DIR, ".self-update-check");
 // names are two different questions and must not be answered with one answer.
 const _inflight = new Map();
 
+// ── what a forced check may cost ─────────────────────────────────────────────
+//
+// `_inflight` deduplicates callers that OVERLAP and nothing else. `checkDue`
+// answers `true` on `force` before it asks anything else, so a caller that
+// waited for one check to settle and then asked again got a fresh
+// `https://registry.npmjs.org/…/dist-tags` every time. Reads on this server are
+// deliberately open — `isTrustedRead` does not apply the `Sec-Fetch-Site` test
+// that `isTrustedMutation` does, because a cross-site read of
+// `http://127.0.0.1:4317` is an ordinary top-level navigation — so
+//
+//     (async function spin() {
+//       for (;;) await fetch("http://127.0.0.1:4317/api/version?refresh=1",
+//                            { mode: "no-cors" });
+//     })();
+//
+// from any page the user had open was one registry request per turn, as fast as
+// the round trip allows, and every so often two of them: `runCheck` confirms a
+// tag it has not seen before against the version document. The requests are
+// small — the whole reason the dist-tags endpoint is used here rather than the
+// packument — but they leave the user's address, carrying the user-agent this
+// deck sets, and they are aimed at a third party rather than at the machine the
+// loop is running on. That makes it #580's shape with the cost pointed
+// outwards, which if anything is the worse direction.
+//
+// Nothing above this line was going to stop it. The hour is written to a marker
+// FILE, and `force` walks past it; `first` walks past it too; and on a machine
+// where `~/.agents-deck` cannot be written `writeMarker` swallows the failure,
+// so `checkDue` sees "never checked" on every single call and the hour is not
+// really there at all.
+//
+// So the floor sits under all of it, in this process's own memory, between the
+// last rule that admitted a check and the request it admitted. It is quota.mjs's
+// number and codex-quota.mjs's and codex-usage.mjs's — the five routes in this
+// deck's router that accept `?refresh=1` and can pay for it have no business
+// disagreeing about what it costs.
+const FORCE_POLL_MS = 60_000;
+
+// Stamped when a check STARTS rather than when npm answers, because what the
+// floor rations is the request. Per package name, like `_inflight` and like the
+// markers: two names are two different questions, and one of them being asked
+// is not a reason to refuse the other. Deliberately in memory rather than on
+// disk — the marker is shared by every deck running that package and this is
+// about what THIS process is sending.
+const _lastAskAt = new Map();
+
+/**
+ * Whether we may spend a registry request right now.
+ *
+ * Exported for tests, for the same reason quota.mjs exports `maySelfPoll`,
+ * codex-quota.mjs `mayFetchQuota` and codex-usage.mjs `mayScanUsage`: this is
+ * the rule, it is pure, and it is worth pinning down away from the request it
+ * guards.
+ */
+export function mayAskNpm({ now, lastAskAt }) {
+  // A stamp from the future is a clock that moved, not a check that just ran —
+  // the same case `checkDue` answers twice below with `> now`, and the same
+  // answer. Without it, a machine whose clock corrects backwards by an hour
+  // would go an hour without a version check.
+  if (lastAskAt > now) return true;
+  return now - lastAskAt >= FORCE_POLL_MS;
+}
+
 // ── version comparison ───────────────────────────────────────────────────────
 
 /** True when `a` sorts before `b`. Numeric-segment compare — non-numeric
@@ -113,9 +175,24 @@ function readManifest(dir) {
 
 /** Version currently written in the package's own package.json. Deliberately
  *  read fresh on every call: that is the whole point — it changes under a
- *  running process when npm replaces the install. */
+ *  running process when npm replaces the install.
+ *
+ *  And sometimes the directory changes with it. A `npm i -g ccdeck` performed
+ *  before #340 left the deck nested inside a launcher package; upgrading such an
+ *  install now writes the flat tarball over that launcher, and npm's reify takes
+ *  the nested copy — the one this process is running out of — with it. Reading
+ *  our own manifest then answers null, which pickNotice reads as "nothing is
+ *  installed" and turns into the same upgrade offered forever, with the restart
+ *  notice this module exists for never firing at all.
+ *
+ *  The version is not lost, it moved one directory up. successorRoot is where
+ *  to, and it answers null in every layout where nothing moved — so the normal
+ *  case still reads exactly one manifest. */
 export function installedVersion(pkgRoot) {
-  const v = readManifest(pkgRoot)?.version;
+  const own = readManifest(pkgRoot);
+  if (typeof own?.version === "string") return own.version;
+  const moved = successorRoot(pkgRoot);
+  const v = moved ? readManifest(moved)?.version : null;
   return typeof v === "string" ? v : null;
 }
 
@@ -139,7 +216,16 @@ export function isNpxInstall(pkgRoot) {
  *  returning "git pull && npm run build", `upgradeName` refusing to move a
  *  checkout onto a published alias, and `startUpgrade` refusing with
  *  `git_checkout`. A test importing the predicate would restate what those three
- *  already prove, one level further from the behaviour a user can see. */
+ *  already prove, one level further from the behaviour a user can see.
+ *
+ *  `existsSync` and not a directory test, deliberately (#587). Git writes `.git`
+ *  as a directory only for an ordinary clone; a linked worktree and a submodule
+ *  each get a FILE whose whole content is one `gitdir:` line, and all three are
+ *  checkouts nobody may install over. Nothing here reads that line, which is
+ *  also what keeps the rule identical on Windows, where the path inside it
+ *  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) {
   try { return existsSync(join(pkgRoot, ".git")); } catch { return false; }
 }
@@ -245,8 +331,9 @@ export function npxRestartSpec(pkgRoot, name = "agents-deck") {
 /** Every name this deck is published under.
  *
  *  `agents-deck` and `agent-dag` are one tarball published twice — see
- *  .github/workflows/publish.yml, which renames it between the two — and
- *  `ccdeck` is the stub that depends on it. The same three strings as
+ *  .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
  *  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
@@ -330,6 +417,43 @@ export function hostPackage(pkgRoot, name = "agents-deck") {
   return host ? { root, name: host } : null;
 }
 
+/**
+ * The directory that holds this install's code AFTER an upgrade replaced it,
+ * or null when nothing has been replaced.
+ *
+ * One layout produces this and it is a transitional one. Before #340, `npm i -g
+ * ccdeck` installed a launcher package with the deck nested inside it:
+ *
+ *     <prefix>/lib/node_modules/ccdeck/                     the launcher
+ *     <prefix>/lib/node_modules/ccdeck/node_modules/agents-deck/   pkgRoot
+ *
+ * upgradeName reads the host's declared dependency and correctly answers
+ * `ccdeck`, so the upgrade runs `npm i -g ccdeck@latest` — which since #340
+ * installs the deck itself over the host directory and removes everything that
+ * was under it, including pkgRoot. The process keeps running (POSIX keeps an
+ * open inode alive, and the modules are already loaded) out of a directory that
+ * no longer exists.
+ *
+ * Deliberately NOT hostPackage. That function recognises a host by the
+ * dependency it declares on us, and the whole point here is that the host has
+ * just stopped declaring one — it is no longer a launcher, it is the deck. What
+ * identifies it instead is its name, confined to the three we publish, for the
+ * same reason installedName confines its answer: this decides what a version
+ * report says about the user's machine, and a directory that merely happens to
+ * sit above us is not evidence.
+ *
+ * Guarded on our own manifest being unreadable, so nothing changes for an
+ * install that is intact — including the ordinary nested layout before it is
+ * upgraded, where pkgRoot answers for itself and this is never consulted.
+ */
+export function successorRoot(pkgRoot) {
+  if (readManifest(pkgRoot)) return null;
+  const root = hostRoot(pkgRoot);
+  if (!root) return null;
+  const name = readManifest(root)?.name;
+  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.
  *
@@ -372,7 +496,21 @@ export function upgradeName(pkgRoot, name = "agents-deck") {
   // the deck is nested one level down inside a package it is not named after,
   // and this build's own name for `npm i -g agents-deck` and `npm i -g
   // agent-dag`, where the deck IS the whole package and nothing is above it.
-  return hostPackage(pkgRoot, self)?.name ?? self;
+  //
+  // successorRoot is the third case, and it is the second half of the same
+  // question. Once that stub install HAS been upgraded, the host has stopped
+  // declaring a dependency on us — which is the only thing hostPackage
+  // recognises a host by — so this fell through to `self`, and `self` is the
+  // fallback `agents-deck` because our own manifest went with the directory.
+  // The user was then shown `npm i -g agents-deck@latest`: a different package,
+  // a second global tree, and their `ccdeck` binary left exactly where it was.
+  // That is #358 verbatim, arriving through the upgrade that was supposed to be
+  // the end of it. The successor's own manifest names it, and that name is what
+  // the next upgrade has to install.
+  const host = hostPackage(pkgRoot, self)?.name;
+  if (host) return host;
+  const moved = successorRoot(pkgRoot);
+  return moved ? installedName(moved, self) : self;
 }
 
 /** The exact line the user can paste, for the way THIS copy was installed. */
@@ -602,7 +740,8 @@ export function checkDue({ at, failedAt, pendingAt, now, first = false, force =
  *  cached answer immediately when the window has not elapsed.
  *
  *  `force` skips the window: the first call in this process, and an explicit
- *  "check now" from the UI. */
+ *  "check now" from the UI. What it does not skip is FORCE_POLL_MS — see
+ *  mayAskNpm, and the note above it for what a forced call used to cost. */
 async function latestOnNpm(name, now, force = false) {
   const m = readMarker(name);
   const key = markerFileName(name);
@@ -611,8 +750,18 @@ async function latestOnNpm(name, now, force = false) {
   if (!checkDue({ at: m?.at, failedAt: m?.failedAt, pendingAt: m?.pendingAt, now, first, force })) {
     return m?.version ?? null;
   }
+  // Offered before the floor: a check that has not answered yet is a lookup
+  // newer than the marker, which is what refresh asked for, and joining it costs
+  // nothing.
   const inflight = _inflight.get(key);
   if (inflight) return inflight;
+  // The floor, under every rule above it. A refused check is answered with the
+  // version we already hold — the same string an ordinary cached call returns,
+  // carrying the marker's own `checkedAt` rather than the moment of the read
+  // that was refused, so /api/version reports exactly what it reported a moment
+  // ago and no surface learns a new failure mode from being asked twice.
+  if (!mayAskNpm({ now, lastAskAt: _lastAskAt.get(key) ?? 0 })) return m?.version ?? null;
+  _lastAskAt.set(key, now);
   const run = runCheck(name, m, now)
     // Record the outcome, not just the moment, and record it against THIS
     // package: only an answer stamps `at`; a failure takes the short retry
@@ -663,13 +812,50 @@ export function pickNotice({ running, installed, latest }) {
 
 // ── installing ───────────────────────────────────────────────────────────────
 
-// npm is a .cmd shim on Windows, which spawn can only launch through a shell.
-// Everywhere else shell:false — with a shell, Node warns that arguments are
-// concatenated rather than escaped. Same pair the ccusage installer uses.
-const NPM = process.platform === "win32" ? "npm.cmd" : "npm";
-const NPM_SHELL = process.platform === "win32";
 const INSTALL_TIMEOUT_MS = 300_000; // a cold global install on a slow line
 
+/**
+ * What `spawn` gets for `npm install -g <target>@latest`.
+ *
+ * This was the last caller still spelling it the way #362 and #456 were written
+ * to remove: `spawn("npm.cmd", args, { shell: true })`, with a comment claiming
+ * it was "the same pair the ccusage installer uses". ccusage stopped using that
+ * pair when #456 fixed it, and this one was never revisited — it does not go
+ * through `run`/`runInteractive`/`runDetached`, so #457's sweep of their callers
+ * could not see it and exec-shim-callers.test.ts never listed it.
+ *
+ * Both halves of the old spelling were wrong on Windows and only one of them
+ * bites today.
+ *
+ * The one that bites: a `.cmd` shim locates its payload relative to `%~dp0`,
+ * the drive and path of the command token cmd.exe was handed, and a BARE
+ * `npm.cmd` carries no directory — so `%~dp0` came out as the deck's working
+ * directory and npm's shim went looking for `node_modules\npm\bin\npm-cli.js`
+ * underneath it. A user with a global install, deck started from
+ * `C:\Users\vceban`, clicks Update now and npm dies with `Cannot find module
+ * 'C:\Users\vceban\node_modules\npm\bin\npm-cli.js'` — on a machine whose npm
+ * is perfectly healthy, and where typing the same command at the same prompt
+ * works. shimPath is the answer, and `?? "npm.cmd"` keeps a layout it cannot see
+ * exactly as well off as it was.
+ *
+ * The one that does not, yet: `shell: true` makes Node join file and args with
+ * single spaces and no quoting. These arguments contain no spaces, so it has
+ * never mattered here — but it is the #362 defect sitting one argument away, and
+ * spawnSpec removes it by quoting every token into the cmd.exe line.
+ *
+ * POSIX is untouched: `npm` there is a real executable, isBatch is false, and
+ * the vector goes to spawn exactly as it always has.
+ *
+ * Exported for tests: the platform is a parameter so the Windows command line
+ * can be checked from any OS, and `deps` stands in for the Windows filesystem
+ * the shim lookup asks about. The same shape ccusage.mjs's installSpec has.
+ */
+export function upgradeSpec(target, platform = process.platform, deps) {
+  const args = ["install", "-g", `${target}@latest`, "--no-audit", "--no-fund", "--loglevel", "error"];
+  const file = platform === "win32" ? (shimPath("npm.cmd", deps) ?? "npm.cmd") : "npm";
+  return { ...spawnSpec(file, args, platform), plain: args };
+}
+
 /**
  * Why an in-app upgrade would be wrong here, or null when it is fine.
  *
@@ -725,7 +911,15 @@ export function upgradeBlock(pkgRoot) {
   // reason upgradeName is: the host is recognised by the dependency it declares
   // on us, and "us" is whatever the manifest here says — `agents-deck` under the
   // stub npm publishes today, but nothing in this rule should assume that.
-  const target = hostPackage(pkgRoot, installedName(pkgRoot))?.root ?? pkgRoot;
+  //
+  // successorRoot covers the case after such an upgrade has run: pkgRoot is
+  // gone, so hostPackage cannot recognise a host that no longer declares us,
+  // and asking accessSync about a deleted directory answers ENOENT — which this
+  // function reported as `not_writable`, telling the user their npm prefix was
+  // read-only when it was not.
+  const target = hostPackage(pkgRoot, installedName(pkgRoot))?.root
+    ?? successorRoot(pkgRoot)
+    ?? pkgRoot;
   return upgradeBlockedReason({
     git: isGitCheckout(pkgRoot),
     npx: isNpxInstall(pkgRoot),
@@ -934,13 +1128,17 @@ export function startUpgrade({ pkgRoot, name = "agents-deck" }) {
   // there wrote a tree this process never reads, so the version on disk never
   // moved and the same update was offered forever.
   const target = upgradeName(pkgRoot, name);
-  const args = ["install", "-g", `${target}@latest`, "--no-audit", "--no-fund", "--loglevel", "error"];
-  const command = `npm ${args.join(" ")}`;
+  const spec = upgradeSpec(target);
+  // The LOGICAL vector, not the cmd.exe line: this string is shown to the user
+  // and is the one they can paste. `cmd /d /s /c "…"` is an implementation
+  // detail of how this platform reaches npm, and pasting it would be advice
+  // about the deck rather than about their install.
+  const command = `npm ${spec.plain.join(" ")}`;
   _upgrade = { state: "running", command, error: null, at: Date.now() };
 
   let child;
   try {
-    child = spawn(NPM, args, { shell: NPM_SHELL, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+    child = spawn(spec.file, spec.args, { ...spec.opts, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
   } catch (err) {
     _upgrade = { state: "failed", command, error: err?.message ?? String(err), at: Date.now() };
     return { ok: false, reason: "spawn_failed", command };
@@ -955,7 +1153,7 @@ export function startUpgrade({ pkgRoot, name = "agents-deck" }) {
 
   // The deadline states the outcome itself, and only then kills.
   //
-  // npm is a .cmd shim on Windows and is therefore spawned through a shell, so
+  // npm is a .cmd shim on Windows and is therefore spawned through cmd.exe, so
   // `child` is cmd.exe and npm itself is a grandchild — a plain kill would
   // report the install as timed out while it carried on writing to
   // node_modules. killTree is what reaches it (taskkill /T there, the same
@@ -1008,12 +1206,55 @@ export function startUpgrade({ pkgRoot, name = "agents-deck" }) {
   return { ok: true, command };
 }
 
-/** npm's real complaint is usually the last non-empty, non-decorative line. */
+// The furniture around a Node crash, none of which is the reason anything
+// failed. npm's own log needs none of this — it is `npm ERR!` lines and a rule —
+// but the two get mixed the moment the thing npm's shim tried to load is
+// missing, which is what #535's bare `npm.cmd` produced on every attempt.
+const CRASH_NOISE = [
+  /^\s*at\s/,                                  // stack frames
+  /^\s*\^+\s*$/,                                // the caret under the throw
+  /^node:internal\//,                           // the frame node leads with
+  /^\s*throw\s/,
+  /^Node\.js v/,                                // the last line, and the one that was quoted
+  /^\s*[{}]\s*$/,                               // the error object's braces
+  /^\s*(code|errno|syscall|path|requireStack|stack):/,
+  /^Require stack:/,
+  /^-+$/,
+  /^A complete log/,
+];
+
+/** npm's real complaint, for the banner: the last line that is not furniture.
+ *
+ *  Last rather than first, and that is the whole reason this is not npx.mjs's
+ *  summariser under another name. The two read different documents. npm's log
+ *  opens with its codes — `code EACCES`, `syscall mkdir` — and ends with the
+ *  sentence a person can act on, so the last line wins. An npx failure is a Node
+ *  crash dump, which opens with the sentence and ends with a stack, a brace and
+ *  a version banner, so the first signal line wins there. Sharing one function
+ *  would mean picking one of those and being wrong about the other half the
+ *  time; sharing the NOISE list would be the copy this comment exists instead
+ *  of.
+ *
+ *  What was wrong was not the rule but its list. `lastMeaningfulLine` dropped
+ *  `npm ERR!` prefixes, rules and "A complete log", and nothing else — so when
+ *  #535's spawn failed with a MODULE_NOT_FOUND dump, the last surviving line was
+ *  `Node.js v22.11.0`, and that string was the entire explanation the UI gave
+ *  for a failed upgrade. */
 export function lastMeaningfulLine(text) {
   const lines = String(text ?? "").split(/\r?\n/)
     .map(l => l.replace(/^npm (ERR!|WARN)\s*/, "").trim())
-    .filter(l => l && !/^-+$/.test(l) && !/^A complete log/.test(l));
-  return lines.length ? lines[lines.length - 1].slice(0, 300) : "";
+    .filter(l => l && !CRASH_NOISE.some(re => re.test(l)));
+  if (!lines.length) return "";
+  // A line that names an error outranks a later line that does not, because
+  // what survives the filter after one is usually its context rather than its
+  // successor: `Require stack:` is furniture, but the paths listed under it are
+  // not shaped like furniture and would otherwise be the last thing standing.
+  // Still the LAST such line, not the first — npm's own log builds up to its
+  // sentence, and picking the first would answer `code EACCES` where the next
+  // line says which directory and why.
+  const named = lines.filter(l => /(^|\s)[A-Za-z]*Error:/.test(l));
+  const pick = named.length ? named[named.length - 1] : lines[lines.length - 1];
+  return pick.slice(0, 300);
 }
 
 /** Full answer for GET /api/version. Never throws, and answers the local half