ccdeck 3.29.11 → 3.31.0

package/hook/hook.js

@@ -56,8 +56,9 @@ const PROVIDER = parseProvider(process.argv.slice(2));
  * arrived short — `%TEMP%` under a shortened profile directory, which is what
  * every GitHub Windows runner has — the two canonicalisers that exist to agree
  * disagreed by a whole path: C:\Users\RUNNER~1\… against C:\Users\runneradmin\….
- * canonicalWorkspace in src/server/index.mjs says the rest of it, including why
- * the long form is the canonical one; all three sites name `.native` out loud.
+ * canonicalWorkspace in src/server/canonical-path.mjs says the rest of it,
+ * including why the long form is the canonical one; all three sites name
+ * `.native` out loud.
  *
  * Exported for that test: it is half of what `--workspace` means, and a
  * predicate handed an already-canonical path cannot show that the caller
@@ -179,7 +180,7 @@ function cwdInWorkspace(cwd, workspace, platform = process.platform) {
  * payload with no cwd — it is here because the rule has to be stated the same
  * way on both sides to be pinned against the other one.
  *
- * src/server/log-writer.mjs answers this same question, for the sessions the
+ * src/server/log-election.mjs answers this same question, for the sessions the
  * server builds itself out of Codex's rollout files, under the name
  * codexCwdInWorkspace — this script is copied out of the package and run
  * standalone, so it cannot import that copy. A test walks one table of paths
@@ -233,11 +234,11 @@ function isAlive(pid) {
  * The platform is a parameter, like cwdInWorkspace's, so the case-folding half
  * is testable from any machine.
  *
- * src/server/log-writer.mjs repeats this rule for the events no hook delivers —
- * the ones the server builds itself from Codex's rollout files — because this
- * script is copied out of the package and cannot import it. A test compares the
- * two directly: they decide for the same decks, and a disagreement is a line
- * written twice or not at all.
+ * src/server/log-election.mjs repeats this rule for the events no hook
+ * delivers — the ones the server builds itself from Codex's rollout files —
+ * because this script is copied out of the package and cannot import it. A test
+ * compares the two directly: they decide for the same decks, and a disagreement
+ * is a line written twice or not at all.
  */
 function electWriters(decks, platform = process.platform) {
   const byLog = new Map();
@@ -527,7 +528,7 @@ function prove(d, cb, attempt = 0) {
  * The election has to be decided over the decks that are actually going to be
  * handed the payload, and the only thing that establishes that is the handshake.
  * So: prove, then elect, then post. It costs no extra round trip, only this
- * ordering, and it is the same reordering src/server/index.mjs makes in
+ * ordering, and it is the same reordering src/server/live-decks.mjs makes in
  * readLiveDecks for the Codex rollouts no hook ever sees.
  *
  * A FAILED CHALLENGE ON ITS OWN IS STILL NOT PROOF THE DECK IS GONE. A dead pid
@@ -793,10 +794,10 @@ function readRecord(file, resolvedCwd, found, done) {
     // every tool call, and nothing removes the record: pid 1 is init, so
     // isAlive is true forever and the unlink below never fires.
     //
-    // index.mjs:2156 reads these same files and always refused them. Two
-    // readers of one directory disagreeing is the bug; this is the stronger
-    // half, which is the one that belongs in the process that cannot afford
-    // to throw.
+    // sweepStaleDiscovery, in src/server/stale-discovery.mjs, reads these same
+    // files and always refused them. Two readers of one directory disagreeing
+    // is the bug; this is the stronger half, which is the one that belongs in
+    // the process that cannot afford to throw.
     //
     // IT IS INSIDE THE fs CALLBACK NOW, and that is where it has to be rather
     // than merely where it ended up. The reads are asynchronous (#1018), so the
@@ -1040,7 +1041,7 @@ function main() {
       // /private/tmp/proj) and then comes back empty after a restart. Silently —
       // replayLog does not count or warn about an out-of-scope line.
       //
-      // The Codex watcher already stores the canonical form (index.mjs:2203,
+      // The Codex watcher already stores the canonical form (codex-watch.mjs,
       // `cwd: await canonicalCwd(...)`, the same resolve+realpath this is), which
       // is why the two providers disagreed on one board. One spelling in the log
       // is the whole fix.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccdeck",
-  "version": "3.29.11",
+  "version": "3.31.0",
   "description": "Live dashboard for Claude Code and Codex — which agent is waiting on you, tool calls, token spend and every Claude Code subagent on one calm canvas. Run it with npx ccdeck.",
   "type": "module",
   "bin": {

package/release-notes.json

@@ -59,6 +59,46 @@
     "3.29.7",
     "3.29.9"
   ],
+  "3.31.0": [
+    {
+      "title": "📊 Account capacity",
+      "body": "A gauge button in the accounts panel's header opens Account capacity: how many of your Claude accounts are ready now, what the 5-hour and 7-day windows have left across all of them, and a row for each account with its use, its state (Ready, Limited, Exhausted or Stale) and when it was last read. Each window also says whose reset comes next."
+    },
+    {
+      "title": "🚦 Claude and Codex incidents",
+      "body": "When Anthropic's or OpenAI's status page reports an incident on something your sessions use, the deck says so in the topbar, the Usage panel and the tray, and every mark links to the status page. A provider with nothing wrong draws nothing."
+    },
+    {
+      "title": "↕️ Order your other accounts",
+      "body": "The Other accounts row can sort the list by slot, by how full a window is, or by most room, and open every account at once. Both stay as you left them after a reload."
+    },
+    {
+      "title": "🔐 A settings folder left by sudo can be given back",
+      "body": "On a Mac, running ccdeck once with sudo left its settings folder owned by another user, and every settings change was refused, sharing an account included. The message now offers \"give it back\": macOS asks for your password, the folder is yours again, and the deck reads its settings back without a restart."
+    }
+  ],
+  "3.30.0": [
+    {
+      "title": "🧮 Token counts and costs are no longer doubled",
+      "body": "Claude Code writes a reply that has thinking, text and tool calls as several transcript lines, each carrying the whole request's usage. The deck added up every line, so a session's tokens and cost on its card came out close to twice what it was billed, and the context panel counted each part of a reply as its own message. Each request is now counted once. Expect the totals on your cards to come down."
+    },
+    {
+      "title": "⏳ Claude's saved limit resets on the Usage panel",
+      "body": "When your Claude account has free limit resets to spend (\"Reset for free\" in Claude's Settings → Usage), the Claude card now says how many there are and when the first one expires, the way the Codex card already did. The deck only reports them; you spend them in Claude's own settings."
+    },
+    {
+      "title": "🔑 LAN invites need the other deck updated",
+      "body": "An invite's code is now a long random secret instead of six digits, so nobody else on the network can work it out and pair in your place, and a wrong code is refused by name. An invite made on this version can only be joined from a deck on this version or later: an older deck answers \"That is not an invite\". Update that deck, or make the invite on the older one and join it here."
+    },
+    {
+      "title": "🔕 AGENTS_DECK_NO_NOTIFY keeps Browser Watch quiet too",
+      "body": "A deck started with AGENTS_DECK_NO_NOTIFY=1 still raised a desktop notification for every new Browser Watch finding. It no longer does. The finding is still in the Browser Watch panel and its log, which says why no notification came."
+    },
+    {
+      "title": "🛠️ Smaller fixes",
+      "body": "Delete removes the card you just clicked. A LAN address you typed stays in the list when a round cannot reach it, and the status line under the LAN switch now agrees with the rows below it. In the desktop app, a dismissed \"update is ready\" notice stays dismissed after you answer the first-launch question. Sizes read the same in every panel (\"1.1 KB\"). Faded text stays readable, a keyboard can see the scrollbar, and numbers use a monospaced font on Windows and Linux as well."
+    }
+  ],
   "3.29.11": [
     {
       "title": "💲 Claude Sonnet 5.5 has a price",

package/src/server/account-projects.mjs

@@ -4,11 +4,11 @@
 // The account cards show account-wide rate-limit utilisation, which has no
 // project dimension and cannot be sliced. This is the other axis: for one
 // account, the tokens it spent per project, which the web side prices with the
-// board's own pricing table (pricing.ts). Cost is NOT computed here — the
-// server is plain .mjs with no build step and cannot import the .ts price
-// table, and keeping one source of prices beats a second copy that drifts. So
-// this file tallies TOKENS per (account, project, day, model) and the client
-// multiplies by the rates it already owns.
+// board's own rates (rate-table.ts, through pricing.ts's costForUsage). Cost is
+// NOT computed here — the server is plain .mjs with no build step and cannot
+// import the .ts rate table, and keeping one source of prices beats a second
+// copy that drifts. So this file tallies TOKENS per (account, project, day,
+// model) and the client multiplies by the rates it already owns.
 //
 // Attribution is per MESSAGE, not per session. A running session migrates to a
 // newly-activated account on its next message, so a whole session can span two
@@ -25,10 +25,14 @@ import { open, stat, readdir, readFile, writeFile, mkdir } from "node:fs/promise
 import { homedir } from "node:os";
 import { join, resolve, basename, dirname, relative } from "node:path";
 import { StringDecoder } from "node:string_decoder";
-import { renameWithRetry } from "./installer.mjs";
+import { renameWithRetry } from "./atomic-write.mjs";
 import { ccProjectSlug, claudeConfigDir } from "./claude-dir.mjs";
 import { accountKey } from "./lan-sync.mjs";
 import { readSwapLog, accountAtTime, trackedSince, seedActive, markGap } from "./swap-log.mjs";
+// The two rules the live transcript scan counts a line's usage by, so this
+// rollup and a session's card cannot disagree about which lines billed
+// anything — see transcript-scan.mjs.
+import { hasSpend, repeatsRequestUsage } from "./transcript-scan.mjs";
 
 /** The pseudo-account for messages the swap log cannot place — everything
  *  before tracking began, or a gap. Shown once, apart from any real account, so
@@ -80,6 +84,16 @@ export function countersFrom(usage) {
   };
 }
 
+/** The same counters under the names a usage block gives them, which is the
+ *  shape transcript-scan.mjs's hasSpend reads. */
+function asUsageTotals(c) {
+  return {
+    input_tokens: c.i, output_tokens: c.o,
+    cache_read_input_tokens: c.cr, cache_creation_input_tokens: c.cc,
+    ephemeral_1h_input_tokens: c.c1h, ephemeral_5m_input_tokens: c.c5m,
+  };
+}
+
 function addInto(dst, src) {
   dst.i += src.i; dst.o += src.o; dst.cr += src.cr;
   dst.cc += src.cc; dst.c1h += src.c1h; dst.c5m += src.c5m;
@@ -187,16 +201,16 @@ export function foldLine(tally, line, timeline, from) {
   if (!line || !line.includes('"usage"')) return;
   let obj = null;
   try { obj = JSON.parse(line); } catch { return; }
-  // Claude writes one assistant record for each content block in a request.
-  // Every block repeats the request's usage, so only block 0 is billable for
-  // this rollup. Older records without the field are kept compatible.
-  if (obj?.apiBlockIndex !== undefined && obj.apiBlockIndex !== 0) return;
+  // Claude writes one assistant record for each content block in a request,
+  // and every block repeats the request's usage, so only block 0 is billable
+  // — see repeatsRequestUsage.
+  if (repeatsRequestUsage(obj)) return;
   const usage = obj?.message?.usage;
   if (!usage || typeof usage !== "object") return;
   const ts = Date.parse(obj?.timestamp);
   if (!Number.isFinite(ts)) return;
   const c = countersFrom(usage);
-  if (!(c.i || c.o || c.cr || c.cc)) return;   // a usage block that billed nothing
+  if (!hasSpend(asUsageTotals(c))) return;   // a usage block that billed nothing
   const model = typeof obj?.message?.model === "string" ? obj.message.model : "";
   const lineCwd = (typeof obj?.cwd === "string" && obj.cwd) ? obj.cwd : "";
   const cwd = projectPath(folderOf(lineCwd, from));   // a worktree counts under the repo it checks out

package/src/server/account-routes.mjs

@@ -0,0 +1,254 @@
+// The HTTP face of the Claude accounts surface: the roster, the switch, sign-in
+// and the store's admin verbs, auto-switch, and the per-account Projects report.
+//
+// These lived in src/server/index.mjs, on either side of the self-update pin,
+// and they are the thinnest layer in the deck: each one reads a query or a
+// body, hands it to claude-accounts.mjs, cswap-admin.mjs, cswap-auto.mjs or the
+// project rollup, and answers with what came back. Every one of those modules
+// is still imported lazily and by the same package-root URL PINNED_MODULES
+// loads, so moving the routes here puts no import on the path to a listening
+// socket and takes none out of the pin.
+//
+// Four things are exported beyond the handlers. Three because index.mjs reaches
+// for them: wireStaleCopyRepair, which startServer runs to hand the roster its
+// stale-copy repair, cswapAutoModule, which it uses to start auto-switch, and
+// getProjectRollup, which it starts at boot. The fourth is CHECKS_IMPORTS,
+// which lan-deck.mjs reads because a LAN round checks the imports it lands the
+// same way the paste box does.
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { readBody, send } from "./http-io.mjs";
+
+// Resolved the way pinned-build.mjs resolves it, from a file in the same
+// directory, so every lazy import below is the URL the pin has already evaluated.
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+// Whether every import is followed by checkImports, which only asks on a Mac.
+// When it does, the import skips its own detached collection — see importAccount.
+export const CHECKS_IMPORTS = process.platform === "darwin";
+
+export async function handleClaudeAccounts(req, res) {
+  const { fetchClaudeAccounts } = await import(
+    pathToFileURL(join(PKG_ROOT, "src/server/claude-accounts.mjs")).href
+  );
+  const url = new URL(req.url, "http://localhost");
+  const force = url.searchParams.get("refresh") === "1";
+  send(res, 200, await fetchClaudeAccounts({ force }));
+}
+
+export async function handleClaudeAccountSwitch(req, res) {
+  const { switchClaudeAccount, invalidateClaudeAccountsCache } = await import(
+    pathToFileURL(join(PKG_ROOT, "src/server/claude-accounts.mjs")).href
+  );
+  const body = await readBody(req, res).catch(() => null);
+  let parsed = null;
+  try { parsed = JSON.parse(body ?? ""); } catch { /* handled below */ }
+  if (!parsed || typeof parsed !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
+
+  const result = await switchClaudeAccount(parsed.account);
+  // The active account just moved; the next poll should see it immediately
+  // rather than serving the pre-switch roster for another few seconds.
+  invalidateClaudeAccountsCache();
+  // The 5h/7d percentages moved with it — they are read for whichever account is
+  // active — and only this side knows: /api/quota is polled by the usage panel,
+  // which has no idea the accounts panel just switched and so never sends
+  // ?refresh=1. Without this the two panels sit on one screen disagreeing about
+  // the same account for a full poll cycle, and the stale one is the one the
+  // user just acted on. Only on a switch that took: a refused one left the
+  // account where it was, and throwing away a reading we paid for costs a real
+  // answer to fix nothing.
+  if (result.ok) {
+    const { invalidateQuotaCache } = await import(
+      pathToFileURL(join(PKG_ROOT, "src/server/quota.mjs")).href
+    );
+    invalidateQuotaCache();
+    // Note who became active, and when, for the account-projects report. Best
+    // effort — a failed log write must never fail the switch — so it is not
+    // awaited into the response.
+    import(pathToFileURL(join(PKG_ROOT, "src/server/swap-log.mjs")).href)
+      .then(({ recordSwap }) => recordSwap(parsed.account, "manual"))
+      .catch(() => {});
+  }
+  send(res, result.ok ? 200 : 400, result);
+}
+
+// The account-projects rollup, started once and shared. Its timer is unref'd
+// inside start(), so holding the instance here never keeps the process alive.
+let _projectRollup = null;
+export function getProjectRollup() {
+  if (!_projectRollup) {
+    _projectRollup = import(pathToFileURL(join(PKG_ROOT, "src/server/account-projects.mjs")).href)
+      .then(m => { const r = m.createProjectRollup(); r.start().catch(() => {}); return r; });
+  }
+  return _projectRollup;
+}
+
+/**
+ * The "Projects" report for one account: how many tokens it spent per project
+ * over a window. The server tallies only tokens (per model); the web side
+ * prices them with its own table, so cost never lives in two places. `num` is
+ * the account's slot, resolved to its `(email, org)` key here; `days` is 1, 7,
+ * 30, or 0 for all tracked.
+ */
+export async function handleAccountProjects(req, res) {
+  const url = new URL(req.url, "http://localhost");
+  const num = Number(url.searchParams.get("num"));
+  const d = Number(url.searchParams.get("days"));
+  const days = d === 1 ? 1 : d === 30 ? 30 : d === 0 ? 0 : 7;
+  if (!Number.isInteger(num) || num <= 0) return send(res, 400, { ok: false, reason: "bad_account" });
+  const { identityForSlot } = await import(pathToFileURL(join(PKG_ROOT, "src/server/swap-log.mjs")).href);
+  const id = await identityForSlot(num);
+  if (!id) return send(res, 400, { ok: false, reason: "bad_account" });
+  const { accountKey } = await import(pathToFileURL(join(PKG_ROOT, "src/server/lan-sync.mjs")).href);
+  const rollup = await getProjectRollup();
+  const report = await rollup.report(accountKey(id.email, id.orgUuid), days);
+  send(res, 200, { ok: true, ...report });
+}
+
+function cswapAdminModule() {
+  return import(pathToFileURL(join(PKG_ROOT, "src/server/cswap-admin.mjs")).href);
+}
+
+/**
+ * Hand cswap-admin's autoRecapture to the roster read, so a `stale-copy` row
+ * carries its own repair rather than a button — see repairStaleCopyWith.
+ *
+ * startServer calls this once per boot on a deck that watches Claude Code, and
+ * does not wait for it. It lived in startServer itself and moved here, beside
+ * cswapAdminModule and the package root it imports the pair by; the body is
+ * unchanged.
+ */
+export function wireStaleCopyRepair() {
+  // THIS WIRING IS WHERE AN IMPORT CYCLE SHOWED UP AS A SILENT NO-OP, and it
+  // is the cycle that has been fixed rather than this line — see
+  // claude-identity.mjs.
+  //
+  // claude-accounts.mjs used to take `currentIdentity` from cswap-admin.mjs
+  // while cswap-admin.mjs took `backupRoot`, `invalidateClaudeAccountsCache`
+  // and `verdictNow` back, which was the only static import cycle in
+  // src/server. Two dynamic imports entering a cycle concurrently are each
+  // handed the other module's HALF-BUILT namespace rather than waiting for
+  // it, and a half-built namespace has no exports on it at all: measured on
+  // CI, both came back with zero keys, so `accounts.repairStaleCopyWith` was
+  // a TypeError in a promise nothing awaits. The repair was never wired and
+  // nothing said so — every test passed, and the run exited 1 on an unhandled
+  // rejection alone.
+  //
+  // Several importers reach this pair within a few ticks at boot —
+  // startServer's `cswapAutoModule()` imports claude-accounts.mjs too, and
+  // `startServer` can be called again before this has settled — so it was a
+  // timing defect that any change to those import lists could trip, and
+  // sequencing one call site was never going to be enough.
+  //
+  // Asked for one at a time anyway, which is now belt as well as braces: with
+  // no cycle left, a concurrent pair would simply wait for each other.
+  // boot-module-graph.test.ts asserts the braces — that src/server has no
+  // import cycles at all — rather than trying to police call sites.
+  void (async () => {
+    let accounts, admin;
+    // An import that genuinely fails stays tolerated, exactly as the
+    // `() => {}` this replaced tolerated it: the wiring is best-effort. A
+    // namespace that arrives WITHOUT the function is a different thing and
+    // must stay loud, because that is the failure described above.
+    try {
+      accounts = await import(pathToFileURL(join(PKG_ROOT, "src/server/claude-accounts.mjs")).href);
+      admin = await cswapAdminModule();
+    } catch { return; }
+    accounts.repairStaleCopyWith(admin.autoRecapture);
+  })();
+}
+
+// Reading the login's progress. The browser polls this while its dialog is
+// open, the same way the upgrade notice polls /api/version.
+export async function handleAccountLoginState(_req, res) {
+  const { loginState } = await cswapAdminModule();
+  send(res, 200, { ok: true, ...loginState() });
+}
+
+/**
+ * Everything that changes the account store, behind one verb switch — the shape
+ * handleCswapAutoAction already uses.
+ *
+ * The sign-in code is the one field here that is a credential. It is read out
+ * of the body, handed straight to the child's stdin, and never logged, echoed
+ * back, or written anywhere — which is also why this is a POST body and not a
+ * query parameter.
+ */
+export async function handleClaudeAccountAdmin(req, res) {
+  const admin = await cswapAdminModule();
+  const body = await readBody(req, res).catch(() => null);
+  let parsed = null;
+  try { parsed = JSON.parse(body ?? ""); } catch { /* handled below */ }
+  if (!parsed || typeof parsed !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
+
+  let result;
+  switch (parsed.action) {
+    case "login":        result = await admin.startLogin({ email: parsed.email }); break;
+    case "login-code":   result = await admin.submitLoginCode(parsed.code); break;
+    case "login-cancel": result = await admin.cancelLogin(); break;
+    // `accounts` is a chosen set, `account` the single row's own button. Both
+    // go to shareAccounts, which treats one account as a bundle of one so the
+    // two entry points cannot drift into two envelope shapes.
+    case "share":        result = await admin.shareAccounts(parsed.accounts ?? parsed.account); break;
+    // `only` names one account inside the pasted bundle, and is the only way
+    // `force` is honoured at all - see importAccount for why the pair is
+    // required rather than the flag alone.
+    case "import": {
+      const out = await admin.importAccount(parsed.blob, {
+        force: parsed.force === true,
+        only: parsed.only ?? null,
+        collect: !CHECKS_IMPORTS,
+      });
+      // Checked the way a LAN round's arrivals are (#1244): `cswap import`
+      // exiting 0 on a Mac is not proof this process can read what it wrote.
+      result = out?.ok ? { ...out, results: await admin.checkImportResults(out.results) } : out;
+      break;
+    }
+    case "remove":       result = await admin.removeAccount(parsed.account); break;
+    // #721. Re-captures the active slot's credentials in place; see
+    // recaptureActive for why this is not a login and cannot become one.
+    case "recapture":    result = await admin.recaptureActive(); break;
+    case "alias":        result = await admin.setAlias(parsed.account, parsed.alias); break;
+    case "move":         result = await admin.moveAccount(parsed.account, parsed.slot); break;
+    default: return send(res, 400, { ok: false, reason: "unknown_action" });
+  }
+  send(res, result.ok ? 200 : 400, result);
+}
+
+export function cswapAutoModule() {
+  return import(pathToFileURL(join(PKG_ROOT, "src/server/cswap-auto.mjs")).href);
+}
+
+export async function handleCswapAuto(req, res) {
+  const { autoStatus } = await cswapAutoModule();
+  send(res, 200, await autoStatus());
+}
+
+/**
+ * One POST for every auto-switch control, keyed by `action`. Each one can move
+ * the user's live Claude account or change when it moves, so nothing here is
+ * reachable by GET.
+ */
+export async function handleCswapAutoAction(req, res) {
+  const mod = await cswapAutoModule();
+  const body = await readBody(req, res).catch(() => null);
+  let parsed = null;
+  try { parsed = JSON.parse(body ?? ""); } catch { /* handled below */ }
+  if (!parsed || typeof parsed !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
+
+  let result;
+  switch (parsed.action) {
+    case "enable":
+      result = await mod.setAutoEnabled(parsed.enabled === true);
+      break;
+    case "setting":
+      result = await mod.setCswapConfig(String(parsed.key ?? ""), parsed.value);
+      break;
+    case "account":
+      result = await mod.setAccountEnabled(parsed.account, parsed.enabled === true);
+      break;
+    default:
+      return send(res, 400, { ok: false, reason: "unknown_action" });
+  }
+  send(res, result.ok ? 200 : 400, result);
+}

package/src/server/activity.mjs

@@ -23,9 +23,9 @@ const CLOSES = new Set(["Stop", "SessionEnd"]);
 
 /** More turns open at once than any machine runs — the same figure as the
  *  deck's own working limit for the sessions it tracks (MAX_TRACKED_SESSIONS in
- *  index.mjs). A bound because the ids arrive from outside: this is fed from
- *  pushEvent for every live event, and `/api/event` takes them without a
- *  credential. presence.mjs caps its map of tab ids for the same reason.
+ *  session-tracking.mjs). A bound because the ids arrive from outside: this is
+ *  fed from pushEvent for every live event, and `/api/event` takes them without
+ *  a credential. presence.mjs caps its map of tab ids for the same reason.
  *
  *  Past it the turn heard from least recently goes, and that costs `busy` no
  *  accuracy at all: the map is kept in the order turns were last heard from

package/src/server/append-budget.mjs

@@ -0,0 +1,185 @@
+// What the events log's append queue is allowed to weigh (#1030): the ceiling
+// on lines accepted and not yet written, the charge each line carries until
+// its write settles, and what the queue refused at the door because of it.
+//
+// Moved out of log-writer.mjs unchanged. appendLogLine asks queueIsFull at the
+// door, then either counts a refusal (noteRefused) or takes the line's charge
+// (takeCharge) and gives it back once the write has landed or failed
+// (releaseCharge). log-writer.mjs re-exports MAX_PENDING_APPEND_CHARS and
+// appendQueueStats, which is where the suite reaches them.
+import { PRODUCT } from "./brand.mjs";
+
+// ─── What the queue is allowed to weigh ───────────────────────────────────
+//
+// The chain in log-writer.mjs ORDERS appends. Nothing bounded them. Every line
+// handed over is retained by the closure that will eventually write it, and
+// the only brake on how many of those exist at once is how fast write(2)
+// returns — while pushEvent hands them over fire-and-forget and answers
+// `{ok:true, seq}` on the next statement, so `POST /api/event` admits lines as
+// fast as a socket can deliver them.
+//
+// MEASURED (Linux 7.0 / Node 24.21 / ext4 on NVMe), eight sockets posting 1 MB
+// `tool_response` bodies to a sandboxed deck for four seconds, sampled twice a
+// second:
+//
+//   t=1.0s  log_MB=19    rss_MB=881
+//   t=2.5s  log_MB=51    rss_MB=1741
+//   t=4.1s  log_MB=85    rss_MB=2260   <- ingest stops; 1540 MB acknowledged
+//   t=5.5s  log_MB=1135  rss_MB=935
+//   t=6.0s  log_MB=1540  rss_MB=546    <- queue finally drained
+//
+// 85 MB on disk against 1540 MB the deck had said it had: 1455 MB of serialized
+// lines held in the heap, and an RSS peak of 2260 MB — 17x MAX_BUFFER_CHARS,
+// the budget the ring beside this keeps exactly. The disk is not the amplifier;
+// the event loop is. Ingest and the writer share it, so the log grew at 21 MB/s
+// while the posting continued and at 800 MB/s the instant it stopped.
+//
+// The same burst under `--max-old-space-size=1024`:
+//
+//   FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
+//   [deck exited code=null sig=SIGABRT]   3.2s in, 50 MB written
+//
+// That abort is not catchable, so the SSE stream, the hook ingest and the log
+// stop together — and `/api/event` is a deliberate OPEN_MUTATION, so this is a
+// few hundred unauthenticated posts from any local process ending the deck.
+// It is the failure MAX_BUFFER_CHARS was added to close (#625), reached through
+// the door beside the one it guards (#1030).
+//
+// Who gets there without trying: `--history` accepts any path. The 40 events/s
+// of 1 MB that is trivial on NVMe is roughly 30 MB/s of pure accumulation on a
+// 5-10 MB/s network mount or a slow external drive, where the queue's only
+// brake is that much slower than the traffic filling it.
+
+/**
+ * The ceiling on pending append bytes, and the ring's sibling on purpose.
+ *
+ * 128 MiB, the same number and the same three readings that pick
+ * MAX_BUFFER_CHARS in ring-bounds.mjs:
+ *
+ *   - It is 26 times the largest single line ingest can produce (5,000,000
+ *     characters plus the deck's envelope), so a burst of maximum-size tool
+ *     responses — eight subagents each returning a big Read — is queued whole
+ *     rather than shed.
+ *   - It is thirteen times a completely full 2000-event ring of ordinary
+ *     traffic. The mean serialized event is about 5 KB, so the ~26,000 lines
+ *     this holds are far more than any honest burst produces: ordinary traffic
+ *     never meets this bound at all.
+ *   - Its worst case is a bounded fraction of the heap, and a bounded ADDITION
+ *     to the ring's. 128 MiB of charged characters is at most 256 MiB retained
+ *     — a two-byte string costs twice what it is charged, the same 2x
+ *     MAX_CLIENT_BUFFER_BYTES' note describes — so the ring's 320 MiB and this
+ *     together are about 576 MiB of the 2 GB heap an 8 GB laptop picks, against
+ *     the 2260 MB one four-second burst reached with no bound here at all.
+ *
+ * CHARGED IN CHARACTERS, not in UTF-8 bytes, and the unit is deliberate. These
+ * lines are already serialized, so `line.length` is the size of the thing being
+ * retained and costs nothing to read; `Buffer.byteLength` would be a second
+ * full scan of a five-megabyte string on the hottest path in the process for a
+ * number that is FURTHER from the retained heap, not closer — JSON.stringify
+ * leaves non-ASCII unescaped, so a CJK line is two bytes of heap per character
+ * and three bytes of UTF-8.
+ *
+ * Deliberately NOT summed into MAX_BUFFER_CHARS, which #1030 raises as an
+ * option. The two hold different things — the ring holds parsed payloads
+ * charged by payloadChars' walk, this holds their serialization — so one
+ * counter would be adding two units; and eviction cannot free a queued line
+ * anyway, so a shared budget would answer a slow disk by collapsing the replay
+ * depth of the ring, which is the one part of this that was never broken.
+ */
+export const MAX_PENDING_APPEND_CHARS = 128 * 1024 * 1024;
+
+// What has been accepted and not yet written, what has been refused because of
+// it, and whether we are inside an episode of refusing. These move with the
+// chain in appendLogLine and nowhere else, through takeCharge, noteRefused and
+// releaseCharge below — the same rule `bufferedChars` and `events` keep in
+// event-ring.mjs, and for the same reason: a total that names lines the queue
+// no longer holds is a permanent debt against the budget.
+let pendingLines = 0;
+let pendingChars = 0;
+let droppedLines = 0;
+let droppedChars = 0;
+let dropEpisodes = 0;
+// Reset at the start of each episode, so the line printed when the queue
+// drains describes THAT burst rather than the life of the process.
+let episodeLines = 0;
+let episodeChars = 0;
+let shedding = false;
+
+/**
+ * What the append queue holds right now, and what it has refused.
+ *
+ * Exported for exactly the reason eventBufferStats and MAX_BUFFER_CHARS are —
+ * "a bound whose only observable failure is the process running out of memory
+ * is a bound no test can assert". With this, the bound is observable without
+ * watching a process die, and so is the loss it trades for.
+ *
+ * `droppedLines` / `droppedChars` are cumulative for the life of the process.
+ * They count lines that were never ATTEMPTED; an append that was attempted and
+ * failed is a different number, which #991 is open about and which belongs
+ * beside these rather than tangled into them.
+ */
+export function appendQueueStats() {
+  return { pendingLines, pendingChars, droppedLines, droppedChars, dropEpisodes };
+}
+
+const mb = chars => `${(chars / 1024 / 1024).toFixed(0)}MB`;
+
+/**
+ * Would a line of `charged` characters be refused at the door right now?
+ *
+ * The queue always accepts a line when it is EMPTY, whatever that line
+ * weighs. Ingest admits 5,000,000 characters and a Codex rollout line read
+ * off disk has no length bound at all, so refusing an oversized line outright
+ * would mean a deck that silently never records its largest events — and the
+ * ring one file over makes the same exception for the same reason ("a single
+ * event is allowed to be larger than the entire budget"). So the true ceiling
+ * is MAX_PENDING_APPEND_CHARS plus one line, stated here rather than
+ * pretended away.
+ */
+export function queueIsFull(charged) {
+  return pendingLines > 0 && pendingChars + charged > MAX_PENDING_APPEND_CHARS;
+}
+
+/** One line accepted: charge it until releaseCharge gives the charge back. */
+export function takeCharge(charged) {
+  pendingLines++;
+  pendingChars += charged;
+}
+
+/** One line refused at the door: count it, and open an episode if this is the
+ *  first refusal since the queue last drained. */
+export function noteRefused(filePath, charged) {
+  droppedLines++;
+  droppedChars += charged;
+  episodeLines++;
+  episodeChars += charged;
+  if (!shedding) {
+    shedding = true;
+    dropEpisodes++;
+    // One line, at the start of the episode. Per refusal it would be
+    // thousands of lines onto the terminal the deck paints over, which is its
+    // own version of the problem being fixed.
+    console.error(`${PRODUCT}: the log append queue is full (${mb(pendingChars)} waiting for ${filePath}) — dropping events until it drains`);
+  }
+}
+
+/**
+ * One line has left the queue. Give its charge back, and close the episode if
+ * that was the last of them.
+ *
+ * The episode ends when the queue is EMPTY rather than the moment it dips back
+ * under the bound, because it dips under the bound once per completed write:
+ * keyed on the bound this would print a pair of lines per event for the length
+ * of the burst. Empty is also the honest boundary for the number being
+ * reported — while anything is still queued the next line can still be refused,
+ * and the total would have to be retracted.
+ */
+export function releaseCharge(charged) {
+  pendingLines--;
+  pendingChars -= charged;
+  if (pendingLines > 0 || !shedding) return;
+  console.error(`${PRODUCT}: the log append queue drained — ${episodeLines} event(s) (${mb(episodeChars)}) were dropped and are not in the log`);
+  shedding = false;
+  episodeLines = 0;
+  episodeChars = 0;
+}