trantor 0.18.62 → 0.18.63

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 {
@@ -192,7 +193,7 @@ export function writeOrchSession(project, sid, by = "unknown") {
 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 +204,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 +219,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 +274,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 +287,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;
 }

package/lib/seat-record.mjs

@@ -1,17 +1,6 @@
-// #7762: the seat record is DERIVED, never a store. The hub already logs every card move
-// (/tasks cards carry history + the note log; /events keeps moves for aged-out cards) and the
-// runner's ledger rows (~/.agent-bus/logs/<seat>-<project>.jsonl) carry per-turn outcome +
-// tokens + card id. From those three this computes, PER PROJECT and PER SEAT, the last
-// RECORD_LIMIT cards as completed / empty / bounced:
-//   bounced — a testing→doing move by someone other than the seat (the assigner sent it back),
-//             or a HOLLOW: note on the card (#7750)
-//   completed — the card reached done with no bounce on its trail
-//   empty — the card never reached done and none of the seat's ledger turns on it completed
-//           (outcome empty/stalled/cut — the turn produced nothing)
-// relay_advise (bin/advise.mjs) benches a seat at a difficulty when its last STRIKE cards there
-// are all empty/bounced. The ONLY forgiveness paths: `trantor seat-record --reset <seat>`
-// (drops evidence older than the reset stamp) and new completed cards aging the bad ones out
-// of the STRIKE window — so no seat is blacklisted forever.
+// #7762: the seat record is DERIVED from card history and the runner's ledger, never a store, so
+// a seat benched by relay_advise can always be un-benched. Rules: docs/CONTRACT-lib.md, Crew turn
+// policy and failure classification.
 import { readFileSync, writeFileSync, renameSync, readdirSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";

package/lib/seat-why.mjs

@@ -4,6 +4,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
+import { asNumber, asRecord } from "./decode.mjs";
 
 const busDir = () => process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus");
 
@@ -18,7 +19,7 @@ function readTelemetry(file) {
   const out = [];
   for (const line of readF(file).split("\n")) {
     if (!line.trim()) continue;
-    try { const r = JSON.parse(line); if (r && typeof r === "object") out.push(r); } catch {}
+    try { const r = asRecord(JSON.parse(line)); if (r) out.push(r); } catch {}
   }
   return out;
 }
@@ -60,7 +61,7 @@ const rel = (ts) => {
 // print none contribute 0, which is why the count is reported alongside — "3 of 7 turns reported".
 export function todaySpend(telemetry, now = Date.now()) {
   const midnight = new Date(now); midnight.setHours(0, 0, 0, 0);
-  const rows = telemetry.filter(r => typeof r.turn === "number" && r.ts >= midnight.getTime());
+  const rows = telemetry.filter(r => asNumber(r.turn) !== null && r.ts >= midnight.getTime());
   const withTokens = rows.filter(r => Number(r.tokens) > 0);
   return {
     turns: rows.length,
@@ -86,7 +87,7 @@ export function seatWhy(project, agent, opts = {}) {
   const telemetry = readTelemetry(join(dir, "logs", `${agent}-${project}.jsonl`));
   const pane = findPane(dir, project, agent);
   const pids = opts.pidCheck ? opts.pidCheck(project, agent) : scanPids(project, agent);
-  const last = [...telemetry].reverse().find(r => typeof r.turn === "number") || null;
+  const last = [...telemetry].reverse().find(r => asNumber(r.turn) !== null) || null;
   const boots = telemetry.filter(r => r.boot).length;
   const errTail = errText.trim().split("\n").filter(Boolean).slice(-2).join(" | ").slice(0, 240);
 

package/lib/seats.mjs

@@ -4,39 +4,43 @@ import { execFileSync, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { readConfig, writeConfigPublic, resolveProject, resolveHubInfo } from "./project.mjs";
+import { asRecord, asString } from "./decode.mjs";
 
 // ── the registry ────────────────────────────────────────────────────────────────
 // config.json gains `seats: { <project>: { dir } }`. Same file as `hubs`, same shape of decision:
 // a deliberate operator statement, not an inference.
 export function readSeats() {
   try {
-    const s = readConfig()?.seats;
-    if (!s || typeof s !== "object") return {};
+    const s = asRecord(readConfig()?.seats);
+    if (!s) return {};
     const out = {};
     for (const [p, v] of Object.entries(s)) {
-      const dir = typeof v === "string" ? v : v?.dir;
-      const agent = (typeof v === "object" && typeof v?.agent === "string" && v.agent) ? v.agent : "claude";
-      if (typeof dir === "string" && dir) out[p] = { dir, agent };
+      const dir = asString(v) ?? asRecord(v)?.dir;
+      const agent = asString(asRecord(v)?.agent) || "claude";
+      if (asString(dir)) out[p] = { dir, agent };
     }
     return out;
   } catch { return {}; }
 }
 
 export function declareSeat(project, dir, agent = "claude") {
-  if (!project || typeof project !== "string") throw new Error("project required");
+  if (!asString(project)) throw new Error("project required");
   const abs = resolve(dir || process.cwd());
   if (!existsSync(abs)) throw new Error(`directory does not exist: ${abs}`);
   const cfg = readConfig();
-  cfg.seats = { ...(cfg.seats && typeof cfg.seats === "object" ? cfg.seats : {}), [project]: { dir: abs, agent } };
+  const seats = { ...(asRecord(cfg.seats) ?? {}) };
+  seats[project] = { dir: abs, agent };
+  cfg.seats = seats;
   writeConfigPublic(cfg);
   return { project, dir: abs, agent };
 }
 
 export function undeclareSeat(project) {
   const cfg = readConfig();
-  if (!cfg.seats || typeof cfg.seats !== "object" || !(project in cfg.seats)) return false;
-  delete cfg.seats[project];
-  if (!Object.keys(cfg.seats).length) delete cfg.seats;
+  const seats = asRecord(cfg.seats);
+  if (!seats || !(project in seats)) return false;
+  delete seats[project];
+  if (!Object.keys(seats).length) delete cfg.seats;
   writeConfigPublic(cfg);
   return true;
 }
@@ -123,7 +127,7 @@ export function launchSeat(seat, { command, dryRun = false } = {}) {
 // a guessed seat is exactly the kind of inference this file exists to replace.
 export function suggestSeats(workspace) {
   const cfg = readConfig();
-  const pinned = cfg?.hubs && typeof cfg.hubs === "object" ? Object.keys(cfg.hubs) : [];
+  const pinned = Object.keys(asRecord(cfg?.hubs) ?? {});
   const declared = readSeats();
   const out = [];
   for (const project of pinned) {

package/lib/state/driver.mjs

@@ -15,8 +15,9 @@ import { fromEnvelope } from "./cost.mjs";
 // upward is the deliberate inversion, since no number gets a second home. Its dispatch is guarded.
 import { PATCH_BUDGET, appendJsonl, patchesPath, runPath, seatClass } from "../../bin/state-bench.mjs";
 
-/** The flag. Absent or not "1" = the transcript path, byte for byte (§4.6). */
-export const STATE_ENV = "TRANTOR_STATE_ASSEMBLE";
+// The flag name lives in flags.mjs (#7159), beside the resolution list — re-exported so the
+// runner's import surface is unchanged.
+export { STATE_ENV } from "./flags.mjs";
 
 /** §7.3's window: the rolling invalid rate is measured over a seat's last 20 turns. */
 export const BREAKER_WINDOW = 20;
@@ -268,6 +269,7 @@ export async function runStep({
   let gateRun = null;
   // Whether the CLI was CUT at the time box. It is the transport that knows, so the transport says
   // so on the way back rather than the caller guessing before the turn has run (§8.7 reads it).
+  // Per attempt, not per step (#7226): a cut on the first attempt belongs to that attempt's row.
   let stepCut = cut === true;
 
   // §7.3's fallback ladder: a MALFORMED patch earns exactly one retry, with the rejection message
@@ -282,9 +284,11 @@ export async function runStep({
     trace.push("cli");
     const run = await D.callCli(prompt, { attempt });
     exit = run && Number.isInteger(run.exit) ? run.exit : 1;
-    if (run && run.cut === true) stepCut = true;
+    stepCut = cut === true || (run && run.cut === true);
     const parsed = parseEnvelope(run ? run.stdout : "");
-    if (parsed.cost) cost = parsed.cost;
+    // The price of THIS call. A retry that came back unpriced must not inherit the first attempt's
+    // cost into its own row: two rows, one price each, or the bench sums a call twice.
+    cost = parsed.cost || null;
 
     // ---- 4. TIER 1: git touch + credit expiry, EVERY turn, before the apply ----
     trace.push("tier1");
@@ -325,6 +329,14 @@ export async function runStep({
     if (attempt === 0) first = rejection ? rejection.code : null;
     if (!rejection) break;
     if (attempt >= 1 || !MALFORMED_CODES.includes(rejection.code)) break;
+    // #7226: the attempt about to be retried was a CLI call of its own — often a boxed one, since a
+    // cut turn is no output and no output is malformed — so it gets its own run row HERE, before the
+    // retry's call. Written now, a runner that dies during the retry cannot fold it into the step's
+    // row, and §8.7 counts every turn the box actually ran instead of one per step.
+    recordStep(D, project, card, {
+      turn: state.cursor.turn, rev: null, by: seat, ts: now, exit, cost, cut: stepCut, disturbed,
+      action: null, verify: null, verified_paths: [], rejected: rejection, retry: true,
+    });
     attempt++;
     obs = `${observation}\n\n${rejectionObservation(rejection)}`.trim();
   }
@@ -424,8 +436,9 @@ export async function runStep({
   };
 }
 
-/** One run-step row for `~/.agent-bus/state/runs/<project>-<card>.jsonl`. The FIELD NAMES ARE A CONTRACT
- *  with bin/state-bench.mjs (docs/CONTRACT-state.md §run record); a missing cost stays null, never 0. */
+/** One run row for `~/.agent-bus/state/runs/<project>-<card>.jsonl` — one per CLI call the step made,
+ *  so a retried attempt is a row of its own (#7226). The FIELD NAMES ARE A CONTRACT with
+ *  bin/state-bench.mjs (docs/CONTRACT-state.md §run record); a missing cost stays null, never 0. */
 export function recordStep(D, project, card, row) {
   const c = row.cost || {};
   const out = {
@@ -448,6 +461,7 @@ export function recordStep(D, project, card, row) {
   };
   if (row.cut) out.cut = true;
   if (row.disturbed) out.disturbed = true;
+  if (row.retry) out.retry = true;   // #7226: the attempt runStep retried in-step; its outcome is the next row
   try { D.appendJsonl(runPath(project, card), out); } catch { /* a recorder that throws must not end a turn */ }
   return out;
 }

package/lib/state/flags.mjs

@@ -0,0 +1,26 @@
+// Trantor State flags (#7159) — the ONE place the runner's TRANTOR_STATE* names resolve. The runner
+// boots from its OWN process env, so a flag set in ~/.agent-bus/.env (the file the turn wrapper
+// sources on the spawned CLI, one level too deep for the runner) never reached it. Here process env
+// wins and the file fills every name the launcher did not set; `trantor doctor` reports the layers.
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { parseEnvFile } from "../provider-keys.mjs";
+
+/** §4.6: absent or not "1" = the transcript path, byte for byte. The name lives here so the list
+ *  below and the runner's armed check cannot drift; driver.mjs re-exports it for its importers. */
+export const STATE_ENV = "TRANTOR_STATE_ASSEMBLE";
+
+// The names bin/crew/core.mjs forwards from whoever ran `trantor up` — one list, so forwarding and
+// resolution cannot drift apart.
+export const STATE_FLAGS = ["TRANTOR_STATE", "TRANTOR_STATE_ASSEMBLE", "TRANTOR_STATE_HANDOFF", "TRANTOR_STATE_GATE"];
+
+/** `{ [name]: { value, layer } }` per flag; layer is "process env", "~/.agent-bus/.env (crew)" or
+ *  "unset". Pure — env in, no writes — so the doctor reports the same answer the runner got. */
+export function resolveStateFlags(env = process.env, file = join(homedir(), ".agent-bus", ".env")) {
+  const fromFile = parseEnvFile(file);   // a missing file parses to {}
+  return Object.fromEntries(STATE_FLAGS.map((name) => {
+    if (env[name] !== undefined) return [name, { value: env[name], layer: "process env" }];
+    if (fromFile[name] !== undefined) return [name, { value: fromFile[name], layer: "~/.agent-bus/.env (crew)" }];
+    return [name, { value: "", layer: "unset" }];
+  }));
+}

package/lib/subagent-manifest.mjs

@@ -3,6 +3,7 @@
 import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { join, dirname, basename, relative } from "node:path";
 import { homedir } from "node:os";
+import { asString } from "./decode.mjs";
 
 const EDIT_TOOLS = /^(Write|Edit|MultiEdit|NotebookEdit)$/;
 
@@ -80,7 +81,7 @@ function analyzeAgent(meta, completedIds, projectRoot) {
         const content = b.input.content ?? b.input.new_string ?? "";
         wrote.set(b.input.file_path, content.length); // last write to a path wins
       }
-      if (b?.type === "text" && typeof b.text === "string" && b.text.trim()) result = b.text.trim();
+      if (b?.type === "text") { const text = asString(b.text)?.trim(); if (text) result = text; }
     }
   }
   const status = meta.toolUseId && completedIds.has(meta.toolUseId) ? "completed" : "in-flight";

package/mcp.mjs

@@ -197,11 +197,11 @@ server.tool("relay_contracts", "What you dispatched and are still owed. Lists ev
   });
 
 server.tool("relay_task_add", "Add a Kanban card to a project's board on the dashboard (what you're about to work on). Defaults: THIS project, assigned to you, status 'todo'. Pass `project` to target another board — e.g. when you orchestrate a crew that runs in a different directory than the one you launched Claude from. Keep the team's progress visible. Attach a `note` whenever context isn't obvious from the title — it lands on the card's permanent log ({ts,by,text}, kept: last 40).",
-  { title: z.string().describe("short task title"), status: z.enum(["todo","doing","testing","failed","done","blocked"]).optional(), assignee: z.string().optional().describe("session id to assign (default: you)"), difficulty: z.enum(["easy","medium","hard"]).optional().describe("difficulty tag — drives model/agent routing (relay_advise) and shows on the board"), model: z.string().optional().describe("the model this card is routed to (from relay_advise routing, or the CLI default) — shown on the card"), deps: z.array(z.number()).optional().describe("card ids this card depends on — drawn as branch edges in the Flow view (e.g. integration depends on every crew card)"), phase: z.string().optional().describe("phase/milestone this card belongs to (e.g. 'P5', 'Auth', 'Launch') — groups it in the Flow view's phase flowchart. Optional; otherwise inferred from the title prefix + time."), note: z.string().max(2000).optional().describe("optional card-log entry (<=2000 chars): context, the plan, or a link — stored on the card as {ts,by,text}"), project: z.string().optional().describe("board to add to (default: this session's project). Set to the crew's project when you orchestrate from a different directory"), checklist: z.array(z.string().max(200)).max(20).optional().describe("acceptance items for the card — the honest denominator for its progress bar. Tick them off with relay_task_check as each is truly met") },
-  async ({ title, status, assignee, difficulty, model, deps, phase, note, project, checklist }) => {
+  { title: z.string().describe("short task title"), status: z.enum(["todo","doing","testing","failed","done","blocked"]).optional(), assignee: z.string().optional().describe("session id to assign (default: you)"), difficulty: z.enum(["easy","medium","hard"]).optional().describe("difficulty tag — drives model/agent routing (relay_advise) and shows on the board"), model: z.string().optional().describe("the model this card is routed to (from relay_advise routing, or the CLI default) — shown on the card"), deps: z.array(z.number()).optional().describe("card ids this card depends on — drawn as branch edges in the Flow view (e.g. integration depends on every crew card)"), phase: z.string().optional().describe("phase/milestone this card belongs to (e.g. 'P5', 'Auth', 'Launch') — groups it in the Flow view's phase flowchart. Optional; otherwise inferred from the title prefix + time."), note: z.string().max(2000).optional().describe("optional card-log entry (<=2000 chars): context, the plan, or a link — stored on the card as {ts,by,text}"), project: z.string().optional().describe("board to add to (default: this session's project). Set to the crew's project when you orchestrate from a different directory"), checklist: z.array(z.string().max(200)).max(20).optional().describe("acceptance items for the card — the honest denominator for its progress bar. Tick them off with relay_task_check as each is truly met"), drill: z.string().max(300).optional().describe("the card's DRILL (build doctrine rule 1, <=300 chars): the exact thing a person does on the built artifact and what they must see — not a test command. The hub refuses to move a card to done without a drill line (this field, a checklist item or a note starting with 'Drill:'), so a card cut without one is not ready to be worked") },
+  async ({ title, status, assignee, difficulty, model, deps, phase, note, project, checklist, drill }) => {
     const proj = project || PROJECT;
-    const { task } = await api("POST", "/task", { project: proj, title, status: status || "todo", assignee: assignee || SESSION, difficulty, model, deps, phase, note, checklist, by: SESSION });
-    return { content: [{ type: "text", text: `card #${task.id} added to ${proj}: "${title}" [${task.status}]${phase?` · phase ${phase}`:""}${task.checklist?.length?` · ${task.checklist.length} acceptance item(s)`:""}` }] };
+    const { task } = await api("POST", "/task", { project: proj, title, status: status || "todo", assignee: assignee || SESSION, difficulty, model, deps, phase, note, checklist, drill, by: SESSION });
+    return { content: [{ type: "text", text: `card #${task.id} added to ${proj}: "${title}" [${task.status}]${phase?` · phase ${phase}`:""}${task.checklist?.length?` · ${task.checklist.length} acceptance item(s)`:""}${task.drill ? " · drill set" : " · NO DRILL — the hub will refuse done until one is set"}` }] };
   });
 
 server.tool("relay_task_check", "Tick (or untick) ONE acceptance item on a card's checklist — the card's progress bar reads checked/total, so tick an item only when it is genuinely met (tests run, behavior observed), never to make the bar move. Items are 0-indexed in the order relay_task_add listed them.",
@@ -220,9 +220,9 @@ server.tool("relay_phase_goal", "Set what a PHASE is for — its goal — shown
     return { content: [{ type: "text", text: `phase "${phase}" goal set for ${proj}` }] };
   });
 
-server.tool("relay_task_move", "Move a Kanban card as you progress: todo -> doing -> testing -> done. NEVER move straight to done: move to 'testing' when you finish, run the project's tests/typecheck, then 'done' only if green — or 'failed' (with a relay_send explaining what broke) if not. The orchestrator bounces failed cards back to doing. blocked = waiting on something external. A move to 'testing' or 'done' MUST carry a `note` (<=2000 chars): what you changed and the evidence (the test command + counts). The note lands on the card's permanent log — the board shows its ·N count, so a silent move reads as unverified work. A testing/done move with NO worktree diff, no new files, no ticked checklist items and no test command in the note is flagged HOLLOW: and reported to the card's assigner (#7750) — a legitimately no-code card (docs, investigation, refusal, answered on the bus) avoids the flag by declaring that outcome in the note.",
-  { id: z.number(), status: z.enum(["todo","doing","testing","failed","done","blocked"]), note: z.string().max(2000).optional().describe("card-log entry (<=2000 chars) — REQUIRED on moves to testing/done: what changed + the evidence (command, pass counts)") },
-  async ({ id, status, note }) => {
+server.tool("relay_task_move", "Move a Kanban card as you progress: todo -> doing -> testing -> done. NEVER move straight to done: move to 'testing' when you finish, run the project's tests/typecheck, then 'done' only if green — or 'failed' (with a relay_send explaining what broke) if not. The orchestrator bounces failed cards back to doing. blocked = waiting on something external. A move to 'testing' or 'done' MUST carry a `note` (<=2000 chars): what you changed and the evidence (the test command + counts). The note lands on the card's permanent log — the board shows its ·N count, so a silent move reads as unverified work.",
+  { id: z.number(), status: z.enum(["todo","doing","testing","failed","done","blocked"]), note: z.string().max(2000).optional().describe("card-log entry (<=2000 chars) — REQUIRED on moves to testing/done: what changed + the evidence (command, pass counts)"), drill: z.string().max(300).optional().describe("set or fix the card's drill line (<=300 chars) in the same call — what a person does on the built artifact and must see. A move to done is refused by the hub when the card has no drill line") },
+  async ({ id, status, note, drill }) => {
     // #7750: seat-side hollow-move check. The hub cannot see this worktree, so the evidence is
     // gathered HERE at report time; a hollow move still lands (never blocks a no-code card), the
     // note is prefixed HOLLOW: and the card's assigner gets one bus line. Never throws into the move.
@@ -250,7 +250,14 @@ server.tool("relay_task_move", "Move a Kanban card as you progress: todo -> doin
         }
       }
     } catch { /* the flag must never break a move */ }
-    await api("POST", "/task/update", { id, status, note: outNote, by: SESSION, ...(blast ? { blast } : {}) });
+    try {
+      await api("POST", "/task/update", { id, status, note: outNote, drill, by: SESSION, ...(blast ? { blast } : {}) });
+    } catch (error) {
+      // #6452: a refused move is the teaching moment — say why the hub said no (no drill line,
+      // frozen assignee), not "hub 409".
+      if (error?.status === 409) return { content: [{ type: "text", text: `REFUSED: card #${id} stays where it is — ${error.hubError || error.message}` }], isError: true };
+      throw error;
+    }
     return { content: [{ type: "text", text: `card #${id} -> ${status}` }] };
   });
 
@@ -374,7 +381,10 @@ function cardView(tasks, id, proj) {
   const card = tasks.find(t => t.id === id);
   if (!card) return `${proj}: no card #${id}`;
   const out = [`#${card.id} ${card.title}`,
-    `status: ${card.status}${card.assignee ? ` · @${card.assignee}` : ""}${card.difficulty ? ` · ${card.difficulty}` : ""}${card.model ? ` · ${card.model}` : ""}`];
+    `status: ${card.status}${card.assignee ? ` · @${card.assignee}` : ""}${card.difficulty ? ` · ${card.difficulty}` : ""}${card.model ? ` · ${card.model}` : ""}`,
+    // #6452: the drill is what a person does on the built artifact to see this card's work; the
+    // hub refuses done without one, so a card view says so up front.
+    card.drill ? `drill: ${card.drill}` : `drill: (none on the card — the hub refuses a move to done until a drill line exists: relay_task_move with \`drill\`, a checklist item or a note starting "Drill:")`];
 
   const deps = (Array.isArray(card.deps) ? card.deps : []).map(d => {
     const t = tasks.find(x => x.id === d);
@@ -430,7 +440,7 @@ server.tool("relay_board", "Show a project's Kanban board (all cards + their sta
   if (!tasks.length) return { content: [{ type: "text", text: `${proj}: no cards yet` }] };
   if (card) return { content: [{ type: "text", text: cardView(tasks, card, proj) }] };
   const by = { todo: [], doing: [], testing: [], failed: [], done: [], blocked: [] };
-  for (const t of tasks) (by[t.status] || by.todo).push(`#${t.id} ${t.title}${t.assignee ? ` (@${t.assignee})` : ""}${noteCount(t) ? ` ·${noteCount(t)}` : ""}`);
+  for (const t of tasks) (by[t.status] || by.todo).push(`#${t.id} ${t.title}${t.assignee ? ` (@${t.assignee})` : ""}${noteCount(t) ? ` ·${noteCount(t)}` : ""}${t.drill ? " ·drill" : ""}`);
   const cols = Object.entries(by).filter(([, v]) => v.length).map(([k, v]) => `${k.toUpperCase()}:\n  ${v.join("\n  ")}`);
   return { content: [{ type: "text", text: `${proj} board\n${cols.join("\n")}` }] };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.62",
+  "version": "0.18.63",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"
@@ -28,7 +28,8 @@
     ".claude-plugin/",
     "README.md",
     "LICENSE",
-    "engine/"
+    "engine/",
+    "docs/BUILD-DOCTRINE.md"
   ],
   "repository": {
     "type": "git",

package/skills/crew/SKILL.md

@@ -36,9 +36,14 @@ explicit EVENT/INTERFACE CONTRACT — cross-agent bugs come from contract drift.
    from the brief, hooks, hub brief + first card) — it never spawns a session; firing the crew
    is this phase's job.
 1. `relay_project_brief("<what + why + goal>")`
-2. One card per package: `relay_task_add(title, assignee, difficulty, model)` — set `model`
-   to the advisor-routed model (or the CLI's default name); difficulty + model show as badges
-   on the card. Assignees: `codex:<project>` etc. Keep one for yourself.
+2. One card per package: `relay_task_add(title, assignee, difficulty, model, drill)` — set
+   `model` to the advisor-routed model (or the CLI's default name); difficulty + model show as
+   badges on the card. Assignees: `codex:<project>` etc. Keep one for yourself.
+   **Every card names its drill** (build doctrine rule 1): `drill` is the exact thing a person
+   does on the built artifact and what they must see ("open Settings, toggle X, the badge turns
+   green"), not a test command. A card without a drill line is not ready to be worked, and the
+   hub refuses to move it to done: `/task/update` answers 409 unless the card carries a `drill`,
+   a checklist item or a note starting with `Drill:`. Cutting a card without one is a defect.
 3. Open the dashboard: **`trantor ui`** — which opens the **desktop app**, not a browser.
    Do NOT open the hub URL in a browser. A remote hub runs `auth:enforce`, and a browser cannot
    sign its requests: the page loads but `/projects`, `/tasks` and `/peers` all return 401, so the
@@ -150,10 +155,16 @@ orchestrator runs the full suite at integration) plus `node bin/slop-gate.mjs` w
 one (the anti-slop lint over the seat's changed files — a card must not reach done failing it);
 `done` only green, and moves to testing/done carry a `note` with the evidence — the note is the
 card's permanent story; `failed` (+ bus report) pulses red on the board until you bounce it.
-Enforce the gate — bounce anything that skipped it (bounces are visible: "↩ bounced" on the
-card, history in its tooltip). When all report done: integrate, fix contract mismatches
-YOURSELF, move your card through testing → done, broadcast "🚀 <thing> is live", and when the
-user is finished: `trantor down`.
+**The seat that wrote the code never closes its own card to done.** `testing` is the seat's
+last move; `done` is yours, after you ran the card's drill on the built artifact (the installed
+app, the live hub, the real CLI) and wrote the result on the card. Say so in every contract:
+"move to testing with the evidence, then stop; the orchestrator runs the drill and closes". The
+hub enforces the drill half: a move to done on a card with no drill line is refused (409), your
+own moves included. Enforce the rest — bounce anything that skipped the gate (bounces are
+visible: "↩ bounced" on the card, history in its tooltip). When all report testing: run each
+drill, close the cards that pass, bounce the rest, integrate, fix contract mismatches
+YOURSELF, move your own card through testing → done (its drill run and noted, same as any
+other), broadcast "🚀 <thing> is live", and when the user is finished: `trantor down`.
 
 ## Rules
 - Coordinate ONLY over the bus; messages <280 chars; the dashboard lanes are the user's view.