trantor 0.18.92 → 0.18.94

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.92",
+  "version": "0.18.94",
   "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/README.md

@@ -436,7 +436,12 @@ trantor setup | doctor | connect | profile | provider | models
   `add <name> --key … [--plan api] [--base-url <url> --models a,b]` to bring any provider (custom
   endpoints are wired into OpenCode for you) · `remove <name>`.
 - **`trantor models [<provider>]`** — browse the live models behind each seat + the router's pick
-  per difficulty.
+  per difficulty. A model with no known price is listed as unpriced and never picked.
+- **`trantor memory`** — pins a project's Claude memory notes to the code they describe
+  (graft symbols and files) and flags a note **stale** when a pinned symbol's body changes, or
+  **broken** when it disappears. `check [--strict]` reports; `pin <note> | --all [--dry-run]`
+  pins or re-pins. Notes are pinned automatically when saved, and a session's first context line
+  names any stale or broken note. Terms: [GLOSSARY.md](GLOSSARY.md).
 - **`trantor up`** — `agent:model` pins a model (`deepseek:deepseek-v4-pro`); `agent:provider
   --task <k> --difficulty <d>` picks the **best live model** for the work at spawn
   (`glm:zai-coding-plan --difficulty hard`); spawns are verified on the bus with one retry;

package/bin/cli.mjs

@@ -26,6 +26,7 @@ switch (cmd) {
   case "secrets": run("bin/secrets.mjs"); break;
   case "keys":    run("bin/keys.mjs"); break;
   case "models": run("bin/models.mjs"); break;
+  case "memory": run("bin/memory.mjs"); break;
   case "advise":  run("bin/advise.mjs"); break;
   case "verify":  run("bin/crew-verify.mjs"); break;
   case "up":      runCrew(); break;
@@ -271,6 +272,8 @@ switch (cmd) {
   trantor hub         run the hub in the foreground (setup installs it as a service instead)
                       …or manage per-project hub pins: hub list · hub set <project> <url> · hub unset <project>
                       seats: which project lives in which directory — seats · seats add · seats up · seats login install
+  trantor memory check [--project <dir>] [--json]  check note pins for stale or broken code
+  trantor memory pin <note> | --all [--dry-run]  pin or re-pin notes from code mentions
   trantor state       a seat's working memory: show <seat> <card> [--json] · validate · reset --force · gc [--apply]
   trantor seat-why    WHY a seat is down (err file, logs, pids): seat-why <agent> [--json] — quota, auth, crash, or just no pane
   trantor seat-record the per-project seat record the advisor benches from (✓/∅/↩ per difficulty) — [--project p] [--reset <seat>] [--json]

package/bin/crew-runner.mjs

@@ -29,6 +29,7 @@ import {
 } from "../lib/turn-policy.mjs";
 import { snapshotBeforeCut } from "./cut-snapshot.mjs";
 import { ocTurnUsage, dshTurnUsage, usageTotal } from "../lib/turn-usage.mjs";
+import { ocCompactionContent } from "../lib/seat-compaction.mjs";
 import { listContainers, newContainers, recordContainers, statePathFor as dockerStatePathFor, sweep as dockerSweep } from "../lib/docker-janitor.mjs";
 import {
   auditDutyNudges, claimDutyNudges, claudeTranscriptDir, dutyEscalations, dutyNudgeDirective,
@@ -746,6 +747,21 @@ const PARK_WINDOW_MS = Math.max(0, Number(process.env.TRANTOR_PARK_WINDOW_MS ||
 // The card the CURRENT CLI session belongs to (#6134). 0 = the kickoff session, which belongs to
 // no card, so the first contract that names one starts a session of its own.
 let sessionCard = releaseState?.sessionCard || 0;
+// #11559: per-card token accounting from the runner's own ledger (stdout usage lines, or the
+// provider's session DB when the CLI prints none). A card that crosses its budget pauses — no
+// further turn is bought for THAT card — until the card changes or the seat restarts, both of
+// which reset the counter. The budget itself is an env knob, not a constant in the wall.
+const CARD_TOKEN_BUDGET = Math.max(0, Number(process.env.TRANTOR_CARD_TOKEN_BUDGET || 1_000_000));
+const BUDGET_RETRY_MS = 10 * 60 * 1000;   // a paused card's OWN redelivery pace, never other cards'
+let cardTokens = releaseState?.cardTokens || 0;
+let cardStartedAt = releaseState?.cardStartedAt || 0;
+let budgetStop = releaseState?.budgetStop || null;   // { card, tokens } once the card crossed
+let budgetRetryAt = releaseState?.budgetRetryAt || 0;   // paces the paused card's OWN redeliveries
+
+// #11559: the compaction block injected to opencode-family seats via OPENCODE_CONFIG_CONTENT.
+// "" injects nothing (the operator set TRANTOR_OC_COMPACTION=off, or its JSON is invalid — the
+// seat then behaves exactly as before, never with a half-armed config).
+const OC_COMPACTION = ocCompactionContent(process.env);
 
 let sid = releaseState?.sid || "";
 // #6206: the watchdog is DETACHED, so a runner that dies without ending it leaves an orphan
@@ -930,18 +946,23 @@ exit $turn_exit`;
     // spawned. stdin is /dev/null: a background group that reads the terminal stops on SIGTTIN.
     detached: true,
     cwd: TURN_DIR, encoding: "utf8", stdio: cli.sid ? ["ignore", "pipe", "inherit"] : ["ignore", "inherit", "inherit"],
-    env: { ...process.env, ...shadowEnv(secrets), RELAY_URL: HUB, RELAY_AGENT: AGENT, RELAY_SESSION: SESSION, RELAY_PROJECT: PROJ,
-      // #6228: marks this env as belonging to PROJ, unlike a one-off RELAY_PROJECT override; crew.mjs's
-      // `up` guard refuses to bring up another project's crew from a shell carrying this badge.
-      TRANTOR_SEAT: PROJ,
-      // A runner-managed seat must never hand itself a baton: the runner is its lifecycle manager,
-      // so a handoff spawn would only leak an unmanaged interactive window.
-      TRANTOR_NO_HANDOFF_SPAWN: "1", TRANTOR_NO_BATON_SPAWN: "1",
-      // #6206: the seat's transcript dir — a real CLI ignores it, a drill's fake CLI writes
-      // its transcript lines there so the watchdog sees the liveness a real claude shows.
-      TRANTOR_TRANSCRIPT_DIR: TRANSCRIPT_DIR },
-    maxBuffer: 16 * 1024 * 1024,
   };
+  const spawnEnv = { ...process.env, ...shadowEnv(secrets), RELAY_URL: HUB, RELAY_AGENT: AGENT, RELAY_SESSION: SESSION, RELAY_PROJECT: PROJ,
+    // #6228: marks this env as belonging to PROJ, unlike a one-off RELAY_PROJECT override; crew.mjs's
+    // `up` guard refuses to bring up another project's crew from a shell carrying this badge.
+    TRANTOR_SEAT: PROJ,
+    // A runner-managed seat must never hand itself a baton: the runner is its lifecycle manager,
+    // so a handoff spawn would only leak an unmanaged interactive window.
+    TRANTOR_NO_HANDOFF_SPAWN: "1", TRANTOR_NO_BATON_SPAWN: "1",
+    // #6206: the seat's transcript dir — a real CLI ignores it, a drill's fake CLI writes
+    // its transcript lines there so the watchdog sees the liveness a real claude shows.
+    TRANTOR_TRANSCRIPT_DIR: TRANSCRIPT_DIR };
+  // #11559: opencode only compacts when the context is FULL, which on big-limit models is far
+  // past the point a seat card should reach. The merged-content injection arms compaction per
+  // seat (schema: opencode.ai/config.json) without touching the operator's global config.
+  if (cli.pinned && OC_COMPACTION) spawnEnv.OPENCODE_CONFIG_CONTENT = OC_COMPACTION;
+  spawnOpts.env = spawnEnv;
+  spawnOpts.maxBuffer = 16 * 1024 * 1024;
   // The timeout signals the shell to snapshot before sweeping, just like the normal box.
   // Its 30s margin keeps it out of the normal cut path.
   if (TURN_MAX_MS) { spawnOpts.timeout = (TURN_EXTENSIONS_MAX ? TURN_CEILING_MS : TURN_MAX_MS) + 30000; spawnOpts.killSignal = "SIGTERM"; }
@@ -1069,14 +1090,16 @@ exit $turn_exit`;
     // 0 means "this CLI printed no usage", never "free" — so only overwrite when the envelope
     // actually carried counts.
     if (c) tokens = c.input + c.output + c.cache_read + c.cache_creation;
-  }
-  // #8234: the CLIs that print no usage on stdout keep the counts in their own session records —
+  }  // #8234: the CLIs that print no usage on stdout keep the counts in their own session records —
   // opencode's db, the session resolved for this turn exactly like the `-s` resume id. Sum this
   // turn's window there; null (unknown) leaves the stdout paths above standing — never 0 ("free").
   const usage = cli.pinned && sid ? ocTurnUsage(OC_DB, sid, t0, Date.now())
     : AGENT === "dsh" ? dshTurnUsage(join(homedir(), ".dsh", "sessions"), TURN_DIR, t0, Date.now())
     : null;
   if (usage) tokens = usageTotal(usage);
+  // #11559: every token this turn spent rides the card it served. A card-0 turn (kickoff, pulse,
+  // duty) belongs to no card and adds nothing; the counter resets when the served card changes.
+  if (sessionCard > 0 && Number.isFinite(tokens) && tokens > 0) cardTokens += tokens;
   // #9724: usage RESOLVED to all zeros means no model work happened — never success; null stays
   // unknown, never failure, and a shipped commit is real work (stale record, not the turn).
   const zeroUsage = realExit === 0 && effExit === 0 && !newCommit && usageSaysNoWork(usage);
@@ -1111,7 +1134,13 @@ exit $turn_exit`;
     if (endStatus !== null) {
       cardStatusAtEnd = endStatus;
       const moved = ["testing", "done"].includes(endStatus) && !["testing", "done"].includes(cardStatusBefore);
-      noDelivery = !newCommit && !moved && !askVerdict && !blockedVerdict;
+      // #11551: a card ALREADY at testing/done when the turn began is delivered work — the
+      // codex-2 specimen's redelivered contract could neither commit anew nor move the card, and
+      // the check parked the seat for work it had already shipped. It only stands while the card
+      // still IS testing/done: a mid-turn bounce to doing (endStatus doing) reopens the contract.
+      const alreadyDelivered = ["testing", "done"].includes(cardStatusBefore)
+        && ["testing", "done"].includes(endStatus);
+      noDelivery = !newCommit && !moved && !alreadyDelivered && !askVerdict && !blockedVerdict;
     }
   }
   lastNoDelivery = noDelivery;
@@ -1457,7 +1486,8 @@ async function resolveWakeCard(messages, { session }) {
       writeFileSync(PENDF, JSON.stringify({ persona: PERSONA, agent: AGENT, project: PROJ, ts: Date.now(),
         wake: pendingWake, bcast: pendingBcast, seen: seenLedger, ask: awaitingAsk?.id || 0, askTo: awaitingAsk?.to || "" }));
       const state = { cursor, turn: TURN, sid, sessionCard, retryAt, deliveryFails,
-        noDeliveryRetry, askReleased, lastTurnAt, attempted: [...attemptedVersions] };
+        noDeliveryRetry, askReleased, lastTurnAt, attempted: [...attemptedVersions],
+        cardTokens, cardStartedAt, budgetStop, budgetRetryAt };
       process.execve(process.execPath, [process.execPath, ...process.execArgv, ...process.argv.slice(1)],
         { ...process.env, CREW_RELEASE_STATE: JSON.stringify(state) });
     } catch (error) { log(`runner restart failed: ${error.message}`); }
@@ -1479,14 +1509,15 @@ async function resolveWakeCard(messages, { session }) {
       log("parked — waiting for the next message or pulse");
       continue;
     }
-    // A due REDELIVERY runs before we go back to waiting — during an outage the bus is silent by
-    // definition, so the retry timer is the only thing that will ever move these messages.
-    // #7756: a held ask is owed but NEVER redelivered — only the assigner's answer releases it.
-    if (pendingWake.length && !awaitingAsk && Date.now() >= retryAt) { await deliverWake(); continue; }
+    // A due REDELIVERY runs before we go back to waiting: during an outage the bus is silent, so
+    // the retryAt timer is the only thing that will ever move these messages. #7756: a held ask
+    // is owed but NEVER redelivered. #11559: a budget-paused card paces its own redeliveries on
+    // budgetRetryAt - a clock that never delays a poll-delivered contract for a different card.
+    if (pendingWake.length && !awaitingAsk && Date.now() >= retryAt && Date.now() >= budgetRetryAt) { await deliverWake(); continue; }
     // cap the long-poll hold so neither a due pulse nor a due redelivery waits out a silent 280s window
     const due = [];
     if (PULSE_MS) due.push(PULSE_MS - (Date.now() - lastTurnAt));
-    if (pendingWake.length && !awaitingAsk) due.push(retryAt - Date.now());
+    if (pendingWake.length && !awaitingAsk) due.push(Math.min(retryAt, budgetRetryAt || retryAt) - Date.now());
     const holdS = due.length
       ? Math.max(5, Math.min(280, Math.ceil(Math.min(...due) / 1000)))
       : 280;
@@ -1749,6 +1780,20 @@ async function resolveWakeCard(messages, { session }) {
     // and never inherits the previous contract's card (#10197's judge then reads the right card).
     const sessionCardForTurn = card || baseCard;
     const fresh = !resumedAfterAsk && sessionCardForTurn > 0 && sessionCardForTurn !== sessionCard;
+    // #11559: a pause rides the card, not the seat — a contract for a DIFFERENT card lifts it
+    // (and resets the counter with the fresh session below); the paused card itself never buys
+    // another CLI session. The wake stays owed and retries on a long clock, so the orchestrator
+    // sees the pause, not a silent seat.
+    if (budgetStop && sessionCardForTurn > 0 && sessionCardForTurn === budgetStop.card) {
+      log(`\x1b[33mqueued — #${budgetStop.card} is over its token budget (${budgetStop.tokens} ≥ ${CARD_TOKEN_BUDGET}); paused until the card moves or \`trantor up ${AGENT}\` resets the budget\x1b[0m`);
+      // Pace only the SELF-redelivery path (a non-empty queue with retryAt=0 would otherwise
+      // hot-loop this branch and starve the poll): budgetRetryAt gates that line alone. A new
+      // contract delivered by the poll never waits on it — a different card lifts the pause.
+      budgetRetryAt = Date.now() + BUDGET_RETRY_MS;
+      return;
+    }
+    if (budgetStop && fresh) { budgetStop = null; budgetRetryAt = 0; }
+    if (fresh) { cardTokens = 0; cardStartedAt = Date.now(); }
     sessionCard = card;
     const cited = [...new Set(wakeForTurn.flatMap(m => cardRefs(m.text)))];
     const freshText = fresh
@@ -1951,6 +1996,19 @@ async function resolveWakeCard(messages, { session }) {
       await notifyAssigners(assigners,
         `✅ done on ${SESSION} (exit 0, ${secs}s) · asked: "${asked}" · check the board card and the files for what changed`);
     }
+    // #11559: the pause is judged AFTER the classification so it never masks it — a failed turn
+    // (ec !== 0) stays in its own ladder, and only a clean-exit turn hands its card to the stop.
+    // The stop blocks FUTURE turns for THIS card only: a different card starts clean, and the
+    // alert names the two ways out (move the card, or restart the seat, resetting the counter).
+    if (!budgetStop && CARD_TOKEN_BUDGET > 0 && sessionCard > 0 && cardTokens >= CARD_TOKEN_BUDGET && ec === 0) {
+      budgetStop = { card: sessionCard, tokens: cardTokens };
+      const text = `⛔ #${sessionCard} hit its token budget on ${SESSION}: ${cardTokens} ≥ ${CARD_TOKEN_BUDGET} tokens this card.`
+        + ` Further turns for THIS card are paused until it moves (new contract, or testing/done) or \`trantor up ${AGENT}\` resets the budget.`;
+      log(`\x1b[33m${text}\x1b[0m`);
+      await notifyAssigners(assigners, text);
+      const orch = `${hostId()}:${PROJ}`;
+      if (!assigners.some(a => a.from === orch)) await api("/send", { from: SESSION, to: orch, text, project: PROJ, kind: "alert" }).catch(() => {});
+    }
     lastTurnAt = Date.now();
   }
 })();

package/bin/memory.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { checkMemory, formatMemoryCheck } from "../lib/memory-pins.mjs";
+import { pinMemory, formatMemoryPin } from "../lib/memory-pin-write.mjs";
+
+const usage = "Usage: trantor memory check [--project <dir>] [--json] [--strict]\n       trantor memory pin <note> | --all [--dry-run] [--project <dir>] [--json]";
+try {
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+    project: { type: "string" }, json: { type: "boolean" }, help: { type: "boolean" },
+    strict: { type: "boolean" }, all: { type: "boolean" }, "dry-run": { type: "boolean" },
+  } });
+  if (values.help) {
+    console.log(usage);
+  } else {
+    const [command, note] = positionals;
+    let result;
+    let format;
+    if (command === "check" && positionals.length === 1 && !values.all && !values["dry-run"]) {
+      result = checkMemory({ project: values.project });
+      format = formatMemoryCheck;
+      if (values.strict && result.notes.some(note => note.pins.some(pin => ["stale", "broken"].includes(pin.status)))) process.exitCode = 1;
+    } else if (command === "pin" && !values.strict && positionals.length <= 2 && Boolean(note) !== Boolean(values.all)) {
+      result = pinMemory({ project: values.project, note, all: values.all, dryRun: values["dry-run"] });
+      format = formatMemoryPin;
+    } else {
+      throw new Error(usage);
+    }
+    const output = values.json ? JSON.stringify(result, null, 2) : format(result);
+    if (output) console.log(output);
+  }
+} catch (error) {
+  console.error(`memory: ${error.message}`);
+  process.exitCode = 1;
+}

package/bin/seat-tokens.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// trantor seat-tokens (#11559) — per-provider token totals for the seat fleet from opencode's
+// session store, the 30-day shape compared week over week: sessions, assistant steps, tokens,
+// the single biggest step, and cost. Read-only; a missing or locked DB prints "no data".
+//   node bin/seat-tokens.mjs [--days 30] [--db <path>] [--json]
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { seatTokensReport } from "../lib/seat-tokens.mjs";
+
+const argv = process.argv.slice(2);
+const val = (k, d) => { const i = argv.indexOf(k); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
+const DAYS = Math.max(1, Number(val("--days", 30)) || 30);
+const DB = val("--db", join(process.env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "opencode", "opencode.db"));
+const since = Date.now() - DAYS * 24 * 60 * 60 * 1000;
+const rows = seatTokensReport({ dbPath: DB, sinceMs: since });
+const fmt = (n) => Number(n).toLocaleString("en-US");
+
+if (val("--json", "")) { console.log(JSON.stringify({ db: DB, days: DAYS, providers: rows }, null, 1)); process.exit(0); }
+if (!rows.length) { console.log(`no session data in ${DB} for the last ${DAYS} day(s)`); process.exit(0); }
+console.log(`opencode seat usage, last ${DAYS} day(s) — ${DB}\n`);
+console.log("provider            sessions   steps  input        output     cache-read     cache-write  peak-step     cost");
+for (const r of rows) {
+  console.log(
+    String(r.provider).padEnd(18),
+    String(r.sessions).padStart(8),
+    String(r.steps).padStart(8),
+    fmt(r.input).padStart(12),
+    fmt(r.output).padStart(10),
+    fmt(r.cacheRead).padStart(14),
+    fmt(r.cacheWrite).padStart(14),
+    fmt(r.peakInput).padStart(12),
+    fmt(Math.round(r.cost)).padStart(6),
+  );
+}

package/hooks/hooks.json

@@ -150,6 +150,17 @@
             "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ask-sidecar.mjs"
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/memory-pin.mjs",
+            "async": true,
+            "timeout": 130
+          }
+        ]
       }
     ],
     "PostToolUseFailure": [

package/hooks/lib/memory-start.mjs

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { isMainThread, parentPort, Worker, workerData } from "node:worker_threads";
+import { gitCheckoutRoot } from "./git-checkout.mjs";
+
+const SLOW = "pin check skipped (slow), run trantor memory check";
+
+export function memoryStartLine(project) {
+  return new Promise(resolveLine => {
+    let worker;
+    let settled = false;
+    const finish = line => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolveLine(line);
+      if (worker) void worker.terminate().catch(() => {});
+    };
+    // Keep synchronous graph parsing and file reads off the hook's deadline timer.
+    const timer = setTimeout(() => finish(SLOW), 500);
+    try {
+      worker = new Worker(new URL(import.meta.url), { workerData: { project } });
+      worker.once("message", finish);
+      worker.once("error", () => finish(""));
+      worker.once("exit", () => finish(""));
+    } catch { finish(""); }
+  });
+}
+
+async function cachedMemoryLine(directory) {
+  const project = gitCheckoutRoot(directory) || resolve(directory);
+  const graphPath = join(project, "graft/.graph/wiring.json");
+  if (!existsSync(graphPath)) return "";
+  const { checkPin, memoryDirectory, notePins, pinFileNewer } = await import("../../lib/memory-pins.mjs");
+  const memoryDir = memoryDirectory(project);
+  if (!existsSync(memoryDir)) return "";
+  const graph = JSON.parse(readFileSync(graphPath, "utf8"));
+  const nodes = new Map(graph.nodes.map(node => [node.id, node]));
+  const graphTime = statSync(graphPath).mtimeMs;
+  let unchecked = 0;
+  const stale = new Set(), broken = new Set();
+  const notes = readdirSync(memoryDir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith(".md") && entry.name !== "MEMORY.md");
+  for (const note of notes) {
+    try {
+      const pins = notePins(readFileSync(join(memoryDir, note.name), "utf8"));
+      for (const pin of pins) {
+        if (pinFileNewer(project, pin, graphTime)) { unchecked++; continue; }
+        const { status } = checkPin(pin, project, nodes);
+        if (status === "stale") stale.add(note.name);
+        if (status === "broken") broken.add(note.name);
+      }
+    } catch { /* A concurrent edit or invalid span must not suppress other notes. */ }
+  }
+  const names = [...new Set([...stale, ...broken])].sort().map(name => name.replace(/[\s\x00-\x1f\x7f]+/g, " "));
+  const suffix = unchecked ? ` (${unchecked} unchecked: graph older than code, run trantor memory check)` : "";
+  return names.length || unchecked ? `${stale.size} stale, ${broken.size} broken notes: ${names.join(", ")}; run trantor memory check${suffix}` : "";
+}
+
+if (!isMainThread) {
+  try { parentPort.postMessage(await cachedMemoryLine(workerData.project)); }
+  catch { parentPort.postMessage(""); }
+}

package/hooks/memory-pin.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { pinMemory } from "../lib/memory-pin-write.mjs";
+import { memoryDirectory } from "../lib/memory-pins.mjs";
+import { gitCheckoutRoot } from "./lib/git-checkout.mjs";
+
+async function pinSavedNote() {
+  let raw = "";
+  for await (const chunk of process.stdin) raw += chunk;
+  const input = JSON.parse(raw);
+  if (!["Write", "Edit"].includes(input.tool_name) || !input.cwd || !input.tool_input?.file_path) return;
+  const path = resolve(input.cwd, input.tool_input.file_path);
+  if (!path.endsWith(".md") || basename(path) === "MEMORY.md") return;
+  const memoryRoot = dirname(dirname(memoryDirectory(input.cwd)));
+  if (!path.startsWith(`${memoryRoot}/`) || basename(dirname(path)) !== "memory") return;
+  const project = gitCheckoutRoot(input.cwd) || resolve(input.cwd);
+  const memoryDir = memoryDirectory(project);
+  if (dirname(path) !== memoryDir) return;
+  // A symlink must not turn a note-save hook into a write outside project memory.
+  if (dirname(realpathSync(path)) !== realpathSync(memoryDir)) return;
+  const result = pinMemory({ project, memoryDir, note: basename(path) });
+  if (result.message) console.error(`memory-pin: ${result.message}`);
+  for (const note of result.notes) {
+    for (const diagnostic of note.diagnostics) console.error(`memory-pin: ${note.name}: ${diagnostic}`);
+  }
+}
+
+try { await pinSavedNote(); }
+catch (error) { console.error(`memory-pin: ${error.message}`); }

package/hooks/sessionstart.mjs

@@ -16,6 +16,7 @@ import { maybeCheckBalances } from "./lib/balance-check.mjs";
 import { getJSON, signedGet, signedPost, loadIdentity } from "./lib/api.mjs";
 import { ledgerPaths, ensureStart, anchorCursor, writeCursor } from "./lib/inbox-ledger.mjs";
 import { ensureEnrolled } from "../lib/enroll.mjs";
+import { memoryStartLine } from "./lib/memory-start.mjs";
 
 // The build doctrine (docs/BUILD-DOCTRINE.md) in short form, one line per rule, injected for every
 // project's ORCHESTRATOR at boot (#6452): orchestrators that never opened the doc missed the ruling.
@@ -156,6 +157,8 @@ try {
     process.stdout.write(emit(ctx, banner, ""));
     process.exit(0);
   }
+  const memoryLine = await memoryStartLine(projectDir);
+  if (memoryLine) additionalContext += `${memoryLine}\n`;
   const project = resolveProject(projectDir);
   sessionTitle = project;   // baseline — enriched with the current work item after the catch-up fetch below
   const session = process.env.RELAY_SESSION

package/hub/routes/cards.mjs

@@ -38,7 +38,7 @@ export async function routeCards({ req, res, q, P, auth, ctx }) {
     appendTaskLog, appendTaskNote, cleanChecklist, cleanDrill, hasDrillLine, linkCommitToFocus,
     derivePhases, PROPOSAL_CAP, propFp, healthOf, REAP_GRACE_MS, subFp,
     prunePeers, canRead, HUB_VERSION, cmpSemver, isCardEvent, fmtAge, hubSend,
-    ONLINE_MS, PEER_TTL_MS,
+    ONLINE_MS, PEER_TTL_MS, AUTH_MODE,
   } = ctx;
     if (req.method === "POST" && P === "/task") {           // create a card
       const b = await body(req);
@@ -596,6 +596,22 @@ export async function routeCards({ req, res, q, P, auth, ctx }) {
       appendEvent("lesson", lProj, b.by || "", { text, scope });
       return json(res, 200, { ok: true, count: state.lessons.length });
     }
+    // A lesson can outlive the world it was learned in; only a global owner rewrites one, keeping its id and old text.
+    if (req.method === "POST" && P === "/lesson/update") {
+      if (AUTH_MODE !== "off" && !auth?.identity?.scopes?.some(s => s.project === "*" && s.role === "owner")) {
+        return json(res, 403, { error: "global owner permission required" });
+      }
+      const b = await body(req);
+      const lesson = state.lessons.find(l => l.id === Number(b.id));
+      if (!lesson) return json(res, 404, { error: "no such lesson" });
+      const text = stripNulText(b.text).trim().slice(0, 400);
+      if (!text) return json(res, 400, { error: "text required" });
+      lesson.revisions = [...(lesson.revisions || []), { text: lesson.text, by: lesson.by, ts: lesson.ts }].slice(-5);
+      Object.assign(lesson, { text, by: b.by || "", ts: now() });
+      markDirty();
+      appendEvent("lesson.revised", "", b.by || "", { id: lesson.id, text, scope: lesson.scope });
+      return json(res, 200, { ok: true, lesson });
+    }
     // --- verification gates: structured "must verify before shipping" claims that travel with
     // handoffs and surface PROMINENTLY to whoever takes over (so a safety-critical check can't be
     // skimmed past in narrative prose — the "verify Gail coefficients" intent that got lost). ---

package/lib/dep.mjs

@@ -0,0 +1,37 @@
+// Load an npm dependency from code that may run inside the Claude plugin snapshot, which ships
+// no node_modules: plain import first, then borrow from the globally installed trantor (as mcp.mjs does).
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const req = createRequire(import.meta.url);
+let fallbackRoots = null;
+
+function borrowRoots() {
+  if (fallbackRoots) return fallbackRoots;
+  const roots = [];
+  const add = p => { if (p && !roots.includes(p)) roots.push(p); };
+  if (process.env.npm_config_prefix) add(join(process.env.npm_config_prefix, "lib", "node_modules"));
+  add(join(dirname(process.execPath), "..", "lib", "node_modules"));
+  for (const prefix of ["/opt/homebrew", "/usr/local"]) add(join(prefix, "lib", "node_modules"));
+  if (!roots.some(r => existsSync(join(r, "trantor")))) {
+    try { add(execSync("npm root -g", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).trim()); } catch {}
+  }
+  fallbackRoots = roots.flatMap(r => [join(r, "trantor"), r]);
+  return fallbackRoots;
+}
+
+export async function dep(spec) {
+  try {
+    return await import(spec);
+  } catch (error) {
+    if (error?.code !== "ERR_MODULE_NOT_FOUND" && error?.code !== "ERR_PACKAGE_PATH_NOT_EXPORTED") throw error;
+  }
+  for (const path of [HERE, ...borrowRoots()]) {
+    try { return await import(pathToFileURL(req.resolve(spec, { paths: [path] })).href); } catch {}
+  }
+  throw new Error(`cannot resolve '${spec}': this plugin snapshot has no node_modules and no global trantor install to borrow from (npm i -g trantor)`);
+}

package/lib/memory-pin-write.mjs

@@ -0,0 +1,165 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, renameSync, unlinkSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { dep } from "./dep.mjs";
+import { checkPin, frontMatter, memoryDirectory, notePins, pinTarget, refreshPinGraph, symbolFingerprint } from "./memory-pins.mjs";
+
+const { stringify } = await dep("yaml");
+
+export function replaceNotePins(text, pins) {
+  const front = frontMatter(text);
+  const newline = text.includes("\r\n") ? "\r\n" : "\n";
+  const value = stringify(pins, { collectionStyle: "flow", lineWidth: 0 }).trimEnd();
+  if (!front) return `---${newline}pins: ${value}${newline}---${newline}${text}`;
+  const pair = front.document.contents?.items.find(item => item.key?.value === "pins");
+  if (!pair) {
+    if (front.document.contents?.flow) throw new Error("cannot add pins to flow-style front matter without changing other keys");
+    const at = front.start + front.yaml.length;
+    return `${text.slice(0, at)}pins: ${value}${newline}${text.slice(at)}`;
+  }
+  // Value ranges exclude neighboring keys and their comments; never reserialize the whole note.
+  const [start, end] = pair.value.range;
+  const old = front.yaml.slice(start, end);
+  const ending = old.match(/\r?\n$/)?.[0] || "";
+  const spacing = start === end ? " " : "";
+  return text.slice(0, front.start + start) + spacing + value + ending + text.slice(front.start + end);
+}
+
+export function extractMentions(text, project, nodes, siblingNotes = new Set()) {
+  const front = frontMatter(text);
+  const body = (front ? text.slice(front.end) : text)
+    .replace(/\[\[[\s\S]*?\]\]/g, " ").replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, " ");
+  const paths = new Set([...nodes.values()].map(node => node.path));
+  const mentions = [];
+  const seen = new Set();
+  const pattern = /(?<![\w./\\-])((?:\.\/)?(?:[\w@.-]+\/)*[\w@.-]+)(?:#([\w$.-]+)|:(\d+))?/g;
+  for (const match of body.matchAll(pattern)) {
+    let file = match[1].replace(/^\.\//, "").replace(/[.,]+$/, "");
+    if (!pinTarget({ file }) || file === "Node.js") continue;
+    if (siblingNotes.has(file)) continue;
+    if (!file.includes("/") && /^v?\d+(?:\.[\da-z-]+)+$/i.test(file)
+      && !/\.(?:[cm]?jsx?|tsx?|py|rs|go|swift|c|h|cpp|hpp|java|kt|rb|sh|php|vue|svelte)$/i.test(file)) continue;
+    const prefix = `${basename(project)}/`;
+    if (!existingFile(project, file) && file.startsWith(prefix) && existingFile(project, file.slice(prefix.length))) {
+      file = file.slice(prefix.length);
+    }
+    if (!paths.has(file) && !existingFile(project, file) && !file.includes("/") && !/\.(?:[cm]?jsx?|tsx?|py|rs|go|swift|c|h|cpp|hpp|java|kt|rb|sh|php|vue|svelte|md|mdx|txt|json|ya?ml|toml|sql|css|html)$/i.test(file)) continue;
+    const symbol = match[2]?.replace(/\.+$/, "");
+    const mention = symbol ? { file, symbol: `${file}#${symbol}` }
+      : match[3] ? { file, line: Number(match[3]) } : { file };
+    const key = JSON.stringify(mention);
+    if (!seen.has(key)) { seen.add(key); mentions.push(mention); }
+  }
+  return mentions;
+}
+
+function existingFile(project, file) {
+  try { return statSync(join(project, file)).isFile(); }
+  catch { return false; }
+}
+
+function resolveMention(mention, nodes, project) {
+  if (!existingFile(project, mention.file)) return null;
+  if (mention.symbol) return nodes.has(mention.symbol) ? { symbol: mention.symbol, fp: symbolFingerprint(project, nodes.get(mention.symbol)) } : null;
+  if (mention.line === undefined) return { file: mention.file };
+  const lines = readFileSync(join(project, mention.file), "utf8").split(/\r?\n/);
+  if (mention.line < 1 || mention.line > lines.length) return null;
+  const enclosing = [...nodes.values()].filter(node => node.path === mention.file && node.kind !== "file")
+    .map(node => ({ node, span: /^L(\d+)-L(\d+)$/.exec(node.span) }))
+    .filter(({ span }) => span && +span[1] <= mention.line && +span[2] >= mention.line)
+    .sort((a, b) => (+a.span[2] - +a.span[1]) - (+b.span[2] - +b.span[1]));
+  return enclosing.length ? { symbol: enclosing[0].node.id, fp: symbolFingerprint(project, enclosing[0].node) } : { file: mention.file };
+}
+
+function planNote(text, project, nodes, date, siblingNotes) {
+  const pins = notePins(text);
+  const diagnostics = [];
+  const keys = new Set(pins.map(pin => pinTarget(pin)).filter(Boolean).map(pin => pin.symbol || pin.file));
+  for (const mention of extractMentions(text, project, nodes, siblingNotes)) {
+    if (!existingFile(project, mention.file)) {
+      diagnostics.push(`mentions a path that doesn't exist: ${mention.file}`);
+      continue;
+    }
+    const pin = resolveMention(mention, nodes, project);
+    if (!pin) { diagnostics.push(`unresolved mention: ${mention.symbol || `${mention.file}:${mention.line}`}`); continue; }
+    const key = pin.symbol || pin.file;
+    if (!keys.has(key)) { pins.push({ ...pin, at: date }); keys.add(key); }
+  }
+  const refreshed = pins.map(pin => {
+    const checked = checkPin(pin, project, nodes);
+    if (checked.status === "broken" || checked.status === "invalid pin") {
+      diagnostics.push(`${checked.status}: ${checked.detail}`);
+      return pin;
+    }
+    const refreshed = { ...pin };
+    if (checked.actual) { refreshed.fp = checked.actual; refreshed.at = date; }
+    return refreshed;
+  });
+  return { pins: refreshed, diagnostics, text: refreshed.length ? replaceNotePins(text, refreshed) : text };
+}
+
+export function pinMemory({ project = process.cwd(), memoryDir = memoryDirectory(project), note, all = false, dryRun = false } = {}) {
+  project = resolve(project);
+  if (Boolean(note) === Boolean(all)) throw new Error("specify one note or --all");
+  const files = existsSync(memoryDir) ? readdirSync(memoryDir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith(".md") && entry.name !== "MEMORY.md").map(entry => entry.name).sort() : [];
+  let selected = files;
+  if (!all) {
+    const requested = note.endsWith(".md") ? note : `${note}.md`;
+    const name = basename(requested);
+    if (name === "MEMORY.md") throw new Error("MEMORY.md is an index and cannot be pinned");
+    if (resolve(memoryDir, requested) !== resolve(memoryDir, name) || !files.includes(name)) throw new Error(`note not found in project memory: ${note}`);
+    selected = [name];
+  }
+  const siblingNotes = new Set(files);
+  const plans = selected.map(name => {
+    const plan = { name, path: join(memoryDir, name), original: undefined, pins: [], diagnostics: [], targets: [] };
+    try {
+      plan.original = readFileSync(plan.path, "utf8");
+      plan.text = plan.original;
+      plan.pins = notePins(plan.original);
+      plan.targets = [...plan.pins, ...extractMentions(plan.original, project, new Map(), siblingNotes)
+        .map(mention => ({ file: mention.file }))];
+    } catch (error) { failNote(plan, error); }
+    return plan;
+  });
+  const nodes = refreshPinGraph(project, plans.flatMap(plan => plan.targets));
+  if (!nodes) return { project, status: "pins off", message: "no graft graph, pins off", notes: [] };
+  const date = new Date().toISOString().slice(0, 10);
+  for (const plan of plans) {
+    if (plan.failed) continue;
+    try {
+      Object.assign(plan, planNote(plan.original, project, nodes, date, siblingNotes));
+      if (!dryRun && plan.text !== plan.original) atomicNoteWrite(plan);
+    } catch (error) { failNote(plan, error); }
+  }
+  return { project, status: dryRun ? "dry run" : "pinned", notes: plans.map(plan => {
+    const note = { name: plan.name, pins: plan.pins, diagnostics: plan.diagnostics, changed: plan.text !== plan.original };
+    if (plan.failed) note.failed = true;
+    return note;
+  }) };
+}
+
+function failNote(plan, error) {
+  plan.failed = true;
+  plan.text = plan.original;
+  plan.pins = plan.original === undefined ? [] : notePins(plan.original);
+  plan.diagnostics.push(error.message);
+}
+
+function atomicNoteWrite(plan) {
+  const temp = join(dirname(plan.path), `.${basename(plan.path)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temp, plan.text, { flag: "wx", mode: statSync(plan.path).mode });
+    if (readFileSync(plan.path, "utf8") !== plan.original) throw new Error(`note changed during pinning: ${plan.name}; retry`);
+    renameSync(temp, plan.path);
+  } finally { if (existsSync(temp)) unlinkSync(temp); }
+}
+
+export function formatMemoryPin(result) {
+  if (result.message) return result.message;
+  return result.notes.map(note => {
+    const pins = note.pins.map(pin => pinTarget(pin)).map(pin => pin?.symbol || pin?.file || "invalid pin");
+    return `${note.name}: ${note.failed ? "failed" : result.status} — ${pins.join(", ") || "no pins"}${note.diagnostics.map(message => `\n  ${message}`).join("")}`;
+  }).join("\n");
+}

package/lib/memory-pins.mjs

@@ -0,0 +1,153 @@
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, openSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { dep } from "./dep.mjs";
+
+const { isMap, parseDocument } = await dep("yaml");
+const { z } = await dep("zod");
+
+export function fingerprint(text) {
+  const normalized = text.replace(/\r\n/g, "\n").split("\n")
+    .map(line => line.trimEnd()).join("\n").replace(/^\n+|\n+$/g, "");
+  return `sha256:${createHash("sha256").update(normalized, "utf8").digest("hex").slice(0, 16)}`;
+}
+
+export function memoryDirectory(project, configDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude")) {
+  return join(configDir, "projects", resolve(project).replace(/[^a-zA-Z0-9]/g, "-"), "memory");
+}
+
+export function frontMatter(text) {
+  const match = /^(---\r?\n)([\s\S]*?)(^---(?:\r?\n|$))/m.exec(text);
+  if (!match || match.index !== 0) {
+    if (/^---\r?\n/.test(text)) throw new Error("unterminated front matter");
+    return null;
+  }
+  const document = parseDocument(match[2]);
+  if (document.errors.length) throw new Error(`invalid front matter: ${document.errors[0].message.split("\n")[0]}`);
+  if (document.contents && !isMap(document.contents)) throw new Error("front matter must be a mapping");
+  return { document, yaml: match[2], start: match[1].length, end: match[0].length };
+}
+
+export function notePins(text) {
+  try {
+    const front = frontMatter(text);
+    const data = front?.document.toJS();
+    if (!data || data.pins == null) return [];
+    return Array.isArray(data.pins) ? data.pins : [data.pins];
+  } catch (error) {
+    return [{ invalid: error.message.split("\n")[0] }];
+  }
+}
+
+const fileSchema = z.string().min(1).refine(file => !isAbsolute(file)
+  && !file.split(/[\\/]/).some(part => part === ".." || part === "" || part === "."));
+const symbolSchema = z.object({
+  symbol: z.string().refine(symbol => {
+    const split = symbol.lastIndexOf("#");
+    return split > 0 && split < symbol.length - 1 && fileSchema.safeParse(symbol.slice(0, split)).success;
+  }),
+  fp: z.string().regex(/^sha256:[0-9a-f]{16}$/),
+}).passthrough().refine(pin => !Object.hasOwn(pin, "file"));
+const pinSchema = z.union([
+  symbolSchema,
+  z.object({ file: fileSchema }).passthrough()
+    .refine(pin => !Object.hasOwn(pin, "symbol") && !Object.hasOwn(pin, "fp")),
+]);
+
+export function pinTarget(pin) {
+  const parsed = pinSchema.safeParse(pin);
+  if (!parsed.success) return null;
+  const value = parsed.data;
+  return value.symbol ? { file: value.symbol.slice(0, value.symbol.lastIndexOf("#")), symbol: value.symbol }
+    : { file: value.file };
+}
+
+export function checkPin(pin, project, nodes) {
+  try { return checkTarget(pin, project, nodes); }
+  catch (error) { return { pin, status: "invalid pin", detail: error.message }; }
+}
+
+function checkTarget(pin, project, nodes) {
+  const target = pinTarget(pin);
+  if (!target) return { pin, status: "invalid pin", detail: pin?.invalid || "expected symbol + fp, or file without fp" };
+  const path = join(project, target.file);
+  if (!existsSync(path) || !statSync(path).isFile()) return { pin, status: "broken", detail: `file gone: ${target.file}` };
+  if (!target.symbol) return { pin, status: "ok" };
+  const node = nodes.get(target.symbol);
+  if (!node) return { pin, status: "broken", detail: `symbol gone: ${target.symbol}` };
+  const actual = symbolFingerprint(project, node);
+  return actual === pin.fp ? { pin, status: "ok" }
+    : { pin, status: "stale", actual, detail: `body changed: ${target.symbol} (${pin.fp} -> ${actual})` };
+}
+
+export function symbolFingerprint(project, node) {
+  const span = /^L(\d+)-L(\d+)$/.exec(node.span);
+  const lines = readFileSync(join(project, node.path), "utf8").replace(/\r\n/g, "\n").split("\n");
+  if (!span || +span[1] < 1 || +span[2] < +span[1] || +span[2] > lines.length) {
+    throw new Error(`invalid graft span for ${node.id}; run graft build`);
+  }
+  return fingerprint(lines.slice(+span[1] - 1, +span[2]).join("\n"));
+}
+
+export function pinFileNewer(project, pin, graphTime) {
+  const target = pinTarget(pin);
+  if (!target) return false;
+  try { return statSync(join(project, target.file)).mtimeMs > graphTime; }
+  catch { return false; }
+}
+
+export function refreshPinGraph(project, pins = []) {
+  const graphPath = join(project, "graft", ".graph", "wiring.json");
+  if (!existsSync(graphPath)) return null;
+  const needsBuild = () => pins.some(pin => pinFileNewer(project, pin, statSync(graphPath).mtimeMs));
+  if (needsBuild()) {
+    const lockPath = `${graphPath}.lock`;
+    const deadline = Date.now() + 125000;
+    let lock;
+    while (lock === undefined) {
+      try { lock = openSync(lockPath, "wx"); }
+      catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        if (Date.now() >= deadline) throw new Error("timed out waiting for graft build lock");
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+      }
+    }
+    try {
+      // Another note writer may have refreshed the graph while we waited.
+      if (needsBuild()) {
+        const build = spawnSync("graft", ["build", project, "--no-gitignore", "--no-ignore"], {
+          encoding: "utf8", timeout: 120000, maxBuffer: 16 * 1024 * 1024,
+        });
+        if (build.error || build.status !== 0) throw new Error(`graft build failed: ${build.error?.message || build.stderr || build.stdout}`);
+      }
+    } finally { closeSync(lock); unlinkSync(lockPath); }
+  }
+  const graph = JSON.parse(readFileSync(graphPath, "utf8"));
+  if (!Array.isArray(graph.nodes)) throw new Error("invalid graft wiring graph: missing nodes");
+  return new Map(graph.nodes.map(node => [node.id, node]));
+}
+
+export function checkMemory({ project = process.cwd(), memoryDir = memoryDirectory(project) } = {}) {
+  project = resolve(project);
+  const graphPath = join(project, "graft", ".graph", "wiring.json");
+  if (!existsSync(graphPath)) return { project, status: "pins off", message: "no graft graph, pins off", notes: [] };
+  const notes = existsSync(memoryDir) ? readdirSync(memoryDir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith(".md") && entry.name !== "MEMORY.md")
+    .map(entry => ({ name: entry.name, pins: notePins(readFileSync(join(memoryDir, entry.name), "utf8")) })) : [];
+  let nodes = new Map();
+  if (notes.some(note => note.pins.some(pin => pinTarget(pin)?.symbol))) {
+    try { nodes = refreshPinGraph(project, notes.flatMap(note => note.pins)); }
+    catch (error) { return { project, status: "pins off", message: `pins off: ${error.message}`, notes: [] }; }
+  }
+  return { project, status: "checked", notes: notes.map(note => ({
+    name: note.name, pins: note.pins.map(pin => checkPin(pin, project, nodes)),
+  })) };
+}
+
+export function formatMemoryCheck(result) {
+  if (result.message) return result.message;
+  return result.notes.flatMap(note => note.pins.filter(pin => pin.status !== "ok")
+    .map(pin => `${note.name}: ${pin.status} — ${pin.detail}`)).join("\n") || `ok: ${result.notes.length} notes, ${result.notes.reduce((sum, note) => sum + note.pins.length, 0)} pins`;
+}

package/lib/seat-compaction.mjs

@@ -0,0 +1,34 @@
+// #11559: seats run long cards in ONE opencode session (#6134's design), and opencode only
+// auto-compacts when the context is FULL - far past 100K on big-limit models. The knob is the
+// top-level `compaction` block (schema: opencode.ai/config.json), injected per seat via
+// OPENCODE_CONFIG_CONTENT (override: TRANTOR_OC_COMPACTION), which MERGES with the operator's global config.
+
+export const OC_COMPACTION_ENV = "TRANTOR_OC_COMPACTION";
+
+// The seat default: compaction on, old tool outputs pruned, a small recent window preserved.
+// `reserved` is the buffer subtracted from the model's window before opencode calls the context
+// full, so a larger value fires compaction earlier. Override the whole block with
+// TRANTOR_OC_COMPACTION=<json>, or set it to "off" to ship no config content at all.
+export const OC_COMPACTION_DEFAULT = {
+  auto: true,
+  prune: true,
+  tail_turns: 4,
+  preserve_recent_tokens: 24_000,
+  reserved: 64_000,
+};
+
+/// A JSON string for OPENCODE_CONFIG_CONTENT, or "" when nothing should be injected: "off" opts
+/// out, invalid JSON opts out loudly at the caller (never arms a half-parsed block), custom JSON
+/// is wrapped as { compaction: <the value> } so the env stays one knob.
+export function ocCompactionContent(env = process.env) {
+  const raw = String(env[OC_COMPACTION_ENV] || "").trim();
+  if (raw === "off") return "";
+  if (!raw) return JSON.stringify({ compaction: OC_COMPACTION_DEFAULT });
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return ""; }
+  // SAFETY: the operator's raw JSON arrives here untyped — a bare number, string or null must
+  // opt OUT (no config), never arm a half-shaped compaction block at every opencode seat.
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return "";
+  return JSON.stringify({ compaction: parsed });
+}

package/lib/seat-tokens.mjs

@@ -0,0 +1,72 @@
+// #11559: the seat fleet's token burn was invisible — mined by hand from opencode's DB. This
+// reader makes it a command: per-provider 30-day session/step/token totals, read-only, so a
+// week-over-week comparison is one line. No DB at all is "no data", never zero. Read path
+// mirrors lib/turn-usage.mjs (sqlite3 CLI, -readonly, fail-open).
+import { spawnSync } from "node:child_process";
+
+const num = (v) => { const n = Number(v); return Number.isInteger(n) && n >= 0 ? n : 0; };
+
+/// "provider/model" → "provider"; a bare model reads "?" so the row still groups. The 1.16.x DB
+/// also stores whole JSON blobs ({"id":…,"providerID":…,"variant":…}) in session.model — the
+/// provider then lives at $.providerID. The SQL mirrors this in CASE/WHEN form.
+export function providerOf(model) {
+  const s = String(model || "").trim();
+  if (s.startsWith("{")) {
+    try { return String(JSON.parse(s).providerID || "?"); } catch { return "?"; }
+  }
+  const at = s.indexOf("/");
+  return at > 0 ? s.slice(0, at) : "?";
+}
+
+const PROVIDER_SQL = (col) => `CASE WHEN substr(${col},1,1)='{' THEN COALESCE(json_extract(${col},'$.providerID'),'?')`
+  + ` WHEN instr(${col},'/')>1 THEN substr(${col},1,instr(${col},'/')-1) ELSE '?' END`;
+
+export const SESSIONS_SQL = (sinceMs) => `SELECT ${SESSION_COLS} FROM session`
+  + ` WHERE time_updated>=${Math.floor(sinceMs)} GROUP BY p ORDER BY total DESC;`;
+const SESSION_COLS = `${PROVIDER_SQL("model")} AS p, COUNT(*) AS sessions,`
+  + ` COALESCE(SUM(tokens_input),0), COALESCE(SUM(tokens_output),0), COALESCE(SUM(tokens_cache_read),0),`
+  + ` COALESCE(SUM(tokens_cache_write),0), COALESCE(SUM(cost),0), COALESCE(MIN(time_created),0),`
+  + ` COALESCE(MAX(time_updated),0), COALESCE(SUM(tokens_input+tokens_output+tokens_cache_read+tokens_cache_write),0) AS total`;
+
+export const STEPS_SQL = (sinceMs) => `SELECT ${PROVIDER_SQL("s.model")} AS p,`
+  + ` COUNT(m.id), COALESCE(MAX(json_extract(m.data,'$.tokens.input')),0)`
+  + ` FROM message m JOIN session s ON s.id=m.session_id`
+  + ` WHERE json_extract(m.data,'$.role')='assistant' AND m.time_created>=${Math.floor(sinceMs)} GROUP BY p;`;
+
+const pipeRows = (text, cols) => String(text || "").split("\n").filter((l) => l.trim() !== "")
+  .map((line) => {
+    const parts = line.split("|");
+    return parts.length === cols ? parts : null;
+  })
+  .filter(Boolean);
+
+/// { provider, sessions, input, output, cacheRead, cacheWrite, cost, firstAt, lastAt, tokens,
+///   steps, peakInput } per provider, tokens descending. [] when both queries return nothing —
+/// an empty fleet and an unreadable DB print the same "no data" line, never zeros that lie.
+export function seatTokensReport({ dbPath, sinceMs, run = spawnSync } = {}) {
+  if (!dbPath || !Number.isFinite(sinceMs)) return [];
+  const q = (sql) => {
+    let r;
+    try { r = run("sqlite3", ["-readonly", dbPath, sql], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 15000 }); }
+    catch { return null; }
+    return !r || r.error || r.status !== 0 ? null : r.stdout;
+  };
+  const sessions = pipeRows(q(SESSIONS_SQL(sinceMs)), 10);
+  const steps = pipeRows(q(STEPS_SQL(sinceMs)), 3);
+  const byProvider = new Map(sessions.map((c) => [c[0], {
+    provider: c[0],
+    sessions: num(c[1]),
+    input: num(c[2]), output: num(c[3]), cacheRead: num(c[4]), cacheWrite: num(c[5]),
+    cost: Number(c[6]) || 0,
+    firstAt: num(c[7]), lastAt: num(c[8]),
+    tokens: num(c[9]),
+    steps: 0, peakInput: 0,
+  }]));
+  for (const [p, count, peak] of steps) {
+    const row = byProvider.get(p);
+    if (!row) continue;
+    row.steps = num(count);
+    row.peakInput = num(peak);
+  }
+  return [...byProvider.values()].sort((a, b) => b.tokens - a.tokens);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.92",
+  "version": "0.18.94",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"
@@ -8,6 +8,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "pg": "^8.22.0",
+    "yaml": "^2.9.1",
     "zod": "^4.4.3"
   },
   "scripts": {