trantor 0.18.62 → 0.18.64

package/docs/BUILD-DOCTRINE.md

@@ -0,0 +1,117 @@
+# Build doctrine
+
+How Trantor is built, and how every project run through Trantor is built. These are rules with
+a gate each, not advice. An orchestrator that cannot show the gate has not followed the rule.
+Operator ruling 2026-09-04, after a week in which the code was heavily tested and still broke on
+the real path four times.
+
+## 1. The real path is the gate
+
+- Every card names its drill: the exact thing a person does on the built artifact and what they
+  must see. A card without a drill line is not ready to be worked.
+- Nothing merges until the orchestrator has run that drill on the built artifact (the installed
+  app, the live hub, the real CLI on this machine) and written the result on the card.
+- Unit tests are necessary and never sufficient. "All tests green" is not evidence that the
+  operator will see the feature work.
+- The seat that wrote the code never closes its own card to done. Testing is the seat's last
+  move; done is the orchestrator's, after the drill.
+
+## 2. Red blocks merge
+
+- The whole suite runs on every push in CI. A red suite blocks merge, no exceptions.
+- A suite red for more than one day is an incident with a card, not debt to be gated around.
+- A flaky test is fixed or deleted within a week. Timing drills live in a quarantine lane that
+  cannot hide a real failure.
+- Tests never depend on the runner's own environment (identity badge, pane id, project). A test
+  that inherits the badge and passes is lying.
+
+## 3. One owner per subsystem
+
+- Every subsystem (runner, hub, hooks, crew launcher, desktop shell, chat, code, board) has one
+  named owner per wave. The owner reviews every change to it and may say no.
+- A cross-seat edit to a subsystem goes through its owner over the bus before it lands.
+- The orchestrator owns the gates and the merges. No seat merges to main.
+
+## 4. Causes, not symptoms
+
+- A fix names its cause in the commit message and adds the drill that fails without the fix.
+  "Made X not happen" without a why is bounced.
+- A second fix in the same seam within a week stops the line: the seam gets a contract document
+  (docs/CONTRACT-*.md) reviewed by the orchestrator before more code lands there.
+- Trace first. A bug report becomes a card only after the orchestrator has the trace, log, or
+  crash report line that shows the mechanism. Guessing is not a plan.
+
+## 5. Fewer parts
+
+- Prefer deleting to patching. A subsystem that has needed three fixes in a month is a candidate
+  for removal, not a fourth fix.
+- No hand-rolled protocol, transport, sync, or auth layer when a maintained library does the job.
+  If the library is installed, use it the way it is meant to be used; do not bypass it.
+- Look at the reference product first (the Orca rule). Adopt its shape, then adapt. Inventing is
+  the last option and needs a stated reason.
+
+## 6. Shape limits
+
+- A source file is at most 800 lines (Rust 1,000). A function is at most 80 lines. Past the
+  limit, split by feature before adding to it.
+- One language per layer. A shell script that parses JSON becomes a Node program.
+- A module has one reason to change. A file named after a card, a date, or a person is wrong.
+
+## 7. Comments and records
+
+- A code comment is one line of why. The incident story lives on the card or in docs, and the
+  comment links to it by number.
+- Contracts live in docs/CONTRACT-*.md and are the source of truth for a seam. Code that
+  contradicts a contract is the bug, whichever came second.
+- Memory records decisions and traps, not code structure. The repo records code.
+
+## 8. Rust and native boundaries
+
+- No `unwrap` or `expect` outside tests. Clippy denies `unwrap_used` and `expect_used`.
+- Every callback boundary into native code (extern "C", event handlers, window callbacks)
+  catches panics and logs them. A panic there aborts the app, and the crash report will not say
+  why.
+- A patched or vendored dependency carries the upstream issue link and an expiry date in its
+  directory. Past the expiry, it is re-evaluated, not kept by default.
+
+## 9. Dependencies and releases
+
+- Dependencies are pinned. An upgrade is a card with a drill, never a side effect.
+- A release is: version bump, build, install on the operator's machine, drill, card note, memory
+  line. Published is not shipped; installed and drilled is shipped.
+- Every substantive change reports with the four evidence blocks: code written, builds (command
+  and exit code), tested (command and counts), observed (the drill result). A report missing one
+  says which and why.
+
+## 10. Turn economy
+
+- A seat's turn ends with a commit. Work that is not committed does not exist.
+- A contract names the card, the files, the gate, and the drill. It never says "look into".
+- No acks over the bus. A message either carries a contract, a bounce, a delivery, or a question
+  that blocks work. Everything else is batched or not sent.
+- A seat that exits non-zero twice on one contract parks. The orchestrator reads why before
+  anything is redelivered.
+
+## 11. Anything that warns
+
+The monitoring doctrine applies: state, not event; episodes, not timers; never warn about what
+the operator declared; report duration, not repetition; quiet is not dead; every wake costs a
+turn.
+
+## 12. Seats never touch the operator's live surfaces
+
+- A seat never launches, quits, installs or replaces the installed app; never drives the running
+  app's UI; never logs the operator into or out of any provider; never runs `trantor up`, `down`
+  or `open` for any seat, its own included. These are the operator's surfaces and the
+  orchestrator's hands.
+- A seat's real-path evidence ends at: tests green, a build that exits 0 from its own worktree,
+  and a note naming the drill. The orchestrator runs the drill, with the operator when it touches
+  a live account.
+- A seat dispatches no sessions of its own outside its worktree. Work that leaves the worktree
+  does not exist.
+
+## 13. Audit
+
+A project is audited against this document before its next wave: file shape, test tree and CI,
+owners, real-path drills, dependency pins, comment policy. The audit produces a scorecard and a
+consolidation phase, and the wave waits for the phase where the scorecard says so.

package/engine/bin/scrooge

@@ -553,14 +553,16 @@ def cmd_call(reg, args):
     try:
         resp = http_post(url, headers, payload)
     except urllib.error.HTTPError as e:
-        body = e.read().decode(errors="replace")[:500]
+        # ONE stderr line naming the status and the model (#6893): a provider body with
+        # newlines must not smear the ✗ across the caller's log — collapse, then clamp.
+        body = " ".join(e.read().decode(errors="replace").split())[:500]
         err(RED("🪙 scrooge ✗ %s/%s HTTP %s: %s" % (provider, model, e.code, body)))
         append_ledger({"ts": int(t0), "provider": provider, "model": model, "task": args.task,
                        "project": proj, "cwd": cwd,
                        "ok": False, "error": "HTTP %s" % e.code, "duration_ms": int((time.time()-t0)*1000)})
         raise SystemExit(2)
     except Exception as e:
-        err(RED("🪙 scrooge ✗ %s/%s: %s" % (provider, model, e)))
+        err(RED("🪙 scrooge ✗ %s/%s: %s" % (provider, model, " ".join(str(e).split()))))
         append_ledger({"ts": int(t0), "provider": provider, "model": model, "task": args.task,
                        "project": proj, "cwd": cwd,
                        "ok": False, "error": str(e), "duration_ms": int((time.time()-t0)*1000)})
@@ -586,6 +588,12 @@ def cmd_call(reg, args):
                              "prompt_preview": preview})
     err(ORANGE("🪙 scrooge ✓ %s/%s · %d→%d tok · ~$%.5f · %.1fs%s" %
                (provider, model, tin, tout, c, dt, (" · ledger#%d" % line_no) if line_no else "")))
+    # A genuinely empty model answer is a SUCCESS the caller must be able to tell from a
+    # failed call (#6893): exit 0, stdout stays EMPTY (not even a newline), and stderr
+    # carries the "empty answer" note — the ✗/exit-2 path is the only other possibility.
+    if not text.strip():
+        err(DIM("🪙 scrooge · empty answer"))
+        return
     sys.stdout.write(text)
     if not text.endswith("\n"):
         sys.stdout.write("\n")

package/hooks/handoff-now.mjs

@@ -14,11 +14,18 @@ try {
   const { file, record } = result;
   process.stderr.write(`[trantor] baton handoff written: ${file}\n`);
   await pingBus(basename(projectDir), record.id, conf);
-  if (maybeSpawn(projectDir, conf)) {                 // open the fresh session that takes over
+  // The handoff file goes in: a pane baton cannot be driven without it (#8089).
+  if (maybeSpawn(projectDir, conf, file)) {           // open the fresh session that takes over
     // AUTO baton: close the original ONLY when config.autoCloseOriginal is true; an auto-close must
-    // never kill an in-flight session, so the default leaves the original alive.
+    // never kill an in-flight session, so the default leaves the original alive. A pane baton
+    // replaces its own pane and resolves no window, so there is nothing here to arm.
     const armed = windowId ? armBatonClose(file, windowId, tty, conf, { auto: true }) : false;
     process.stderr.write(`[trantor] fresh session spawned${armed ? ` · baton-close armed for window ${windowId}` : " · original window left alive (auto-close off by default)"}\n`);
+  } else {
+    // #8089's second half: this used to be an `if` with no `else`, so a declined spawn printed
+    // NOTHING. The record was written, no successor came, and the only evidence was a handoff stuck
+    // at `written`. A path that decides not to act still has to say so.
+    process.stderr.write(`[trantor] NO successor session opened for ${basename(projectDir)} — handoff ${basename(file)} is written but unclaimed; open one to take over\n`);
   }
 } catch (e) {
   process.stderr.write(`[trantor] handoff-now error: ${e?.message || e}\n`);

package/hooks/lib/handoff.mjs

@@ -738,26 +738,58 @@ export async function pingBus(projectName, id, conf = readConfig()) {
 // Spawn a fresh same-agent session (macOS) that takes over via the handoff.
 // Default = ON (prompt with a timeout, default button "Open fresh session").
 // Disable with config.autoHandoffPrompt:false or env TRANTOR_NO_HANDOFF_SPAWN=1.
-export function maybeSpawn(projectDir, conf = readConfig()) {
+export function maybeSpawn(projectDir, conf = readConfig(), handoffFile = "", deps = {}) {
+  // Injection points, for the same reason spawnBaton has them: "A DRILL MUST BE ABLE TO SAY NO —
+  // a path that spawns windows needs an off switch or it cannot be tested honestly." maybeSpawn had
+  // none, so its pane branch was never drilled, and that is exactly where #8089 lived for weeks.
+  const _pane = deps.paneSurfaceEnv || paneSurfaceEnv;
+  const _spawnPane = deps.spawnPaneBaton || spawnPaneBaton;
+  const _hasPane = deps.hasOrchPane || hasOrchPane;
+  const _platform = deps.platform || process.platform;
+  const _env = deps.env || process.env;
+  const _log = deps.log || ((s) => process.stderr.write(s));
   try {
-    if (process.platform !== "darwin") return false;
-    if (process.env.TRANTOR_NO_HANDOFF_SPAWN === "1") return false;
-    // #6074: a session in a hosted pane never gets a Terminal window — the pane is the successor
-    // surface, and the pane claims the handoff (trantor open) on its own.
-    if (paneSurfaceEnv()) {
-      process.stderr.write(`[trantor] session lives in herdr pane ${paneSurfaceEnv()} — no Terminal window; the pane claims the handoff\n`);
-      return false;
+    if (_platform !== "darwin") return false;
+    if (_env.TRANTOR_NO_HANDOFF_SPAWN === "1") return false;
+    // #8089: a pane session gets NO Terminal window — but it does get a successor. This used to
+    // return false on the theory that "the pane claims the handoff (trantor open) on its own",
+    // and for an ARMED baton nothing was driving that: /trantor:handoff always runs inside a turn,
+    // so it always arms, so this is always the path taken — and spawnPaneBaton, which the direct
+    // path (spawnBaton) calls right here, was never reached. The record was written and the session
+    // sat there. Witnessed on crebral-health 2026-09-19: written 00:18:58, unclaimed, original alive.
+    const paneId = _pane(_env);
+    if (paneId) {
+      if (!handoffFile) {
+        _log(`[trantor] pane ${paneId} needs the handoff file to pass the baton and none was given — no successor opened\n`);
+        return false;
+      }
+      const ok = _spawnPane(projectDir, handoffFile, paneId);
+      _log(`[trantor] herdr pane ${paneId}: ${ok ? "baton driver spawned — it replaces this pane in place" : "baton driver FAILED to spawn — no successor"}\n`);
+      return ok;
     }
     if (conf.autoHandoffPrompt === false) return false;
-    if (hasOrchPane(basename(projectDir))) {
-      process.stderr.write(`[trantor] orch pane hosts ${basename(projectDir)} — no Terminal window; the pane claims the handoff on its next open\n`);
-      return false;
+    if (_hasPane(basename(projectDir))) {
+      // Same correction as above for the cwd-keyed pane: drive the replacement, do not assume
+      // something else will. Without HERDR_PANE_ID the driver resolves the pane from crew-windows.
+      if (!handoffFile) {
+        _log(`[trantor] orch pane hosts ${basename(projectDir)} but no handoff file was given — no successor opened\n`);
+        return false;
+      }
+      const ok = _spawnPane(projectDir, handoffFile);
+      _log(`[trantor] orch pane hosts ${basename(projectDir)}: ${ok ? "baton driver spawned — it replaces the pane in place" : "baton driver FAILED to spawn — no successor"}\n`);
+      return ok;
     }
     const script = join(HERE, "..", "..", "bin", "handoff-prompt.sh");
-    if (!existsSync(script)) { process.stderr.write(`[trantor] handoff-prompt.sh missing\n`); return false; }
+    if (!existsSync(script)) { _log(`[trantor] handoff-prompt.sh missing\n`); return false; }
     const timeout = String(conf.handoffPromptTimeout || 25);
-    const child = spawn("/bin/bash", [script, projectDir, timeout], { detached: true, stdio: "ignore" });
-    child.unref();
+    // Injectable for the same reason the pane legs are: this line opens a REAL Terminal window, and
+    // a drill that reaches it opens one per run. That is not hypothetical — test-pane-baton-spawn's
+    // "no pane" case fell through to here and opened a window on every `npm test`, with a comment
+    // above it claiming the drill did not exercise this leg. Four of them were sitting on the
+    // operator's desktop before anyone noticed, and only a non-existent fixture path stopped each
+    // one from starting a live billable session.
+    const child = (deps.spawnPrompt || spawn)("/bin/bash", [script, projectDir, timeout], { detached: true, stdio: "ignore" });
+    if (child && typeof child.unref === "function") child.unref();
     return true;
   } catch (e) { process.stderr.write(`[trantor] maybeSpawn error: ${e?.message}\n`); return false; }
 }

package/hooks/sessionstart.mjs

@@ -16,6 +16,30 @@ 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";
 
+// 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.
+// test/hooks/test.mjs checks every heading of the doc has a line here, so the two cannot drift.
+function buildDoctrineShortForm() {
+  const doc = join(dirname(dirname(fileURLToPath(import.meta.url))), "docs", "BUILD-DOCTRINE.md");
+  return `<trantor-build-doctrine>\n` +
+    `📐 **Build doctrine** (operator ruling 2026-09-04; rules with a gate each, not advice). Full text: ${doc}\n` +
+    `1. The real path is the gate — every card names its DRILL (what a person does on the built artifact and must see); nothing merges until you ran it and wrote the result on the card; unit tests are never sufficient; the seat that wrote the code never closes its own card to done (testing is the seat's last move, done is yours after the drill).\n` +
+    `2. Red blocks merge — a red suite blocks merge; red for a day is an incident with a card; a flaky test is fixed or deleted within a week; no test inherits the runner's identity.\n` +
+    `3. One owner per subsystem — one named owner per wave who reviews every change; cross-seat edits go through the owner over the bus; you own the gates and merges, no seat merges to main.\n` +
+    `4. Causes, not symptoms — a fix names its cause in the commit and adds the drill that fails without it; a second fix in one seam within a week stops the line for a docs/CONTRACT-*.md; trace first, a bug becomes a card only with the mechanism in hand.\n` +
+    `5. Fewer parts — prefer deleting to patching (three fixes in a month = removal candidate); no hand-rolled protocol/transport/sync/auth when a maintained library does it; look at the reference product first (the Orca rule).\n` +
+    `6. Shape limits — a file is at most 800 lines (Rust 1,000), a function at most 80; one language per layer; a module has one reason to change and is never named after a card, date or person.\n` +
+    `7. Comments and records — a code comment is one line of why linking the card; contracts live in docs/CONTRACT-*.md and code that contradicts one is the bug; memory records decisions and traps, the repo records code.\n` +
+    `8. Rust and native boundaries — no unwrap/expect outside tests (clippy denies them); every callback into native code catches and logs panics; a patched/vendored dependency carries its upstream link and an expiry date.\n` +
+    `9. Dependencies and releases — dependencies are pinned and an upgrade is a card with a drill; a release is bump, build, install on the operator's machine, drill, card note, memory line (published is not shipped); every report carries the four evidence blocks: code, build, tests, observed.\n` +
+    `10. Turn economy — a seat's turn ends with a commit (uncommitted work does not exist); a contract names card, files, gate and drill, never "look into"; no acks over the bus; a seat that exits non-zero twice on one contract parks.\n` +
+    `11. Anything that warns — the monitoring doctrine: state not event, episodes not timers, never warn about what the operator declared, report duration not repetition, quiet is not dead, every wake costs a turn.\n` +
+    `12. Seats never touch the operator's live surfaces — a seat never launches/quits/installs the app, drives its UI, logs into providers, or runs trantor up/down/open; its evidence ends at tests green, a build from its worktree and a note naming the drill; you run the drill.\n` +
+    `13. Audit — a project is audited against the doctrine before its next wave (file shape, tests and CI, owners, drills, pins, comments); the wave waits for the consolidation phase the scorecard demands.\n` +
+    `Mechanics: relay_task_add has a \`drill\` field; the hub refuses any move to done, yours included, when the card carries no drill line.\n` +
+    `</trantor-build-doctrine>\n`;
+}
+
 // Load the most recent UNCONSUMED handoff for this project; `claim` marks it consumed so exactly one
 // session takes it. A compaction-triggered start may show it but must NOT claim it from the new window.
 function loadPendingHandoff(projectName, { claim = true, freshSession = null } = {}) {
@@ -366,6 +390,7 @@ try {
         `- Check relay_inbox and the board before asking the operator anything a peer may already have answered.\n` +
         `- Dispatch rule: the target project is confirmed from the session's badge and cwd before any relay_send, relay_task_add or \`trantor up\` — an ambiguous instruction is not a project name; and a session asking the operator a question never triggers a wake (its messages batch until the answer).\n` +
         `</trantor-orchestrator-role>\n`;
+      additionalContext += buildDoctrineShortForm();
       process.stderr.write(`[trantor] injected orchestrator-role doctrine for ${project}\n`);
     }
   } catch {}

package/hub/routes/cards.mjs

@@ -26,7 +26,7 @@ export async function routeCards({ req, res, q, P, auth, ctx }) {
   const {
     state, body, json, crossProjectGuard, touch, canon, filterReadable,
     appendEvent, appendCardEvent, now, markDirty, stripNulText,
-    appendTaskLog, appendTaskNote, cleanChecklist, linkCommitToFocus,
+    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,
@@ -177,6 +177,7 @@ export async function routeCards({ req, res, q, P, auth, ctx }) {
         by: b.by || "", ts: ts0, updated: ts0,
         history: [{ to: st0, by: b.by || "", ts: ts0 }] };
       { const cl = cleanChecklist(b.checklist); if (cl?.length) t.checklist = cl; }   // #5624 — rides `extra`, survives restarts
+      { const dr = cleanDrill(b.drill); if (dr) t.drill = dr; }                        // #6452 — the card's drill line, rides `extra`
       if (b.source === "cc-subagent") { t._fp = subFp(b.title); if (b.agentType) t._atype = String(b.agentType).slice(0, 40); if (b.agentId) t._aid = String(b.agentId).slice(0, 80); if (b.parent) t.parent = String(b.parent).slice(0, 120); t.count = 1; if (t.status === "doing") { t._everStarted = true; t._inflight = 1; } }
       appendTaskNote(t, b, ts0);
       state.tasks.push(t); if (state.tasks.length > 2000) state.tasks.splice(0, 500);
@@ -210,6 +211,12 @@ export async function routeCards({ req, res, q, P, auth, ctx }) {
           }
         }
       }
+      // The done gate (#6452, build doctrine rule 1): done only with a drill line (store.hasDrillLine),
+      // whoever moves it, the orchestrator included. Runs BEFORE any mutation so a refused close leaves
+      // the card as it was; a bridge mirror replicates a status its source hub already gated.
+      if (b.status === "done" && t.status !== "done" && t.source !== "bridge" && !hasDrillLine(t, b)) {
+        return json(res, 409, { error: `no drill line on card #${t.id}: a card names what a person does on the built artifact and must see before it can be done — set \`drill\`, add a checklist item or a note starting with "Drill:", or close with a note naming the gate command you ran (build doctrine rule 1)`, id: t.id, status: t.status });
+      }
       let eventType = "updated", eventFrom = null, eventTo = null;
       if (b.status && ["todo","doing","testing","failed","done","blocked","stale"].includes(b.status) && b.status !== t.status) {
         eventType = "moved"; eventFrom = t.status; eventTo = b.status;
@@ -238,6 +245,7 @@ export async function routeCards({ req, res, q, P, auth, ctx }) {
       // the narrative line a human reads on the board ("assigned — did"), written by the cheap
       // summarizer; rides the tasks.extra column, so it survives restarts everywhere
       if (b.summary !== undefined) t.summary = String(b.summary).slice(0, 220);
+      if (b.drill !== undefined) { const dr = cleanDrill(b.drill); if (dr) t.drill = dr; else delete t.drill; }   // #6452: set or clear the drill line
       // #5624: full checklist replace (null clears). Item-level toggles ride /task/checklist-toggle.
       if (b.checklist !== undefined) {
         const cl = cleanChecklist(b.checklist);

package/hub/store.mjs

@@ -44,6 +44,24 @@ function appendTaskNote(t, b, ts = Date.now()) {
   if (!b || typeof b.note !== "string") return false;
   return appendTaskLog(t, b.by || "", b.note, ts);
 }
+// #6452: a card's drill line (build doctrine rule 1) — the `drill` field, a checklist item or a log
+// note starting "Drill:", or the move's own note; that note also counts when it names the gate
+// command it ran (the orchestrator closes with "verified at <sha>" + the gate). The command shapes
+// mirror hooks/lib/hollow-move.mjs, minus bare pass counts: "12/12" names no gate.
+const DRILL_MAX = 300;
+const DRILL_LINE = /^\s*drill:/i;
+const GATE_CMD = /(node\s+test\/|npm\s+(run\s+)?test|pnpm\s+test|yarn\s+test|vitest|pytest|go\s+test|cargo\s+test|make\s+test)/i;
+function cleanDrill(v) {
+  const s = stripNulText(v).replace(/\s+/g, " ").trim();
+  return s ? s.slice(0, DRILL_MAX) : "";
+}
+function hasDrillLine(t, b = {}) {
+  if (cleanDrill(b.drill) || cleanDrill(t.drill)) return true;
+  if (Array.isArray(t.checklist) && t.checklist.some(c => DRILL_LINE.test(String(c?.text ?? "")))) return true;
+  if (Array.isArray(t.log) && t.log.some(e => DRILL_LINE.test(String(e?.text ?? "")))) return true;
+  return typeof b.note === "string" && (DRILL_LINE.test(b.note) || GATE_CMD.test(b.note));
+}
+
 // Card checklists (#5624): acceptance items are the one honest denominator for a progress bar.
 // Accepts plain strings (fresh items) or {text,done} (round-trips); caps 20 items x 200 chars.
 // Returns null for a non-array so callers can distinguish "not sent" from "sent empty".
@@ -106,11 +124,9 @@ function normalizeState(loaded = {}) {
     // migrate old numeric form
     s.peers[session] = typeof v === "number"
       ? { lastSeen: v, status: "", project: "" }
-      // #6170: `kind` must be carried across the load. This normalizer rebuilds every peer from an
-      // explicit field list, so a field missing here is dropped no matter how faithfully the store
-      // returned it — which is exactly what happened: the column was added, Postgres held the right
-      // values, and the kinds still came back empty on the first live restart. llm/model stay
-      // out on purpose: those ARE in-memory presence, re-supplied by the next heartbeat.
+      // #6170: `kind` rides the load. This normalizer rebuilds every peer from an explicit field
+      // list, so a field missing here is dropped however faithfully the store returned it (the kinds
+      // came back empty on the first live restart). llm/model stay out: they are in-memory presence.
       : { lastSeen: v.lastSeen || 0, status: v.status || "", project: v.project || "", pubkey: v.pubkey || "", identity: v.identity || null, authWarning: v.authWarning || "", hookVersion: v.hookVersion || "", kind: v.kind || "", deliveredUpTo: v.deliveredUpTo || v.delivered_up_to || 0, _on: v._on === true || v.online === true };
   }
   return s;
@@ -240,6 +256,6 @@ setInterval(persist, persistTickMs).unref?.();
 
   return {
     state, durableStore, persist, persistHealth, markDirty, reload, startChangeSubscription,
-    HUB_SRC, appendTaskLog, appendTaskNote, cleanChecklist, stripNulText,
+    HUB_SRC, appendTaskLog, appendTaskNote, cleanChecklist, cleanDrill, hasDrillLine, stripNulText,
   };
 }

package/lib/autonomy.mjs

@@ -3,6 +3,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
+import { asRecord } from "./decode.mjs";
 
 export const AUTONOMY_PATH = () =>
   join(process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus"), "autonomy.json");
@@ -32,7 +33,7 @@ export function loadAutonomy() {
     return {
       version: 1,
       defaults: { ...DEFAULTS, ...(raw.defaults || {}) },
-      projects: raw.projects && typeof raw.projects === "object" ? raw.projects : {},
+      projects: asRecord(raw.projects) ?? {},
     };
   } catch {
     // A corrupt file must not hand out permissions nobody granted. Fall back to the safe defaults.

package/lib/decode.mjs

@@ -0,0 +1,13 @@
+/* oxlint-disable anti-slop/no-runtime-typeof -- SAFETY: this module IS the I/O boundary decoder for
+   lib/. Everything it is handed came off disk (config.json, autonomy.json, model-catalog.json), out
+   of a JSONL transcript written by whatever CLI version produced it, or off an HTTP request — the
+   type of any field is exactly what cannot be assumed, so these typeof checks are the parse that
+   establishes the contract, not a substitute for one (#7174). */
+// Each helper returns the value at its known shape or null, so callers branch on a domain value.
+// Deliberately permissive where the inline checks they replaced were: asRecord admits arrays and
+// asNumber admits NaN, because `typeof x === "object"` and `typeof x === "number"` did (#7174).
+
+export function asRecord(v) { return v && typeof v === "object" ? v : null; }
+export function asString(v) { return typeof v === "string" ? v : null; }
+export function asNumber(v) { return typeof v === "number" ? v : null; }
+export function asFunction(v) { return typeof v === "function" ? v : null; }

package/lib/identity.mjs

@@ -4,6 +4,7 @@ import { generateKeyPairSync, createPublicKey, createPrivateKey, sign as cryptoS
 import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, chmodSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { asFunction, asString } from "./decode.mjs";
 
 export const SCHEME = "trantor-v1";
 export const INST_SCHEME = "trantor-inst-v1";
@@ -105,7 +106,7 @@ export function publicView(identity) {
 // --- canonical request -------------------------------------------------------------------------
 export function bodyHash(body) {
   if (body === undefined || body === null || body === "") return "";
-  const buf = Buffer.isBuffer(body) ? body : Buffer.from(typeof body === "string" ? body : JSON.stringify(body), "utf8");
+  const buf = Buffer.isBuffer(body) ? body : Buffer.from(asString(body) ?? JSON.stringify(body), "utf8");
   return createHash("sha256").update(buf).digest("hex");
 }
 
@@ -199,7 +200,8 @@ export function verifyEndorsement({ durablePubkey, instancePubkey, instanceId, c
 // (is this pubkey known? may it touch this project?) belong to the hub, which owns that state.
 // Returns { ok, pubkey, ts, nonce, reason }.
 export function verifyRequest({ headers, method, path, body, now = Date.now() }) {
-  const get = (k) => (typeof headers?.get === "function" ? headers.get(k) : headers?.[k] ?? headers?.[k.toLowerCase()]);
+  const lookup = asFunction(headers?.get);
+  const get = (k) => (lookup ? lookup.call(headers, k) : headers?.[k] ?? headers?.[k.toLowerCase()]);
   const pubkey = get(HDR.pubkey), sig = get(HDR.sig), ts = get(HDR.ts), nonce = get(HDR.nonce);
   if (!pubkey || !sig || !ts || !nonce) return { ok: false, reason: "unsigned" };
   if (!/^[0-9a-f]{64}$/i.test(pubkey)) return { ok: false, reason: "bad-pubkey" };

package/lib/model-catalog.mjs

@@ -1,17 +1,9 @@
-// lib/model-catalog.mjs — the declarative model catalog (card #7777).
-//
-// configs/model-catalog.json records, per "<provider>/<model-id>": which API kinds it speaks,
-// context window, max output, input modalities, and — the part capabilities.json does not have —
-// an `effort` block mapping each crew difficulty (easy/medium/hard) to CONCRETE request
-// parameters PER API KIND (reasoning_effort, thinking, effort). Scores pick WHICH model; this
-// catalog says HOW to call it. A model missing from the catalog still works at its provider
-// default: lookup() returns an entry whose status says "not in catalog, provider default".
-//
-// Model ids come from `trantor models` / the provider adapters and CLI defaults — never typed
-// from memory — and every entry cites its limits with a url.
+// lib/model-catalog.mjs — the declarative model catalog (#7777): scores pick WHICH model, this
+// says HOW to call it. Shape and rules: docs/CONTRACT-lib.md, Providers and balances.
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { asRecord } from "./decode.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 export const CATALOG_PATH = process.env.TRANTOR_MODEL_CATALOG || join(ROOT, "configs", "model-catalog.json");
@@ -22,8 +14,8 @@ export function loadCatalog(path = CATALOG_PATH) {
   if (CACHE && path === CATALOG_PATH) return CACHE;
   let cat;
   try { cat = JSON.parse(readFileSync(path, "utf8")); } catch { cat = null; }
-  if (!cat || typeof cat !== "object") cat = { version: 0, models: {} };
-  if (!cat.models || typeof cat.models !== "object") cat.models = {};
+  if (!asRecord(cat)) cat = { version: 0, models: {} };
+  if (!asRecord(cat.models)) cat.models = {};
   if (path === CATALOG_PATH) CACHE = cat;
   return cat;
 }
@@ -87,14 +79,11 @@ export function resolveEffort(agent, modelId, difficulty, cat = loadCatalog()) {
     const kinds = Object.keys(level);
     params = kinds.length === 1 ? level[kinds[0]] : {};
   }
-  return { found: true, agent, model: entry.id, difficulty, api, params: params && typeof params === "object" ? params : {} };
+  return { found: true, agent, model: entry.id, difficulty, api, params: asRecord(params) ?? {} };
 }
 
-// cliEffortFlag(agent, effort) → { flag, text }: the per-CLI argument that carries the effort
-// parameters, plus the ONE log line the runner prints about it. Only the parameters a CLI can
-// actually carry are applied (codex: -c model_reasoning_effort; claude: --effort; opencode
-// seats: --variant, opencode's provider-specific reasoning effort); anything else stays at
-// provider default and the line says so.
+// The per-CLI argument carrying the effort parameters, plus the one log line the runner prints.
+// Only what a CLI can actually carry is applied; the rest stays at provider default and says so.
 export function cliEffortFlag(agent, effort) {
   if (!effort) return { flag: "", text: "" };
   const difficulty = effort.difficulty || "?";

package/lib/project.mjs

@@ -5,6 +5,7 @@ import { execSync } from "node:child_process";
 import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, readdirSync, statSync, realpathSync } from "node:fs";
 import { basename, join, dirname, resolve, sep } from "node:path";
 import { homedir, hostname } from "node:os";
+import { asRecord, asString } from "./decode.mjs";
 
 export function gitRoot(dir) {
   try {
@@ -189,10 +190,30 @@ export function writeOrchSession(project, sid, by = "unknown") {
     return true;
   } catch { return false; }
 }
+// Drop a project's row from the map. A session the map does not name cannot be resolved as a wake
+// recipient (bin/wake-nudge.mjs), which is how a retired pane stops buying turns (#8017).
+export function clearOrchSession(project, by = "unknown") {
+  try {
+    if (!project) return false;
+    const p = orchSessionsPath();
+    if (!existsSync(p)) return false;
+    const rows = readFileSync(p, "utf8").split("\n").filter(Boolean);
+    const prev = rows.find(r => r.split("\t")[0] === project)?.split("\t")[1] || "";
+    if (!prev) return false;
+    const kept = rows.filter(r => r.split("\t")[0] !== project);
+    writeFileSync(p, kept.length ? kept.join("\n") + "\n" : "");
+    try {
+      appendFileSync(join(busDir(), "orch-sessions.log"),
+        `${new Date().toISOString()}\t${project}\t${prev}\t-\t${by}\n`);
+    } catch {}
+    return true;
+  } catch { return false; }
+}
+
 function configPath() { return join(busDir(), "config.json"); }
 
 export function readConfig() {
-  try { const c = configPath(); if (existsSync(c)) { const j = JSON.parse(readFileSync(c, "utf8")); if (j && typeof j === "object") return j; } } catch {}
+  try { const c = configPath(); if (existsSync(c)) { const j = asRecord(JSON.parse(readFileSync(c, "utf8"))); if (j) return j; } } catch {}
   return {};
 }
 
@@ -203,9 +224,10 @@ export function resolveHubInfo(project, env = process.env) {
     if (env.RELAY_URL) return { url: env.RELAY_URL, via: "env" };
     const cfg = readConfig();
     const name = project || resolveProject();
-    const u = cfg?.hubs?.[name];
-    if (u && typeof u === "string") return { url: u, via: "pin" };
-    if (cfg?.url && typeof cfg.url === "string") return { url: cfg.url, via: "global" };
+    const pinned = asString(cfg?.hubs?.[name]);
+    if (pinned) return { url: pinned, via: "pin" };
+    const globalUrl = asString(cfg?.url);
+    if (globalUrl) return { url: globalUrl, via: "global" };
   } catch {}
   return { url: DEFAULT_HUB_URL, via: "default" };
 }
@@ -217,7 +239,7 @@ export function resolveHub(project, env = process.env) {
 // Every project the operator has deliberately pinned — the "expected one of these" list a
 // misplaced session needs in order to fix itself.
 export function knownProjects() {
-  try { const h = readConfig()?.hubs; return h && typeof h === "object" ? Object.keys(h).sort() : []; } catch { return []; }
+  try { return Object.keys(asRecord(readConfig()?.hubs) ?? {}).sort(); } catch { return []; }
 }
 
 // How many IMMEDIATE children of `dir` are git repos. Bounded (first 200 entries) and fail-safe:
@@ -272,10 +294,12 @@ function writeConfig(cfg) {
 // Pin a project to a hub. URL must be absolute http(s); trailing slash stripped so
 // `${hub}/path` concatenation never double-slashes.
 export function setProjectHub(project, url) {
-  if (!project || typeof project !== "string") throw new Error("project required");
+  if (!asString(project)) throw new Error("project required");
   if (!/^https?:\/\//.test(String(url || ""))) throw new Error("url must start with http:// or https://");
   const cfg = readConfig();
-  cfg.hubs = { ...(cfg.hubs && typeof cfg.hubs === "object" ? cfg.hubs : {}), [project]: String(url).replace(/\/+$/, "") };
+  const hubs = { ...(asRecord(cfg.hubs) ?? {}) };
+  hubs[project] = String(url).replace(/\/+$/, "");
+  cfg.hubs = hubs;
   writeConfig(cfg);
 }
 
@@ -283,9 +307,10 @@ export function setProjectHub(project, url) {
 // a mapping existed.
 export function unsetProjectHub(project) {
   const cfg = readConfig();
-  if (!cfg.hubs || typeof cfg.hubs !== "object" || !(project in cfg.hubs)) return false;
-  delete cfg.hubs[project];
-  if (!Object.keys(cfg.hubs).length) delete cfg.hubs;
+  const hubs = asRecord(cfg.hubs);
+  if (!hubs || !(project in hubs)) return false;
+  delete hubs[project];
+  if (!Object.keys(hubs).length) delete cfg.hubs;
   writeConfig(cfg);
   return true;
 }