agent-dag 1.42.0 → 1.44.1

package/src/server/sound-hook.mjs

@@ -4,7 +4,7 @@
 // command — `afplay …` on macOS, a PowerShell one-liner on Windows — ending in
 // `|| true`. Each is a silent no-op on every other machine, so a settings.json
 // synced across devices ends up with several of them stacked, none of which
-// work everywhere. This installs a single entry pointing at notify.js, which
+// work everywhere. This installs a single entry pointing at notify.mjs, which
 // picks its own player at run time.
 //
 // Only ever touches its own entry, tagged `__agent-dag-sound`. Hooks the user
@@ -21,7 +21,7 @@
 // learn a second provider, src/web/provider-copy.ts's finishSoundTitle is the
 // sentence that has to move with it, and finish-sound-scope.test.ts fails until
 // it does (#394).
-import { readFile, mkdir } from "node:fs/promises";
+import { readFile, mkdir, rm } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
@@ -34,7 +34,32 @@ const PKG_ROOT      = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const CLAUDE_DIR    = claudeConfigDir();
 const SETTINGS_PATH = join(CLAUDE_DIR, "settings.json");
 const INSTALL_DIR   = join(CLAUDE_DIR, "agent-dag");
-const NOTIFY_PATH   = join(INSTALL_DIR, "notify.js");
+
+// `.mjs`, and the extension is the whole feature on the machines it matters on.
+//
+// This script is ESM — `import { spawn } from "node:child_process"` on its first
+// executable line — and in the package that is settled by package.json's
+// `"type": "module"` two directories up. Installed, it lands in <claude config
+// dir>/agent-dag/, where there is normally no package.json between it and the
+// filesystem root, so the extension alone decides the format and a `.js` with
+// nothing above it is CommonJS. Node's module-syntax detection rescued that, but
+// only where detection is on by default: v20.19.0 and v22.7.0 and later. The
+// package's own `engines` says `>=18`, and on 18.x, 19.x, 20.0–20.18.x, 21.x and
+// 22.0–22.6.x the Stop hook was a `SyntaxError: Cannot use import statement
+// outside a module` printed at the end of every turn instead of a sound.
+//
+// `.mjs` is ESM on every Node that has ever had ESM, with nothing above it
+// consulted and no detection involved. A package.json beside the script would
+// have been the other spelling of the fix and is the wrong one here: hook.js
+// lives in this same directory, is deliberately CommonJS because that is what
+// this directory's layout means, and a `{"type":"module"}` next to it would
+// break the event forwarder to fix the sound.
+const NOTIFY_NAME     = "notify.mjs";
+const PACKAGED_NOTIFY = join(PKG_ROOT, "hook", NOTIFY_NAME);
+const NOTIFY_PATH     = join(INSTALL_DIR, NOTIFY_NAME);
+// What the same script was called before it declared its own format. Swept once
+// the entry that named it has been rewritten — see sweepLegacySoundScript.
+const LEGACY_NOTIFY_PATH = join(INSTALL_DIR, "notify.js");
 
 const MARK = "__agent-dag-sound";
 const EVENT = "Stop";
@@ -51,11 +76,13 @@ const SOUND_HINTS = [/\bafplay\b/i, /Media\.SoundPlayer/i, /\bpaplay\b/i, /\bapl
  *
  * Same shape and same reasoning as installer.mjs's hookCommand — see the note
  * there — kept separate because this entry takes no `--provider` and is written
- * to a different key. Exported, with the node path injectable, so the escaping
- * is checked against a path the test names.
+ * to a different key. Exported, with the node path and the platform injectable,
+ * for the reason hookCommand gives: the two quoting rules are different, and a
+ * test that cannot name a platform can only ever assert its own.
  */
-export function soundHookCommand(notifyPath, node = process.execPath) {
-  return `${shellQuoteArg(node)} ${shellQuoteArg(notifyPath)}`;
+export function soundHookCommand(notifyPath, node = process.execPath,
+                                 platform = process.platform) {
+  return `${shellQuoteArg(node, platform)} ${shellQuoteArg(notifyPath, platform)}`;
 }
 
 /**
@@ -285,7 +312,7 @@ export async function restoreParkedSoundHooks() {
  * Take the toggle off the machine entirely, for `agents-deck --uninstall`.
  *
  * uninstallHooks only knows the `__agent-dag` mark the event forwarders carry;
- * this entry is marked `__agent-dag-sound` and its command points at notify.js,
+ * this entry is marked `__agent-dag-sound` and its command points at notify.mjs,
  * so it used to survive an uninstall and keep playing a sound on every turn. The
  * user's own hooks were the worse half: parked here when the toggle went on,
  * they stayed in a file under ~/.agents-deck that nothing left on the machine
@@ -318,6 +345,116 @@ export async function uninstallSoundHook() {
   return { ok: true, removed, restored: restore.restored ?? 0 };
 }
 
+/**
+ * Our Stop entry, built fresh from this machine's node and this machine's paths.
+ *
+ * One function rather than an object literal in each writer, because the entry
+ * has to be IDENTICAL wherever it comes from: reassertSoundHook decides whether
+ * to rewrite by comparing what is in settings.json against what this returns, so
+ * a second copy of the shape that drifted by a field would make every boot look
+ * like a change and rewrite the user's settings.json forever.
+ */
+function soundHookEntry() {
+  return {
+    [MARK]: true,
+    hooks: [{
+      type: "command",
+      // Absolute node path, matching how the event hooks are installed: the
+      // shell a hook runs in does not necessarily have the user's PATH. And
+      // properly escaped for that shell, for the reason installer.mjs's
+      // hookCommand spells out — NOTIFY_PATH is built from $CLAUDE_CONFIG_DIR,
+      // double quotes do not suppress `$(…)` or a backtick on POSIX, and this
+      // string is executed at the end of every turn.
+      command: soundHookCommand(NOTIFY_PATH),
+      timeout: 5,
+    }],
+  };
+}
+
+/**
+ * Bring the installed sound hook back up to the packaged one, in a settings
+ * object the caller is about to write.
+ *
+ * The forwarder gets this for free: installHooks re-asserts hook.js on every
+ * boot, so a machine that upgrades the deck upgrades the script Claude Code
+ * actually executes. notify.js had exactly one installer — setSoundHook(true) —
+ * so the copy on disk was whatever shipped in the release the user last TOGGLED
+ * THE SOUND ON WITH, and every later release stopped at the package directory.
+ * That is not a theoretical drift: #548 replaced a `printf "\a"` player that
+ * spawned a BEL into `stdio: "ignore"` — silent by construction — and could not
+ * reach a single machine that already had the toggle on, which is precisely the
+ * set of machines it was written for.
+ *
+ * The presence of our entry in settings.json is the whole of the permission
+ * check, and it is deliberately the only one. A user who turned the sound OFF
+ * has no entry, so nothing here writes a script into their config dir on a boot
+ * they asked nothing of; a user who has it ON has already consented to this file
+ * existing, and keeping it current is the deck's job rather than theirs.
+ *
+ * The entry is rebuilt rather than inspected, which is the other half of the
+ * report. settings.json is commonly synced between machines and the command
+ * bakes in `process.execPath` and this machine's $CLAUDE_CONFIG_DIR — so a file
+ * carried over from a laptop names that laptop's node binary inside that
+ * laptop's home directory, soundHookStatus reports `enabled: true`, and the turn
+ * ends in an ENOENT nobody sees. Rewriting it from soundHookEntry() re-derives
+ * both against the machine the deck is running on.
+ *
+ * Mutates `settings` and returns what it did; the caller owns the write, so a
+ * boot that would otherwise change nothing still changes nothing.
+ */
+export async function reassertSoundHook(settings) {
+  const group = settings?.hooks?.[EVENT];
+  if (!Array.isArray(group) || !group.some(isOurs)) return { present: false, script: false, entry: false };
+
+  if (!existsSync(INSTALL_DIR)) await mkdir(INSTALL_DIR, { recursive: true });
+  // Same reason the event forwarder is installed this way: the Stop hook fires
+  // this file from sessions that are already running, so replacing it must not
+  // leave one of them executing a half-copied program. installScript renames a
+  // finished copy over the name, and skips the write entirely when the bytes
+  // already match — which is every boot after the first.
+  const script = await installScript(PACKAGED_NOTIFY, NOTIFY_PATH);
+
+  const rebuilt = soundHookEntry();
+  const wanted = JSON.stringify(rebuilt);
+  const next = [];
+  let entry = false;
+  let kept = false;
+  for (const g of group) {
+    if (!isOurs(g)) { next.push(g); continue; }
+    // More than one of ours is a settings.json that has been merged by hand or
+    // by a sync tool. One sound per turn, so the extras are dropped rather than
+    // rewritten alongside the first.
+    if (kept) { entry = true; continue; }
+    kept = true;
+    if (JSON.stringify(g) !== wanted) entry = true;
+    next.push(rebuilt);
+  }
+  settings.hooks[EVENT] = next;
+  return { present: true, script, entry };
+}
+
+/**
+ * Delete the `notify.js` an older deck installed, now that nothing names it.
+ *
+ * Called AFTER settings.json has been written, and that ordering is the point:
+ * until the new entry is on disk the old command is still what a live Claude
+ * Code session will run at the end of its next turn, and deleting the file it
+ * names would turn a stale sound into a "Cannot find module" in the user's
+ * session. Best-effort on the way out — a Windows lock or a read-only config dir
+ * leaves one stale file behind, which is litter, not a failure worth reporting
+ * over a hook that is now installed correctly.
+ */
+export async function sweepLegacySoundScript() {
+  if (LEGACY_NOTIFY_PATH === NOTIFY_PATH) return false;
+  try {
+    if (!existsSync(LEGACY_NOTIFY_PATH)) return false;
+    await rm(LEGACY_NOTIFY_PATH, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function setSoundHook(enabled) {
   // Read before anything else. A file we cannot parse stops the toggle here,
   // with nothing parked, nothing copied and settings.json untouched.
@@ -354,24 +491,10 @@ export async function setSoundHook(enabled) {
   if (enabled) {
     if (!existsSync(INSTALL_DIR)) await mkdir(INSTALL_DIR, { recursive: true });
     // Same reason the event forwarder is installed this way: the Stop hook fires
-    // notify.js from sessions that are already running, and toggling the sound
+    // notify.mjs from sessions that are already running, and toggling the sound
     // on must not leave one of them executing a half-copied file.
-    await installScript(join(PKG_ROOT, "hook", "notify.js"), NOTIFY_PATH);
-    others.push({
-      [MARK]: true,
-      hooks: [{
-        type: "command",
-        // Absolute node path, matching how the event hooks are installed: the
-        // shell a hook runs in does not necessarily have the user's PATH. And
-        // properly escaped for that shell, for the reason installer.mjs's
-        // hookCommand spells out — NOTIFY_PATH is built from
-        // $CLAUDE_CONFIG_DIR, double quotes do not suppress `$(…)` or a
-        // backtick on POSIX, and this string is executed at the end of every
-        // turn.
-        command: soundHookCommand(NOTIFY_PATH),
-        timeout: 5,
-      }],
-    });
+    await installScript(PACKAGED_NOTIFY, NOTIFY_PATH);
+    others.push(soundHookEntry());
     settings.hooks[EVENT] = others;
   } else if (others.length) {
     settings.hooks[EVENT] = others;
@@ -380,9 +503,16 @@ export async function setSoundHook(enabled) {
   }
 
   await writeSettings(settings);
+  // Last, and after the write, for the reason sweepLegacySoundScript gives: the
+  // file an older deck installed is only safe to delete once nothing in
+  // settings.json still points at it.
+  if (enabled) await sweepLegacySoundScript();
   return { ok: true, enabled };
 }
 
-// Both paths are exported so a test can prove it is pointed at a sandbox
-// before it writes anything — the real ones are the user's own settings.
-export { SETTINGS_PATH, PARKED_PATH };
+// All four paths are exported so a test can prove it is pointed at a sandbox
+// before it writes anything — the real ones are the user's own settings. The two
+// script paths are also the only honest way for a test to ask where the sound
+// hook ACTUALLY lands: rebuilding `<config dir>/agent-dag/notify.mjs` in the test
+// would keep passing on the day this module started installing somewhere else.
+export { SETTINGS_PATH, PARKED_PATH, NOTIFY_PATH, LEGACY_NOTIFY_PATH };

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) {

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;
 }
 
 /**

package/src/server/uv-bootstrap.mjs

@@ -7,17 +7,18 @@
 // narrower thing instead: fetch one named release artifact from Astral's own
 // GitHub releases, check it against the SHA-256 that release publishes beside
 // it, and unpack it inside ~/.agents-deck. Nothing is executed until it has
-// been verified, nothing lands outside a directory the deck already owns, and
-// deleting that directory undoes all of it.
+// been verified, nothing lands outside a directory the deck already owns — the
+// staging directory included, which is what #551 was about — and deleting that
+// directory undoes all of it.
 //
 // It is still a network fetch of an executable, so it only happens when there
 // is no other way: uv, pipx, and python -m pipx have all already been ruled out
 // by the caller. AGENTS_DECK_NO_INSTALL=1 disables it along with everything else.
 import { createHash } from "node:crypto";
-import { mkdir, writeFile, rm, chmod, readdir, copyFile, open } from "node:fs/promises";
+import { mkdir, mkdtemp, writeFile, rm, chmod, readdir, copyFile, open } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { homedir, tmpdir } from "node:os";
+import { homedir } from "node:os";
 import { run } from "./exec.mjs";
 // The same rename used to replace settings.json, for the same reason: on
 // Windows a rename over an existing file fails outright while any other process
@@ -91,10 +92,11 @@ async function download(url, { asText = false } = {}) {
  * Inside single quotes PowerShell expands nothing, so a doubled quote is both
  * the only escape it has and the only one needed. Windows filenames cannot
  * contain `"`, `<`, `>` or `|`, but they can contain an apostrophe — and the
- * archive lands under os.tmpdir(), which on Windows is inside the user's own
- * profile: C:\Users\O'Brien\AppData\Local\Temp. Pasted in raw, that apostrophe
- * ended the string mid-path and Expand-Archive died of a syntax error, so uv
- * could never be bootstrapped on an account whose owner has that name.
+ * archive lands under the user's own profile either way, which is where an
+ * apostrophe comes from: C:\Users\O'Brien\.agents-deck\tools. Pasted in raw,
+ * that apostrophe ended the string mid-path and Expand-Archive died of a syntax
+ * error, so uv could never be bootstrapped on an account whose owner has that
+ * name.
  */
 const psQuote = (s) => `'${String(s).replace(/'/g, "''")}'`;
 
@@ -194,7 +196,9 @@ export async function bootstrapUv() {
   const version = await latestVersion();
   const base = `${DOWNLOAD_BASE}/${version}/${asset}`;
 
-  const staging = join(tmpdir(), `agents-deck-uv-${process.pid}`);
+  // Created inside the try, because it is created rather than merely named:
+  // see the mkdtemp below for why that distinction is the whole fix.
+  let staging = null;
   // Set while a half-finished binary exists under a name of its own, cleared the
   // moment it is renamed into place; the finally below removes whatever is left.
   let partial = null;
@@ -214,7 +218,35 @@ export async function bootstrapUv() {
     const actual = createHash("sha256").update(archive).digest("hex");
     if (actual !== expected) return { ok: false, reason: "checksum_mismatch" };
 
-    await mkdir(staging, { recursive: true });
+    // ── where the archive is unpacked, and why it is not the system temp dir ──
+    //
+    // This used to be `join(tmpdir(), `agents-deck-uv-${process.pid}`)`, created
+    // with `mkdir(..., { recursive: true })` — which does not fail on a
+    // directory that is already there.
+    //
+    // On macOS tmpdir() is a per-user `/var/folders/…/T` and on Windows it is
+    // inside the profile, so the header's promise held on both. On Linux it is
+    // `/tmp`, mode 1777, writable by every account on the box. The comment two
+    // hundred lines up reasons carefully about tmpdir() being inside the user's
+    // profile ON WINDOWS and never asks the Linux question.
+    //
+    // Three things then line up. The name is derived from a pid, so it is
+    // cheap to blanket the whole plausible range in advance. `findUv` returns a
+    // depth-0 file before it recurses, while the genuine uv always sits one
+    // level down inside the archive's versioned directory — so a planted
+    // `/tmp/agents-deck-uv-<pid>/uv` wins deterministically rather than by
+    // racing. And the SHA-256 above is computed on the downloaded buffer, never
+    // on the extracted file, so it does not cover the thing that is executed.
+    // What followed was a copy, a chmod 0755, a `--version` run, a rename to
+    // the permanent name and reuse of that name forever.
+    //
+    // `mkdtemp` under TOOL_DIR fixes all three at once: the directory is inside
+    // a tree the user already owns, its name is unpredictable, and mkdtemp
+    // CREATES — it cannot be handed a directory somebody else made. findUv's
+    // ordering is left alone deliberately; it is not wrong on its own, and it
+    // stops being reachable once nobody else can write here.
+    await mkdir(TOOL_DIR, { recursive: true });
+    staging = await mkdtemp(join(TOOL_DIR, "uv-staging-"));
     const archivePath = join(staging, asset);
     await writeFile(archivePath, archive);
     if (!(await extract(archivePath, staging))) return { ok: false, reason: "extract_failed" };
@@ -258,7 +290,12 @@ export async function bootstrapUv() {
   } catch (err) {
     return { ok: false, reason: "error", detail: String(err?.message ?? err).slice(0, 200) };
   } finally {
-    await rm(staging, { recursive: true, force: true }).catch(() => {});
+    // maxRetries for the reason the ccusage repair gives: the archive was just
+    // unpacked here and `partial` was just run out of it, and on Windows a file
+    // a handle has not finished releasing cannot be deleted — the directory
+    // then refuses to go with ENOTEMPTY. Litter rather than a failure, since
+    // this is swallowed, but litter in the user's home that nothing else sweeps.
+    if (staging) await rm(staging, { recursive: true, force: true, maxRetries: 10, retryDelay: 25 }).catch(() => {});
     if (partial) await rm(partial, { force: true }).catch(() => {});
   }
 }