agent-dag 1.43.0 → 1.45.0

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

package/src/server/supervisor.mjs

@@ -97,6 +97,42 @@ export function signalExitAction(signal, platform = process.platform, numbers =
  *
  * `proc` is a parameter so the whole sequence can be driven in a test child.
  */
+/**
+ * What to say when the upgrade that just succeeded took this install with it,
+ * or null when that is not what happened.
+ *
+ * `npm i -g ccdeck` performed before #340 nests the deck inside a launcher
+ * package. Upgrading such an install now writes the deck itself over that
+ * launcher, and npm's reify removes everything that was underneath — including
+ * the directory this supervisor and its worker are running from. The process
+ * survives, because everything it needs is already loaded. The next spawn does
+ * not: bin/deck.js is a path, and npm has just deleted it.
+ *
+ * That reached the user as `could not start …/bin/deck.js: ENOENT` and an exit
+ * 1 — a dead deck and an errno, one click after an upgrade that reported
+ * success. Nothing was broken. The new version is on the machine, and the
+ * command they typed already points at it, because npm rewrote the bin shim in
+ * the same install. The only thing missing was a sentence saying so.
+ *
+ * Deliberately not a hand-off. This process could spawn the successor's worker
+ * instead, and that would be a new worker under an old supervisor — a pair
+ * nothing has ever tested together, decided at the worst possible moment. One
+ * command the user runs themselves is the smaller promise and the one that
+ * cannot go wrong.
+ *
+ * Pure, and given its two filesystem answers rather than asking for them,
+ * because the state it describes only ever exists in a process whose own files
+ * were deleted after it started — which no test can produce by spawning one.
+ */
+export function replacedNote({ workerExists, moved, product = "ccdeck", command = "ccdeck" }) {
+  if (workerExists || !moved) return null;
+  return [
+    `${product}: the upgrade replaced this install, so it cannot restart in place.`,
+    `  the new version is in ${moved}`,
+    `  run \`${command}\` again to start it`,
+  ].join("\n");
+}
+
 export function dieOfSignal(signal, proc = process) {
   const { reraise, code } = signalExitAction(signal, proc.platform);
   if (reraise) {
@@ -197,3 +233,70 @@ export function upgradeRefusalText({ reason, waitMs = 0, attempt = 0 } = {}, tar
   const left = waitMs >= 60_000 ? `${Math.ceil(waitMs / 60_000)}m` : `${Math.max(1, Math.ceil(waitMs / 1000))}s`;
   return `${what} failed to fetch a moment ago — waiting ${left} before trying again`;
 }
+
+/**
+ * Die when the process that started this one does — on all three operating
+ * systems (#702).
+ *
+ * The deck is two processes: bin/agent-dag.js supervises, bin/deck.js serves.
+ * The supervisor kills the worker on every path it knows about — a restart, an
+ * upgrade, a Ctrl+C, its own exit — and cannot kill it on the one path it never
+ * gets to run: being killed itself. SIGKILL cannot be handled, a crash runs no
+ * handler, and a `taskkill` without `/T` reaches only the process it names. On
+ * POSIX the worker is then re-parented to init and keeps its port, its temp
+ * directory and its 40-60 MB of RSS forever. 310 of those were alive on one
+ * development machine, the oldest a day and four hours old, every one a worker
+ * whose supervisor a test's teardown had SIGKILLed.
+ *
+ * WHY THE IPC CHANNEL, AND NOT ANY OF THE OBVIOUS ALTERNATIVES. The requirement
+ * is one signal meaning "whoever started me is gone", and the usual answers are
+ * each missing a platform:
+ *
+ *   • `process.ppid === 1` — POSIX re-parents an orphan to init, so polling ppid
+ *     works there and answers nothing on Windows, which does not re-parent at
+ *     all: the ppid goes on naming a pid that no longer exists.
+ *   • process groups and `kill(-pgid)` — a POSIX concept. Windows job objects
+ *     are the nearest equivalent and Node exposes none of it.
+ *   • a SIGTERM the parent sends on its way out — Windows delivers no signals to
+ *     a Node process, so `process.on("SIGTERM")` there never fires; and a parent
+ *     that was killed sends nothing anywhere.
+ *
+ * The channel is the one mechanism that behaves the same everywhere, because
+ * Node normalises it: a Unix socketpair on POSIX, a named pipe on Windows, both
+ * closed by the kernel when the process holding the other end stops existing,
+ * however it stopped. Node turns that close into a single `disconnect` event on
+ * the child's own `process`, and it arrives for a SIGKILL, a crash, a
+ * `taskkill /F`, a closed console window and an ordinary exit alike. That is the
+ * same reasoning the header above gives for Ctrl+C: what differs between
+ * platforms is how a process dies, not that this notices.
+ *
+ * The channel is not created for this. It already carries `{type:"listening"}`
+ * and the upgrade handshake; this only says what its closure means.
+ *
+ * ARMED ONLY WHERE THERE IS A PARENT TO DIE WITH — `process.send` is a function
+ * exactly when a channel was given. `node bin/deck.js` run by hand has none, and
+ * that is the same question `SUPERVISED` in bin/deck.js already asks before it
+ * offers /api/restart.
+ *
+ * WHAT IT DELIBERATELY DOES NOT COVER: a parent that calls `child.disconnect()`
+ * and stays alive would look identical from here. Nothing in this repo does
+ * that, and the alternative — an "are you still there" ping — is a second
+ * protocol to keep correct in exchange for a case that does not exist.
+ *
+ * Returns whether a leash was armed, so a caller can state it rather than infer
+ * it. `proc` is a parameter for the reason `workerExitAction` takes `stopping`:
+ * the behaviour has to be checkable without a second process.
+ */
+export function dieWithParent(stop, proc = process) {
+  if (!proc || typeof proc.once !== "function" || typeof proc.send !== "function") return false;
+  let done = false;
+  proc.once("disconnect", () => {
+    if (done) return;
+    done = true;
+    // A stop that throws must still end the process: the whole point is that
+    // nothing is left behind, and there is no parent left to notice a child
+    // that failed to leave.
+    try { stop(); } catch { proc.exit?.(0); }
+  });
+  return true;
+}

package/src/server/system-metrics.mjs

@@ -111,12 +111,43 @@ function cpuPercent() {
   return Math.max(0, Math.min(100, Math.round(pct * 10) / 10));
 }
 
+/**
+ * The locale every child of this module is parsed in.
+ *
+ * Not a preference — a correctness requirement. Every command spawned here has
+ * its output read by a regex, and every one of those regexes reads a number
+ * with a `.` in it. `ps` and `sysctl` honour LC_NUMERIC, so on a machine set to
+ * de_DE, fr_FR, ru_RU or pt_BR — comma is the decimal separator for most of
+ * Europe and Latin America — the same commands print:
+ *
+ *     ps      1   0,2  0,0 /sbin/launchd
+ *     sysctl  total = 8192,00M  used = 7189,75M  free = 1002,25M
+ *
+ * and the parsers matched nothing at all. Not partially: `parsePsProcesses`
+ * `continue`s on every row, so the process panel was permanently empty, and
+ * `swapFromSysctl` returned null, so the macOS swap meter was permanently
+ * blank. Silently, with nothing in the log, on a machine where everything else
+ * worked.
+ *
+ * Forcing the locale rather than teaching the parsers to read a comma is the
+ * fix that scales: it makes the OUTPUT invariant, which is what every parser
+ * here was written against and what every parser added later will assume. The
+ * comma tolerance below is defence in depth for the case where a sandbox strips
+ * the environment, not the primary answer.
+ *
+ * Meaningless on Windows, where the branches are PowerShell piped through
+ * ConvertTo-Json and already culture-invariant — and harmless there for the
+ * same reason.
+ */
+const C_LOCALE = { LC_ALL: "C", LANG: "C" };
+
 /** Run a command and resolve its stdout, or null. Never rejects, never inherits
- *  a shell, and is killed rather than allowed to hang the sampler. */
+ *  a shell, never inherits a locale, and is killed rather than allowed to hang
+ *  the sampler. */
 function run(file, args, timeoutMs = 2_000) {
   return new Promise(resolve => {
     let child;
-    try { child = spawn(file, args, { windowsHide: true }); }
+    try { child = spawn(file, args, { windowsHide: true, env: { ...process.env, ...C_LOCALE } }); }
     catch { return resolve(null); }
     let out = "";
     const timer = setTimeout(() => { try { child.kill(); } catch {} resolve(null); }, timeoutMs);
@@ -207,10 +238,15 @@ async function readAvailable(platform = process.platform) {
  */
 export function swapFromSysctl(text) {
   const unit = s => {
-    const m = /^([\d.]+)([KMG])?$/i.exec(s);
+    // `,` as well as `.`: C_LOCALE should mean this never arrives, and a parser
+    // that fails closed on a whole continent's default is not a thing to leave
+    // resting on one environment variable. Safe to accept both here because
+    // sysctl formats with printf's %f, which never groups thousands — so a
+    // comma in this field can only ever be the decimal point.
+    const m = /^([\d.,]+)([KMG])?$/i.exec(s);
     if (!m) return null;
     const mult = { k: 1024, m: 1024 ** 2, g: 1024 ** 3 }[(m[2] || "M").toLowerCase()] ?? 1;
-    return Math.round(Number(m[1]) * mult);
+    return Math.round(Number(m[1].replace(",", ".")) * mult);
   };
   const total = unit(/total\s*=\s*(\S+)/i.exec(String(text ?? ""))?.[1] ?? "");
   const used = unit(/used\s*=\s*(\S+)/i.exec(String(text ?? ""))?.[1] ?? "");
@@ -320,9 +356,14 @@ export function parsePsProcesses(text, limit = TOP_N) {
   const lines = String(text ?? "").trim().split("\n");
   const out = [];
   for (const line of lines.slice(1)) {           // drop the header row
-    const m = /^\s*(\d+)\s+([\d.]+)\s+([\d.]+)\s+(.+?)\s*$/.exec(line);
+    // Both separators, for the reason swapFromSysctl gives: C_LOCALE is the
+    // fix, and this is what keeps a stripped environment from emptying the
+    // panel. `%CPU` and `%MEM` are percentages printed with %.1f, so a comma in
+    // either can only be the decimal point.
+    const m = /^\s*(\d+)\s+([\d.,]+)\s+([\d.,]+)\s+(.+?)\s*$/.exec(line);
     if (!m) continue;
-    out.push({ pid: Number(m[1]), cpu: Number(m[2]), mem: Number(m[3]), name: m[4] });
+    const num = v => Number(v.replace(",", "."));
+    out.push({ pid: Number(m[1]), cpu: num(m[2]), mem: num(m[3]), name: m[4] });
     if (out.length >= limit) break;
   }
   return out;
@@ -412,13 +453,66 @@ export function cpuFromDeltas(rows, prev, elapsedMs, limit = TOP_N) {
   return out.slice(0, limit);
 }
 
-/** The process list, on demand only — never on the ambient timer. */
 /** Previous Windows reading, so the next one can be a rate. Cleared with the
  *  rest of the sampler state. */
 let prevProcCpu = null;
 let prevProcAt = 0;
 
+/** The run producing the next list, and the last one that finished. */
+let procInFlight = null;
+let procLast = null; // { at, procs }
+
+/**
+ * How old a finished reading may be and still answer a caller.
+ *
+ * Well under SystemMeter's PROC_POLL_MS of 4000, so the panel that this exists
+ * for never once gets a cached list; long enough that a second tab, a second
+ * browser, or anything else arriving between two of those polls is handed the
+ * list the first tab is already looking at rather than starting its own child.
+ */
+const PROC_MIN_GAP_MS = 1_500;
+
+/**
+ * The process list, on demand only — never on the ambient timer, and never more
+ * than one child at a time.
+ *
+ * #544: /api/system/processes is a GET with no cache, no dedupe and no
+ * throttle, so the number of `powershell.exe Get-Process` children — about six
+ * seconds each — was whatever the caller asked for. That is the cheap half of
+ * the problem. The expensive half is that concurrent readers also overwrote
+ * each other's baseline: cpuFromDeltas needs the PREVIOUS reading's cpuSec per
+ * pid, prevProcCpu/prevProcAt are one shared pair, and two readers each stored
+ * theirs over the other's, so the CPU column came back computed against a
+ * baseline that belonged to somebody else's reading. That is a wrong number on
+ * screen, not merely wasted work, and it needed no attacker at all: one
+ * Get-Process takes longer than the panel's four-second poll, so a single tab
+ * on Windows already overlapped itself.
+ *
+ * One in-flight run fixes both, because one reader means one baseline. Callers
+ * that arrive while a run is going share its promise; callers that arrive just
+ * after one finished are served that reading.
+ */
 export async function readProcesses(platform = process.platform) {
+  const now = Date.now();
+  if (procLast && now - procLast.at < PROC_MIN_GAP_MS) return procLast.procs;
+  if (procInFlight) return procInFlight;
+  // Only a real reading is remembered. Every failure inside readProcessesNow —
+  // a spawn that never started, a non-zero exit, the timeout — resolves to an
+  // empty array, and no machine has nothing running on it, so an empty list is
+  // a failure by construction. Serving one for the next 1.5s would turn a
+  // single hiccup into a blank panel that outlives it; the next caller retries
+  // instead. The in-flight share still applies, so a burst arriving during a
+  // failing read is one failing child, not a burst of them.
+  procInFlight = readProcessesNow(platform)
+    .then(procs => {
+      if (procs.length) procLast = { at: Date.now(), procs };
+      return procs;
+    })
+    .finally(() => { procInFlight = null; });
+  return procInFlight;
+}
+
+async function readProcessesNow(platform) {
   if (platform === "win32") {
     const out = await run("powershell.exe", [
       "-NoProfile", "-NonInteractive", "-Command",
@@ -490,6 +584,10 @@ export function stopSystemMetrics() {
   swap = null;
   prevProcCpu = null;
   prevProcAt = 0;
+  // The last list goes with the baseline it was computed against. A sampler
+  // that stopped and started again must not answer the first caller with a
+  // reading from before the stop.
+  procLast = null;
 }
 
 /**