ccdeck 3.29.10 → 3.30.0

package/dist/web/index.html

@@ -62,8 +62,8 @@
           stored === "light" || (stored !== "dark" && light) ? "light" : "dark");
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-C1YFI9f4.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-Ck2RAla3.css">
+    <script type="module" crossorigin src="/assets/index-BVTWHDta.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-3vS6A0vt.css">
   </head>
   <body>
     <div id="root"></div>

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.10",
+  "version": "3.30.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,34 @@
     "3.29.7",
     "3.29.9"
   ],
+  "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",
+      "body": "Sessions on Claude Sonnet 5.5 showed \"not priced\" on the board, and the Projects report could only show a minimum for them. They are now priced at Anthropic's published rate, the same as Sonnet 5: $2 per million input tokens and $10 per million output tokens."
+    }
+  ],
   "3.29.10": [
     {
       "title": "💲 Claude Opus 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;
+}