trantor 0.18.49 → 0.18.51

package/lib/state/derive.mjs

@@ -0,0 +1,229 @@
+// Trantor State P4 — derive (TDD §4.5). Build a WorkingState for a handoff that has no sidecar
+// behind it, from two sources that are both already there: git's account of the worktree, and the
+// model's own STATE block in the handoff it just wrote.
+//
+// Why this exists at all: nothing writes a `state/` sidecar until the P6 runner applies patches
+// (Phase 2a). A Phase-1 writer that only READ a sidecar would read a file that does not exist,
+// every handoff would carry `state: null`, and the Phase-1 exit gate — ten real handoffs carrying
+// a schema-valid STATE — could not go green until the phase after it shipped.
+//
+// The rule that keeps this honest: A DERIVED STATE CARRIES NO CREDIT. Every path is
+// `verified: false`, `verify` is empty, and neither is reachable from the patch (both are
+// harness-written, §4.2's write matrix). So a derived state satisfies neither route (a) — the gate
+// went green this turn — nor route (b) — every named path is credited — and the successor has to
+// re-earn its evidence before anything moves to `done`. That is the honest outcome, not a
+// limitation: no gate ran, so there is nothing to inherit.
+//
+// The model's block goes through `applyTurn`, not through a second parser. That is the whole
+// design: the write matrix, the caps, the evidence marker and the verified-done rule then hold on
+// the handoff path exactly as they hold on the runner path, for free, instead of being a promise a
+// second parser would have to keep and would eventually break.
+import { execFileSync } from "node:child_process";
+import { CAPS, LISTS, emptyState, stateError } from "./schema.mjs";
+import { applyTurn } from "./apply.mjs";
+import { gitTouched } from "./store.mjs";
+
+/** The line every derived state carries, so the successor reads the absence of credit as a fact
+ *  rather than inferring it from an empty `verify`. */
+export const DERIVED_NOTE = "derived: no gate ran at this handoff — every path is uncredited and nothing here is evidence";
+
+/** `git diff --name-only HEAD`, NUL-separated. `-z` for the same reason the gate uses it: without
+ *  it git C-quotes any path with a non-ASCII byte and `café.mjs` arrives as `caf\303\251.mjs`, a
+ *  path that does not exist (#6901). */
+export function gitDiffPaths(cwd) {
+  if (!cwd) return [];
+  try {
+    const out = execFileSync("git", ["diff", "--name-only", "-z", "HEAD"], {
+      cwd, encoding: "utf8", maxBuffer: 16 * 1024 * 1024, stdio: ["pipe", "pipe", "pipe"],
+    });
+    return out.split("\0").filter(Boolean);
+  } catch {
+    return [];   // no git, no repo, or no HEAD yet — a derived state without files is still valid
+  }
+}
+
+/**
+ * Ground truth for `files`: every path the worktree has changed, `touched: true` and
+ * `verified: false` without exception. These are harness facts, so they ride `ctx.files` into
+ * applyTurn's runtime pass rather than the patch — a patch cannot write `files` at all.
+ * @returns {Record<string, { touched: boolean, verified: boolean }>}
+ */
+export function deriveFiles(worktree) {
+  const out = {};
+  for (const p of [...gitTouched(worktree), ...gitDiffPaths(worktree)]) {
+    // A path over CAPS.PATH cannot be a key in a schema-valid state, and truncating it would
+    // credit a file that is not there. Drop it; `files_count` is not the place to hide it either,
+    // because nothing was compacted.
+    if (!p || p.length > CAPS.PATH) continue;
+    out[p] = { touched: true, verified: false };
+  }
+  return out;
+}
+
+/** Which of the handoff's sections a heading opens. Anchored at the front on purpose: the sections
+ *  the Stop path asks for ("TASK (what we're doing + the goal)", "OPEN THREADS & NEXT STEPS") lead
+ *  with their keyword and mention other keywords later in the same line. */
+function sectionOf(heading) {
+  const h = String(heading).trim().toLowerCase().replace(/^[^a-z]+/, "");
+  if (/^(task|goal|objective)/.test(h)) return "task";
+  if (/^(state|status|progress so far)/.test(h)) return "state";
+  if (/^(done|completed|shipped|landed|delivered)/.test(h)) return "done";
+  if (/^(in[ -]?progress|in[ -]?flight|wip|doing|current)/.test(h)) return "in_flight";
+  if (/^(next|open thread|todo|to do|remaining|follow[ -]?up|upcoming)/.test(h)) return "next";
+  if (/^(blocker|blocked|risk)/.test(h)) return "blockers";
+  return "other";
+}
+
+/** A heading line: `## STATE`, `**STATE**`, or a bare `STATE:` / `STATE (done / in-progress)`. */
+function headingText(line) {
+  const hash = /^\s{0,3}#{1,6}\s+(.+?)\s*$/.exec(line);
+  if (hash) return hash[1].replace(/[*_`]/g, "");
+  const bold = /^\s{0,3}\*\*(.+?)\*\*\s*:?\s*$/.exec(line);
+  if (bold) return bold[1];
+  const bare = /^([A-Z][A-Z0-9 &'’(),./-]{2,})\s*:?\s*$/.exec(line);
+  if (bare) return bare[1];
+  return "";
+}
+
+const BULLET = /^\s*(?:[-*+•]|\d+[.)])\s+(.+)$/;
+/** An inline label on a bullet overrides the section it sits in — "- done: wired the promoter". */
+const INLINE_LABEL = /^(?:\*\*)?(done|completed|shipped|in[ -]?progress|in[ -]?flight|wip|doing|next|todo|blocked|blocker)(?:\*\*)?\s*[:\-–—]\s+/i;
+
+/** The bucket a label word names. */
+function bucketOfLabel(word) {
+  const w = String(word).toLowerCase().replace(/[ -]/g, "");
+  if (["done", "completed", "shipped"].includes(w)) return "done";
+  if (["inprogress", "inflight", "wip", "doing"].includes(w)) return "in_flight";
+  if (["next", "todo"].includes(w)) return "next";
+  return "blockers";
+}
+
+/** Leading status glyphs carry the same meaning as a label and are stripped with it. */
+function glyphBucket(text) {
+  if (/^(?:✅|✔️?|☑️?|\[x\]|\[X\])\s*/.test(text)) return "done";
+  if (/^(?:⛔|❌|🚫|🛑)\s*/.test(text)) return "blockers";
+  if (/^(?:🚧|🔄|▶️?)\s*/.test(text)) return "in_flight";
+  return "";
+}
+
+/** Strip markdown emphasis, glyphs and a trailing colon so the item reads as one claim. */
+function cleanItem(raw) {
+  return String(raw)
+    .replace(/^(?:✅|✔️?|☑️?|\[[ xX]\]|⛔|❌|🚫|🛑|🚧|🔄|▶️?)\s*/, "")
+    .replace(/\*\*/g, "")
+    .replace(/^[*_`]+|[*_`]+$/g, "")
+    .replace(/\s+/g, " ")
+    .replace(/[:;,]$/, "")
+    .trim();
+}
+
+/**
+ * Read the model's own handoff into the four lists. Bullets only: a paragraph in a STATE section
+ * is prose about the work, not an item, and turning it into one would fill the successor's state
+ * with sentences it cannot address by id.
+ *
+ * An unlabelled bullet inside STATE lands in `in_flight`, never `done`. That default is the
+ * conservative one on purpose — "the work is still open" costs the successor one re-check, while
+ * "the work is finished" is a claim nothing verified.
+ * @returns {{ done: string[], in_flight: string[], next: string[], blockers: string[], task: string }}
+ */
+export function parseHandoffState(text) {
+  const out = { done: [], in_flight: [], next: [], blockers: [], task: "" };
+
+  let section = "other";
+  let bucket = "";
+  // Anything that is not handoff markdown simply has no headings and no bullets, so it parses to
+  // four empty lists — the same answer a null summary gives, without a shape check standing in for
+  // a boundary this function does not have.
+  for (const line of String(text ?? "").split(/\r?\n/)) {
+    const heading = headingText(line);
+    if (heading) {
+      section = sectionOf(heading);
+      bucket = LISTS.includes(section) ? section : section === "state" ? "in_flight" : "";
+      continue;
+    }
+    const bullet = BULLET.exec(line);
+    if (section === "task") {
+      const t = cleanItem(bullet ? bullet[1] : line);
+      if (t && !out.task) out.task = t;
+      continue;
+    }
+    if (!bullet || !bucket) continue;
+
+    let body = bullet[1].trim();
+    let target = bucket;
+    const glyph = glyphBucket(body);
+    if (glyph) target = glyph;
+    const labelled = INLINE_LABEL.exec(body.replace(/^(?:✅|✔️?|☑️?|\[[ xX]\]|⛔|❌|🚫|🛑|🚧|🔄|▶️?)\s*/, ""));
+    if (labelled) {
+      target = bucketOfLabel(labelled[1]);
+      body = body.replace(/^(?:✅|✔️?|☑️?|\[[ xX]\]|⛔|❌|🚫|🛑|🚧|🔄|▶️?)\s*/, "").slice(labelled[0].length);
+    }
+    const item = cleanItem(body);
+    if (item) out[target].push(item);
+  }
+  return out;
+}
+
+const ID_PREFIX = { done: "d", in_flight: "f", next: "n", blockers: "b" };
+
+/**
+ * The parsed lists as `add` ops. Over-CAPS.LIST lines are dropped HERE, with a notes line naming
+ * the count, rather than being sent into applyTurn where a working-list overflow is a rejection
+ * that would cost every item in the patch (§3.1). Named beats silent, and both beat losing the lot.
+ * @returns {{ ops: object[], dropped: string[] }}
+ */
+function itemOps(parsed) {
+  const ops = [];
+  const dropped = [];
+  for (const list of LISTS) {
+    const lines = parsed[list];
+    if (lines.length > CAPS.LIST) {
+      dropped.push(`derived: ${lines.length - CAPS.LIST} ${list} line(s) over CAPS.LIST (${CAPS.LIST}) were not carried`);
+    }
+    lines.slice(0, CAPS.LIST).forEach((text, n) => {
+      ops.push({ add: { list, item: { id: `${ID_PREFIX[list]}${n + 1}`, text } } });
+    });
+  }
+  return { ops, dropped };
+}
+
+/**
+ * Build a WorkingState for a handoff with no sidecar behind it.
+ *
+ * `card` and `task` come from the record and the card title; `files` from git; the four lists from
+ * the handoff's own STATE block, through applyTurn. A rejected patch does not cost the state: the
+ * git-derived files, the task and one notes line naming the rejection code still make a
+ * schema-valid state, which is exactly what the Phase-1 gate measures.
+ *
+ * @returns {object|null} a state the validator accepts, or null — never a half-built one.
+ */
+export function deriveState({ project, seat, card, worktree, handoffText, cardTitle, now, by } = {}) {
+  // The bus names a seat `<seat>:<project>`. A caller that passes the two halves separately (the
+  // sidecar path's components) gets the same `cursor.by` the runner path would have written.
+  const bare = String(seat || "");
+  const author = String(by || (bare && project && !bare.includes(":") ? `${bare}:${project}` : bare));
+  const base = emptyState(Number.isInteger(card) && card >= 0 ? card : 0, author);
+  const ctx = {
+    now: Number.isInteger(now) ? now : Math.floor(Date.now() / 1000),
+    by: author,
+    files: deriveFiles(worktree),
+  };
+
+  const parsed = parseHandoffState(handoffText);
+  const task = String(cardTitle || parsed.task || "").replace(/\s+/g, " ").trim().slice(0, CAPS.TASK);
+  const { ops, dropped } = itemOps(parsed);
+
+  const setTask = task ? [{ set: { field: "task", value: task } }] : [];
+  const notes = (lines) => ({ set: { field: "notes", value: [DERIVED_NOTE, ...lines].join("\n") } });
+
+  let r = applyTurn(base, { patch: [...setTask, notes(dropped), ...ops], action: { continue: true } }, ctx);
+  if (!r.ok) {
+    const why = `derived: STATE block rejected (${r.code} at ${r.at}) — items dropped, files and task kept`;
+    r = applyTurn(base, { patch: [...setTask, notes([why])], action: { continue: true } }, ctx);
+  }
+  if (!r.ok) return null;
+  // The contract is "something the validator accepts, or nothing at all". applyTurn should never
+  // hand back an invalid state; if it ever does, a derived handoff is the wrong place to find out.
+  return stateError(r.state) === "" ? r.state : null;
+}

package/lib/state/gate.mjs

@@ -0,0 +1,355 @@
+// Trantor State P5.5 — the gate (TDD §4.8).
+//
+// runGate(spec, opts) is the lazy half of the evidence pipeline: the driver calls it once at the
+// `move → done` boundary to cure NEEDS_GATE, and the shape it returns feeds ctx.gate_attempted
+// and ctx.files on the retry. It NEVER touches state — it computes and returns; apply.mjs stage 5
+// lands the memo through the single apply point.
+//
+//   runGate({ items, paths }, { cwd }) ->
+//     { verify, files, coverage, cmd, exit, ms, tail, memo, memoHit }
+//
+// The three invariants this file exists to hold:
+//   1. The memo keys on tree CONTENT (scratch-index `git write-tree`), never on
+//      `git status --porcelain` — porcelain records that a path is modified, never what is in
+//      it, so a re-edit of an ALREADY-modified file is byte-identical to porcelain and a stale
+//      green would be reused as evidence for a done-move (the bust test in test-gate.mjs).
+//   2. Scoped resolves BEFORE scripts.test. scripts.test here is the full suite; a seat running
+//      the whole thing collides with sibling seats on fixed ports. Three reviewers hit this.
+//   3. `verified` means "a gate covering this path passed" (R11): on scoped coverage, touched
+//      paths OUTSIDE the scope come back verified:false — a scoped suite is not evidence about
+//      files it never loaded.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, mkdtempSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { CAPS } from "./schema.mjs";
+
+const DEFAULT_MAX_MS = 300_000;
+/** GNU timeout's convention: a timebox kill is a RED gate, never a missing one. */
+export const TIMED_OUT_EXIT = 124;
+
+const sh = (cmd, args, opts = {}) => {
+  const r = spawnSync(cmd, args, { encoding: "utf8", ...opts });
+  return {
+    status: r.status,
+    timedOut: r.error?.code === "ABORT_ERR" || (r.error?.code === "ETIMEDOUT"),
+    stdout: r.stdout || "",
+    stderr: r.stderr || "",
+  };
+};
+
+/** Last `CAPS.OBS_TOKENS` bytes of combined output — the seat's next observation starts here. */
+const tailOf = (...outs) => {
+  const t = outs.filter(Boolean).join("\n").trim();
+  return t.length > CAPS.OBS_TOKENS ? t.slice(-CAPS.OBS_TOKENS) : t;
+};
+
+/**
+ * Command resolution (§4.8), first match wins. Exported for direct tests — resolution is pure.
+ *
+ * TRANTOR_STATE_GATE (explicit, per project)
+ *   → the SCOPED form `node test/run.mjs --only <subsystem>`, when every path in spec.paths sits
+ *     under one subsystem that has a sibling suite dir (lib/state/* ↔ test/state/) — BEFORE
+ *     scripts.test, deliberately: scripts.test is the full suite and seats must never run it
+ *   → package.json scripts.test
+ *   → none.
+ *
+ * A subsystem for a path is any directory segment `<name>` of the path for which
+ * `<cwd>/test/<name>/` exists and contains suites. Build command resolves the same way:
+ * TRANTOR_STATE_BUILD → scripts.typecheck → scripts.build → none.
+ */
+export function resolveGateCommand(spec = {}, { cwd = process.cwd(), env = process.env } = {}) {
+  if (env.TRANTOR_STATE_GATE) {
+    return { kind: "explicit", cmd: env.TRANTOR_STATE_GATE };
+  }
+  const subsystem = scopedSubsystem(spec.paths || [], { cwd });
+  if (subsystem) {
+    return { kind: "scoped", subsystem, cmd: `node test/run.mjs --only ${subsystem}` };
+  }
+  const pkg = readPkg(cwd);
+  if (pkg?.scripts?.test) return { kind: "scripts.test", cmd: `npm test` };
+  return { kind: "none", cmd: null };
+}
+
+export function resolveBuildCommand({ cwd = process.cwd(), env = process.env } = {}) {
+  if (env.TRANTOR_STATE_BUILD) return { kind: "explicit", cmd: env.TRANTOR_STATE_BUILD };
+  const pkg = readPkg(cwd);
+  if (pkg?.scripts?.typecheck) return { kind: "scripts.typecheck", cmd: "npm run typecheck" };
+  if (pkg?.scripts?.build) return { kind: "scripts.build", cmd: "npm run build" };
+  return { kind: "none", cmd: null };
+}
+
+function readPkg(cwd) {
+  try {
+    return JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Idempotently add `entry` to the repo's local excludes (never a tracked file, so it cannot
+ *  change the tree or a diff — it only changes what `add -A` picks up). */
+function ensureIgnored(cwd, entry) {
+  const p = sh("git", ["rev-parse", "--git-path", "info/exclude"], { cwd });
+  const f = p.status === 0 && p.stdout.trim() ? resolve(cwd, p.stdout.trim()) : null;
+  if (!f) return;
+  let cur = "";
+  try { cur = readFileSync(f, "utf8"); } catch { /* first write */ }
+  if (!cur.split("\n").includes(entry)) {
+    try {
+      mkdirSync(dirname(f), { recursive: true });
+      writeFileSync(f, `${cur}${cur.endsWith("\n") || !cur ? "" : "\n"}${entry}\n`);
+    } catch { /* read-only git dir: the add below may then fold the scratch in — the memo
+                 misses every time, which is the safe direction (re-run, never stale green). */ }
+  }
+}
+
+function hasSuites(cwd, sub) {
+  const dir = join(cwd, "test", sub);
+  if (!existsSync(dir)) return false;
+  try {
+    return existsSync(join(dir, "test.mjs")) ||
+      readdirSync(dir).some(f => /^test-[\w.-]+\.(mjs|sh)$/.test(f));
+  } catch {
+    return false;
+  }
+}
+
+/** The one subsystem all paths share, or null. `lib/state/gate.mjs` → "state" when test/state/ has suites. */
+function scopedSubsystem(paths, opts) {
+  if (!paths.length) return null;
+  let shared = null;
+  for (const p of paths) {
+    const sub = subsystemOf(p, opts);
+    if (!sub) return null; // a path no suite dir covers → scope cannot place the work
+    if (shared === null) shared = sub;
+    else if (shared !== sub) return null; // spans two subsystems → not one scoped suite
+  }
+  return shared;
+}
+
+/** Shallowest directory segment of `p` that has a sibling suite dir — the subsystem a path
+ *  belongs to, or null. ONE rule for both resolution and credits, so the lane that ran and the
+ *  lane that gets credited can never drift apart. */
+function subsystemOf(p, { cwd }) {
+  const segs = p.split("/");
+  return segs.slice(0, -1).find(s => s && s !== ".." && hasSuites(cwd, s)) || null;
+}
+
+/**
+ * Tree CONTENT hash: HEAD sha + the worktree's tree sha, computed against a SCRATCH index so the
+ * seat's real `.git/index` is never touched. `git add -A` into the scratch index folds in
+ * untracked files, so a brand-new test file busts the memo too. The scratch dir defaults to
+ * `<cwd>/.agent-bus-out/` (gitignored, same filesystem) and falls back to a temp dir when that
+ * is not writable.
+ */
+export function contentHash(cwd) {
+  const scratchDir = join(cwd, ".agent-bus-out");
+  let dir = scratchDir;
+  let outside = false;
+  try {
+    mkdirSync(scratchDir, { recursive: true });
+  } catch {
+    dir = mkdtempSync(join(tmpdir(), "trantor-gate-"));
+    outside = true;
+  }
+  // The design's premise is that the scratch dir is gitignored; make that true locally (idempotent,
+  // repo-local `.git/info/exclude` — `--git-path` resolves the right git dir inside linked
+  // worktrees too). Unignored, `add -A` would fold the index file's own timestamp-varying bytes
+  // into the tree and the memo could never hit. The dir is NOT touched with a pathspec: an
+  // explicit `:(exclude)` naming an ignored path makes git REFUSE the add outright.
+  if (!outside) {
+    ensureIgnored(cwd, ".agent-bus-out/");
+  }
+  const env = { ...process.env, GIT_INDEX_FILE: join(dir, "gate-index") };
+  const add = sh("git", ["add", "-A"], { cwd, env });
+  if (add.status !== 0) return null;
+  const tree = sh("git", ["write-tree"], { cwd, env });
+  if (tree.status !== 0) return null;
+  const head = sh("git", ["rev-parse", "HEAD"], { cwd, env });
+  return `${head.stdout.trim()}+${tree.stdout.trim()}`;
+}
+
+/** Paths the worktree has actually changed vs HEAD — the TOUCHED set (tier 1's fact).
+ *  `-uall` so an untracked DIRECTORY expands to the files inside it (`?? bin/` would hide the
+ *  path a credit must name). Porcelain is fine HERE: touched is about which paths differ, not
+ *  about evidence. The memo hash above is where content, not status letters, is the only key. */
+export function touchedPaths(cwd) {
+  // -z, and it is not a style preference. WITHOUT it git C-quotes any path with a non-ASCII byte,
+  // a space-with-quote, or a backslash: `café.mjs` arrives as `"caf\303\251.mjs"`, and stripping
+  // the surrounding quotes leaves `caf\303\251.mjs` — a path that does not exist. The credit a
+  // seat names would then never match its file, so route (b) would silently never grant evidence
+  // for that path. It fails closed rather than granting a false credit, which is why nothing but a
+  // deliberate test catches it. -z emits literal NUL-separated paths with no quoting at all.
+  const out = sh("git", ["status", "--porcelain", "-z", "-uall"], { cwd });
+  if (out.status !== 0) return [];
+  const fields = out.stdout.split("\0").filter(Boolean);
+  const paths = [];
+  for (let i = 0; i < fields.length; i++) {
+    const entry = fields[i];
+    if (entry.length < 4) continue;
+    paths.push(entry.slice(3));
+    // A rename or copy emits its ORIGINAL path as the next NUL-terminated field. Consume it so it
+    // is not mistaken for a status entry, and count it too: the old path changed as surely as the
+    // new one did.
+    if (entry[0] === "R" || entry[0] === "C" || entry[1] === "R" || entry[1] === "C") {
+      const src = fields[++i];
+      if (src) paths.push(src);
+    }
+  }
+  return paths;
+}
+
+/** In scope for a `scoped:test/<sub>` credit = the path maps to the same subsystem the scoped
+ *  suite covers, by the one rule above. Paths outside stay verified:false (R11). */
+const inScope = (p, sub, opts) => (sub ? subsystemOf(p, opts) === sub : true);
+
+/**
+ * Run the gate. `spec` is the `gate` field NEEDS_GATE carried (`{ items, paths }`). `opts`:
+ *   cwd        — the seat worktree (default process.cwd())
+ *   env        — overrides process.env (tests inject TRANTOR_STATE_GATE without leaking)
+ *   memo       — the prior ext._gate record `{ hash, verify, coverage, ts, ... }`, if any
+ *   maxMs      — GATE_MAX_MS, default 300000; a timeout is a RED gate (exit 124)
+ *
+ * Returns `{ verify, files, coverage, cmd, exit, ms, tail, memo, memoHit }`:
+ *   verify  — `{ tested, cmd, exit }` (+ `built` only when a build command resolved and ran).
+ *             `observed` is NEVER set here: a test runner is not an observation.
+ *   files   — every touched path: credited ones `{ touched, verified:true, hash }` (blob sha,
+ *             what tier 1 later expires against), everything else `{ touched, verified:false }`.
+ *   memo    — the record the driver should land in ext._gate via ctx.gate.
+ *   memoHit — true when the recorded GREEN result was reused with no spawn.
+ *
+ * A RED gate (test fails, build fails, slop-gate fails, or timeout) credits no path and carries
+ * cmd/exit/tail for UNVERIFIED_DONE. This function returns no rejection codes of its own — the
+ * NEEDS_GATE/UNVERIFIED_DONE split belongs to the core (ctx.gate_attempted).
+ */
+export function runGate(spec = {}, opts = {}) {
+  const cwd = resolve(opts.cwd || process.cwd());
+  const env = { ...process.env, ...opts.env };
+  const maxMs = opts.maxMs ?? (Number(env.GATE_MAX_MS) || DEFAULT_MAX_MS);
+  const t0 = Date.now();
+
+  // ---- resolve first: the command is part of the memo key, not just its output ----
+  const build = resolveBuildCommand({ cwd, env });
+  const gateCmd = resolveGateCommand(spec, { cwd, env });
+
+  // ---- the memo is keyed on CONTENT, and checked before anything spawns ----
+  // Same HEAD + same tree bytes + SAME GATE COMMAND as the green run. The command is in the key
+  // because a different TRANTOR_STATE_GATE on unchanged bytes is a different gate — reusing the
+  // old green there would be exactly the stale-green-as-evidence bug this file exists to prevent.
+  const hash = contentHash(cwd);
+  if (hash && opts.memo && opts.memo.hash === hash &&
+      opts.memo.cmd === gateCmd.cmd && opts.memo.verify?.tested === true) {
+    // Same HEAD + same tree bytes as the green run: reuse, no spawn, no slop re-run. The touched
+    // set is identical too (same diff), so the recorded files map is still the truth.
+    return {
+      verify: { ...opts.memo.verify },
+      files: JSON.parse(JSON.stringify(opts.memo.files || {})),
+      coverage: opts.memo.coverage,
+      cmd: opts.memo.cmd,
+      exit: opts.memo.exit ?? 0,
+      ms: Date.now() - t0,
+      tail: opts.memo.tail ?? "",
+      memo: opts.memo,
+      memoHit: true,
+    };
+  }
+
+  // ---- touched set, before running anything (git is ground truth, not testimony) ----
+  const touched = touchedPaths(cwd);
+
+  // ---- run: build (if any) → gate command → slop-gate (always, when present) ----
+  let exit = 0;
+  let tail = "";
+  const verify = { tested: false };
+  let coverage = "project";
+  const runCmdLine = (cmdline) => {
+    // A resolved command is a shell line from a trusted source (repo scripts / operator env),
+    // never seat input — spec.paths only SELECTS among them.
+    const r = sh("sh", ["-c", cmdline], { cwd, env, timeout: maxMs, killSignal: "SIGTERM" });
+    return r;
+  };
+
+  if (build.cmd) {
+    const b = runCmdLine(build.cmd);
+    verify.built = b.status === 0 && !b.timedOut;
+    if (b.timedOut) { exit = exit || TIMED_OUT_EXIT; tail += `\n[build] TIMED OUT after ${maxMs}ms\n` + b.stdout + b.stderr; }
+    else if (b.status !== 0) { exit = exit || (b.status ?? 1); tail += `\n[build exit ${b.status}]\n` + b.stdout + b.stderr; }
+  }
+
+  if (gateCmd.kind === "none") {
+    exit = exit || 1;
+    tail += "\n[gate] no test command resolved (TRANTOR_STATE_GATE, scoped form, scripts.test all missed)\n";
+    verify.cmd = null;
+    verify.exit = exit;
+  } else {
+    verify.cmd = gateCmd.cmd;
+    coverage = gateCmd.kind === "scoped" ? `scoped:test/${gateCmd.subsystem}` : "project";
+    const g = runCmdLine(gateCmd.cmd);
+    if (g.timedOut) {
+      verify.exit = TIMED_OUT_EXIT;
+      exit = exit || TIMED_OUT_EXIT; // a timeout is a RED gate, not a missing one
+      tail += `\n[gate] TIMED OUT after ${maxMs}ms: ${gateCmd.cmd}\n` + g.stdout + g.stderr;
+    } else {
+      verify.exit = g.status ?? 1;
+      exit = exit || (g.status ?? 1);
+      tail += `\n[gate exit ${g.status ?? 1}] ${gateCmd.cmd}\n` + g.stdout + g.stderr;
+    }
+  }
+
+  // ---- slop-gate, always, when this repo has one: no card reaches done with it red ----
+  const slopPath = join(cwd, "bin", "slop-gate.mjs");
+  if (existsSync(slopPath)) {
+    const s = sh(process.execPath, [slopPath], { cwd, env, timeout: maxMs });
+    if (s.timedOut) {
+      exit = exit || TIMED_OUT_EXIT;
+      tail += `\n[slop-gate] TIMED OUT after ${maxMs}ms\n` + s.stdout + s.stderr;
+    } else if (s.status !== 0) {
+      exit = exit || (s.status ?? 1); // a green suite with red slop is still a RED gate
+      tail += `\n[slop-gate exit ${s.status}]\n` + s.stdout + s.stderr;
+    }
+  }
+
+  // The design's literal rule — computed AFTER everything that can redden the gate (suite, build,
+  // slop). In the none-case above exit is forced non-zero, so exit===0 already implies a test ran.
+  verify.tested = exit === 0;
+
+  // ---- credits (R11): only paths a gate of this coverage actually passed ----
+  const scopeSub = coverage === "project" ? null : coverage.slice("scoped:test/".length);
+  const files = {};
+  if (verify.tested && exit === 0) {
+    for (const p of touched) {
+      if (!inScope(p, scopeSub, { cwd })) { files[p] = { touched: true, verified: false }; continue; }
+      const h = sh("git", ["hash-object", p], { cwd });
+      files[p] = h.status === 0
+        ? { touched: true, verified: true, hash: h.stdout.trim() }
+        : { touched: true, verified: false };
+    }
+  } else {
+    for (const p of touched) files[p] = { touched: true, verified: false }; // red credits nothing
+  }
+
+  const ms = Date.now() - t0;
+  const memo = {
+    hash,
+    verify: { ...verify },
+    files: { ...files },
+    coverage,
+    cmd: verify.cmd,
+    exit,
+    ms,
+    tail: tailOf(tail),
+    ts: Date.now(),
+  };
+  return {
+    verify: memo.verify,
+    files: memo.files,
+    coverage,
+    cmd: verify.cmd,
+    exit,
+    ms,
+    tail: memo.tail,
+    memo,
+    memoHit: false,
+  };
+}