shapeup-sdlc 1.7.0 → 3.0.0

package/kernel/probe/leg.mjs

@@ -0,0 +1,125 @@
+// probe leg — "did this scope's work actually reach the board?"
+//
+// CONTRACT. A bounded, read-only query over one scope's orders, results and leg-completion rows for
+// one round. Prints `{closed, scope_id, round, orders: [...], unapplied: [...]}` on stdout; exits 0
+// when every order that produced a result has been ingested, 1 when at least one has not, 2 on a bad
+// argv. Writes nothing.
+//
+// WHY IT EXISTS. `probe t0` answers "is the T0 verdict green", and the BUILD round's confirm stage
+// asked only that. A green T0 says the worker's fixtures ran and passed; it says nothing about
+// whether the WorkResult was applied — and this is a state a real run reaches. A build leg can write
+// its code, a green T0 verdict, a kept trial row and its WorkResult to disk, and never run step 3 of
+// its own script, `reduce ingest`. It reports green; a confirm stage that re-verifies only the T0
+// artifact agrees, and the round walks on. That scope's task is left `pending` with zero acceptance
+// criteria ticked while its code sits finished on disk, beside a sibling scope whose task is `done`.
+//
+// Nothing has to be wrong with the order, the receipt or the result for this to happen — ingesting the
+// same file afterwards succeeds and ticks the criteria. The single writer of shared state simply never
+// ran, and the board GATE L2 reads as "100% ✅" silently disagrees with a scope that is genuinely
+// finished. Under fan-out it gets worse rather than better: N legs can each drop the step
+// independently, and the only symptom is a board that lags reality.
+//
+// WHY A LEG ROW IS THE RIGHT EVIDENCE. The row is appended BY `reduce ingest`. Its presence is
+// therefore proof the writer ran, and it is not something the leg can assert about itself — the same
+// reason the dispatch receipt is written by the hook layer rather than by the sub-agent making the
+// call. "The worker says it ingested" is exactly the class of claim this pipeline does not accept.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { runArgs } from "../lib/argv.mjs";
+import { ordersDir, resultsDir, legLedger } from "../lib/paths.mjs";
+
+/** `<scope>-r<round>-a<attempt>.json` — the only address a build order is written under. */
+const BUILD_ORDER = /^(.+)-r(\d+)-a(\d+)\.json$/;
+
+/**
+ * Every leg-completion row on disk, tolerant of a torn last line.
+ * @param {string} path - The leg ledger.
+ * @returns {object[]} Parsed rows; an unparsable line is skipped rather than fatal.
+ */
+export function readLegs(path) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8").split("\n").filter(Boolean)
+    .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(Boolean);
+}
+
+/**
+ * Which of one scope's orders in one round produced a result, and which of those were applied.
+ *
+ * An order with no result has not finished and is not a finding — the leg may still be running, or
+ * may have died, which the round already treats as a spent attempt. What this reports is the
+ * narrower and stranger case: a result on disk that the single writer never applied.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {string} scopeId - Scope contract id.
+ * @param {number} round - Build round.
+ * @returns {{closed: boolean, orders: object[], unapplied: object[]}} `closed` is false only when a
+ *   result exists that was never ingested; a scope with no results at all reports `closed: false`
+ *   with an empty `orders` list, so a caller can tell "nothing ran" from "nothing was applied".
+ */
+export function legState(cwd, slug, scopeId, round) {
+  const oDir = ordersDir(cwd, slug);
+  const rDir = resultsDir(cwd, slug);
+  const legs = readLegs(legLedger(cwd, slug));
+  const ingested = new Set(legs
+    .filter((r) => Number(r.round) === round && r.scope_id === scopeId && r.ingested_at)
+    .map((r) => String(r.order_id)));
+
+  const orders = [];
+  for (const f of (existsSync(oDir) ? readdirSync(oDir) : []).sort()) {
+    const m = f.match(BUILD_ORDER);
+    if (!m || m[1] !== scopeId || Number(m[2]) !== round) continue;
+    // The order id is read off the order rather than rebuilt from the filename: the filename is the
+    // path the round knows, and the id is the key every record joins on, and they are allowed to be
+    // written by different steps.
+    let orderId = null;
+    try { orderId = JSON.parse(readFileSync(join(oDir, f), "utf8")).order_id ?? null; } catch { /* unreadable — reported below */ }
+    orders.push({
+      order: join(oDir, f),
+      order_id: orderId,
+      attempt: Number(m[3]),
+      has_result: existsSync(join(rDir, f)),
+      applied: orderId !== null && ingested.has(orderId),
+    });
+  }
+  const unapplied = orders.filter((o) => o.has_result && !o.applied);
+  return { closed: orders.some((o) => o.applied) && unapplied.length === 0, orders, unapplied };
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs probe leg --slug <slug> --scope <scope-id> --round N [--cwd <dir>]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  scope: { type: "str", required: true },
+  round: { type: "int", min: 1, required: true },
+  cwd: { type: "path" },
+};
+
+/**
+ * Report whether one scope's results for one round reached the board.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {void} Exits 0 when closed, 1 when a result was never applied — the shape a caller can
+ *   branch on without parsing prose.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const s = legState(cwd, args.slug, args.scope, args.round);
+  console.log(JSON.stringify({
+    closed: s.closed,
+    scope_id: args.scope,
+    round: args.round,
+    // The counts travel with the verdict: `closed: false` over zero orders means the leg has not run,
+    // and over three orders means its work is on disk and unapplied. Those need different answers
+    // from the caller, so they must not read the same.
+    orders_total: s.orders.length,
+    results_total: s.orders.filter((o) => o.has_result).length,
+    applied_total: s.orders.filter((o) => o.applied).length,
+    orders: s.orders,
+    unapplied: s.unapplied.map((o) => o.order),
+  }));
+  process.exit(s.closed ? 0 : 1);
+}

package/{skills/tech-lead/scripts/resume-state.mjs → kernel/probe/resume.mjs}

@@ -16,11 +16,10 @@
 //      artifacts rewritten, a spike added, the discovery ledger and two task files mutated.
 //      The cause was one branch reading stored `status` instead of ORIENT's own artifacts,
 //      while WIRE and MAP SCOPES read artifacts and fast-forwarded correctly.
-//   2. IT MATCHED NO PERMISSION GRANT. `permissions.allow` carries
-//      `Bash(node ${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/:*)`; an inline `node -e` matches
-//      no entry and passes only at the safety classifier's discretion. As a script it is covered
-//      by the grant the installer already writes.
-//   3. TWO WRITES HAD NO READER. `setRunStatus` and `writeActiveScope` were the only `mech()`
+//   2. IT MATCHED NO PERMISSION GRANT. An inline `node -e` matches no rule in `permissions.allow`
+//      and passes only at the safety classifier's discretion. As a named script it is covered by
+//      the per-script rules the installer writes (`bin/lib/grant.mjs`).
+//   3. TWO WRITES HAD NO READER. `setRunStatus` and the substrate pointer were the only
 //      call sites in the workflow whose return value was discarded — and they are the only two
 //      whose failure went unnoticed for two entire runs. `status` never left `orienting` across
 //      46 dispatched agents, and `.shapeup/active-scope` still named scope 1 while scope 2 was
@@ -50,25 +49,24 @@
 // disagree about "is this phase done" is the defect class itself.
 //
 // USAGE
-//   node resume-state.mjs --slug <slug> [--cwd <dir>]              # derive, print ResumeState
-//   node resume-state.mjs --slug <slug> --require <phase>          # post-condition: exit 6 if unmet
-//   node resume-state.mjs --slug <slug> --set-status <status>      # write harness-run.md status
-//   node resume-state.mjs --slug <slug> --set-active-scope <id>    # write the substrate pointer
+//   node harness probe resume --slug <slug> [--cwd <dir>]              # derive, print ResumeState
+//   node harness probe resume --slug <slug> --require <phase>          # post-condition: exit 6 if unmet
+//   node harness probe resume --slug <slug> --set-status <status>      # write harness-run.md status
 //
 // Exit: 0 ok · 2 malformed argv (nothing ran) · 3 the target the operation needs is not on disk ·
 //       6 the required phase's artifact is NOT on disk (the phase did not complete).
 
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
-import { splitFrontmatter } from "./lib/contract-md.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { splitFrontmatter } from "../lib/contract.mjs";
+import { globToRegExp } from "../verify/spec.mjs";
 import {
   intake, harnessRun, wiringMap, projectProfile, scopesDir, resultsDir, ordersDir,
-  orientDir, activeScope, activeOrder, usecasesDir,
-} from "./lib/paths.mjs";
+  orientDir, activeOrder, usecasesDir,
+} from "../lib/paths.mjs";
 
-/** The run-state values `references/ledger-schema.md` defines. A typo'd status is a rejection,
+/** The run-state values `references/protocol.md` (Part 4 — State) defines. A typo'd status is a rejection,
  *  not a write — the whole point of this file is that a write nobody validates is a write nobody
  *  can trust. */
 export const RUN_STATUSES = ["orienting", "mapping", "building", "evaluating", "shipped", "escalated"];
@@ -81,7 +79,7 @@ export const ORIENT_SPIKE = /^spike-.+\.md$/;
 
 /**
  * Parse a leading `---` frontmatter block into a flat object, through the ONE library that reads
- * this file form (`lib/contract-md.mjs`).
+ * this file form (`lib/contract.mjs`).
  *
  * It used to be a private scalar-only regex — every value came back a string, including a
  * `key: [a, b]` list. That is why `eval_dimensions` was pinned: the ledger could carry the set the
@@ -107,6 +105,168 @@ export function parseFrontmatter(text) {
  * @param {string} slug - Feature slug.
  * @returns {boolean} True when all three named artifacts and at least one spike file exist.
  */
+/**
+ * Group the scopes into dependency WAVES: every scope in a wave can be built at the same time,
+ * and no wave contains a scope that depends on one still in flight.
+ *
+ * WHY THIS EXISTS, measured rather than reasoned. BUILD chunked the scopes by a fixed width over
+ * whatever order the directory listing gave — alphabetical. On the criterion-1 run that put
+ * `cli-integration` second, in the first wave, alongside the `foundation` and command scopes its own
+ * contract says it consumes ("replaces foundation's bin/todo.js placeholder", "routes to each command
+ * scope's module"). It burned all three attempts at 0/2 fixtures in round 1 and its leg died in round
+ * 2, so `bin/todo.js` stayed a two-line placeholder and four individually T0-green command modules
+ * were unreachable from the entry point. Five of six scopes went green; the sixth was the one that
+ * had to go last, and it was scheduled second by alphabet.
+ *
+ * THE ORDER LIVES IN THE SAME TIER AS THE THING IT ORDERS. Each scope contract declares
+ * `depends_on: [scope_id, …]`, and scope A follows scope B when A names B. This used to be derived
+ * instead — contract `tasks` → the board's task `depends_on` → back to the owning scope — which
+ * read an ordering off the LOCAL board while the contracts it ordered were COMMITTED. On a fresh
+ * clone the board is absent, every scope's task list resolved to nothing, and the whole relation
+ * collapsed to "no edges": the scheduler degraded to the unscheduled fan-out this exists to
+ * replace, and reported nothing, because an empty relation is the same value as no relation.
+ * `scope_id` is the stable cross-machine key, so an edge between two of them survives the clone
+ * that the two-hop join through renumbering task ids never could.
+ *
+ * NON-REGRESSION IS THE DEFAULT. Any missing or unreadable input — no contract declaring
+ * `depends_on`, an id naming a scope that is not here, a dependency cycle — falls back to one wave
+ * containing everything, which is exactly the pre-scheduler behavior. A scheduler that refuses to
+ * run is worse than one that runs unscheduled.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {Array<{scope_id:string, path:string}>} scopes - The scopes, in their existing order.
+ * @returns {string[][]} Waves of resolved scope paths, dependencies first. Order within a wave is
+ *   the input order, so the result is deterministic.
+ */
+export function scopeWaves(cwd, slug, scopes) {
+  const all = scopes.map((s) => s.path);
+  if (scopes.length < 2) return all.length ? [all] : [];
+  const deps = scopeDepGraph(scopes);
+  if (!deps) return [all];
+
+  // Kahn, one wave per level. A cycle cannot stall the build: the remainder ships as one wave.
+  const done = new Set();
+  const waves = [];
+  while (done.size < scopes.length) {
+    const ready = scopes.filter((s) => !done.has(s.scope_id)
+      && [...deps.get(s.scope_id)].every((d) => done.has(d)));
+    if (!ready.length) {
+      waves.push(scopes.filter((s) => !done.has(s.scope_id)).map((s) => s.path));
+      break;
+    }
+    waves.push(ready.map((s) => s.path));
+    for (const s of ready) done.add(s.scope_id);
+  }
+  return waves;
+}
+
+/**
+ * The dependency relation `scopeWaves` levels — parsed once, so the two answers cannot disagree.
+ *
+ * @param {Array<{scope_id:string, path:string}>} scopes - The scopes, in their existing order.
+ * @returns {(Map<string,Set<string>>|null)} scope_id → the scope_ids it waits for, or null when the
+ *   contracts carry no usable relation at all (none declares `depends_on`, or every id it names is
+ *   a scope that is not in this run).
+ */
+function scopeDepGraph(scopes) {
+  const present = new Set(scopes.map((s) => s.scope_id));
+  const deps = new Map(scopes.map((s) => [s.scope_id, new Set()]));
+  let sawEdge = false;
+  for (const s of scopes) {
+    let declared;
+    try { declared = parseFrontmatter(readFileSync(s.path, "utf8")).depends_on; } catch { continue; }
+    if (!Array.isArray(declared)) continue;
+    for (const d of declared) {
+      const id = String(d).trim();
+      // An id naming a scope that is not in this run is DROPPED, not an error: a contract may
+      // legitimately name a scope superseded or cut since it was written, and a scheduler that
+      // stalls on a stale edge is worse than one that ignores it. spec-lint reports the dangling
+      // id — this is the scheduling path, and it fails open.
+      if (id && id !== s.scope_id && present.has(id)) { deps.get(s.scope_id).add(id); sawEdge = true; }
+    }
+  }
+  return sawEdge ? deps : null;
+}
+
+/**
+ * The SAME relation as {@link scopeWaves}, as edges rather than levels.
+ *
+ * WHY BOTH SHAPES SHIP. A level says when it is definitely safe to start a scope; an edge says when
+ * it BECAME safe, and the two differ by however long the slowest sibling in the previous level takes.
+ * A build that releases per level holds `cli-integration` until the last command scope lands even
+ * when the only scope it consumes went green first. Levels remain the ORDER the fan-out considers
+ * scopes in; edges are what release them.
+ *
+ * ADDITIVE, in the same sense `scope_waves` is: a consumer that ignores this field can rebuild the
+ * level-release points from `scope_waves` alone, which is exactly the previous behaviour.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {Array<{scope_id:string, path:string}>} scopes - The scopes, in their existing order.
+ * @returns {string[][]} `[dependant_path, dependency_path]` pairs, resolved paths on both ends so a
+ *   consumer resolves ids the one way it already resolves `scope_files`. Empty when no relation is
+ *   derivable — never a partial or invented one.
+ */
+/**
+ * Pairs of scopes that must not BUILD AT THE SAME TIME, because both may write the same path.
+ *
+ * WHY THIS IS A SCHEDULING FACT AND NOT A LINT. `shared_substrate` is the declared escape hatch from
+ * the disjointness rule: the spec lint passes an overlap both contracts declare, and the sandbox
+ * guard permits that path to every live order that names it. Every layer is individually correct and
+ * the join is wrong — concurrent writers to one declared-shared entry point lose each other's work,
+ * with every check green. An overlap that is NOT declared shared never reaches BUILD (the lint reds
+ * it and the run stops at the board review), so what this returns is precisely the set the escape
+ * hatch created.
+ *
+ * It is an EXCLUSION, not a dependency: neither scope has to go first, they only have to not
+ * overlap. The consumer orients each pair by build position, which is what keeps the constraint from
+ * ever forming a cycle with a real dependency edge.
+ *
+ * ADDITIVE, like the two fields above it: a consumer that ignores it schedules exactly as before.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {Array<{scope_id:string, path:string}>} scopes - The scopes, in their existing order.
+ * @returns {string[][]} Unordered `[pathA, pathB]` pairs. Empty when nothing can collide.
+ */
+export function scopeExclusions(cwd, slug, scopes) {
+  if (scopes.length < 2) return [];
+  const globsOf = (s) => {
+    try {
+      const fm = parseFrontmatter(readFileSync(s.path, "utf8"));
+      return [...(fm.allowed_file_substrate || []), ...(fm.shared_substrate || [])].map((g) => String(g).trim()).filter(Boolean);
+    } catch { return []; }
+  };
+  const globs = new Map(scopes.map((s) => [s.scope_id, globsOf(s)]));
+  // Two globs MEET when either matches the other read as a literal path. It is an approximation of
+  // "these two patterns can name the same file", and it is deliberately the generous one: a false
+  // meet costs two scopes their overlap in time, a missed meet costs one of them its work.
+  const meet = (a, b) => a === b || globToRegExp(a).test(b) || globToRegExp(b).test(a);
+  const out = [];
+  for (let i = 0; i < scopes.length; i++) {
+    for (let j = i + 1; j < scopes.length; j++) {
+      const A = globs.get(scopes[i].scope_id) || [], B = globs.get(scopes[j].scope_id) || [];
+      if (A.some((a) => B.some((b) => meet(a, b)))) out.push([scopes[i].path, scopes[j].path]);
+    }
+  }
+  return out;
+}
+
+export function scopeDeps(cwd, slug, scopes) {
+  if (scopes.length < 2) return [];
+  const deps = scopeDepGraph(scopes);
+  if (!deps) return [];
+  const pathOf = new Map(scopes.map((s) => [s.scope_id, s.path]));
+  const out = [];
+  for (const s of scopes) {
+    for (const d of deps.get(s.scope_id) || []) {
+      if (pathOf.has(d)) out.push([s.path, pathOf.get(d)]);
+    }
+  }
+  return out;
+}
+
 export function hasOrientArtifacts(cwd, slug) {
   const dir = orientDir(cwd, slug);
   if (!existsSync(dir)) return false;
@@ -118,7 +278,7 @@ export function hasOrientArtifacts(cwd, slug) {
 
 /**
  * The use-case directory this run's spec tree lands in. The ledger may name a non-default
- * `spec_folder` (`init-run.mjs --spec-folder`), so honour it when present and fall back to the
+ * `spec_folder` (`harness init run --spec-folder`), so honour it when present and fall back to the
  * registry path otherwise — never a spelled-out root (test #45).
  *
  * @param {string} cwd - Project root.
@@ -202,7 +362,7 @@ export function deriveResumeState(cwd, slug) {
   const hrPath = harnessRun(cwd, slug);
   const hr = existsSync(hrPath) ? parseFrontmatter(readFileSync(hrPath, "utf8")) : {};
 
-  // Resolved contract PATHS, not bare filenames: compile-order.mjs and t0-verify.mjs both resolve
+  // Resolved contract PATHS, not bare filenames: harness compile and harness verify t0 both resolve
   // `--scope` against cwd, so a bare "SC-x.md" names a file that does not exist, compile-order
   // exits 2, and the attempt loop reads that non-zero exit as the stagnation breaker — a resumed
   // run would falsely trip the inner breaker and hammer-propose every scope instead of continuing.
@@ -231,6 +391,19 @@ export function deriveResumeState(cwd, slug) {
     project_profile_path: projectProfile(cwd, slug),
     has_project_profile: existsSync(projectProfile(cwd, slug)),
     scope_files,
+    // The same scopes, grouped so a wave never contains a scope depending on one still in flight.
+    // Additive: a caller that ignores it gets exactly today's behavior.
+    scope_waves: scopeWaves(cwd, slug, scope_files),
+    // The same relation as edges. A wave says when a scope is definitely safe to start; an edge says
+    // when it BECAME safe. A fan-out that releases per wave holds a scope until the slowest member of
+    // the previous wave lands, even when the one scope it consumes finished first. Also additive: the
+    // wave list alone rebuilds the per-wave release points, which is the previous behaviour.
+    scope_deps: scopeDeps(cwd, slug, scope_files),
+    // Pairs that may write the same declared-shared path. Not an ordering — an exclusion: they may
+    // build in either order, and they may not build at the same time. Concurrent writers to one
+    // shared entry point lose each other's work while every check stays green, and the escape hatch
+    // that permits the overlap is the same one that makes it invisible to the disjointness lint.
+    scope_exclusions: scopeExclusions(cwd, slug, scope_files),
     pending_orders: orderFiles.filter((f) => f.endsWith(".json") && !resultFiles.includes(f)),
     eval_rounds_done: resultFiles
       .filter((f) => /^evaluate-r\d+\.json$/.test(f))
@@ -252,11 +425,11 @@ export function deriveResumeState(cwd, slug) {
 export function setRunStatus(cwd, slug, status) {
   const p = harnessRun(cwd, slug);
   if (!existsSync(p)) {
-    return { ok: false, path: p, status, reason: `no harness-run.md for slug "${slug}" — open the run with init-run.mjs (GATE L0.1) before setting its status` };
+    return { ok: false, path: p, status, reason: `no harness-run.md for slug "${slug}" — open the run with harness init run (GATE L0.1) before setting its status` };
   }
   const body = readFileSync(p, "utf8");
   if (!/^status:.*$/m.test(body)) {
-    return { ok: false, path: p, status, reason: `harness-run.md carries no "status:" line to replace — the ledger's frontmatter is malformed (references/ledger-schema.md)` };
+    return { ok: false, path: p, status, reason: `harness-run.md carries no "status:" line to replace — the ledger's frontmatter is malformed (references/protocol.md)` };
   }
   try {
     writeFileSync(p, body.replace(/^status:.*$/m, `status: ${status}`));
@@ -270,35 +443,6 @@ export function setRunStatus(cwd, slug, status) {
   return { ok: true, path: p, status };
 }
 
-/**
- * Point the substrate pointer at the scope about to be built. `hooks/sandbox-guard.mjs` reads
- * this to decide which write-whitelist a worker is held to, so a failed write here does not
- * degrade gracefully — it silently enforces the WRONG scope's substrate.
- *
- * @param {string} cwd - Project root.
- * @param {string} slug - Feature slug.
- * @param {string} scopeId - Scope contract id.
- * @returns {{ok: boolean, path: string, slug: string, scope_id: string, reason?: string}} Outcome.
- */
-export function writeActiveScope(cwd, slug, scopeId) {
-  const p = activeScope(cwd);
-  // A throw here would exit 1 with a stack trace and an empty stdout — readable enough to the
-  // workflow (any non-zero aborts the scope), but the caller learns nothing it can log. Report the
-  // failure as the same outcome record every other operation returns.
-  try {
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, `${JSON.stringify({ slug, scope_id: scopeId }, null, 2)}\n`);
-  } catch (e) {
-    return { ok: false, path: p, slug, scope_id: scopeId, reason: `could not write the substrate pointer: ${e.message}` };
-  }
-  let readBack;
-  try { readBack = JSON.parse(readFileSync(p, "utf8")); } catch { readBack = null; }
-  if (readBack?.scope_id !== scopeId || readBack?.slug !== slug) {
-    return { ok: false, path: p, slug, scope_id: scopeId, reason: `pointer read back as ${JSON.stringify(readBack)} — sandbox-guard would hold the next worker to the wrong substrate` };
-  }
-  return { ok: true, path: p, slug, scope_id: scopeId };
-}
-
 /**
  * Point the substrate pointer at the order about to be executed.
  *
@@ -325,21 +469,27 @@ export function writeActiveOrder(cwd, slug, orderPath) {
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "resume-state.mjs --slug <slug> [--cwd <dir>] [--require <phase> | --set-status <status> | --set-active-scope <scope-id> | --set-active-order <path>]",
+  usage: "harness.mjs probe resume --slug <slug> [--cwd <dir>] [--require <phase> | --set-status <status> | --set-active-order <path>]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str", required: true },
   cwd: { type: "path" },
   require: { type: "enum", values: PHASES },
   "set-status": { type: "enum", values: RUN_STATUSES },
-  "set-active-scope": { type: "str" },
   "set-active-order": { type: "str" },
 };
 
-export function main() {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Derive the run's resume state, or set one of the run pointers.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = args.cwd || process.cwd();
 
-  const ops = [args.require && "--require", args.setStatus && "--set-status", args.setActiveScope && "--set-active-scope", args.setActiveOrder && "--set-active-order"].filter(Boolean);
+  const ops = [args.require && "--require", args.setStatus && "--set-status", args.setActiveOrder && "--set-active-order"].filter(Boolean);
   if (ops.length > 1) {
     process.stderr.write(JSON.stringify({ error: "conflicting_flags", flags: ops, expected: "one operation per invocation" }) + "\n");
     process.exit(2);
@@ -366,12 +516,6 @@ export function main() {
     process.exit(r.ok ? 0 : 3);
   }
 
-  if (args.setActiveScope) {
-    const r = writeActiveScope(cwd, args.slug, args.setActiveScope);
-    console.log(JSON.stringify(r));
-    process.exit(r.ok ? 0 : 3);
-  }
-
   if (args.setActiveOrder) {
     const r = writeActiveOrder(cwd, args.slug, args.setActiveOrder);
     console.log(JSON.stringify(r));
@@ -382,6 +526,3 @@ export function main() {
   process.exit(0);
 }
 
-if (isMain(import.meta.url)) {
-  main();
-}

package/{skills/tech-lead/scripts → kernel/probe}/stats.mjs

@@ -17,14 +17,14 @@
 // Output is a StatsReport (domain.schema.json#/$defs/StatsReport), self-validated before it
 // is emitted; --format table renders the human view from the already-validated object.
 //
-// Usage: node stats.mjs [--cwd <dir>] [--metrics-dir <dir>] [--slug <slug>] [--format json|table]
+// Usage: node `harness probe stats` [--cwd <dir>] [--metrics-dir <dir>] [--slug <slug>] [--format json|table]
 
 import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { resolve, join } from "node:path";
-import { validate } from "./validate-envelope.mjs";
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
-import { localDir, decisions as decisionsPath, metricsDir as metricsDirPath, SHARED } from "./lib/paths.mjs";
+import { validate } from "../verify/envelope.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { collectRun } from "../report/export.mjs";
+import { localDir, decisions as decisionsPath, metricsDir as metricsDirPath, SHARED } from "../lib/paths.mjs";
 
 /**
  * Read every metrics shard, partitioning valid rows, pathology rows, and malformed lines.
@@ -284,6 +284,79 @@ export function readDecisions(cwd) {
   } catch { return []; }
 }
 
+/**
+ * Project run economics for every run in the checkout — measurement-table row 4.
+ *
+ * WHY IT LIVES HERE and reads the run trace rather than the metrics shards: the same reason
+ * `--ratchet` reads `trials.jsonl` and `--hooks` reads `decisions.jsonl`. A harvest row is written
+ * once at SHIP S.6 and carries counts, never durations or cost — so a run that never shipped, which
+ * is exactly the run whose cost you want to see, has no harvest row at all. The journal has one row
+ * per agent call from the first dispatch onwards.
+ *
+ * FACTS ONLY, unchanged: sums, counts and durations over rows that already exist. Nothing here is
+ * divided by an expectation or compared to a target, because that would be a grade.
+ *
+ * @param {string} cwd - Project root.
+ * @param {(string|null)} [slug=null] - Restrict to one feature slug.
+ * @returns {object} `{runs, per_run[]}` — one economics block per run, newest last, each tagged
+ *   with its run_id and slug.
+ */
+export function economicsReport(cwd, slug = null) {
+  const root = localDir(cwd);
+  if (!existsSync(root)) return { runs: 0, per_run: [] };
+  let slugs;
+  try { slugs = slug ? [slug] : readdirSync(root); } catch { return { runs: 0, per_run: [] }; }
+  const per_run = [];
+  for (const s of slugs.sort()) {
+    let collected = null;
+    try { collected = collectRun(cwd, s); } catch { collected = null; }
+    if (!collected) continue; // no receipt ⇒ not a run, which is not an error
+    per_run.push({ run_id: collected.run_id, slug: s, ...collected.economics });
+  }
+  return { runs: per_run.length, per_run };
+}
+
+/**
+ * Format a dollar figure, keeping "no cost row was recorded" visibly different from "$0.0000".
+ * @param {(number|null|undefined)} v - A cost in USD, or null when nothing recorded one.
+ * @returns {string} e.g. `$1.2000`, or `—` when the value is absent.
+ */
+function money(v) {
+  return v === null || v === undefined ? "—" : `$${v.toFixed(4)}`;
+}
+
+/**
+ * Render the economics report as text.
+ * @param {object} r - Output of {@link economicsReport}.
+ * @returns {string} The multi-line report.
+ */
+function renderEconomics(r) {
+  const lines = [`economics: ${r.runs} run(s) with a receipt`];
+  if (!r.runs) {
+    lines.push("", "(no run trace in this checkout — this reads the run's own records, so it is empty");
+    lines.push(" until a run opens, and stays readable after one ends until the trace is cleaned.)");
+    return lines.join("\n");
+  }
+  for (const e of r.per_run) {
+    lines.push("", `  ${e.run_id ?? e.slug}`,
+      `    agent calls           ${e.agent_calls}   (${e.retried_calls} retried, ${e.failed_calls} failed, ${e.killed_calls} killed)`,
+      `    cost                  ${money(e.cost_usd)}   attributed ${money(e.cost_attributed_usd)} · unattributed ${money(e.cost_unattributed_usd)}`,
+      `    wall clock            ${e.wall_ms_total === null ? "—" : `${Math.round(e.wall_ms_total / 1000)}s`}`,
+      `    to first write        ${e.calls_to_first_write ?? "—"} call(s)` +
+        `${e.seconds_to_first_write === null ? "" : ` · ${e.seconds_to_first_write}s`}`,
+      `    dispatches            ${e.dispatches}   (${e.dispatches_answered} answered, ${e.dispatches_costed} costed)`);
+    for (const m of e.by_model) {
+      lines.push(`      ${String(m.model).padEnd(22)}${String(m.calls).padStart(3)} call(s)  ${money(m.cost_usd)}`);
+    }
+    // The gap is named, never left as a quiet shortfall in the total.
+    if (e.dispatches_costed < e.dispatches) {
+      lines.push(`    ⓘ ${e.dispatches - e.dispatches_costed} dispatch(es) carry no cost row — the journal exists only on the`,
+        "      workflow lane, so a prose-lane or --tiny dispatch has no agent call to join to.");
+    }
+  }
+  return lines.join("\n");
+}
+
 /**
  * Render a StatsReport as a human-readable fixed-width table.
  * @param {object} report - A validated StatsReport (see {@link aggregate}).
@@ -321,8 +394,8 @@ function renderTable(report) {
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "stats.mjs [--cwd <dir>] [--metrics-dir <dir>] [--slug <slug>] [--format json|table] " +
-         "[--ratchet] [--hooks]",
+  usage: "harness.mjs probe stats [--cwd <dir>] [--metrics-dir <dir>] [--slug <slug>] [--format json|table] " +
+         "[--ratchet] [--hooks] [--economics]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   cwd: { type: "path" },
   "metrics-dir": { type: "path" },
@@ -330,6 +403,7 @@ export const ARGV_SPEC = {
   format: { type: "enum", values: ["json", "table"], default: "json" },
   ratchet: { type: "flag" },
   hooks: { type: "flag" },
+  economics: { type: "flag" },
 };
 
 /**
@@ -386,23 +460,31 @@ function renderHooks(r) {
   return lines.join("\n");
 }
 
-const isMainModule = isMain(import.meta.url);
-if (isMainModule) {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Aggregate the metric shards, or report the ratchet, hook and economics ledgers.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = resolve(args.cwd || process.cwd());
   const metricsDir = args.metricsDir ? resolve(cwd, args.metricsDir) : metricsDirPath(cwd);
   const format = args.format;
 
   // The two exit measurements are separate modes: each reads a different ledger, and neither is a
   // StatsReport (which is schema-locked to the harvest shards).
-  if (args.ratchet || args.hooks) {
+  if (args.ratchet || args.hooks || args.economics) {
     const out = {};
     if (args.ratchet) out.ratchet = ratchetReport(readAllTrials(cwd, args.slug ?? null));
     if (args.hooks) out.hooks = hooksReport(readDecisions(cwd));
+    if (args.economics) out.economics = economicsReport(cwd, args.slug ?? null);
     if (format === "table") {
       const parts = [];
       if (out.ratchet) parts.push(renderRatchet(out.ratchet));
       if (out.hooks) parts.push(renderHooks(out.hooks));
+      if (out.economics) parts.push(renderEconomics(out.economics));
       console.log(parts.join("\n\n"));
     } else {
       console.log(JSON.stringify(out, null, 2));