agent-dag 3.2.1 → 3.3.0

package/src/server/index.mjs

@@ -662,7 +662,7 @@ export const MAX_SCAN_CHUNK = 8 * 1024 * 1024;
 // pointing one POST at something arbitrarily large: the read still terminates,
 // the cursor keeps whatever it reached, and the next throttled pass continues
 // from there.
-export const MAX_SCAN_BYTES_PER_PASS = 256 * 1024 * 1024;
+const MAX_SCAN_BYTES_PER_PASS = 256 * 1024 * 1024;
 
 const NEWLINE = 0x0a;
 
@@ -1458,7 +1458,7 @@ const pendingNameReads = new Set();     // sid currently being read
 /** The naming the cursor has folded so far, or null when the scan has nothing.
  *  Exported beside readContextFromTranscript for the same reason: the rule is
  *  worth pinning directly rather than through a live server. */
-export async function readSessionNamingFromTranscript(path) {
+async function readSessionNamingFromTranscript(path) {
   const state = await scanTranscript(path);
   if (!state) return null;
   if (!state.agentName && !state.aiTitle) return null;
@@ -3470,7 +3470,13 @@ export function replayScope(workspace, platform = process.platform) {
  * that case cheap needs an index of where a workspace's lines are, which is a
  * different change from this one.
  */
-async function replayLog(filePath, workspace = "") {
+/* Exported for the suite, with both ceilings as parameters. The byte budget is
+ * 128 MiB, so a test that wanted to reach it honestly would have to write 128
+ * MiB — which is why the count bound was the only one anything pinned, and why
+ * the byte bound was the one that broke. Production passes neither argument. */
+export async function replayLog(filePath, workspace = "", {
+  maxEvents = MAX_BUFFER, maxChars = MAX_BUFFER_CHARS,
+} = {}) {
   if (!existsSync(filePath)) return 0;
   let skipped = 0;
   let skippedBytes = 0;
@@ -3499,17 +3505,32 @@ async function replayLog(filePath, workspace = "") {
     }
   } else {
     // Newest first, so this is filled back to front and then walked in reverse
-    // to push. Bounded by MAX_BUFFER, which is what makes the memory here a
-    // property of the ring rather than of the file.
+    // to push. Bounded by BOTH of the ring's limits, which is what makes the
+    // memory here a property of the ring rather than of the file.
+    //
+    // The count alone was not enough, and the comment that used to say it was
+    // predates #625. Eviction is the only thing that applies MAX_BUFFER_CHARS,
+    // and eviction happens inside pushEvent — which does not run until this
+    // array is already full. Measured on a 187 MB log of 40 events of 4.9M
+    // characters each, every one of them under the ingest cap: RSS went from
+    // 215 MB to a peak of 505 MB, and the ring that survived held 27 events and
+    // 126 MiB. About 290 MB staged for a ring capped at 128.
+    //
+    // Rotation at 50 MB normally keeps logs well under this, but rotation is
+    // best-effort and its failure is only logged, and this file's own header
+    // records logs reaching gigabytes.
     const newestFirst = [];
+    let stagedChars = 0;
     for await (const line of linesFromEnd(filePath)) {
       if (!line) continue;
       const evt = parse(line);
       if (!usable(evt) || !admits(evt.payload)) continue;
       newestFirst.push(evt);
+      stagedChars += ENVELOPE_CHARS + payloadChars(evt.payload);
       // Everything older than this would be evicted by the events already held,
       // so reading further is work whose only result is throwing it away.
-      if (newestFirst.length >= MAX_BUFFER) break;
+      // Either limit reaching its ceiling means exactly that.
+      if (newestFirst.length >= maxEvents || stagedChars >= maxChars) break;
     }
     for (let i = newestFirst.length - 1; i >= 0; i--) replay(newestFirst[i]);
     count = newestFirst.length;
@@ -4116,7 +4137,7 @@ async function handleBrowserWatchSettings(req, res) {
   try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
   if (!body || typeof body !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
 
-  const { readStore, writeStore, normalise } = await import(
+  const { readStore, updateStore, normalise } = await import(
     pathToFileURL(join(PKG_ROOT, "src/server/browser-watch-store.mjs")).href
   );
   const { invalidateBrowserWatchCache, noteWatchSetting } = await import(
@@ -4132,7 +4153,11 @@ async function handleBrowserWatchSettings(req, res) {
   // this field ERASES it. Measured — changing the reaction wiped every
   // dismissal, so every episode the reader had reviewed came straight back on
   // the next poll, from a settings change that had nothing to do with them.
-  await writeStore({ settings, episodes: store.episodes, dismissed: store.dismissed });
+  // Only the settings are this route's to change. `updateStore` re-reads inside
+  // the write queue, so a poll that landed between the read above and this line
+  // cannot have its archive thrown away by a settings change — which is what
+  // writing a whole state read seconds earlier used to do.
+  await updateStore(cur => ({ ...cur, settings }));
   // The one line in the log that is somebody acting rather than the deck
   // reading, which is exactly why it is worth its own entry.
   if (settings.enabled !== store.settings.enabled) {
@@ -4168,7 +4193,7 @@ async function handleBrowserWatchDismiss(req, res) {
   const startMs = typeof body?.startMs === "number" && Number.isFinite(body.startMs) ? body.startMs : null;
   if (host === null || startMs === null) return send(res, 400, { ok: false, reason: "bad_request" });
 
-  const { readStore, writeStore, episodeKey } = await import(
+  const { readStore, updateStore, episodeKey } = await import(
     pathToFileURL(join(PKG_ROOT, "src/server/browser-watch-store.mjs")).href
   );
   const { invalidateBrowserWatchCache, noteWatchSetting } = await import(
@@ -4177,7 +4202,7 @@ async function handleBrowserWatchDismiss(req, res) {
   const store = await readStore();
   const key = episodeKey(host, startMs);
   const dismissed = [...new Set([...(store.dismissed ?? []), key])];
-  await writeStore({ settings: store.settings, episodes: store.episodes, dismissed });
+  await updateStore(cur => ({ ...cur, dismissed }));
   // The reader acting on their own list, which is exactly the kind of line the
   // `act` level exists for.
   noteWatchSetting(`dismissed ${host}`);
@@ -4188,6 +4213,12 @@ async function handleBrowserWatchDismiss(req, res) {
 async function handleBrowserWatch(req, res) {
   const url = new URL(req.url, "http://localhost");
   const force = url.searchParams.get("refresh") === "1";
+  // `live=0` is the badge's five-minute poll saying "the archive is enough".
+  // With the watch OFF that is honoured and no browser is read at all — see
+  // browserWatchSnapshot: the switch used to gate only what was KEPT, so a deck
+  // nobody had switched on still copied every History database every five
+  // minutes. A forced read overrides it, because that is the user pressing ↻.
+  const readBrowsers = force || url.searchParams.get("live") !== "0";
 
   // Numbers from a query string are refused rather than coerced: NaN would
   // silently widen the quiet gate to "everything counts", which is the failure
@@ -4217,6 +4248,7 @@ async function handleBrowserWatch(req, res) {
   const ports = await registeredDeckPorts();
   return send(res, 200, await fetchBrowserWatch({
     force,
+    readBrowsers,
     deckOrigins: deckOwnOrigins(undefined, ports),
     quietMs: minutes("quiet"),
     gapMs: minutes("gap"),
@@ -4676,9 +4708,19 @@ function handleHookChallenge(_req, res, url) {
   send(res, 200, { proof: challengeProof(HOOK_TOKEN, nonce) });
 }
 
+// Signal 0 delivers nothing; it asks whether the pid could be signalled.
+//
+// BOTH ERRNOS, and the second one is the Windows spelling. POSIX `kill(2)`
+// answers EPERM for a process this account may not signal. On Windows
+// `uv_kill` calls `OpenProcess`, a denial is ERROR_ACCESS_DENIED, and libuv
+// maps that to EACCES — so a deck started from an elevated terminal, or under
+// another account, read as DEAD to every probe in this repo. What followed was
+// silent: the live deck's discovery file was unlinked on the next hook fire,
+// rewritten five seconds later by keepDiscovery, and its banner went on
+// claiming it was receiving events it had stopped receiving.
 function isProcessAlive(pid) {
   try { process.kill(pid, 0); return true; }
-  catch (e) { return e && e.code === "EPERM"; }
+  catch (e) { return !!e && (e.code === "EPERM" || e.code === "EACCES"); }
 }
 
 async function sweepStaleDiscovery() {
@@ -4990,6 +5032,72 @@ function isDeckUiRequest({ origin, host, secFetchSite } = {}) {
 // presents nothing at all no longer changes anything — and what is opened is
 // the honest door, so a script of the user's own authenticates by reading the
 // token instead of impersonating a page.
+/**
+ * May this request read the deck's OWN data — the events, the accounts, the
+ * browsing episodes?
+ *
+ * The mutation gate exists because `curl -XPOST localhost:4317/…/admin` handed
+ * a live OAuth refresh token to a sandboxed subprocess with loopback egress.
+ * The same caller could still `curl localhost:4317/api/events` and read the
+ * whole ring — prompt text, the Bash command lines the agent ran, the paths and
+ * contents it wrote, the contents of every file it read back — plus the account
+ * roster and the browsing episodes. The threat model had been applied to half
+ * the surface.
+ *
+ * Same shape as isAuthorizedMutation, with one difference forced by the
+ * browser: a same-origin GET carries no `Origin` header at all, so the UI
+ * cannot be recognised the way a POST is. `Sec-Fetch-Site: same-origin` is what
+ * a page's own fetch and its EventSource both send, on every browser new enough
+ * to run this bundle, and it is a header no non-browser client sends by
+ * accident. A caller that sends neither it nor the token is not a page.
+ *
+ * WHAT STAYS OPEN, deliberately: /api/health (the hook's readiness probe),
+ * /api/hook-challenge (the handshake itself), the static files, and every
+ * measurement route — the machine panel's numbers are about the machine, not
+ * about what the user is doing on it.
+ */
+function isAuthorizedDataRead(req) {
+  const headers = req?.headers ?? {};
+  if (presentsDeckToken(headers)) return true;
+  // Addressed to this machine by a name that can only be this machine — so a
+  // rebound page, which also reports same-origin, does not qualify.
+  if (!isLoopbackHost(headers.host)) return false;
+
+  const site = typeof headers["sec-fetch-site"] === "string"
+    ? headers["sec-fetch-site"].trim().toLowerCase() : "";
+  if (site === "same-origin") return true;
+  // ANY FETCH METADATA AT ALL, AND IT SAID SOMETHING ELSE. `cross-site`,
+  // `same-site` and `none` are all a page that is not this one — or a top-level
+  // navigation typed into the address bar, which has no business reading the
+  // ring.
+  if (site !== "") return false;
+
+  // THE BROWSER THAT SENDS NO FETCH METADATA, and this is the whole reason this
+  // branch exists. Sec-Fetch-Site is Safari 16.4 and newer; Safari 16.0-16.3
+  // runs this bundle perfectly well (Vite's default target is Safari 16) and
+  // sends none of it. Without a fallback those users get an empty canvas and a
+  // 401 they cannot act on — an impediment for a browser that is otherwise
+  // fine.
+  //
+  // Referer is what they do send, on a page's own fetches and on its
+  // EventSource, and it must name THIS origin. A cross-site page's Referer
+  // names its own; a rebound page's names the attacker's host, which is not a
+  // loopback identity. It is forgeable by a non-browser client — and so is
+  // Sec-Fetch-Site, which curl sets as easily; neither is the control that
+  // stops a deliberate local caller. That control is the token, and this only
+  // decides which BROWSERS are recognised as the deck's own page.
+  return originMatchesHost(headers.referer, headers.host);
+}
+
+/** The reads that carry the user's own work, rather than the machine's. */
+const GUARDED_READS = new Set([
+  "/events",
+  "/api/events",
+  "/api/claude-accounts",
+  "/api/claude-accounts/login",
+  "/api/browser-watch",
+]);
+
 function isAuthorizedMutation(req) {
   const headers = req?.headers ?? {};
   if (presentsDeckToken(headers)) return true;
@@ -5200,6 +5308,14 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
       return send(res, 401, { error: "unauthenticated" });
     }
 
+    // And the reads that carry the same secrets. See isAuthorizedDataRead: the
+    // gate above was written for a sandboxed subprocess with loopback egress,
+    // and that caller was reading the ring through a GET the whole time.
+    if ((req.method === "GET" || req.method === "HEAD")
+      && GUARDED_READS.has(url.pathname) && !isAuthorizedDataRead(req)) {
+      return send(res, 401, { error: "unauthenticated" });
+    }
+
     // `?persist=0` — another deck was elected to write this event to the log
     // the two of them share. Absent, this deck writes it.
     if (req.method === "POST" && url.pathname === "/api/event") return guard(handleEventIngest(req, res, url.searchParams.get("persist") !== "0"), res);

package/src/server/installer.mjs

@@ -353,7 +353,31 @@ async function writeFileAtomic(rawTarget, text) {
     // to stay 600. No-op on Windows, where chmod only toggles the read-only bit.
     const mode = await stat(target).then(s => s.mode, () => null);
     if (mode !== null) await chmod(tmp, mode).catch(() => {});
+    // A READ-ONLY TARGET IS A DEAD END ON WINDOWS, and only there. libuv's
+    // rename is one MoveFileExW(MOVEFILE_REPLACE_EXISTING), which refuses to
+    // replace a destination carrying FILE_ATTRIBUTE_READONLY; POSIX rename(2)
+    // over a 0444 file succeeds, because only the parent directory's write bit
+    // decides. A settings.json picks that attribute up from a OneDrive restore,
+    // a copy off a network share, or read-only media — and EACCES is in the
+    // retry ladder, so the whole ~1.4s was spent before throwing, on every
+    // boot, forever. Every settings writer goes through here, so hooks never
+    // installed and the sound-hook retirement could never repair a stale entry
+    // either.
+    //
+    // chmod on Windows toggles exactly that attribute and nothing else, which
+    // is why this is safe to do unconditionally there: the mode carried above
+    // is re-applied to the new file after the rename, so a file the user marked
+    // read-only stays read-only.
+    // ONLY WHEN THE TARGET IS ACTUALLY READ-ONLY. Two extra syscalls on the
+    // path between the temp write and the rename are not free on Windows:
+    // discovery-live.test.ts hammers writeDiscovery while a reader holds the
+    // destination open, and the wider window turned a rename the retry ladder
+    // used to win into an EPERM it gave up on. The attribute is what this
+    // clears, so a file that does not carry it has nothing to clear.
+    const readOnly = process.platform === "win32" && mode !== null && (mode & 0o200) === 0;
+    if (readOnly) await chmod(target, 0o666).catch(() => {});
     await renameWithRetry(tmp, target);
+    if (readOnly) await chmod(target, mode).catch(() => {});
   } catch (err) {
     // Cleanup covers the write and the fsync as well as the rename: a full disk
     // used to leave the half-written temp file sitting beside the target.
@@ -405,7 +429,7 @@ function dedupeOurEntries(group) {
 }
 
 /** Install hooks for a single provider. Returns {settingsPath, hookPath, events, changed}. */
-export async function installHooks({ provider = "claude" } = {}) {
+export async function installHooks({ provider = "claude", beforeWrite = null } = {}) {
   const cfg = PROVIDERS[provider];
   if (!cfg) throw new Error(`unknown provider: ${provider}`);
   // An uninstall-only provider has no event list. Saying so beats the
@@ -481,7 +505,38 @@ export async function installHooks({ provider = "claude" } = {}) {
   // compare against the exact bytes we read and, when they match, do nothing.
   const next = JSON.stringify(current, null, 2) + "\n";
   const changed = next !== before;
-  if (changed) await writeFileAtomic(cfg.settingsPath, next);
+  if (changed) {
+    // COMPARE AGAINST THE FILE, NOT AGAINST THE SNAPSHOT, at the last moment.
+    //
+    // Everything above was computed from bytes read at the top of this
+    // function, and two decks booting together — the ordinary case on a machine
+    // where one was already running — interleave inside that window. The one
+    // that loses is unrecoverable rather than merely stale: deck A restores the
+    // user's own sound hooks from the parked file and deletes the park, and
+    // deck B then writes a settings object computed before that restore, with
+    // an empty park behind it. The user's hook is gone from settings.json and
+    // from the only other copy of it.
+    //
+    // So the file is re-read immediately before the write and, if another
+    // writer has touched it, this pass declines. Declining is safe by
+    // construction: every boot reinstalls, so the next one recomputes against
+    // the new bytes and converges — and the entries this function adds are
+    // identical on both decks, which is why the loser has nothing of its own to
+    // lose.
+    // The seam the suite needs, and the only way to test this deterministically:
+    // the window between the read at the top and the write below is filled with
+    // real fs work, so a test that raced it by wall clock would pass or fail by
+    // how fast the machine is. Production passes nothing.
+    if (beforeWrite) await beforeWrite();
+    const { raw: onDisk } = await readSettingsForWrite(cfg.settingsPath).catch(() => ({ raw: before }));
+    if (onDisk !== before) {
+      return {
+        settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider,
+        changed: false, raced: true, retire: { ...retire, pending: false },
+      };
+    }
+    await writeFileAtomic(cfg.settingsPath, next);
+  }
   // After the write, never before it: the notify script an older deck installed
   // is what a live session's cached command still names until the new entry is
   // on disk, and deleting it early turns a stale sound into a missing module.
@@ -773,4 +828,4 @@ export { AGENT_DAG_DIR, CLAUDE_DIR, CODEX_DIR };
 // repo for the same reasons settings.json is, and "never rename onto a link" is
 // one rule: codex-auth.mjs called a realpath of its own before this existed, and
 // two spellings of a rule are two things that can drift.
-export { readSettingsForWrite, writeFileAtomic, installScript, renameWithRetry, createTemp, resolveWriteTarget };
+export { readSettingsForWrite, writeFileAtomic, renameWithRetry, createTemp, resolveWriteTarget };

package/src/server/macmon.mjs

@@ -193,11 +193,6 @@ export function macmonAsset(release) {
   return { version: typeof tag === "string" ? tag : "unknown", url: a.browser_download_url, sha256: m[1] };
 }
 
-/** A macmon this function installed earlier, or null. */
-export function existingBootstrappedMacmon() {
-  const bin = join(MACMON_DIR, "macmon");
-  return existsSync(bin) ? bin : null;
-}
 
 /**
  * Download macmon into ~/.agents-deck/tools/macmon.
@@ -210,9 +205,25 @@ export function existingBootstrappedMacmon() {
  * ioreg and never reaches this file at all.
  */
 export async function bootstrapMacmon({
-  platform = process.platform, env = process.env, fetchFn = fetch, dir = MACMON_DIR,
+  platform = process.platform, arch = process.arch, env = process.env,
+  fetchFn = fetch, dir = MACMON_DIR, findBin = macmonBin,
 } = {}) {
   if (platform !== "darwin") return { ok: false, reason: "unsupported_platform" };
+  // ARM64 ONLY, checked rather than merely documented. The release publishes
+  // one asset and it is an arm64 Mach-O, so an Intel Mac downloaded 746 KB it
+  // could not execute and failed its own --version check afterwards. That is
+  // the small half. The larger half is the promise: the README says an Intel
+  // Mac never downloads anything, and this reached api.github.com on any Mac
+  // whose sensors happened to stay silent — which an Intel Mac's do whenever
+  // ioreg publishes no Temperature(C).
+  if (arch !== "arm64") return { ok: false, reason: "unsupported_arch" };
+  // A macmon the user already has is the other thing the README promises to
+  // notice, and until now the skip was emergent rather than checked: a working
+  // copy produces a reading, the reading sets thermalEverAnswered, and the
+  // give-up branch never fires. That chain breaks on a macmon which runs but
+  // reports values this deck rejects as implausible — and then a machine with
+  // macmon on PATH downloaded a second one.
+  if (await findBin()) return { ok: false, reason: "already_installed" };
   // Both switches, for the reason uv-bootstrap has both: downloading an
   // executable is a bigger step than installing a package with a tool the user
   // already chose, so somebody may want the managed installs and not this.

package/src/server/npx.mjs

@@ -194,7 +194,12 @@ export function npxPrefetch(spec, {
     timer.unref?.();
 
     child.on("error", err => settle({ ok: false, error: `could not run npx: ${err?.message ?? err}`, hint: null }));
-    child.on("exit", (code, signal) => {
+    // 'close' rather than 'exit': 'exit' fires when the process ends and says
+    // nothing about its pipes, so past one pipe buffer the tail this kept —
+    // deliberately the TAIL, because npm's reason is on its last lines — was
+    // still only the first 8 KiB when npxFailureSummary read it. 'close' is
+    // emitted after both streams have been drained.
+    child.on("close", (code, signal) => {
       if (code === 0) { settle({ ok: true, error: null, hint: null }); return; }
       settle({
         ok: false,

package/src/server/open-url.mjs

@@ -166,11 +166,31 @@ export function startCommand(url, env = process.env, comspec) {
  * it and `start` would run it.
  */
 export function isOpenable(url) {
+  return normalizeOpenable(url) !== null;
+}
+
+/**
+ * The address to actually hand the desktop, or null when it is not one.
+ *
+ * The guard used to parse into a local `u`, check its protocol and throw the
+ * parse away — so what reached `launchers` was the RAW string. `new URL()`
+ * accepts characters it normalizes only in `href`, a `"` among them, and on
+ * Windows `startCommand` builds `start "" "<url>"` with
+ * `windowsVerbatimArguments: true`, where a quote is syntax. Today the only
+ * caller passes a loopback URL this deck built itself, so nothing is reachable;
+ * the function's own doc says it exists "for the day a second caller passes a
+ * path", and as written it would not have stopped that caller.
+ *
+ * Returning the normalized `href` means the string that was checked is the
+ * string that is launched.
+ */
+export function normalizeOpenable(url) {
   try {
     const u = new URL(String(url));
-    return u.protocol === "http:" || u.protocol === "https:";
+    if (u.protocol !== "http:" && u.protocol !== "https:") return null;
+    return u.href;
   } catch {
-    return false;
+    return null;
   }
 }
 
@@ -183,8 +203,9 @@ export function isOpenable(url) {
  * the same recovery an error row would have offered.
  */
 export function openUrl(url, { platform = process.platform, env = process.env, spawnFn = spawn } = {}) {
-  if (!isOpenable(url)) return;
-  const tries = launchers(url, { platform, env });
+  const href = normalizeOpenable(url);
+  if (href === null) return;
+  const tries = launchers(href, { platform, env });
 
   const attempt = (i) => {
     if (i >= tries.length) return;

package/src/server/quota.mjs

@@ -35,6 +35,11 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { PRODUCT } from "./brand.mjs";
+// One ANSI stripper for the whole deck. The private copy that used to live
+// here accepted only the BEL terminator for an OSC sequence, while term.mjs's
+// also accepts ESC \\ — so a hyperlink written the other legal way survived
+// into text this module then parsed for quota lines.
+import { stripAnsi } from "./term.mjs";
 import { resetLabelIso } from "./reset-label.mjs";
 
 const USAGE_URL   = "https://api.anthropic.com/api/oauth/usage";
@@ -83,6 +88,73 @@ async function readOAuthToken() {
   }
 }
 
+/**
+ * Whether we may spend a request of the user's budget right now.
+ *
+ * Exported for tests — this is the rule that stopped the deck from starving
+ * claude-swap, and it is worth pinning down.
+ */
+export function maySelfPoll({ now, force, lastSelfPollAt, rateLimitedUntil }) {
+  if (now < rateLimitedUntil) return false;
+  return now - lastSelfPollAt >= (force ? FORCE_POLL_MS : SELF_POLL_MS);
+}
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+/**
+ * A cooldown from a `retry-after`, kept inside limits the deck can live with.
+ *
+ * Unclamped, the header decided the poller's fate in both directions: `0` (or a
+ * value the server rounds down to it) defeats the cooldown entirely and the
+ * next tick asks again immediately, which is the loop a 429 exists to stop; a
+ * large one — a day is a legal value — freezes the reader for the life of the
+ * process, and nothing here re-reads it. Both are the remote side deciding how
+ * this deck behaves, which a header is not entitled to do.
+ *
+ * The floor is the deck's own minimum backoff and the ceiling is an hour: long
+ * enough to be a real retreat, short enough that a quota panel is not dead for
+ * the rest of the day because one reply said so.
+ */
+export function cooldownFromHeader(raw, fallbackMs, minMs = 30_000, maxMs = 3600_000) {
+  const seconds = parseInt(String(raw ?? ""), 10);
+  if (!Number.isFinite(seconds)) return fallbackMs;
+  return Math.min(Math.max(seconds * 1000, minMs), maxMs);
+}
+
+/**
+ * WHETHER THIS MACHINE HAS A SUBSCRIPTION TO REPORT ON AT ALL.
+ *
+ * Every source here needs a Claude.ai OAuth credential: the claude-swap store
+ * holds one, `claudeAiOauth` in the credentials file is one, and
+ * `claude --print /usage` prints windows only for a session signed in with one.
+ * An API-key, Bedrock or Vertex install has none — and there is no quota to
+ * read, because those are billed per token rather than in five-hour windows.
+ *
+ * That mattered because of what the CLI does on such a machine: it RUNS, prints
+ * no quota lines, and the branch below used to read that as "genuine <1%" and
+ * publish `ok: true` with two zeroes. The panel then drew empty bars, which is
+ * a measurement nobody took. Codex already answers this properly, with
+ * `api_key_mode` as its own reason and its own sentence.
+ *
+ * Cheap and synchronous: environment first, because a machine configured for
+ * Bedrock or Vertex says so there, then the presence of the OAuth block in the
+ * credentials file. `readOAuthToken` above answers a different question — it
+ * also rejects an EXPIRED token, and an expired subscription is still a
+ * subscription.
+ */
+export async function hasSubscriptionCredential(env = process.env) {
+  if (env.CLAUDE_CODE_USE_BEDROCK === "1" || env.CLAUDE_CODE_USE_VERTEX === "1") return false;
+  try {
+    const raw = await readFile(credentialsPath(), "utf8");
+    if (JSON.parse(raw)?.claudeAiOauth?.accessToken) return true;
+  } catch { /* absent or unreadable, decided below */ }
+  // A key in the environment and no OAuth block beside it is the API-key
+  // install. Without either, this deck simply has not been signed in yet, and
+  // "sign in" is the right thing to say — which is the `waiting` branch, not
+  // this one.
+  return !(env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN);
+}
+
 // ISO-8601 → "Jun 19, 1:19pm" (local time, matching the CLI display format).
 //
 // The body moved to reset-label.mjs in #374: codex-quota.mjs had a copy that
@@ -156,9 +228,7 @@ async function fetchOAuthUsage() {
     });
 
     if (res.status === 429) {
-      const retryAfter = parseInt(res.headers.get("retry-after") ?? "", 10);
-      const cooldownMs = Number.isFinite(retryAfter) ? retryAfter * 1000 : 5 * 60_000;
-      _rateLimitedUntil = Date.now() + cooldownMs;
+      _rateLimitedUntil = Date.now() + cooldownFromHeader(res.headers.get("retry-after"), 5 * 60_000);
       return null;
     }
     if (!res.ok) return null;
@@ -236,25 +306,6 @@ export function quotaFromStore(entry) {
   return out;
 }
 
-/**
- * Whether we may spend a request of the user's budget right now.
- *
- * Exported for tests — this is the rule that stopped the deck from starving
- * claude-swap, and it is worth pinning down.
- */
-export function maySelfPoll({ now, force, lastSelfPollAt, rateLimitedUntil }) {
-  if (now < rateLimitedUntil) return false;
-  return now - lastSelfPollAt >= (force ? FORCE_POLL_MS : SELF_POLL_MS);
-}
-
-const sleep = (ms) => new Promise(r => setTimeout(r, ms));
-
-function stripAnsi(s) {
-  return s
-    .replace(/\x1B\[[0-9;]*[A-Za-z]/g, "")
-    .replace(/\x1B\][^\x07]*\x07/g, "")
-    .replace(/\x1B[()][AB012]/g, "");
-}
 
 // Parse "Jun 18, 4:09pm" (local time, no tz) into unix seconds.
 // Claude shows times in the user's local timezone, so parsing as local is correct.
@@ -671,12 +722,23 @@ async function _doFetch(now, force = false, gen = _generation) {
     return publish(gen, { ..._lastGood, stale: true }, now - (CACHE_MS - 5_000));
   }
 
-  // Never had good data. CLI ran but lines absent → treat as genuine <1%.
-  // CLI failed entirely → ok:false. Either way short-cache for a quick retry.
-  const result = cliOk
+  // Never had good data. A CLI that RAN and printed no quota lines is two
+  // different machines, and they need two different answers:
+  //
+  //   * a subscription install on a cold invocation — the lines come back on a
+  //     later call, and until then "<1%" is the honest reading of a window that
+  //     has genuinely just reset;
+  //   * an API-key, Bedrock or Vertex install, which has no windows at all.
+  //     Publishing two zeroes there drew empty bars for a measurement nobody
+  //     took, on a machine where no amount of retrying will ever produce one.
+  //
+  // A CLI that failed entirely is `ok: false` as it always was, and the reason
+  // says which of the two the reader is looking at.
+  const subscribed = cliOk ? await hasSubscriptionCredential() : false;
+  const result = cliOk && subscribed
     ? { ok: true, session5hPct: 0, session5hWindowSec: 18000,
         week7dPct: 0, week7dWindowSec: 604800, fetchedAt: now }
-    : { ok: false, fetchedAt: now };
+    : { ok: false, reason: cliOk ? "no_subscription" : "cli_failed", fetchedAt: now };
   return publish(gen, result, now - (CACHE_MS - 5_000));
 }
 

package/src/server/retire-sound-hook.mjs

@@ -94,10 +94,44 @@ const PARKED_PATH = join(homedir(), ".agents-deck", "parked-sound-hooks.json");
 const commandsOf = (entry) =>
   (entry?.hooks ?? []).map(h => (typeof h?.command === "string" ? h.command : ""));
 
+/**
+ * THE TAIL, NOT THE WHOLE PATH — and this is a data-loss fix, not a tidy-up.
+ *
+ * The stored command was written by `shellQuoteArg`, whose POSIX branch
+ * single-quotes the argument and rewrites every `'` as `'\''`. So on a config
+ * dir like `/mnt/Bob's SSD/claude` the command contains `Bob'\''s` and a
+ * `cmd.includes(NOTIFY_PATH)` against the raw path is false — on macOS and
+ * Linux, for a perfectly ordinary directory name.
+ *
+ * What follows is unrecoverable. A mark-less `Stop` entry — the case this
+ * module exists for — is then not recognised as ours, so it is kept; and
+ * `anythingStillNamesOurScripts`, which has no mark to fall back on, also says
+ * no, so the sweep deletes `notify.mjs`. Claude Code throws
+ * `Cannot find module` at the end of every turn afterwards, forever, with the
+ * deck already uninstalled.
+ *
+ * The last two segments are fixed whatever the prefix is — the install
+ * directory is always `<config dir>/agent-dag` — and they contain no character
+ * any quoting rewrites. Case is folded where the filesystem folds it, which is
+ * the other half: `exec.mjs`'s own `sameCommand` lowercases "because Windows
+ * paths are", and this comparison did not.
+ */
+const SCRIPT_TAILS = ["agent-dag/notify.mjs", "agent-dag/notify.js"];
+
+export function namesOurScript(cmd, platform = process.platform) {
+  if (typeof cmd !== "string" || cmd === "") return false;
+  // Backslashes become separators only where they ARE separators. On POSIX a
+  // backslash is an ordinary filename character, and rewriting it there could
+  // invent a match that the filesystem does not have.
+  let hay = platform === "win32" ? cmd.replace(/\\/g, "/") : cmd;
+  if (platform === "win32" || platform === "darwin") hay = hay.toLowerCase();
+  return SCRIPT_TAILS.some(tail => hay.includes(tail));
+}
+
 /** An entry this deck put there: by its mark, or by the script it runs. */
 function isOurs(entry) {
   if (entry?.[MARK] === true) return true;
-  return commandsOf(entry).some(cmd => OUR_SCRIPTS.some(p => cmd.includes(p)));
+  return commandsOf(entry).some(cmd => namesOurScript(cmd));
 }
 
 /** Anywhere in the file — not just `Stop` — that still runs one of our scripts.
@@ -109,7 +143,7 @@ function anythingStillNamesOurScripts(settings) {
   for (const group of Object.values(groups)) {
     if (!Array.isArray(group)) continue;
     for (const entry of group) {
-      if (commandsOf(entry).some(cmd => OUR_SCRIPTS.some(p => cmd.includes(p)))) return true;
+      if (commandsOf(entry).some(cmd => namesOurScript(cmd))) return true;
     }
   }
   return false;