agent-dag 1.34.0 → 1.34.2

package/src/server/cswap-admin.mjs

@@ -443,6 +443,18 @@ async function restoreActive(num) {
  * expiry so a copy left behind in clipboard history stops working, and nothing
  * more: it is not encryption and is not presented as any.
  *
+ * Say the limit of that out loud, because the UI used to imply the opposite.
+ * `exp` is a plain number inside plain base64'd JSON with NO key, MAC or
+ * signature over it, so anyone holding the text can decode it, write a later
+ * `exp`, re-encode, and import it. unwrapShare's check is therefore a check
+ * against staleness, not against an adversary — and it cannot be made into one
+ * here. A MAC needs a secret both decks hold, and two decks that already shared
+ * a secret would not need this function; and even a perfect signature would
+ * only stop THIS import path, since the payload it wraps is the credential
+ * itself and `cswap import` accepts it unwrapped. The honest fix for a share
+ * that got away is to sign the account out and back in. See share-expiry-
+ * forgeable.test.ts, which pins the forgery rather than leaving it implied.
+ *
  * The default export shape is used deliberately, never --full, which would
  * embed the entire ~/.claude.json including every project and MCP server.
  */
@@ -473,7 +485,19 @@ export async function shareAccount(num) {
   if (!Number.isInteger(n) || n < 1 || n > 999) return { ok: false, reason: "bad_account" };
   const r = await run(await cswapBin(), ["export", "-", "--account", String(n)], { timeout: CSWAP_TIMEOUT_MS });
   if (!r.ok || !r.stdout.trim()) {
-    return { ok: false, reason: "export_failed", detail: failureText(r, "cswap export") };
+    // The failure sentence is built from stderr ALONE for this one command,
+    // because its stdout is the credential. `failureText` concatenates
+    // `${stderr}\n${stdout}` and `firstUseful` takes the LAST non-empty line —
+    // right for every other cswap command, and here it means any stdout at all
+    // outranks the real error. claude-swap writes its diagnostics to stderr
+    // specifically so stdout stays pure JSON in pipe mode, and it writes the
+    // envelope as its last act; a non-zero exit after a partial write would
+    // therefore put the tail of `json.dumps(envelope, indent=2)` in front of the
+    // user, and one of those lines is the refresh token on its own.
+    //
+    // Nothing is lost by dropping it: the ENOENT branch keys off `r.code`, which
+    // `run` sets, and cmd.exe's "is not recognized" is stderr's.
+    return { ok: false, reason: "export_failed", detail: failureText({ ...r, stdout: "" }, "cswap export") };
   }
   return { ok: true, blob: wrapShare(r.stdout), expiresAt: Date.now() + SHARE_TTL_MS };
 }
@@ -546,10 +570,32 @@ export async function removeAccount(num) {
   });
 }
 
+/**
+ * What an alias may be made of.
+ *
+ * Every other argument this module sends to cswap is an integer bounded to
+ * 1..999; the alias was the one free-text field, and `.trim()` was the whole of
+ * its validation. That is fine on POSIX, where `run` spawns the argument vector
+ * untouched, and not fine on Windows: cswap is a `.cmd` shim there, so the
+ * vector goes through `cmd.exe /d /s /c` (see viaCmd). Quote-doubling handles
+ * `"` and every other metacharacter, which leaves exactly the residual exec.mjs
+ * documents — `%VAR%` expands inside quotes and a command line has no escape for
+ * it — so `%USERPROFILE%` in an alias stored the user's home path, and an alias
+ * carrying an unbalanced quote plus an `&` could end the quoted region early.
+ * An interior newline survived `.trim()` untouched as well.
+ *
+ * The same allowlist discipline cswap-auto.mjs already applies to its model
+ * list, and it closes the unbounded-length half too: an alias is a short name
+ * shown instead of an email, so 64 characters is not a constraint anyone meets
+ * by accident.
+ */
+const ALIAS_OK = /^[A-Za-z0-9 ._-]{1,64}$/;
+
 export async function setAlias(num, alias) {
   const n = Number(num);
   if (!Number.isInteger(n) || n < 1 || n > 999) return { ok: false, reason: "bad_account" };
   const clean = typeof alias === "string" ? alias.trim() : "";
+  if (clean && !ALIAS_OK.test(clean)) return { ok: false, reason: "bad_value" };
   const args = clean ? ["alias", String(n), clean] : ["alias", String(n), "--unset"];
   return withStoreLock(async () => {
     const r = await run(await cswapBin(), args, { timeout: CSWAP_TIMEOUT_MS });

package/src/server/exec.mjs

@@ -50,8 +50,7 @@ export const isBatch = (file, platform = process.platform) =>
  * cmd.exe understands inside a quoted string.
  */
 export function viaCmd(file, args) {
-  const q = (s) => `"${String(s).replace(/"/g, '""')}"`;
-  const line = [file, ...args].map(q).join(" ");
+  const line = [file, ...args].map(a => shellQuoteArg(a, "win32")).join(" ");
   return {
     file: process.env.comspec || process.env.ComSpec || "cmd.exe",
     args: ["/d", "/s", "/c", `"${line}"`],
@@ -59,6 +58,42 @@ export function viaCmd(file, args) {
   };
 }
 
+/**
+ * Quote ONE argument into a command line a shell will parse.
+ *
+ * Everything else in this module exists to avoid needing this: an argument
+ * vector is handed to spawn untouched and nothing in it is ever read as syntax.
+ * Two callers cannot take that route, and they are the reason this is exported.
+ * A Claude Code hook is registered as `{type:"command", command:"<string>"}` —
+ * the host CLI runs that string THROUGH A SHELL on every tool call, and the
+ * format has no argv form to emit instead. So the string has to be built here,
+ * correctly, once.
+ *
+ * The inputs are not user input in the web sense, but they are not constants
+ * either: the hook path is built from $CLAUDE_CONFIG_DIR and homedir(), and the
+ * node path from process.execPath. Wrapping those in double quotes — what this
+ * used to do — is not escaping on POSIX at all: `$(…)`, a backtick and `\` are
+ * all still live inside them, so a config dir named `/tmp/a$(id)b` became shell
+ * code written into the user's settings.json and executed on every hook fire.
+ * A bare `$` in a path is the same bug wearing a duller hat — `$HOME` expands to
+ * nothing, the hook path silently becomes wrong, and hooks stop firing with no
+ * error anywhere.
+ *
+ * POSIX gets single quotes, inside which NOTHING is special, with the one
+ * escape that form has: close the quote, emit a backslash-quote, reopen.
+ * Windows gets cmd.exe's rule — the same one viaCmd applies above, so this file
+ * has one Windows quoting rule rather than two — with the same single residual
+ * exec.mjs already documents: cmd.exe expands `%VAR%` inside quotes too, and a
+ * command line has no escape for it. That is narrower than it sounds, since
+ * `%foo%` with no variable `foo` is left alone, and it is a limit of the
+ * platform rather than of this function.
+ */
+export function shellQuoteArg(arg, platform = process.platform) {
+  const s = String(arg ?? "");
+  if (platform === "win32") return `"${s.replace(/"/g, '""')}"`;
+  return `'${s.split("'").join("'\\''")}'`;
+}
+
 /**
  * What to hand `spawn`/`execFile` for `file` and `args` on this platform, with
  * the argument vector intact and no shell.
@@ -204,8 +239,13 @@ const TIMEOUT_TAIL = 8 << 10;
  * A run stopped by its deadline answers `{ ok: false, code: "ETIMEDOUT",
  * killed: true, timedOut: true }` — never ok, whatever the child said on its
  * way out.
+ *
+ * `env` replaces the child's environment wholesale, the way spawn's does; pass
+ * `{...process.env, X: "1"}` to add to it. It exists because the quota probe
+ * runs a whole Claude Code and has to mark the run as the deck's own, and that
+ * marker is what stops every poll drawing itself onto the canvas.
  */
-export function run(cmd, args, { timeout = 20_000, maxBuffer = 4 << 20 } = {}) {
+export function run(cmd, args, { timeout = 20_000, maxBuffer = 4 << 20, env } = {}) {
   const tries = candidates(cmd);
   return new Promise((resolve) => {
     const attempt = (i) => {
@@ -260,7 +300,16 @@ export function run(cmd, args, { timeout = 20_000, maxBuffer = 4 << 20 } = {}) {
 
       try {
         const cp = execFile(file, argv,
-          { timeout: 0, shell: false, windowsHide: true, maxBuffer, ...opts }, done);
+          { timeout: 0, shell: false, windowsHide: true, maxBuffer, ...(env ? { env } : {}), ...opts }, done);
+        // Give the child EOF on stdin straight away, which is what this
+        // function's contract has always claimed ("run closes stdin", says
+        // runInteractive's header) and what execFile does not do: it leaves the
+        // pipe open with nobody at the writing end, so a tool that reads stdin
+        // waits for a writer that will never arrive. `claude --print /usage`
+        // waits three seconds for exactly that before giving up, which is why
+        // the shell command it replaced had to end in `< /dev/null`. Closing
+        // the pipe is that redirection without a shell to parse it.
+        try { cp.stdin?.on("error", () => {}); cp.stdin?.end(); } catch { /* no stdin to close */ }
         cp.stdout?.on("data", (d) => { sawOut = (sawOut + d).slice(-TIMEOUT_TAIL); });
         cp.stderr?.on("data", (d) => { sawErr = (sawErr + d).slice(-TIMEOUT_TAIL); });
         // The deadline states the outcome itself and only then kills, which is

package/src/server/index.mjs

@@ -638,7 +638,13 @@ function maybeResolveContext(payload) {
 const CODEX_HOME = process.env.CODEX_HOME
   ? resolve(process.env.CODEX_HOME)
   : join(homedir(), ".codex");
-const CODEX_SESSIONS_DIR = join(CODEX_HOME, "sessions");
+// Exported because bin/deck.js prints this path in the boot banner, and it used
+// to build its own `join(homedir(), ".codex", "sessions")` for the purpose —
+// which ignored CODEX_HOME and so named a directory that does not exist on any
+// machine that sets it. Handing out the binding the watcher itself reads, rather
+// than a second computation of the same rule, is what makes the printed path and
+// the tailed path unable to disagree.
+export const CODEX_SESSIONS_DIR = join(CODEX_HOME, "sessions");
 const codexRolloutPathBySid = new Map();
 const lastCodexUsageReadAt = new Map();
 const pendingCodexUsageReads = new Set();
@@ -1293,20 +1299,57 @@ function readBody(req, limit = 64_000) {
   });
 }
 
+// How long an oversized POST is drained after it has been refused, so the 413
+// reaches a poster that is still uploading. Generous next to hook.js's own
+// one-second budget, and finite so nothing can sit on the socket indefinitely.
+const OVERSIZE_DRAIN_MS = 10_000;
+
 // `persist` is false when the hook posted this event to another deck as well
 // and elected that one to write it to the log they share. The event is still
 // buffered and broadcast here — every matching deck draws it — it is only the
 // second copy on disk that is dropped.
 function handleEventIngest(req, res, persist = true) {
   let body = "";
+  // Set once the cap is hit, because everything after that point is about an
+  // exchange that is already over: more `data` may still be in flight, and
+  // `end` must not go on to parse the truncated half.
+  let refused = false;
   req.setEncoding("utf8");
   req.on("data", c => {
+    if (refused) return;
     body += c;
     if (body.length > 5_000_000) {
-      req.destroy();
+      refused = true;
+      body = "";              // nothing will read it now; let it go
+      // ANSWER, rather than vanish. `req.destroy()` on its own tore the socket
+      // down with no status line on it at all, so the poster learned only that
+      // the connection had gone — indistinguishable from a deck that died or
+      // was never there, and nothing in the exchange to tell those apart. `end`
+      // never fires on a destroyed request either, so the handler below got no
+      // second chance to speak. readBody above gets this right already, by
+      // rejecting into a caller that replies.
+      send(res, 413, { error: "event too large" });
+      // Then keep reading, and throw it away. Answering is not enough on its
+      // own, because the poster is still mid-upload when the answer goes out:
+      // hang up now and its next write lands on a dead socket, it aborts with
+      // EPIPE, and the 413 that was already sitting in its receive buffer is
+      // discarded unread — the same disappearance in a different costume.
+      // `Connection: close` is the tempting version of hanging up and has
+      // exactly that effect: Node destroys the socket the moment such a
+      // response flushes. Draining lets the poster finish and then read the
+      // answer, which is the whole point of answering. `body` no longer grows,
+      // so it costs no memory.
+      req.resume();
+      // Bounded, because draining forever is its own denial of service: a
+      // poster that stops without ending would otherwise hold the socket for as
+      // long as it liked.
+      const grace = setTimeout(() => req.destroy(), OVERSIZE_DRAIN_MS);
+      grace.unref?.();
+      req.on("close", () => clearTimeout(grace));
     }
   });
   req.on("end", () => {
+    if (refused) return;
     let parsed;
     try { parsed = JSON.parse(body); }
     catch { return send(res, 400, { error: "invalid json" }); }
@@ -1314,7 +1357,11 @@ function handleEventIngest(req, res, persist = true) {
     const evt = pushEvent(parsed, "hook", { persist });
     send(res, 200, { ok: true, seq: evt.seq });
   });
-  req.on("error", () => send(res, 400, { error: "bad request" }));
+  // Guarded for the same reason `end` is, and more sharply: destroying the
+  // request above is itself what raises this, and answering a second time on a
+  // response already sent throws ERR_HTTP_HEADERS_SENT out of an error handler,
+  // where nothing is waiting to catch it.
+  req.on("error", () => { if (!refused) send(res, 400, { error: "bad request" }); });
 }
 
 function handleSse(req, res) {

package/src/server/installer.mjs

@@ -12,6 +12,7 @@ import { join, resolve, dirname } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import { claudeConfigDir } from "./claude-dir.mjs";
+import { shellQuoteArg } from "./exec.mjs";
 import { PRODUCT } from "./brand.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -68,9 +69,35 @@ const MARK_KEY = "__agent-dag";
 const LEGACY_MARKS = ["__ccgraph", "__agent-flow"];
 const LEGACY_DIRS = ["ccgraph", "agent-flow", "agent-dag"];
 
-function hookCommand(installedHookPath, provider) {
-  const node = process.execPath;
-  return `"${node}" "${installedHookPath}" --provider ${provider}`;
+/**
+ * The `command` string Claude Code stores for our forwarder, and runs THROUGH A
+ * SHELL on every tool call.
+ *
+ * The settings.json hook format is a string, not an argv, so this is one of the
+ * two places in the codebase that has to build a shell command line by hand —
+ * see shellQuoteArg, which is where the escaping rules and their one Windows
+ * residual are written down.
+ *
+ * It used to wrap both paths in double quotes, which on POSIX escapes nothing:
+ * `$(…)`, a backtick and `\` are all still live inside them. Both paths come
+ * from outside — `installedHookPath` is built from $CLAUDE_CONFIG_DIR (resolved,
+ * never validated) or homedir(), and `node` is process.execPath — so a config
+ * dir called `/tmp/a$(id)b` was shell code, written into the user's own settings
+ * file and executed on every hook fire for as long as it stayed there. The
+ * quieter half of the same bug cost nothing but the feature: an ordinary `$` in
+ * a path expanded to nothing, the hook pointed at a file that was not there, and
+ * hooks stopped firing with no error to explain it.
+ *
+ * `provider` is a key of PROVIDERS — "claude" or "codex", never anything a
+ * caller chose — and is quoted anyway, because that is not a property worth
+ * re-deriving at every reading.
+ *
+ * Exported, with the node path injectable, so the escaping can be checked
+ * against a path the test names rather than against whatever ran the suite.
+ */
+export function hookCommand(installedHookPath, provider, node = process.execPath) {
+  const q = (s) => shellQuoteArg(s);
+  return `${q(node)} ${q(installedHookPath)} --provider ${q(provider)}`;
 }
 
 function isOurEntry(g) {

package/src/server/quota.mjs

@@ -13,29 +13,29 @@
 //      schedule and writes what it got; reading that file costs nothing and
 //      spends none of the budget. Used whenever it holds a recent enough row.
 //   2. The OAuth usage API directly, with the token from
-//      ~/.claude/.credentials.json. Exact and instant. Mechanism
+//      .credentials.json inside the Claude config dir — $CLAUDE_CONFIG_DIR when
+//      it is set, ~/.claude otherwise. Exact and instant. Mechanism
 //      reverse-engineered from steipete/CodexBar.
 //   3. `claude --print /usage`, parsed. Used when there is no readable token —
 //      notably on macOS, where Claude Code keeps credentials in the Keychain
 //      and that file does not exist, so this is the ONLY self-service path
 //      there. It is also the most expensive: a whole Claude Code process per
-//      poll. On Windows the binary may be a .cmd wrapper, so exec()
-//      (shell-based) is used for correct quoting + stdin.
+//      poll. On Windows the binary may be a .cmd wrapper, which spawn cannot
+//      launch directly — exec.mjs's `run` routes that case through cmd.exe with
+//      the argument vector intact, so no shell ever parses a path this module
+//      read out of the environment.
 //
 // 2 and 3 are rate-floored (SELF_POLL_MS) and gated behind the same 429
 // cooldown; 1 is not, because it is a local file read.
 import { activeAccountUsage, requestCollection } from "./claude-accounts.mjs";
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
+import { claudeConfigDir } from "./claude-dir.mjs";
+import { run } from "./exec.mjs";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join, posix as posixPath, win32 as winPath } from "node:path";
 import { homedir } from "node:os";
 import { PRODUCT } from "./brand.mjs";
 
-const execAsync = promisify(exec);
-
-const CREDS_PATH  = join(homedir(), ".claude", ".credentials.json");
 const USAGE_URL   = "https://api.anthropic.com/api/oauth/usage";
 const BETA_HEADER = "oauth-2025-04-20";
 const WIN_5H_SEC  = 18000;
@@ -44,9 +44,34 @@ const WIN_7D_SEC  = 604800;
 // 429 cooldown gate — after a rate-limit, skip the API until this passes.
 let _rateLimitedUntil = 0;
 
+/**
+ * Where Claude Code keeps the OAuth credentials this module borrows a token
+ * from.
+ *
+ * It is `.credentials.json` inside the Claude config dir, and that dir moves:
+ * CLAUDE_CONFIG_DIR replaces ~/.claude wholesale rather than overlaying it, so
+ * on a machine where it is set there is no ~/.claude to read at all. Hardcoding
+ * ~/.claude here did not fail loudly — it made readOAuthToken() return null
+ * forever, which reads exactly like "this machine keeps its credentials in the
+ * Keychain", and the quota chain quietly fell through to source 3 on every poll
+ * it was allowed to make. See src/server/claude-dir.mjs, which owns the rule
+ * and is the only place it is spelled.
+ *
+ * Resolved per call rather than frozen into a module-level constant, for the
+ * same reason claudeConfigDir() is a function: a constant captured at import
+ * time is a value nothing can observe or correct afterwards, and this module is
+ * imported lazily by the /api/quota route rather than at a point in startup
+ * anyone here controls.
+ *
+ * Exported for tests — it is the whole of the bug, and it is pure.
+ */
+export function credentialsPath() {
+  return join(claudeConfigDir(), ".credentials.json");
+}
+
 async function readOAuthToken() {
   try {
-    const raw  = await readFile(CREDS_PATH, "utf8");
+    const raw  = await readFile(credentialsPath(), "utf8");
     const auth = JSON.parse(raw)?.claudeAiOauth;
     if (!auth?.accessToken) return null;
     // expiresAt is epoch milliseconds. If expired, the CLI fallback handles it.
@@ -147,7 +172,7 @@ async function fetchOAuthUsage() {
 
 let _cache    = null;
 let _cacheAt  = 0;
-let _inflight = null;   // deduplicates concurrent exec() calls
+let _inflight = null;   // deduplicates concurrent CLI probes
 let _lastGood = null;   // last result that had real quota percentages
 let _lastSelfPollAt = 0;
 
@@ -346,35 +371,40 @@ export function quotaClaudeCandidates(platform = process.platform, env = process
   ];
 }
 
-/** Build the shell command string for `claude --print /usage`.
+/** Which `claude` to run for `--print /usage`: the first candidate that exists.
+ *
+ *  This used to hand back a whole shell command line — `"<bin>" --print /usage
+ *  < /dev/null` — for `exec()` to parse. Double quotes are not escaping on
+ *  POSIX: `$(…)`, backticks and `\` all still work inside them, and every
+ *  ingredient of that line came from the environment (`%APPDATA%`, `homedir()`),
+ *  so a home directory named `/home/a$(id)b` was shell code the quota poll ran
+ *  every minute. A bare `$` was the duller half of the same bug — it expanded
+ *  to nothing and the probe looked for a binary at a path that did not exist.
  *
- *  We use exec() (shell-based) so cmd.exe / sh processes redirects.
- *  On Windows: `< nul` closes stdin immediately, preventing the 3-second
- *  "no stdin data" wait the claude CLI does when it detects a pipe.
- *  On Unix: `< /dev/null` has the same effect.
+ *  There is nothing left to escape once there is no shell: exec.mjs's `run`
+ *  spawns the argument vector as given, resolves the Windows `.cmd`/`.exe`
+ *  spelling itself, and closes the child's stdin — which is what `< /dev/null`
+ *  was for, since `claude --print` waits three seconds on a stdin pipe nobody
+ *  is writing to.
  *
  *  Exported, with everything it touches injectable, so the Windows branch is
  *  testable from the platforms this repo is actually developed on.
  */
-export function buildQuotaShellCmd(platform = process.platform, env = process.env,
-                                   home = homedir(), exists = existsSync) {
-  const win = platform === "win32";
-  const sep = win ? "\\" : "/";
-  // A bare name is left to the shell's own lookup; a full path is only worth
-  // naming when it is actually there.
-  const bin = quotaClaudeCandidates(platform, env, home)
+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 quotaClaudeCandidates(platform, env, home)
     .find(c => !c.includes(sep) || exists(c)) ?? "claude";
-  // Quote a path — a username can contain a space — but not a bare name, which
-  // cmd.exe resolves more predictably unquoted.
-  const quoted = bin.includes(sep) ? `"${bin}"` : bin;
-  return `${quoted} --print /usage < ${win ? "nul" : "/dev/null"}`;
 }
 
 export async function fetchClaudeQuota({ force = false } = {}) {
   const now = Date.now();
   if (!force && _cache && now - _cacheAt < CACHE_MS) return _cache;
 
-  // If another exec() is already in flight, wait for it instead of spawning a
+  // If another CLI probe is already in flight, wait for it instead of spawning a
   // second concurrent process (which can return empty output and overwrite the
   // good result with 0%).
   if (_inflight) return _inflight;
@@ -436,30 +466,27 @@ async function nudgeAndReread(previous) {
 //   cliOk  — the CLI ran and we recognized its output (preamble present)
 //   parsed — quota percentages object, or null if the "Current session/week"
 //            lines were absent (CLI cold-start, or genuinely <1% usage)
-async function _execOnce(shellCmd) {
-  try {
-    const { stdout, stderr } = await execAsync(shellCmd, {
-      timeout: 15_000,
-      // Marks this Claude Code run as the deck's own. `claude --print /usage`
-      // is a full invocation, so it fires the hooks we installed, and every
-      // quota poll was drawing itself onto the canvas as a fresh session with
-      // no prompt and no tools. Hooks inherit the environment, so hook.js
-      // sees this and stays quiet.
-      env: { ...process.env, NO_COLOR: "1", TERM: "dumb", AGENTS_DECK_INTERNAL: "1" },
-      maxBuffer: 1024 * 1024,
-    });
-    const combined = stdout + "\n" + stderr;
-    const cliOk = /subscription/i.test(combined) || /claude code usage/i.test(combined);
-    return { cliOk, parsed: parseUsageText(combined) };
-  } catch (err) {
-    const msg = err?.stderr ? stripAnsi(err.stderr).trim() : (err?.message ?? String(err));
+async function _execOnce(bin) {
+  const r = await run(bin, ["--print", "/usage"], {
+    timeout: 15_000,
+    maxBuffer: 1024 * 1024,
+    // Marks this Claude Code run as the deck's own. `claude --print /usage`
+    // is a full invocation, so it fires the hooks we installed, and every
+    // quota poll was drawing itself onto the canvas as a fresh session with
+    // no prompt and no tools. Hooks inherit the environment, so hook.js
+    // sees this and stays quiet.
+    env: { ...process.env, NO_COLOR: "1", TERM: "dumb", AGENTS_DECK_INTERNAL: "1" },
+  });
+  // `run` never rejects, so there is one path rather than two — and the output
+  // is kept either way, which matters because the CLI writes the quota lines to
+  // stdout and can still exit non-zero afterwards.
+  const combined = r.stdout + "\n" + r.stderr;
+  if (!r.ok) {
+    const msg = stripAnsi(r.stderr).trim() || `claude exited ${r.code}`;
     console.error(`${PRODUCT} quota: claude CLI failed:`, msg);
-    if (err?.stdout || err?.stderr) {
-      const combined = (err.stdout ?? "") + "\n" + (err.stderr ?? "");
-      return { cliOk: /subscription/i.test(combined), parsed: parseUsageText(combined) };
-    }
-    return { cliOk: false, parsed: null };
   }
+  const cliOk = /subscription/i.test(combined) || /claude code usage/i.test(combined);
+  return { cliOk, parsed: parseUsageText(combined) };
 }
 
 async function _doFetch(now, force = false) {
@@ -515,7 +542,7 @@ async function _doFetch(now, force = false) {
   }
 
   // Source 3: parse `claude --print /usage` CLI output.
-  const shellCmd = buildQuotaShellCmd();
+  const bin = quotaClaudeBin();
 
   // The CLI sometimes omits the "Current session/week" quota lines on a cold
   // invocation (right after the server starts, or after the page is hard-
@@ -525,7 +552,7 @@ async function _doFetch(now, force = false) {
   let parsed = null;
   for (let attempt = 0; attempt < 3; attempt++) {
     if (attempt > 0) await sleep(1200);
-    const r = await _execOnce(shellCmd);
+    const r = await _execOnce(bin);
     cliOk = r.cliOk || cliOk;
     if (r.parsed) { parsed = r.parsed; break; }
   }

package/src/server/sound-hook.mjs

@@ -17,6 +17,7 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { claudeConfigDir } from "./claude-dir.mjs";
 import { readSettingsForWrite, writeFileAtomic, installScript } from "./installer.mjs";
+import { shellQuoteArg } from "./exec.mjs";
 
 const PKG_ROOT      = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const CLAUDE_DIR    = claudeConfigDir();
@@ -34,6 +35,18 @@ const PARKED_PATH = join(homedir(), ".agents-deck", "parked-sound-hooks.json");
 // what is already there — never to modify or remove it.
 const SOUND_HINTS = [/\bafplay\b/i, /Media\.SoundPlayer/i, /\bpaplay\b/i, /\baplay\b/i, /canberra-gtk-play/i];
 
+/**
+ * The Stop hook's `command` string, escaped for the shell that will run it.
+ *
+ * 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.
+ */
+export function soundHookCommand(notifyPath, node = process.execPath) {
+  return `${shellQuoteArg(node)} ${shellQuoteArg(notifyPath)}`;
+}
+
 /**
  * Read settings.json, refusing to guess at a file that will not parse.
  *
@@ -338,8 +351,13 @@ export async function setSoundHook(enabled) {
       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.
-        command: `"${process.execPath}" "${NOTIFY_PATH}"`,
+        // 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,
       }],
     });