trantor 0.17.31 → 0.17.39

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.31",
+  "version": "0.17.39",
   "description": "Trantor — the hub-world for AI agent crews: live message bus, presence, project Kanban/flow board + crew orchestration for independent AI coding agents (Claude, Codex, Gemini, Kimi, DeepSeek)",
   "mcpServers": {
     "relay": {

package/bin/balances.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// trantor balances — show how much credit is left on each prepaid provider (DeepSeek, Kimi, OpenRouter…)
+// so you can refill BEFORE a build stalls. Reads keys from the environment, queries each provider's
+// balance API, prints them, and pushes the snapshot to the hub so the dashboard + other sessions see it.
+//
+// Usage: trantor balances [--json] [--no-push]
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { fetchBalances, isLow, fmtBalance, DEFAULT_LOW, DEFAULT_LOW_QUOTA_PCT } from "../lib/balances.mjs";
+import { loadProfile } from "./profile.mjs";
+import { resolveKeys } from "../lib/provider-keys.mjs";
+
+const args = process.argv.slice(2);
+const asJson = args.includes("--json");
+const noPush = args.includes("--no-push");
+
+// Only check providers the user configured in `trantor profile` — never stray keys in the ambient env.
+const configured = Object.keys(loadProfile().providers || {});
+
+function relayUrl() {
+  if (process.env.RELAY_URL) return process.env.RELAY_URL;
+  try { const c = join(homedir(), ".agent-bus", "config.json"); if (existsSync(c)) { const u = JSON.parse(readFileSync(c, "utf8")).url; if (u) return u; } } catch {}
+  return "http://127.0.0.1:4477";
+}
+let _qpct = DEFAULT_LOW_QUOTA_PCT;
+function thresholds() {
+  try { const c = JSON.parse(readFileSync(join(homedir(), ".agent-bus", "config.json"), "utf8")); if (typeof c.lowQuotaPct === "number") _qpct = c.lowQuotaPct; if (c.lowBalance && typeof c.lowBalance === "object") return { ...DEFAULT_LOW, ...c.lowBalance }; } catch {}
+  return DEFAULT_LOW;
+}
+
+const balances = await fetchBalances(resolveKeys(process.env), { only: configured });
+const low = thresholds();
+
+// push the snapshot to the hub (best-effort) so the dashboard + warning line can use it
+if (!noPush) {
+  try {
+    await fetch(`${relayUrl()}/balances`, { method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ balances, ts: Date.now() }), signal: AbortSignal.timeout(2500) });
+  } catch {}
+}
+
+if (asJson) { console.log(JSON.stringify({ balances, low: balances.filter((b) => isLow(b, low, _qpct)).map((b) => b.provider) }, null, 2)); process.exit(0); }
+
+if (!balances.length) {
+  if (!configured.length) {
+    console.log("no quota profile set — Trantor doesn't know which providers you use.");
+    console.log("declare them:  trantor profile set claude=max kimi=coding-plan deepseek=api zai=coding-plan");
+  } else {
+    console.log(`configured providers: ${configured.join(", ")} — but none expose a balance/quota API with a key present.`);
+    console.log("(subscriptions like claude/codex/gemini have nothing to refill; prepaid/coding-plan providers need their key in the env.)");
+  }
+  process.exit(0);
+}
+console.log("PROVIDER CREDITS\n");
+for (const b of balances) {
+  const hasNum = b.ok && (b.remaining != null || b.remainingPct != null);
+  const flag = isLow(b, low, _qpct) ? "  🔴 REFILL SOON" : (hasNum ? "  🟢" : "");
+  console.log("  " + fmtBalance(b) + flag);
+}
+const lows = balances.filter((b) => isLow(b, low, _qpct));
+if (lows.length) console.log(`\n⚠ ${lows.length} provider(s) low — top up / pace: ${lows.map((b) => b.label).join(", ")}`);

package/bin/cli.mjs

@@ -27,7 +27,11 @@ switch (cmd) {
   case "watch":   run("bin/relay-watch.mjs"); break;
   case "catchup": run("bin/catchup.mjs"); break;
   case "agents":  run("bin/agents.mjs"); break;
+  case "gates":   run("bin/gates.mjs"); break;
   case "backfill": run("bin/git-backfill.mjs"); break;
+  case "init-hooks": run("bin/init-hooks.mjs"); break;
+  case "balances": case "balance": case "credits": run("bin/balances.mjs"); break;
+  case "recost": run("bin/recost.mjs"); break;
   case "handoff": run("bin/baton.mjs"); break;
   case "ui": {
     let url = "http://127.0.0.1:4477";
@@ -50,7 +54,11 @@ switch (cmd) {
   trantor ui          open the live dashboard (board + flow views)
   trantor catchup     "where are we?" — the continuous board + git, with a synthesized brief
   trantor agents      what this session's sub-agents did (task · returned? · files written · survived on disk) — [<sessionId>] [--json]
+  trantor gates       verification gates: "must verify before shipping" claims that survive handoffs — [--all] [--json]
   trantor backfill    card past GIT work onto the board (solo commits that were never carded) — [--since "14 days ago"] [--dry-run]
+  trantor init-hooks  install a git post-commit hook so EVERY commit auto-cards on the board (reliable solo-work backstop) — [--uninstall]
+  trantor balances    how much credit is left on each CONFIGURED provider (from your profile) — refill before you stall — [--json]
+  trantor recost      recompute sub-agent notional cost from on-disk transcripts + reseed the board (repair after upgrade) — [--dry-run]
   trantor handoff     finish this session NOW: write a handoff, open a fresh session that takes over, and close this one (manual baton)
   trantor advise      ask the Advisor directly (JSON on stdin; --demo to see it)
   trantor hub         run the hub in the foreground (setup installs it as a service instead)

package/bin/gates.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// trantor gates [--all] [--json] — verification gates for THIS project: structured "must verify
+// before shipping" claims that survive handoffs and surface to whoever takes over. Open by default;
+// --all includes resolved ones. Set/resolve gates from inside a session via the relay_verify_gate tool.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { resolveProject } from "../lib/project.mjs";
+
+const args = process.argv.slice(2);
+const all = args.includes("--all");
+const asJson = args.includes("--json");
+
+function relayUrl() {
+  if (process.env.RELAY_URL) return process.env.RELAY_URL;
+  try { const u = JSON.parse(readFileSync(join(homedir(), ".agent-bus", "config.json"), "utf8")).url; if (u) return u; } catch {}
+  return "http://127.0.0.1:4477";
+}
+
+const project = resolveProject(process.cwd());
+const url = `${relayUrl()}/verify-gates?project=${encodeURIComponent(project)}${all ? "&all=1" : ""}`;
+let gates = [];
+try {
+  const r = await fetch(url, { signal: AbortSignal.timeout(2500) });
+  gates = (await r.json()).gates || [];
+} catch {
+  console.error(`could not reach the hub at ${relayUrl()} — is it running? (trantor setup / trantor hub)`);
+  process.exit(1);
+}
+
+if (asJson) { process.stdout.write(JSON.stringify(gates, null, 2) + "\n"); process.exit(0); }
+if (!gates.length) { console.log(`${project}: no ${all ? "" : "open "}verification gates`); process.exit(0); }
+
+console.log(`${project} — ${gates.length} ${all ? "" : "open "}verification gate(s):`);
+for (const g of gates) {
+  const badge = g.status === "open" ? "⚠️ OPEN" : `✓ ${g.status}`;
+  console.log(`\n#${g.id}  ${badge}  ${g.claim}`);
+  if (g.why) console.log(`    why: ${g.why}`);
+  if (g.howToVerify) console.log(`    how: ${g.howToVerify}`);
+  if (g.status !== "open" && g.resolvedNote) console.log(`    resolved: ${g.resolvedNote}`);
+}

package/bin/git-backfill.mjs

@@ -27,6 +27,7 @@ const me = `${hostId()}:${project}`;
 
 const themeOf = (s) => {
   let m;
+  if ((m = s.match(/\bv?(\d+\.\d+\.\d+)\b/i))) return "v" + m[1];             // any "v0.17.33" anywhere (feat: v0.17.33 — …) → one card per release
   if ((m = s.match(/^release:\s*v?(\d+\.\d+\.\d+)/i))) return "v" + m[1];     // release: v0.17.15 → v0.17.15 (one card per version)
   if ((m = s.match(/^[a-z]+\(([^)]+)\)\s*:/i))) return m[1].trim();           // feat(engine): → engine
   if ((m = s.match(/^([A-Za-z][\w &+/.]*?)\s*:/))) return m[1].trim();        // "Landing: …" → Landing

package/bin/init-hooks.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// trantor init-hooks — install a git post-commit hook in the current repo so EVERY commit is
+// auto-carded onto the board. This is the reliable backstop for solo work: a session that doesn't
+// fire a crew and doesn't keep a live TodoWrite leaves no work-card otherwise (only presence). The
+// hook calls `trantor backfill` (idempotent, theme-grouped) in the background — never slows a commit.
+//
+// Usage: trantor init-hooks [--since "5 minutes ago"] [--uninstall]
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const args = process.argv.slice(2);
+const arg = (n, d) => { const i = args.indexOf("--" + n); return i >= 0 ? args[i + 1] : d; };
+const since = arg("since", "5 minutes ago");
+const uninstall = args.includes("--uninstall");
+
+const MARK_START = "# >>> trantor auto-card (post-commit) >>>";
+const MARK_END = "# <<< trantor auto-card (post-commit) <<<";
+
+let gitDir;
+try { gitDir = execSync("git rev-parse --git-dir", { encoding: "utf8", cwd: process.cwd() }).trim(); }
+catch { console.error("not a git repository (run this inside a repo)"); process.exit(1); }
+
+const hooksDir = join(gitDir, "hooks");
+const hookPath = join(hooksDir, "post-commit");
+if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
+
+// the trantor block — fail-silent, non-blocking, PATH-robust
+const block = [
+  MARK_START,
+  "# Card this commit onto the trantor board. Non-blocking + fail-silent: never slows/breaks a commit.",
+  'TRANTOR_BIN="$(command -v trantor 2>/dev/null)"',
+  '[ -z "$TRANTOR_BIN" ] && [ -x /opt/homebrew/bin/trantor ] && TRANTOR_BIN=/opt/homebrew/bin/trantor',
+  '[ -z "$TRANTOR_BIN" ] && [ -x /usr/local/bin/trantor ] && TRANTOR_BIN=/usr/local/bin/trantor',
+  `[ -n "$TRANTOR_BIN" ] && ( "$TRANTOR_BIN" backfill --since ${JSON.stringify(since)} >/dev/null 2>&1 & )`,
+  MARK_END,
+].join("\n");
+
+let existing = existsSync(hookPath) ? readFileSync(hookPath, "utf8") : "";
+
+// strip any prior trantor block (idempotent install / clean uninstall)
+const stripped = existing.replace(new RegExp(`\\n?${escapeRe(MARK_START)}[\\s\\S]*?${escapeRe(MARK_END)}\\n?`, "g"), "\n").replace(/\n{3,}/g, "\n\n");
+
+if (uninstall) {
+  if (!existing.includes(MARK_START)) { console.log("no trantor post-commit hook installed — nothing to remove"); process.exit(0); }
+  const out = stripped.trim();
+  if (out && out !== "#!/bin/sh") { writeFileSync(hookPath, out.endsWith("\n") ? out : out + "\n"); }
+  else { writeFileSync(hookPath, "#!/bin/sh\n"); }
+  console.log(`✓ removed trantor auto-card from ${hookPath}`);
+  process.exit(0);
+}
+
+let out;
+if (!stripped.trim()) {
+  out = `#!/bin/sh\n${block}\n`;
+} else {
+  const base = stripped.trim().startsWith("#!") ? stripped.trimEnd() : `#!/bin/sh\n${stripped.trimEnd()}`;
+  out = `${base}\n\n${block}\n`;
+}
+writeFileSync(hookPath, out);
+chmodSync(hookPath, 0o755);
+console.log(`✓ installed trantor auto-card → ${hookPath}`);
+console.log(`  every commit now cards itself on the board (backfill --since ${JSON.stringify(since)}, idempotent).`);
+console.log(`  remove with: trantor init-hooks --uninstall`);
+
+function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }

package/bin/profile.mjs

@@ -37,7 +37,7 @@ const [, , cmd, ...args] = process.argv;
 // text, but import.meta.url is percent-encoded — so any URL-reserved char in the install path (most
 // commonly a SPACE, e.g. ".../Application Support/...") made this false and silently skipped main (exit 0,
 // no write). pathToFileURL is the canonical Node idiom. See regression in test-handoff.mjs / test.mjs.
-if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const prof = loadProfile();
   prof.providers ||= {};
   if (cmd === "set") {

package/bin/recost.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// trantor recost — recompute Claude Code sub-agent NOTIONAL cost from on-disk transcripts and reseed the
+// board, replacing stale/contaminated cc-subagent cards (e.g. after the v0.17.37 transcript-resolution
+// fix). Honest by construction: only transcripts still on disk are counted, and mis-resolved/implausible
+// ones are guarded out. Run it once after upgrading; new sub-agents accrue correctly via the fixed hook.
+//
+// Usage: trantor recost [--dry-run] [--json]
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { scanSubagentCosts } from "../lib/subagent-scan.mjs";
+
+function relayUrl() {
+  if (process.env.RELAY_URL) return process.env.RELAY_URL;
+  try { const c = join(homedir(), ".agent-bus", "config.json"); if (existsSync(c)) { const u = JSON.parse(readFileSync(c, "utf8")).url; if (u) return u; } } catch {}
+  return "http://127.0.0.1:4477";
+}
+
+const dry = process.argv.includes("--dry-run");
+const asJson = process.argv.includes("--json");
+const byProject = scanSubagentCosts();
+
+// flatten to one entry list (each tagged with its raw project) — the hub canon-merges alias lanes
+const allEntries = [];
+for (const [project, entries] of byProject) for (const e of entries) allEntries.push({ ...e, project });
+const scanTotal = allEntries.reduce((s, e) => s + (e.costUsd || 0), 0);
+
+if (dry) {
+  const rows = [...byProject.entries()].map(([project, entries]) => ({ project, cards: entries.length, invocations: entries.reduce((s, e) => s + e.count, 0), usd: +entries.reduce((s, e) => s + (e.costUsd || 0), 0).toFixed(2) })).sort((a, b) => b.usd - a.usd);
+  if (asJson) { console.log(JSON.stringify({ dry: true, scanTotal: +scanTotal.toFixed(2), byScannedProject: rows }, null, 2)); process.exit(0); }
+  console.log("[dry-run] Sub-agent notional recomputed from on-disk transcripts (pre-canonicalization):\n");
+  for (const r of rows) console.log(`  ${r.project.padEnd(24)} ${String(r.cards).padStart(3)} cards · ${String(r.invocations).padStart(4)} inv · $${r.usd.toFixed(2)}`);
+  console.log(`\n[dry-run] scanned total $${scanTotal.toFixed(2)} (drop --dry-run to reseed; only on-board project lanes are kept)`);
+  process.exit(0);
+}
+
+let result;
+try {
+  result = await fetch(`${relayUrl()}/subagent-recost`, { method: "POST", headers: { "content-type": "application/json" },
+    body: JSON.stringify({ entries: allEntries }), signal: AbortSignal.timeout(15000) }).then(x => x.json());
+} catch (e) { console.error(`recost failed: ${e.message}`); process.exit(1); }
+
+const projs = (result?.projects || []);
+const seeded = projs.filter(p => !p.skipped);
+const skipped = projs.filter(p => p.skipped);
+const seededUsd = seeded.reduce((s, p) => s + (p.usd || 0), 0);
+
+if (asJson) { console.log(JSON.stringify(result, null, 2)); process.exit(0); }
+console.log("Sub-agent notional reseeded from on-disk transcripts (canonical project lanes):\n");
+for (const p of seeded.sort((a, b) => (b.usd || 0) - (a.usd || 0))) console.log(`  ${p.project.padEnd(24)} ${String(p.added).padStart(3)} cards · $${(p.usd || 0).toFixed(2)}  ✓`);
+console.log(`\nSEEDED: $${seededUsd.toFixed(2)} notional · ${result.added} cards across ${seeded.length} project lanes → on the board`);
+if (skipped.length) console.log(`skipped ${skipped.length} non-board context(s) (worktrees / non-project dirs) — not real Trantor lanes.`);

package/hooks/lib/balance-check.mjs

@@ -0,0 +1,52 @@
+// trantor SessionStart balance check — the session env HAS the provider keys (the hub, under launchd,
+// does not), so this is where we fetch prepaid credit, push a snapshot to the hub (for the dashboard),
+// and surface a low-balance warning line. Throttled behind a 3h TTL stamp: most starts do ZERO network.
+// Hard-capped at 4s so it can never noticeably slow a session start. Fail-silent by contract.
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { fetchBalances, isLow, fmtBalance, DEFAULT_LOW, DEFAULT_LOW_QUOTA_PCT } from "../../lib/balances.mjs";
+import { loadProfile } from "../../bin/profile.mjs";
+import { resolveKeys } from "../../lib/provider-keys.mjs";
+
+const STAMP = join(homedir(), ".agent-bus", "balances-check.json");
+const TTL_MS = 3 * 3600 * 1000;
+const CAP_MS = 4000;
+
+function relayUrl() {
+  if (process.env.RELAY_URL) return process.env.RELAY_URL;
+  try { const u = JSON.parse(readFileSync(join(homedir(), ".agent-bus", "config.json"), "utf8")).url; if (u) return u; } catch {}
+  return "http://127.0.0.1:4477";
+}
+function thresholds() {
+  let t = DEFAULT_LOW, q = DEFAULT_LOW_QUOTA_PCT;
+  try { const c = JSON.parse(readFileSync(join(homedir(), ".agent-bus", "config.json"), "utf8")); if (c.lowBalance) t = { ...DEFAULT_LOW, ...c.lowBalance }; if (typeof c.lowQuotaPct === "number") q = c.lowQuotaPct; } catch {}
+  return { t, q };
+}
+
+// Returns { low: [{label, line}], cached } — `low` is the list of providers below their refill threshold.
+export async function maybeCheckBalances() {
+  if (process.env.TRANTOR_NO_BALANCE_CHECK === "1") return { low: [] };
+  let stamp = {}; try { stamp = JSON.parse(readFileSync(STAMP, "utf8")); } catch {}
+  if (stamp.ts && Date.now() - stamp.ts < TTL_MS) return { low: stamp.low || [], cached: true };
+
+  // only the providers configured in `trantor profile` (never stray ambient-env keys)
+  const only = Object.keys(loadProfile().providers || {});
+  if (!only.length) return { low: [] };   // no profile → nothing to report
+
+  let balances;
+  try { balances = await Promise.race([fetchBalances(resolveKeys(process.env), { only }), new Promise((_, rej) => setTimeout(() => rej(new Error("cap")), CAP_MS))]); }
+  catch { return { low: stamp.low || [] }; }   // timed out / errored — keep the last known low list, don't rewrite the stamp
+  if (!Array.isArray(balances) || !balances.length) { try { writeFileSync(STAMP, JSON.stringify({ ts: Date.now(), low: [] })); } catch {} return { low: [] }; }
+
+  // push the fresh snapshot to the hub for the dashboard + other sessions (best-effort)
+  try {
+    await fetch(`${relayUrl()}/balances`, { method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ balances, ts: Date.now(), by: process.env.TRANTOR_SESSION || "" }), signal: AbortSignal.timeout(2000) });
+  } catch {}
+
+  const { t, q } = thresholds();
+  const low = balances.filter(b => isLow(b, t, q)).map(b => ({ label: b.label, line: fmtBalance(b) }));
+  try { writeFileSync(STAMP, JSON.stringify({ ts: Date.now(), low })); } catch {}
+  return { low };
+}

package/hooks/lib/handoff.mjs

@@ -227,6 +227,15 @@ export function writeHandoff({ projectDir, sessionId, transcript, trigger, summa
   // baked copy is just orientation if the live command isn't available. Best-effort; never throws.
   let subagents = null;
   try { subagents = deriveSubagentManifest(transcript, { projectRoot: projectDir }); } catch {}
+  // Open verification gates for this project — structured "must verify before shipping" claims that
+  // MUST survive the handoff (a narrative line gets skimmed past; this is what the v0.17.31 incident
+  // taught — the "verify Gail coefficients" intent vanished into prose). Fetched synchronously from
+  // the local hub; best-effort, never blocks the handoff.
+  let verifyGates = [];
+  try {
+    const out = execSync(`curl -s --max-time 2 ${JSON.stringify(relayUrl() + "/verify-gates?project=" + encodeURIComponent(projectName))}`, { encoding: "utf8", timeout: 2500 });
+    verifyGates = JSON.parse(out).gates || [];
+  } catch {}
   const record = {
     id: `${projectName}-${stamp}`,
     project: projectDir, projectName, machine: hostname(),
@@ -234,7 +243,7 @@ export function writeHandoff({ projectDir, sessionId, transcript, trigger, summa
     transcript_path: transcript || "", stamp: Number(stamp) || 0,
     // narrative + a verbatim recent-exchange block so exact in-flight state always survives
     summary: narrative + (tail ? `\n\n---\n## Verbatim recent exchange (exact in-flight state — continue from here)\n${tail}` : ""),
-    gitStatus, subagents, consumed: false,
+    gitStatus, subagents, verifyGates, consumed: false,
   };
   const file = join(HANDOFF_DIR, `${record.id}.json`);
   writeFileSync(file, JSON.stringify(record, null, 2));

package/hooks/lib/subagent-cost-lib.mjs

@@ -0,0 +1,19 @@
+// Pure, testable guards for the SubagentStop cost hook (extracted so they have regression coverage).
+// The v0.17.37 bug: findTranscript() summed the PARENT session transcript (1000+ turns, 100s of M
+// cache-read) onto tiny recall/handoff sub-agent cards → tens of thousands of $ bogus notional.
+import { basename } from "node:path";
+
+// A real sub-agent transcript lives under a /subagents/ tree and is named agent-<id>.jsonl. The MAIN
+// session transcript is <session-uuid>.jsonl at the project root — never accept it as a sub-agent's.
+export function isSubagentTranscript(p) {
+  if (!p) return false;
+  return /(^|[\/\\])subagents[\/\\]/.test(p) && /[\/\\]agent-[^\/\\]*\.jsonl$/.test(p);
+}
+
+// A single sub-agent with >50M cache-read (or >$50 notional) is almost certainly a mis-resolved
+// transcript. Real agents top out ~40M cache-read / ~$30. Treat as suspect → don't record a cost.
+export const SUSPECT_CACHE_READ = 50e6;
+export const SUSPECT_USD = 50;
+export function isImplausibleCost({ usd = null, cacheRead = 0 } = {}) {
+  return (cacheRead || 0) > SUSPECT_CACHE_READ || (typeof usd === "number" && usd > SUSPECT_USD);
+}

package/hooks/sessionstart.mjs

@@ -13,6 +13,7 @@ import { execSync } from "node:child_process";
 import { resolveProject, hostId } from "../lib/project.mjs";
 import { formatSubagentManifest } from "../lib/subagent-manifest.mjs";
 import { updateAvailable, maybeNotifyDesktop, readConfig } from "./lib/update-check.mjs";
+import { maybeCheckBalances } from "./lib/balance-check.mjs";
 
 // Load the most recent UNCONSUMED handoff for this project (written by precompact.mjs
 // / the heartbeat early-warning). `claim` marks it consumed so exactly one session
@@ -184,6 +185,20 @@ try {
     }
   } catch {}
 
+  // Provider credit low? The session env has the keys (the hub doesn't), so check + push the snapshot
+  // here and warn in-terminal so you refill BEFORE a build stalls. Throttled (3h TTL) + 4s-capped +
+  // fail-silent — most starts do zero network. Disable: TRANTOR_NO_BALANCE_CHECK=1.
+  try {
+    const bal = await maybeCheckBalances();
+    if (bal.low && bal.low.length) {
+      const O = "\x1b[1;38;5;208m", R = "\x1b[0m";
+      const line = `🟠 ${O}Provider credit low — refill soon:${R} ${bal.low.map(l => l.line).join("  ·  ")}  ·  check:  ${O}trantor balances${R}`;
+      userBanner = userBanner ? `${userBanner}\n${line}` : line;
+      additionalContext += `<trantor-balance-low>\n⚠️ ${bal.low.length} provider(s) low on prepaid credit: ${sanitize(bal.low.map(l => l.line).join("; "))}. Tell the user to refill before relying on those providers for a build.\n</trantor-balance-low>\n`;
+      process.stderr.write(`[trantor] low balance: ${bal.low.map(l => l.label).join(", ")}\n`);
+    }
+  } catch {}
+
   // Pending handoff? A prior session hit the context limit and left a handoff for this
   // project — take over with this fresh full window instead of starting cold. On a
   // compaction-triggered start, DON'T claim it (that's the same session that wrote it;
@@ -197,6 +212,19 @@ try {
     process.stderr.write(`[trantor] ${isCompact ? "showing (not claiming, compact)" : "loaded"} pending handoff ${handoff.id}\n`);
     additionalContext += `<trantor-handoff id="${sanitize(handoff.id)}" from="${sanitize(handoff.machine)}" trigger="${sanitize(handoff.trigger)}">\n`;
     additionalContext += `🔄 **You are taking over from a prior session that hit its context limit.** This is a fresh full window. Resume the work below — the prior session's summary, git state, and a pointer to its full transcript (searchable; Foundation/Gaia has it ingested) follow. Continue from "OPEN THREADS & NEXT STEPS"; do not restart from scratch.\n\n`;
+    // Verification gates FIRST — these are structured "must verify before shipping" claims the prior
+    // session couldn't independently prove. They go above the summary on purpose: a safety-critical
+    // check must not be skimmed past (the lesson of the lost "verify Gail coefficients" intent).
+    if (Array.isArray(handoff.verifyGates) && handoff.verifyGates.length) {
+      additionalContext += `## ⚠️ UNVERIFIED — verify before shipping (${handoff.verifyGates.length})\n`;
+      additionalContext += `The prior session flagged these as NOT independently verified. Do NOT commit or ship the related work until each is verified (or explicitly waived WITH the user) — passing the author's own tests is not verification. Resolve via the \`relay_verify_gate\` tool (action "resolve") once checked.\n`;
+      for (const g of handoff.verifyGates) {
+        additionalContext += `- **#${sanitize(String(g.id))}: ${sanitize(g.claim)}**${g.why ? ` — ${sanitize(g.why)}` : ""}`;
+        if (g.howToVerify) additionalContext += `\n    how to verify: ${sanitize(g.howToVerify)}`;
+        additionalContext += `\n`;
+      }
+      additionalContext += `\n`;
+    }
     additionalContext += `## Handoff summary\n${sanitize(handoff.summary)}\n`;
     if (handoff.gitStatus) additionalContext += `\n## Git working-tree at handoff\n\`\`\`\n${sanitize(handoff.gitStatus)}\n\`\`\`\n`;
     // Sub-agent manifest: LIVE-primary, snapshot-as-fallback. The prior session may have had

package/hooks/subagent-cost.mjs

@@ -10,6 +10,7 @@ import { join, basename } from "node:path";
 import { homedir } from "node:os";
 import { resolveProject, hostId } from "../lib/project.mjs";
 import { notionalCost } from "./pricing.mjs";
+import { isSubagentTranscript, isImplausibleCost } from "./lib/subagent-cost-lib.mjs";
 
 function readStdin() {
   return new Promise(res => { let d = ""; process.stdin.setEncoding("utf8");
@@ -22,10 +23,11 @@ function relayUrl() {
   return "http://127.0.0.1:4477";
 }
 
-// Resolve the sub-agent's transcript: the payload path, else reconstruct, else newest agent-*.jsonl.
+// Resolve the sub-agent's OWN transcript: the payload path ONLY if it's truly a sub-agent transcript,
+// else reconstruct from the subagents tree (which can only ever find real agent-*.jsonl), else "".
 function findTranscript(input) {
   const direct = input.transcript_path;
-  if (direct && existsSync(direct)) return direct;
+  if (direct && existsSync(direct) && isSubagentTranscript(direct)) return direct;
   const sid = input.session_id, aid = input.agent_id;
   // search the session's subagents tree (plain Task → subagents/agent-<id>.jsonl; Workflow → subagents/workflows/<wf>/agent-<id>.jsonl)
   const roots = [];
@@ -86,6 +88,15 @@ try {
   const ttl = process.env.TRANTOR_CACHE_TTL === "1h" ? "1h" : "5m";
   const { usd, tokens, unpriced, model } = notionalCost(rows, ttl);
 
+  // Sanity guard: a single sub-agent with >50M cache-read (or >$50 notional) is almost certainly a
+  // mis-resolved transcript (e.g. a parent session summed in). Don't card a bogus cost — better a card
+  // with no $ than one claiming thousands. (Real agents top out ~40M cache-read / ~$30; see the v0.17.37 fix.)
+  const totalCacheRead = (tokens?.cacheRead || 0);
+  const suspect = isImplausibleCost({ usd, cacheRead: totalCacheRead });
+  const safeUsd = suspect ? null : usd;
+  const safeNote = suspect ? "skipped-implausible-cost (likely mis-resolved transcript)" : (usd == null ? "usage-unavailable-or-unpriced" : (unpriced ? `${unpriced} turn(s) unpriced` : ""));
+  if (suspect) process.stderr.write(`[trantor] subagent-cost: SKIPPED implausible cost ($${usd?.toFixed?.(0)}, ${(totalCacheRead/1e6).toFixed(0)}M cache-read) — ${basename(file)}\n`);
+
   const task = (firstUserText || agentType).replace(/\s+/g, " ").slice(0, 90);
   const title = `${agentType}: ${task}`.slice(0, 180);
   const costNote = usd == null ? "usage-unavailable-or-unpriced" : (unpriced ? `${unpriced} turn(s) unpriced` : "");
@@ -96,7 +107,7 @@ try {
       project, title, status: "done",
       assignee: `${agentType}:${project}`, by: `${hostId()}:${project}`,
       source: "cc-subagent", costKind: "subagent-notional",
-      costUsd: usd, costNote, model, effort, tokens,
+      costUsd: safeUsd, costNote: safeNote, model, effort, tokens: suspect ? null : tokens,
       phase: "sub-agents",
     }),
     signal: AbortSignal.timeout(2500),

package/lib/balances.mjs

@@ -0,0 +1,147 @@
+// trantor provider credit — read-only "how much is left before I stall" across the providers the crew
+// uses. Keys come from the ENVIRONMENT (no new secret storage); each adapter names the env var(s) it
+// reads. Two kinds of "left":
+//   • prepaid  — a $ balance you top up (OpenRouter, DeepSeek, Moonshot platform). `remaining` = money.
+//   • quota    — a recurring token/usage window that RESETS (Kimi Code, Z.ai GLM coding plans).
+//                `remainingPct` (0-100) + `resetTime`; nothing to "refill", but you can run dry mid-build.
+// Chinese providers split CN vs international endpoints — we use the INTERNATIONAL ones (api.moonshot.ai,
+// api.kimi.com, api.z.ai, api.deepseek.com). Every call is short-timeout + fail-soft: a provider that
+// errors is reported {ok:false,error}, never throws out of fetchBalances.
+//
+// ARCHITECTURE NOTE: the hub runs under launchd with a minimal env (no keys), so it can't fetch these
+// itself. The env-having clients fetch + POST /balances; the hub caches + serves the dashboard.
+
+const TIMEOUT = 8000;
+
+async function getJSON(url, key, extraHeaders = {}) {
+  const r = await fetch(url, {
+    headers: { Authorization: `Bearer ${key}`, "content-type": "application/json", Accept: "application/json", ...extraHeaders },
+    signal: AbortSignal.timeout(TIMEOUT),
+  });
+  const text = await r.text();
+  let body; try { body = JSON.parse(text); } catch { body = null; }
+  if (!r.ok) throw new Error(`HTTP ${r.status}${body?.error?.message ? " — " + body.error.message : ""}`);
+  return body ?? {};
+}
+
+const num = (v) => (v == null || v === "" || isNaN(Number(v))) ? null : Number(v);
+
+// Each adapter: { provider, label, kind, match:[profile names], envKeys:[...], async fetch(key) }.
+// `match` = the `trantor profile` provider name(s) this adapter serves — balances are ONLY queried for
+// providers the user actually configured in their profile, NOT every key that happens to be in the
+// ambient environment (a dev's shell/.env may hold keys for many unrelated projects). prepaid →
+// { remaining, currency, unlimited? }   quota → { remainingPct, plan?, resetTime?, detail? }
+export const ADAPTERS = [
+  {
+    provider: "openrouter", label: "OpenRouter", kind: "prepaid", match: ["openrouter"], envKeys: ["OPENROUTER_API_KEY"],
+    async fetch(key) {
+      const d = (await getJSON("https://openrouter.ai/api/v1/key", key)).data || {};
+      // limit_remaining is OpenRouter's authoritative credits-left (accounts for top-ups); limit−usage
+      // is unreliable (usage is lifetime). null limit_remaining + null limit ⇒ unlimited key.
+      const unlimited = d.limit_remaining == null && d.limit == null;
+      const remaining = num(d.limit_remaining) != null ? num(d.limit_remaining)
+        : (num(d.limit) != null ? Math.max(0, num(d.limit) - (num(d.usage) || 0)) : null);
+      return { remaining, currency: "USD", usage: num(d.usage), limit: num(d.limit), unlimited };
+    },
+  },
+  {
+    provider: "deepseek", label: "DeepSeek", kind: "prepaid", match: ["deepseek"], envKeys: ["DEEPSEEK_API_KEY"],
+    async fetch(key) {
+      const j = await getJSON("https://api.deepseek.com/user/balance", key);   // global endpoint (no CN/intl split)
+      const info = (j.balance_infos || [])[0] || {};
+      return { remaining: num(info.total_balance), currency: info.currency || "USD", available: !!j.is_available };
+    },
+  },
+  {
+    provider: "moonshot", label: "Moonshot", kind: "prepaid", match: ["moonshot"], envKeys: ["MOONSHOT_API_KEY"],
+    async fetch(key) {
+      // international platform; china is api.moonshot.cn. (Distinct from Kimi Code sk-kim keys below.)
+      const j = await getJSON("https://api.moonshot.ai/v1/users/me/balance", key);
+      const d = j.data || j;
+      return { remaining: num(d.available_balance), currency: "CNY", cash: num(d.cash_balance), voucher: num(d.voucher_balance) };
+    },
+  },
+  {
+    provider: "kimi", label: "Kimi Code", kind: "quota", match: ["kimi"], envKeys: ["KIMI_API_KEY"],
+    async fetch(key) {
+      // international Kimi Code; the sk-kim API key works as a bearer here (region REGION_OVERSEA).
+      const j = await getJSON("https://api.kimi.com/coding/v1/usages", key);
+      const tq = j.totalQuota || {};
+      const remainingPct = (num(tq.limit) && num(tq.remaining) != null) ? Math.round(num(tq.remaining) / num(tq.limit) * 100)
+        : (j.usage && num(j.usage.remaining) != null ? num(j.usage.remaining) : null);
+      const w = (j.limits || [])[0];
+      const detail = w?.detail ? `${Math.round(num(w.detail.remaining) / num(w.detail.limit) * 100)}% in ${Math.round((w.window?.duration || 0) / 60)}h window` : "";
+      const plan = (j.user?.membership?.level || "").replace("LEVEL_", "").toLowerCase() || "coding";
+      return { remainingPct, plan, resetTime: j.usage?.resetTime || w?.detail?.resetTime || null, detail };
+    },
+  },
+  {
+    provider: "zai", label: "Z.ai (GLM)", kind: "quota", match: ["zai", "glm", "zhipu"], envKeys: ["ZAI_API_KEY", "GLM_API_KEY"],
+    async fetch(key) {
+      // international Z.ai; coding-plan quota lives at undocumented monitor endpoints (used by their own UI).
+      const j = await getJSON("https://api.z.ai/api/monitor/usage/quota/limit", key);
+      const limits = j.data?.limits || [];
+      const tokens = limits.filter(l => l.type === "TOKENS_LIMIT");
+      // headline = the most-consumed token window (lowest remaining %)
+      const head = [...tokens].sort((a, b) => (b.percentage || 0) - (a.percentage || 0))[0] || tokens[0];
+      const remainingPct = head ? Math.max(0, 100 - (num(head.percentage) || 0)) : null;
+      let plan = j.data?.level ? `GLM ${String(j.data.level).toUpperCase()}` : "GLM coding";
+      try { const sub = await getJSON("https://api.z.ai/api/biz/subscription/list", key); const p = (sub.data || []).find(x => x.status === "VALID") || (sub.data || [])[0]; if (p?.productName) plan = p.productName; } catch {}
+      return { remainingPct, plan, resetTime: head?.nextResetTime || null, detail: "" };
+    },
+  },
+];
+
+// thresholds: prepaid by currency, quota by percent-remaining. Override via config.json `lowBalance`
+// (currency keys) and `lowQuotaPct`.
+export const DEFAULT_LOW = { USD: 5, CNY: 35, EUR: 5 };
+export const DEFAULT_LOW_QUOTA_PCT = 15;
+
+export function isLow(entry, thresholds = DEFAULT_LOW, quotaPct = DEFAULT_LOW_QUOTA_PCT) {
+  if (!entry || !entry.ok) return false;
+  if (entry.kind === "quota") return entry.remainingPct != null && entry.remainingPct < quotaPct;
+  if (entry.remaining == null) return false;   // prepaid unlimited/unknown
+  const t = thresholds[entry.currency] ?? thresholds.USD ?? 5;
+  return entry.remaining < t;
+}
+
+// Fetch credit ONLY for the providers the user configured in `trantor profile` (opts.only = the set of
+// profile provider names). An adapter runs only if it serves a configured provider AND its key is in the
+// env — so a stray OPENROUTER_API_KEY in a dev's .env is NOT reported unless they actually run OpenRouter
+// through Trantor. If `only` is omitted (no profile yet), nothing is fetched — better empty than wrong.
+export async function fetchBalances(env = process.env, opts = {}) {
+  const only = Array.isArray(opts.only) ? new Set(opts.only.map((s) => String(s).toLowerCase())) : null;
+  const jobs = ADAPTERS.map(async (a) => {
+    const names = (a.match || [a.provider]).map((s) => s.toLowerCase());
+    if (!only || !names.some((n) => only.has(n))) return null;   // not a Trantor-configured provider → skip
+    const envKey = a.envKeys.find((k) => env[k]);
+    if (!envKey) return null;                                    // configured but no key in env → can't query
+    const base = { provider: a.provider, label: a.label, kind: a.kind, via: envKey };
+    try { return { ...base, ok: true, ...(await a.fetch(env[envKey])) }; }
+    catch (e) { return { ...base, ok: false, error: String(e?.message || e) }; }
+  });
+  return (await Promise.all(jobs)).filter(Boolean);
+}
+
+// human one-liner for a credit entry (CLI + warning line)
+export function fmtBalance(e) {
+  if (!e.ok) return `${e.label}: ⚠ ${e.error}`;
+  if (e.kind === "quota") {
+    if (e.remainingPct == null) return `${e.label}${e.plan ? " (" + e.plan + ")" : ""}: quota unknown`;
+    const reset = e.resetTime ? ` · resets ${fmtReset(e.resetTime)}` : "";
+    return `${e.label}${e.plan ? " (" + e.plan + ")" : ""}: ${e.remainingPct}% left${reset}`;
+  }
+  const sym = e.currency === "CNY" ? "¥" : e.currency === "EUR" ? "€" : "$";
+  if (e.unlimited || e.remaining == null) return `${e.label}: ${e.kind === "prepaid" ? "no limit / unknown" : e.kind}`;
+  const amt = e.remaining.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+  return `${e.label}: ${sym}${amt} ${e.currency} left`;
+}
+
+function fmtReset(t) {
+  const ms = typeof t === "number" ? t : Date.parse(t);
+  if (!ms || isNaN(ms)) return "";
+  const hrs = (ms - Date.now()) / 3600e3;
+  if (hrs < 0) return "soon";
+  if (hrs < 48) return `${Math.round(hrs)}h`;
+  return `${Math.round(hrs / 24)}d`;
+}

package/lib/provider-keys.mjs

@@ -0,0 +1,37 @@
+// Resolve provider API keys the SAME way the crew does (bin/crew-runner.mjs:130) so the balance checker
+// can't miss a key that the agents themselves use. The crew sources, in order, ~/.token-scrooge/.env
+// (Scrooge's integrated keys — deepseek/opencode-routed providers) then ~/.agent-bus/.env (Trantor's own
+// key file — wins), on top of the inherited process.env. Reading bare process.env was the bug: keys like
+// DEEPSEEK_API_KEY live in those .env files, not necessarily in the session/launchd environment.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// Minimal .env parser: KEY=value / export KEY=value, strips matching quotes, ignores blanks/comments.
+export function parseEnvFile(file) {
+  const out = {};
+  try {
+    for (const raw of readFileSync(file, "utf8").split("\n")) {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) continue;
+      const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+      if (!m) continue;
+      let v = m[2].trim();
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+      out[m[1]] = v;
+    }
+  } catch {}
+  return out;
+}
+
+// The key files Trantor/the crew read, low → high precedence (later wins), matching crew-runner.
+export function keyFiles() {
+  return [join(homedir(), ".token-scrooge", ".env"), join(homedir(), ".agent-bus", ".env")];
+}
+
+// process.env overlaid by the key files (~/.agent-bus/.env wins). Use this everywhere a provider key is read.
+export function resolveKeys(env = process.env, files = keyFiles()) {
+  let merged = { ...env };
+  for (const f of files) if (existsSync(f)) merged = { ...merged, ...parseEnvFile(f) };
+  return merged;
+}

package/mcp.mjs

@@ -105,6 +105,32 @@ server.tool("relay_lesson", "Record a LESSON learned from a failure so future cr
     return { content: [{ type: "text", text: r.dedup ? "lesson already recorded" : `lesson recorded (${r.count} total)` }] };
   });
 
+server.tool("relay_verify_gate", "Record a VERIFICATION GATE — a claim that MUST be independently verified before the related work ships (e.g. 'Gail breast coefficients match the published BCRAT model'). Unlike a note buried in a handoff narrative, a gate is STRUCTURED: it travels with handoffs and is shown PROMINENTLY to whoever takes over, so a safety-critical 'verify before commit' can't be skimmed past. action 'add' when you produce code whose correctness you have NOT independently proven (especially formulas/coefficients/security/data-shape); 'resolve' once you've verified it (or waived with the user); 'list' to see open gates. Defaults to THIS project.",
+  { action: z.enum(["add", "resolve", "list"]).describe("add a gate · resolve one · list open gates"),
+    claim: z.string().optional().describe("what must be verified (required for add) — a specific, checkable claim"),
+    why: z.string().optional().describe("why it matters / the risk if it ships unverified"),
+    howToVerify: z.string().optional().describe("the concrete check that would verify it (source to cross-check, command to run)"),
+    id: z.number().optional().describe("gate id to resolve"),
+    status: z.string().optional().describe("resolve status: 'verified' (default) | 'failed' | 'waived'"),
+    note: z.string().optional().describe("resolution note (what you checked / why waived)"),
+    project: z.string().optional().describe("target project (default: this session's project)") },
+  async ({ action, claim, why, howToVerify, id, status, note, project }) => {
+    const proj = project || PROJECT;
+    if (action === "list") {
+      const { gates } = await api("GET", `/verify-gates?project=${encodeURIComponent(proj)}`);
+      if (!gates || !gates.length) return { content: [{ type: "text", text: `${proj}: no open verification gates` }] };
+      return { content: [{ type: "text", text: gates.map(g => `#${g.id} ⚠️ ${g.claim}${g.why ? ` — ${g.why}` : ""}`).join("\n") }] };
+    }
+    if (action === "resolve") {
+      if (!id) return { content: [{ type: "text", text: "id required to resolve a gate" }] };
+      const r = await api("POST", "/verify-gate", { resolve: true, id, status: status || "verified", note, project: proj, by: SESSION });
+      return { content: [{ type: "text", text: r.error ? `error: ${r.error}` : `gate #${id} resolved (${r.gate?.status || status || "verified"})` }] };
+    }
+    if (!claim) return { content: [{ type: "text", text: "claim required to add a gate" }] };
+    const r = await api("POST", "/verify-gate", { claim, why, howToVerify, project: proj, by: SESSION });
+    return { content: [{ type: "text", text: r.dedup ? `gate already open (#${r.gate.id})` : `🔒 verification gate #${r.gate.id} recorded — surfaces on every handoff until you resolve it` }] };
+  });
+
 server.tool("relay_board", "Show a project's Kanban board (all cards + their status + assignee). Defaults to THIS project; pass `project` to read a crew board you orchestrate from elsewhere.",
   { project: z.string().optional().describe("board to show (default: this session's project)") },
   async ({ project }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.31",
+  "version": "0.17.39",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"
@@ -10,7 +10,7 @@
     "zod": "^4.4.3"
   },
   "scripts": {
-    "test": "node test.mjs && node test-scenarios.mjs && node test-failure.mjs && node test-handoff.mjs && node test-agents.mjs && node test-update.mjs"
+    "test": "node test.mjs && node test-scenarios.mjs && node test-failure.mjs && node test-handoff.mjs && node test-agents.mjs && node test-update.mjs && node test-balances.mjs && node test-subagent-cost.mjs"
   },
   "description": "The hub-world for AI agent crews — orchestrate Claude Code, Codex, Gemini, Kimi & DeepSeek as live crews with a plan-aware Advisor, a Kanban/flow command center, a testing gate, and an economics brain (Scrooge).",
   "files": [

package/ui.html

@@ -11,6 +11,7 @@ header{display:flex;align-items:center;gap:13px;padding:11px 18px;border-bottom:
 .dot.off{background:var(--dim);box-shadow:none}
 .muted{color:var(--mut)}.dim{color:var(--dim)}.spacer{flex:1}
 .pill{background:var(--card);border:1px solid var(--line);border-radius:20px;padding:3px 11px;font-size:12px;color:var(--mut)}
+.pill.lowbal{color:#ffb4b4;border-color:#5a2c2c;background:#2a1517;animation:failpulse 2.4s ease-in-out infinite}
 main{flex:1;display:grid;grid-template-columns:var(--lw,44px) 1fr 330px;min-height:0}
 main.learn-open{--lw:372px}
 .boards{overflow-y:auto;padding:16px 18px}
@@ -89,6 +90,7 @@ main:not(.learn-open) .learn-body{display:none}
 .diff.easy{background:#13302b;color:#2dd4bf}.diff.medium{background:#2c2a17;color:#f5d90b}.diff.hard{background:#33181f;color:#ff7a90}
 .bounce{display:inline-block;font-size:9.5px;font-weight:700;color:#ef6a6a;background:#2a1517;border:1px solid #5a2c2c;border-radius:8px;padding:1px 6px;margin-left:5px}
 .mdl{font-size:9px;font-family:ui-monospace,monospace;color:#8fa3be;background:#16202f;border:1px solid #243049;border-radius:7px;padding:1px 5px;margin-left:4px;vertical-align:1px}
+.xcount{font-size:9px;font-weight:800;color:#cbd5e1;background:#1c2740;border:1px solid #2c3a52;border-radius:8px;padding:1px 5px;margin-left:5px;vertical-align:1px}
 .tcard.done{opacity:.65}.tcard.done span{text-decoration:line-through}
 .empty{color:var(--dim);text-align:center;padding:30px}
 .empty.big{padding:60px 20px;font-size:15px}
@@ -269,6 +271,7 @@ aside h2{font-size:10.5px;text-transform:uppercase;letter-spacing:.09em;color:va
   <span class="pill" id="hub">—</span>
   <span class="spacer"></span>
   <span class="pill" id="econ" title="Trantor savings vs frontier models — lifetime running total + last 24h (from the Scrooge ledger)" style="display:none"></span>
+  <span class="pill" id="credits" title="Provider credit left — $ balance (prepaid) or % quota (coding plans). Refill/pace before a build stalls. Pushed by sessions/CLI (the hub has no keys)." style="display:none"></span>
   <span class="pill"><span id="nproj">0</span> projects · <span id="nsess">0</span> live · <span id="ntask">0</span> cards</span>
 </header>
 <main>
@@ -293,6 +296,10 @@ aside h2{font-size:10.5px;text-transform:uppercase;letter-spacing:.09em;color:va
 <script>
 const $=s=>document.querySelector(s);
 const esc=s=>String(s).replace(/[&<>"]/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c]));
+// money: thousands separators + 2dp, readable as dollar amounts ($131,965.50). `usd()` returns just the
+// number; `$usd()` prefixes the currency symbol.
+const usd=(n,dp=2)=>(Number(n)||0).toLocaleString('en-US',{minimumFractionDigits:dp,maximumFractionDigits:dp});
+const $usd=(n,sym='$',dp=2)=>sym+usd(n,dp);
 const COLS=[['todo','To Do'],['doing','In Progress'],['testing','Testing'],['done','Done'],['blocked','Blocked']];
 let nmsg=0;
 
@@ -325,10 +332,17 @@ function econNotional(win){
   const ck=ECON&&ECON.costKinds&&ECON.costKinds[win]; if(!ck)return 0;
   return ((ck['subagent-notional']&&ck['subagent-notional'].usd)||0)+((ck['orchestrator-notional']&&ck['orchestrator-notional'].usd)||0);
 }
+// invocation count behind the notional figure — lets the pill stay visible (rebuilding) at $0 after a
+// reset, instead of vanishing, since there's still recorded sub-agent activity.
+function econNotionalCount(win){
+  const ck=ECON&&ECON.costKinds&&ECON.costKinds[win]; if(!ck)return 0;
+  return ((ck['subagent-notional']&&ck['subagent-notional'].count)||0)+((ck['orchestrator-notional']&&ck['orchestrator-notional'].count)||0);
+}
 function renderEcon(){
   const lifeCalls=(ECON&&ECON.lifetime&&ECON.lifetime.calls)||0;
   const notionalLife=ECON?econNotional('lifetime'):0;
-  if(!ECON||(!lifeCalls&&!(notionalLife>0)))return;     // show once we have EITHER real savings OR notional CC cost
+  const notionalCnt=ECON?econNotionalCount('lifetime'):0;
+  if(!ECON||(!lifeCalls&&!notionalCnt&&!(notionalLife>0)))return;     // show once we have real savings OR any CC sub-agent activity
   const el=$('#econ'); el.style.display='';
   // lifetime running total is the fixed headline; the dropdown picks the comparison window.
   if(!el.dataset.built){
@@ -343,12 +357,12 @@ function renderEcon(){
     el.dataset.built='1';
   }
   const w=(ECON.windows&&ECON.windows[econWin])||ECON.scrooge, wc=w?w.calls:0;
-  $('#econlife').textContent='$'+econSaved(ECON.lifetime).toFixed(2);
-  $('#econwinval').textContent=' $'+econSaved(w).toFixed(2)+' ('+wc+' call'+(wc===1?'':'s')+')';
+  $('#econlife').textContent=$usd(econSaved(ECON.lifetime));
+  $('#econwinval').textContent=' '+$usd(econSaved(w))+' ('+wc+' call'+(wc===1?'':'s')+')';
   // separate notional line — distinct icon + "notional" wording, never added to the savings number
   const nEl=$('#econnotional');
-  if(nEl) nEl.innerHTML = notionalLife>0
-    ? `<span style="opacity:.5"> · </span>🤖 CC sub-agents <b style="color:var(--blu)">$${notionalLife.toFixed(2)}</b> <span style="opacity:.7">notional</span>`
+  if(nEl) nEl.innerHTML = (notionalLife>0||notionalCnt>0)
+    ? `<span style="opacity:.5"> · </span>🤖 CC sub-agents <b style="color:var(--blu)">${$usd(notionalLife)}</b> <span style="opacity:.7">notional${notionalLife<=0&&notionalCnt>0?' · rebuilding':''}</span>`
     : '';
   const sel=$('#econsel'); if(sel)sel.value=econWin;
 }
@@ -360,6 +374,42 @@ async function econ(){
   }catch(_){}
 }
 econ();setInterval(econ,15000);
+async function credits(){
+  try{
+    const b=await (await fetch('/balances')).json();
+    const el=$('#credits'); if(!el)return;
+    const all=(b.entries||[]);
+    if(!all.length){el.style.display='none';return;}
+    el.style.display='';
+    const sym=c=>c==='CNY'?'¥':c==='EUR'?'€':'$';
+    const lbl=e=>e.label.replace(/ \(.*/,'');
+    const cap=s=>String(s||'').replace(/^./,c=>c.toUpperCase());
+    const txt=e=>e.kind==='quota'
+      ? `${lbl(e)} ${e.remainingPct==null?'?':e.remainingPct+'%'}`
+      : `${lbl(e)} ${e.remaining==null?'∞':$usd(e.remaining,sym(e.currency))}`;
+    const metered=all.filter(e=>e.kind==='prepaid'||e.kind==='quota');
+    const subs=all.filter(e=>e.kind==='subscription');
+    const ok=metered.filter(e=>e.ok && (e.remaining!=null||e.remainingPct!=null));
+    const lows=ok.filter(e=>e.low);
+    const errs=metered.filter(e=>!e.ok).map(lbl);
+    const staleTag=b.stale?' · <span style="opacity:.6">stale</span>':'';
+    // subscriptions (claude/codex/gemini) have no balance to refill — show them dimmed so the configured
+    // crew is fully visible, just not as $ figures.
+    const subTxt=subs.length?` <span style="opacity:.5">· ${subs.map(e=>cap(lbl(e))+(e.plan?' ('+e.plan+')':'')).join(' · ')} (sub)</span>`:'';
+    if(lows.length){
+      el.classList.add('lowbal');
+      const rest=ok.filter(e=>!e.low);
+      el.innerHTML=`🔴 <b>low:</b> ${lows.map(txt).join(' · ')}`+(rest.length?` <span style="opacity:.7">| ${rest.map(txt).join(' · ')}</span>`:'')+subTxt+staleTag;
+    } else if(ok.length){
+      el.classList.remove('lowbal');
+      el.innerHTML=`💳 ${ok.map(txt).join(' · ')}`+(errs.length?` <span style="opacity:.55">· ${errs.join(',')} ?</span>`:'')+subTxt+staleTag;
+    } else {
+      el.classList.remove('lowbal');
+      el.innerHTML=`💳 <span style="opacity:.6">${subs.length?'metered: none':'no credit reporting'}${errs.length?' ('+errs.join(',')+' ?)':''}</span>`+subTxt;
+    }
+  }catch(_){}
+}
+credits();setInterval(credits,30000);
 function poolOf(session){const b=brandOf(session);const k=b==='anthropic'?'claude':b==='openai'?'codex':b==='moonshot'?'kimi':b;return POOLS[k]||'';}
 const VIEWS = JSON.parse(localStorage.getItem("abViews") || "{}");
 let HISTORY = {};
@@ -386,6 +436,8 @@ function flowHTML(pt, proj){
   if (!data.phases || !data.phases.length) return '<div class="pflowwrap"><div class="empty">no cards yet</div></div>';
   const SCOL = { todo:'#3a4458', doing:'#4a90d9', testing:'#f59e0b', failed:'#ef6a6a', blocked:'#ef6a6a', done:'#14b8a6' };
   const NW = 168, NH = 34, RG = 11, CG = 64, PGAP = 76, MT = 64, MB = 22;
+  const MAXPC = 10;            // max nodes stacked per column before collapsing into a "+N more" node
+  let pi0 = 0;                 // running id base so each phase's overflow nodes get unique negative ids
   const stackH = n => n*NH + Math.max(0,n-1)*RG;
   // Per-phase layout: cards spread by their INTRA-PHASE dependency depth. Independent cards share
   // column 0 (parallel, hanging off the plan node); a card that depends on another lands one column
@@ -403,16 +455,30 @@ function flowHTML(pt, proj){
     };
     cards.forEach(c => c._d = depth(c));
     const maxDepth = Math.max(0, ...cards.map(c => c._d));
-    const cols = []; for (let d = 0; d <= maxDepth; d++) cols[d] = cards.filter(c => c._d === d);
+    let cols = []; for (let d = 0; d <= maxDepth; d++) cols[d] = cards.filter(c => c._d === d);
     const hasChild = c => cards.some(o => parentsOf(o).includes(c.id));
-    return { ph, cards, byId, parentsOf, hasChild, maxDepth, cols };
+    // DEFENSIVE CAP: never stack more than MAXPC nodes in one column. A phase that legitimately (or
+    // through a bug — see the cc-subagent dedup) has hundreds of independent cards would otherwise make
+    // the whole canvas thousands of px tall. Collapse the overflow into one "+N more" summary node.
+    cols = cols.map((col, d) => {
+      if (col.length <= MAXPC) return col;
+      const shown = col.slice(0, MAXPC - 1);
+      const rest = col.slice(MAXPC - 1);
+      const runs = rest.reduce((n, c) => n + (c.count || 1), 0);
+      shown.push({ id: -(pi0 + d + 1), title: `+${rest.length} more · ${runs} run${runs > 1 ? 's' : ''}`,
+        status: rest[0].status, agent: '', synthetic: true, deps: [], _d: d, _overflow: true });
+      return shown;
+    });
+    pi0 += maxDepth + 1;
+    const displayCards = cols.flat();
+    return { ph, cards: displayCards, byId, parentsOf, hasChild, maxDepth, cols };
   });
   const maxColCount = Math.max(1, ...layouts.flatMap(L => L.cols.map(c => c.length)));
   const Y0 = MT + stackH(maxColCount)/2;               // shared horizontal spine midline
   const totalH = MT + stackH(maxColCount) + MB;
   const gnode = (x, y, title, status, id, orch, agent, cost) => {
     const stripe = SCOL[status] || '#3a4458';
-    const c = (typeof cost === 'number') ? (cost < 0.005 ? '$' + cost.toFixed(4) : '$' + cost.toFixed(2)) : '';
+    const c = (typeof cost === 'number') ? (cost < 0.005 ? '$' + cost.toFixed(4) : $usd(cost)) : '';
     return `<g class="gnode ${status}${orch?' orch':''}"${id?` data-id="${id}"`:''}>`
       + `<rect class="gnbox" x="${x}" y="${y}" width="${NW}" height="${NH}" rx="8"/>`
       + `<rect x="${x}" y="${y}" width="4" height="${NH}" rx="2" fill="${stripe}"/>`
@@ -452,7 +518,9 @@ function flowHTML(pt, proj){
       const p = pos[c.id], parents = parentsOf(c);
       if (parents.length) for (const pid of parents){ const pp = pos[pid]; if (pp) svg += gedge(pp.x+NW, pp.y+NH/2, p.x, p.y+NH/2, byId[pid].status==='done'); }
       else svg += gedge(planX+NW, planY+NH/2, p.x, p.y+NH/2, ph.status==='done');   // root → plan
-      svg += gnode(p.x, p.y, (c.id?'#'+c.id+' ':'')+c.title, c.status, c.synthetic?null:c.id, !!c._orch, c.agent||'', c.costUsd);
+      const idPrefix = (c.id > 0 && !c.synthetic) ? '#'+c.id+' ' : '';
+      const cnt = (c.count > 1) ? ' ×'+c.count : '';
+      svg += gnode(p.x, p.y, idPrefix+c.title+cnt, c.status, c.synthetic?null:c.id, !!c._orch, c.agent||'', c.costUsd);
       if (!hasChild(c)) svg += gedge(p.x+NW, p.y+NH/2, intX, intY+NH/2, c.status==='done');   // leaf → integrate
     }
     svg += gnode(intX, intY, '◆ integrate', ph.status, null, true, '');
@@ -711,7 +779,7 @@ async function render(){
         const rank={todo:0,doing:1,testing:2,done:3};
         const bounced=last&&last.from!==undefined&&rank[last.to]<rank[last.from]&&(Date.now()-last.ts)<10*60*1000;
         const trail=hist.map(h=>`${h.from?h.from+'→':''}${h.to}${h.by?' by '+String(h.by).split(':')[0]:''} @${new Date(h.ts).toLocaleTimeString([],{hour:'2-digit',minute:'2-digit'})}`).join('\n');
-        return `<div class="tcard ${t.status}" data-id="${t.id}" title="${esc(trail)||'click to advance'}"><span>${esc(t.title)}</span>${t.difficulty?`<span class="diff ${t.difficulty}">${t.difficulty[0].toUpperCase()}</span>`:''}${t.model?`<span class="mdl">${esc(t.model)}</span>`:''}${bounced?`<span class="bounce">↩ bounced${last.by?' by '+esc(String(last.by).split(':')[0]):''}</span>`:''}${t.assignee?`<div class="who">${iconFor(t.assignee,12)}@${esc(t.assignee)}</div>`:''}</div>`;
+        return `<div class="tcard ${t.status}" data-id="${t.id}" title="${esc(trail)||'click to advance'}"><span>${esc(t.title)}</span>${t.count>1?`<span class="xcount">×${t.count}</span>`:''}${t.difficulty?`<span class="diff ${t.difficulty}">${t.difficulty[0].toUpperCase()}</span>`:''}${t.model?`<span class="mdl">${esc(t.model)}</span>`:''}${bounced?`<span class="bounce">↩ bounced${last.by?' by '+esc(String(last.by).split(':')[0]):''}</span>`:''}${t.assignee?`<div class="who">${iconFor(t.assignee,12)}@${esc(t.assignee)}</div>`:''}</div>`;
       })()).join('')}</div>`;
     }).join('');
     const ph=p.phase||'';