@renzrollon/interlock 1.1.0 → 1.2.0

package/bin/interlock

@@ -14,13 +14,28 @@
 // own — only the agents it spawns run commands. So a policy module that is not
 // wired to a subcommand here is a policy the model will improvise in prose.
 
-import { execFileSync } from 'node:child_process'
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { execFileSync, spawnSync } from 'node:child_process'
+import {
+  appendFileSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs'
+import { dirname, isAbsolute, join, relative, sep } from 'node:path'
+import { constants as osConstants, cpus, tmpdir } from 'node:os'
 import { performance } from 'node:perf_hooks'
 import {
   planWaves,
   formatPlan,
+  laneLabel,
+  laneModel,
   createRunState,
   nextStep,
   recordBatchResult,
@@ -31,8 +46,11 @@ import {
 } from '../lib/waves.mjs'
 import {
   CLASSIFIED_PATH,
+  LAST_STEP_PATH,
+  VERIFY_TIMINGS_PATH,
   checkSequence,
   readManifest,
+  relayStep,
   runClassified,
   runClose,
   runCommit,
@@ -43,9 +61,13 @@ import {
   runReplan,
   runReviewed,
   runStart,
-  runVerifyFinal
+  runVerifyFinal,
+  writeManifest
 } from '../lib/run.mjs'
 import { haltStep } from '../lib/run.mjs'
+import { explicitStateHome, resolveStateHome } from '../lib/state-home.mjs'
+import { probeClaudeEffort, probeClaudeVersion } from '../lib/host/claude-cli.mjs'
+import { observeClaudeEnv, runtimeSlotsOf } from '../lib/host/claude-env.mjs'
 import { composeCheckpointMessage, postNtfy, readNotifyConfig, NOTIFY_TOPIC_ENV } from '../lib/notify.mjs'
 import { classifySurface } from '../lib/surface.mjs'
 import { evaluateGate, formatGate, TOLERANCE_BAND } from '../lib/findings.mjs'
@@ -170,6 +192,9 @@ Usage:
   interlock run close [--halt <reason>]      names, writes the results, calls
                       [--host-banners <f>]
                       [--host-observed <f>]
+  (record-batch, judge, reviewed, remediated, commit, replan and close also
+  take --host-records <f>: the runner's per-spawn host observations, beside
+  --results and never inside them)
                                             \`then.argv\`, and repeats until
                                             \`then\` is null. It decides nothing:
                                             every branch the loop has (apply-only,
@@ -265,6 +290,8 @@ Usage:
   interlock verify unit --result <file>     Judge a unit result on its own
   interlock verify spill --run-id <id> --kind <k> --input <f>
                                            Spill oversized stdout/stderr to disk
+  interlock verify exec --kind <k> --command <cmd>
+                                           Run one planned check and time it
   interlock verify cluster --failures <f>   Group failures by root-cause signature
   interlock verify repair --state <file>    Decide repair / halt / accept next
   interlock plan fingerprint [change]      Fingerprint a change's planning inputs
@@ -286,6 +313,10 @@ Usage:
 Common options:
   --json                 Emit JSON instead of human-readable text
   --root <dir>           Repo root (default: cwd)
+  --state-home <dir>     Where corpora (trajectories, outcomes, metrics, resume
+                         cards, interrupted notes, autonomy ledger) are read and
+                         written; default INTERLOCK_STATE_HOME, else the main
+                         checkout when --root is a linked worktree, else --root
   Any <file> argument accepts "-" to read that input from stdin. Only one input
   per invocation may be "-", since stdin can only be drained once.
 
@@ -643,6 +674,17 @@ verify spill:
   head/tail slice bounded by \`interlock limits\`' verify preview budget.
   Always exits 0.
 
+verify exec:
+  --kind <k>             The planned step this runs, e.g. typecheck/unit/lint (required)
+  --command <cmd>        The planned command, verbatim; run through the shell (required)
+  --cwd <dir>            Directory to run it in (default: the current one)
+  Runs the command with its stdout, stderr and exit code passed through
+  unchanged, and appends { kind, exitCode, durationMs, command, at } to
+  .claude/ship/verify-timings.jsonl. \`run judge\` folds those durations into
+  the inter-wave verify budget, so the budget counts the checks themselves
+  rather than the relay and agent time around them. A failed append is a
+  stderr warning; the exit code is always the command's.
+
 plan:
   fingerprint [change]   Hash the inputs a plan for this change is derived from:
                          proposal.md, design.md, tasks.md (with checkbox markers
@@ -826,6 +868,51 @@ function readStdin() {
   }
 }
 
+/**
+ * The explicit state home, if one was given: `--state-home <dir>`, else
+ * `INTERLOCK_STATE_HOME` (ship/state-home). `--root` keeps naming the working
+ * tree; this names where its corpora go.
+ */
+function explicitHome(flags) {
+  return explicitStateHome({
+    flag: typeof flags['state-home'] === 'string' ? flags['state-home'] : undefined,
+    env: process.env
+  })
+}
+
+/**
+ * The state home a run starts with: the explicit value, else the resolver. Never
+ * a manifest already at the root — that is the PREVIOUS run's.
+ */
+function startStateHome(root, flags) {
+  return resolveStateHome(root, { explicit: explicitHome(flags) || undefined, env: {} })
+}
+
+/**
+ * The state home a corpus command reads and writes (design D14): the home the
+ * live run at this root recorded, so a lane's `wave-state` append or a report
+ * run mid-run never disagrees with the run's own; else the explicit value; else
+ * the resolver. Resolved once per invocation and handed to every corpus reader
+ * and writer the command calls.
+ *
+ * @returns {{home: string, surface: string, reason: string|null, resolvedFrom: string}}
+ */
+function corpusHome(root, flags) {
+  const explicit = explicitHome(flags)
+  if (!explicit) {
+    const manifest = readManifest(root)
+    if (manifest && typeof manifest.stateHome === 'string' && manifest.stateHome) {
+      return {
+        home: manifest.stateHome,
+        surface: typeof manifest.surface === 'string' ? manifest.surface : 'unknown',
+        reason: typeof manifest.stateHomeReason === 'string' ? manifest.stateHomeReason : null,
+        resolvedFrom: typeof manifest.stateHomeFrom === 'string' ? manifest.stateHomeFrom : 'git'
+      }
+    }
+  }
+  return resolveStateHome(root, { explicit: explicit || undefined, env: {} })
+}
+
 function readInput(value, what) {
   if (!value || value === true) die(`${what} is required`)
   const raw = value === '-' ? readStdin() : readFileSync(value, 'utf8')
@@ -875,6 +962,51 @@ function emit(json, obj, text) {
   process.stdout.write(json ? JSON.stringify(obj, null, 2) + '\n' : text)
 }
 
+/**
+ * Print a `run` step, shaped for the host that will read it, and keep a copy of
+ * the exact bytes printed.
+ *
+ * `relay: true` routes the step through `relayStep`, which slims it for the
+ * Workflow host — the one host whose stdout is retyped by a model rather than
+ * read by a process. The close does not come through here at all: its summary
+ * is what it is for, and it must not overwrite the copy a halt points at.
+ *
+ * The copy at LAST_STEP_PATH is forensic, not a corpus: when a relay's copy
+ * does not parse, the halt points here instead of at a transcript. A failed
+ * write is spoken on stderr and never touches the exit code — losing the copy
+ * must not lose the step.
+ */
+/**
+ * The machine's CPU count, or null when the platform will not say. The vendor
+ * reduces the Workflow runtime's concurrency on small machines by an amount it
+ * does not publish, so this is recorded beside the default and never turned
+ * into a number of its own.
+ */
+function cpuCount() {
+  try {
+    const n = cpus().length
+    return Number.isInteger(n) && n > 0 ? n : null
+  } catch {
+    return null
+  }
+}
+
+function emitRunStep(json, root, step, text, { relay = false } = {}) {
+  if (!json) {
+    process.stdout.write(text)
+    return
+  }
+  const shaped = relay ? relayStep(readManifest(root), step) : step
+  const out = JSON.stringify(shaped, null, 2) + '\n'
+  try {
+    mkdirSync(join(root, dirname(LAST_STEP_PATH)), { recursive: true })
+    writeFileSync(join(root, LAST_STEP_PATH), out)
+  } catch (err) {
+    process.stderr.write(`interlock: ${LAST_STEP_PATH} not written: ${(err && err.message) || err}\n`)
+  }
+  process.stdout.write(out)
+}
+
 /**
  * record-* / replan: default stdout is the new state. --write-state writes that
  * state to a file and stdout becomes nextStep() — the shape `wave-state next`
@@ -932,13 +1064,18 @@ function changeFor(state, flagChange) {
   return changeOf(state) || flag
 }
 
-// `wave-state next` / `--write-state` both surface the state machine's next
-// step. A `run-batch`/`test-wave` step carries `tasks[]` (the current batch, as
-// LANES) and `remainingBatches` (rest of the wave, as batches of lanes). ship.js
-// runs remainingBatches sequentially before the next record ping, so the
-// reconstructable spawn list is remainingBatches — not only tasks[]. Mid-wave
-// record-batch --write-state is cursor catch-up and MUST NOT duplicate those
-// events.
+// The `wave-state` protocol: `wave-state next` / `--write-state` both surface
+// the state machine's next step. A `run-batch`/`test-wave` step carries
+// `tasks[]` (the current batch, as LANES) and `remainingBatches` (rest of the
+// wave, as batches of lanes). A caller of that protocol runs remainingBatches
+// sequentially before its next record call, so the reconstructable spawn list
+// is remainingBatches — not only tasks[]. Mid-wave record-batch --write-state
+// is cursor catch-up and MUST NOT duplicate those events.
+//
+// The `run` program is NOT that protocol: it emits one step per batch, so it
+// passes the batch's own `lanes` and gets exactly those logged (see
+// `logLaneSpawns` in lib/run.mjs). Logging a whole wave there wrote spawn events
+// for lanes a halted run never dispatched.
 //
 // One spawn per LANE, because a lane is one agent. Counting per task would
 // report four spawns for a wave that ran two, which is the fold this change
@@ -955,36 +1092,30 @@ function spawnLanesOf(step) {
     .filter(lane => lane.length)
 }
 
-// The label the workflow gives the same agent (`workflows/ship.js` laneLabel), so
-// a trajectory line and the agent it describes carry one name rather than two.
-function laneLabelOf(lane) {
-  return lane.length === 1 ? lane[0].id : `${lane[0].id}+${lane.length - 1}`
-}
-
-// The model the lane runs on: its hardest task's. A lane is one agent and that
-// agent has to be capable of everything in it.
-function laneModelOf(lane) {
-  const tier = lane.reduce((m, t) => (Number.isInteger(t.tier) && t.tier > m ? t.tier : m), 0)
-  const hardest = lane.find(t => t.tier === tier) || lane[0]
-  return hardest && typeof hardest.model === 'string' ? hardest.model : undefined
-}
-
 // Takes the run's `state` rather than a runId, so the change name is resolved
 // from it the same way `logWaveMutation` does instead of being threaded in by a
 // caller who may not have been given one.
-function logAgentSpawns(root, { state, change, step, source }) {
-  if (!step || (step.action !== 'run-batch' && step.action !== 'test-wave')) return true
-  if (source === 'record-batch' && Number(step.batchIndex) > 0) return true
+function logAgentSpawns(root, { state, change, step, source, lanes }) {
+  const explicit = Array.isArray(lanes)
+  if (!explicit) {
+    if (!step || (step.action !== 'run-batch' && step.action !== 'test-wave')) return true
+    if (source === 'record-batch' && Number(step.batchIndex) > 0) return true
+  }
   const runId = runIdOf(state)
   const changeName = changeFor(state, change)
+  const dispatched = explicit
+    ? lanes
+        .map(lane => (Array.isArray(lane) ? lane.filter(t => t && typeof t === 'object') : []))
+        .filter(lane => lane.length)
+    : spawnLanesOf(step)
   let ok = true
-  for (const lane of spawnLanesOf(step)) {
+  for (const lane of dispatched) {
     const spawn = appendRunLogEvent(root, {
       runId,
       change: changeName,
       type: 'agent-spawn',
-      label: laneLabelOf(lane),
-      model: laneModelOf(lane),
+      label: laneLabel(lane),
+      model: laneModel(lane),
       kind: 'implementer',
       // The lane's anchor task. A multi-task lane's later ids are recoverable
       // from the plan and from its per-task record-batch results; what this line
@@ -1217,6 +1348,127 @@ function observedChangedPaths(root) {
   return paths
 }
 
+// The identity a shared-tree snapshot is committed under. It is nobody's: it is
+// set in the environment of the one `commit-tree` call and never in any config,
+// because `commit-tree` refuses to write without an identity, a CI checkout
+// often has none, and the user's name does not belong on an object they did not
+// author.
+const SNAPSHOT_IDENTITY = {
+  GIT_AUTHOR_NAME: 'Interlock',
+  GIT_AUTHOR_EMAIL: 'interlock@localhost',
+  GIT_COMMITTER_NAME: 'Interlock',
+  GIT_COMMITTER_EMAIL: 'interlock@localhost'
+}
+
+/**
+ * Every linked worktree of the repository that lies inside `root`, as a
+ * root-relative path with forward slashes. Read from git at capture time rather
+ * than kept as a list, so a host that moves where it puts its worktrees is
+ * still covered. Both sides are resolved through `realpathSync` because git
+ * reports real paths and `root` may arrive through a symlink (macOS's `/tmp`).
+ */
+function linkedWorktreesInside(root, porcelain) {
+  const top = realpathSync(root)
+  const inside = []
+  for (const line of porcelain.split('\n')) {
+    if (!line.startsWith('worktree ')) continue
+    let path = line.slice('worktree '.length)
+    try {
+      path = realpathSync(path)
+    } catch {
+      // A worktree whose directory is gone is compared as git listed it.
+    }
+    const rel = relative(top, path)
+    if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) continue
+    inside.push(rel.split(sep).join('/'))
+  }
+  return inside
+}
+
+/**
+ * The commit an isolated batch's lanes fork from: the shared tree as it stands,
+ * with every tracked edit, every deletion and every untracked file the ignore
+ * rules let through — so it holds every earlier fold of the run, which HEAD
+ * never does (the ship commit is the run's last step).
+ *
+ * Built through a temporary index and plumbing only. No ref moves, the
+ * repository's own index is never opened for writing, and no working-tree file
+ * changes. The commit is pinned by nothing: the lane worktrees forked from it
+ * keep it reachable until the fold, and git's own expiry takes it after.
+ *
+ * - The index is seeded from HEAD, so a tracked-but-ignored file keeps its
+ *   committed content instead of dropping out of the tree.
+ * - Interlock's run state and every linked worktree inside the root are left
+ *   out. Staged, a worktree becomes an embedded-repository entry; a lane's
+ *   checkout holds an empty directory there; and the fold reads that as a
+ *   deletion of a sibling lane's worktree.
+ * - A tree identical to HEAD's returns HEAD itself and creates no object.
+ *
+ * @param {string} root
+ * @param {string} [change] named in the snapshot's message, for whoever finds it
+ * @returns {string|null} null on any failure — `decorate` halts on it rather
+ *   than forking lanes from a base nobody captured
+ */
+function snapshotTree(root, change) {
+  let dir = null
+  try {
+    dir = mkdtempSync(join(tmpdir(), 'interlock-snapshot-'))
+    const env = { ...process.env, GIT_INDEX_FILE: join(dir, 'index') }
+    const git = (args, extraEnv = {}) =>
+      execFileSync('git', args, {
+        cwd: root,
+        encoding: 'utf8',
+        env: { ...env, ...extraEnv },
+        stdio: ['ignore', 'pipe', 'ignore']
+      }).trim()
+
+    git(['read-tree', 'HEAD'])
+    const worktrees = linkedWorktreesInside(root, git(['worktree', 'list', '--porcelain']))
+    git([
+      'add',
+      '-A',
+      '--',
+      '.',
+      ':(exclude).claude/ship',
+      ...worktrees.map(rel => `:(exclude,literal)${rel}`)
+    ])
+    const tree = git(['write-tree'])
+    const head = git(['rev-parse', 'HEAD'])
+    if (tree === git(['rev-parse', 'HEAD^{tree}'])) return head || null
+    // --no-gpg-sign: `commit.gpgSign` would otherwise ask a signing agent to
+    // sign an object nobody will ever push.
+    const message = `interlock: shared-tree snapshot (${change || 'unknown change'})`
+    return git(['commit-tree', '--no-gpg-sign', tree, '-p', head, '-m', message], SNAPSHOT_IDENTITY) || null
+  } catch {
+    return null
+  } finally {
+    if (dir) rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+/**
+ * The commit a lane worktree is checked out at, as git reports it from inside
+ * the worktree — never the base the lane's agent says it forked from, because
+ * that report is the thing being audited. `null` when git cannot answer,
+ * including when the directory is gone.
+ *
+ * @param {string} worktreePath
+ * @returns {string|null}
+ */
+function worktreeHead(worktreePath) {
+  if (typeof worktreePath !== 'string' || !worktreePath || !existsSync(worktreePath)) return null
+  try {
+    return (
+      execFileSync('git', ['-C', worktreePath, 'rev-parse', 'HEAD'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore']
+      }).trim() || null
+    )
+  } catch {
+    return null
+  }
+}
+
 /**
  * A lane worktree's actual writes relative to the shared base commit, as git
  * sees them — never a prediction. `null` means git could not answer (bad
@@ -1594,7 +1846,7 @@ async function main() {
       if (flags.metrics !== undefined) {
         if (flags.metrics === true) die('--metrics requires a change name')
         const surviving = result.total + result.malformed.length
-        metrics = writeReviewMetrics(root, {
+        metrics = writeReviewMetrics(corpusHome(root, flags).home, {
           change: String(flags.metrics),
           counts: {
             raised: result.dismissedCount + result.droppedByQuality + surviving,
@@ -1647,6 +1899,7 @@ async function main() {
       // would encode. Every value here is one `if` away from a threshold; the
       // absence of that `if` is the feature. See the header of lib/report.mjs.
       const report = buildReport(root, {
+        stateHome: corpusHome(root, flags),
         since: typeof flags.since === 'string' ? flags.since : undefined,
         change: typeof flags.change === 'string' ? flags.change : undefined,
         maxRuns: num(flags, 'max-runs')
@@ -1710,23 +1963,27 @@ async function main() {
       // `limits`: LIMITS holds positive-integer loop counts (its invariant test
       // asserts it), whereas the lane-cap table is a tier→cap map and the solo
       // envelope is a separate object — the same reason `effort` is emitted apart.
+      // The slot count this machine's runtime will honour, as far as this
+      // process can see it — beside the vendor fact, never instead of it.
+      const runtimeObserved = runtimeSlotsOf(observeClaudeEnv(process.env, { cpuCount: cpuCount() }))
       emit(
         json,
         {
           limits: LIMITS,
-          runtime: RUNTIME,
+          runtime: { ...RUNTIME, observed: runtimeObserved },
           evals: EVAL_CAPS,
           // Its own group, beside `evals` rather than inside it: the eval caps
           // are scalars a reader compares a running total against, and this is
           // the table that produced the total. Its `id` is what a recorded
-          // result row is keyed against.
+          // result row is keyed against. Emitted whole, so each model's own
+          // `cacheMultipliers.read` entry and both write tiers travel with it.
           prices: MODEL_PRICES,
           report: REPORT_CAPS,
           effort: EFFORT,
           laneCaps: LANE_CAPS,
           solo: SOLO
         },
-        formatLimits()
+        formatLimits({ runtimeObserved })
       )
       break
     }
@@ -1791,7 +2048,7 @@ async function main() {
       // Read-only by construction — see the header of lib/doctor.mjs. The exit
       // code is the whole point: a preflight that only prints is a preflight a
       // zero-touch run walks straight past.
-      const report = diagnose(root)
+      const report = diagnose(root, { cpuCount: cpuCount(), stateHome: explicitHome(flags) || undefined })
       emit(json, report, formatDoctor(report))
       if (!report.ok) process.exit(1)
       break
@@ -1810,6 +2067,7 @@ async function main() {
         const outDir = typeof flags.out === 'string' ? flags.out : ''
         if (!outDir) die('evals capture requires --out <dir>')
         const result = captureCase(root, {
+          stateHome: corpusHome(root, flags).home,
           runId,
           taskId: typeof flags.task === 'string' ? flags.task : undefined,
           outDir
@@ -1923,7 +2181,7 @@ async function main() {
       let metrics = null
       if (flags.metrics !== undefined) {
         if (flags.metrics === true) die('--metrics requires a change name')
-        metrics = writeReviewMetrics(root, { change: String(flags.metrics), counts: result.counts })
+        metrics = writeReviewMetrics(corpusHome(root, flags).home, { change: String(flags.metrics), counts: result.counts })
         if (!metrics.written) warn(`metrics not written: ${metrics.reason}`)
       }
 
@@ -2041,10 +2299,11 @@ async function main() {
         // trusting the untrusted source exactly when the trusted one is
         // missing would defeat the partition on the runs most likely to need
         // it.
+        const home = corpusHome(root, flags).home
         const receipt = runId
-          ? queryRunLog(root, runId, { type: 'run-receipt' }).records.pop() || null
+          ? queryRunLog(home, runId, { type: 'run-receipt' }).records.pop() || null
           : null
-        const written = appendOutcome(root, { ...reportedHalf, observed: observedFromReceipt(receipt) })
+        const written = appendOutcome(home, { ...reportedHalf, observed: observedFromReceipt(receipt) })
         if (carriedObserved) {
           warn(
             'outcome record carried an "observed" group: refused. Observed values are derived ' +
@@ -2066,7 +2325,7 @@ async function main() {
           `${written.written ? `recorded → ${written.path}` : `not recorded: ${written.reason}`}\n`
         )
       } else if (sub === 'list' || sub === undefined) {
-        const result = readOutcomes(root)
+        const result = readOutcomes(corpusHome(root, flags).home)
         emit(json, result, formatOutcomes(result))
       } else {
         die(`unknown outcomes subcommand: ${sub}`)
@@ -2076,9 +2335,10 @@ async function main() {
 
     case 'run-log': {
       const sub = positional[1]
+      const logHome = corpusHome(root, flags).home
       if (sub === 'append') {
         const record = readInput(flags.event, '--event <file|->')
-        const { written, path, reason } = appendRunLogEvent(root, record)
+        const { written, path, reason } = appendRunLogEvent(logHome, record)
         if (!written) {
           // Never fatal: losing a trajectory line must not fail the run that
           // produced it. Say so on stderr and exit 0.
@@ -2087,17 +2347,17 @@ async function main() {
         emit(json, { written, path, reason }, `${written ? `recorded → ${path}` : `not recorded: ${reason}`}\n`)
       } else if (sub === 'list') {
         const change = typeof flags.change === 'string' ? flags.change : undefined
-        const runs = listRunLogs(root, { change })
+        const runs = listRunLogs(logHome, { change })
         emit(json, { runs }, formatRunLogList(runs))
       } else if (sub === 'show') {
         const runId = positional[2]
         if (!runId) die('run-log show requires a runId')
-        const result = readRunLog(root, runId)
+        const result = readRunLog(logHome, runId)
         emit(json, result, formatRunLog(result))
       } else if (sub === 'query') {
         const runId = typeof flags.run === 'string' ? flags.run : undefined
         if (!runId) die('--run is required')
-        const result = queryRunLog(root, runId, {
+        const result = queryRunLog(logHome, runId, {
           type: typeof flags.type === 'string' ? flags.type : undefined,
           halted: flags.halted === true
         })
@@ -2105,7 +2365,7 @@ async function main() {
       } else if (sub === 'check') {
         const runId = runIdFromFlags(flags)
         if (!runId) die('run-log check requires --state <file> (with a runId) or --run-id <id>')
-        const result = checkRunLog(root, runId)
+        const result = checkRunLog(logHome, runId)
         emit(json, result, formatRunLogCheck(result))
         if (!result.ok) process.exit(1)
       } else {
@@ -2217,7 +2477,7 @@ async function main() {
         }
         const opts = { context, ...verifyJudgeOpts(flags) }
         const verdict = judgeVerification(plan, results, opts)
-        const logOk = logVerifyJudgement(root, {
+        const logOk = logVerifyJudgement(corpusHome(root, flags).home, {
           runId: runIdFromFlags(flags),
           // Same precedence as every wave-state append site: the state names the
           // run, the flag is only the pre-state-name fallback.
@@ -2249,6 +2509,42 @@ async function main() {
           result,
           `spilled ${result.bytes} byte(s) → ${result.locator}${result.truncated ? ' (truncated preview)' : ''}\n`
         )
+      } else if (sub === 'exec') {
+        const kind = typeof flags.kind === 'string' ? flags.kind.trim() : ''
+        if (!kind) die('--kind is required')
+        const command = typeof flags.command === 'string' ? flags.command : ''
+        if (!command.trim()) die('--command is required')
+        const cwd = typeof flags.cwd === 'string' && flags.cwd.trim() ? flags.cwd : undefined
+        // Timed here, around the command and nothing else: the inter-wave budget
+        // used to be clocked from the step's dispatch to its judgement, which
+        // charged two relays and the verify agent's own turns to "verification"
+        // and spent the whole budget on the first checkpoint of every Workflow run.
+        const started = performance.now()
+        const ran = spawnSync(command, { shell: true, stdio: 'inherit', cwd })
+        const durationMs = Math.round(performance.now() - started)
+        let exitCode
+        if (ran.error) {
+          process.stderr.write(`interlock: verify exec could not run the command: ${ran.error.message}\n`)
+          exitCode = 127
+        } else if (typeof ran.status === 'number') {
+          exitCode = ran.status
+        } else {
+          const signal = ran.signal && osConstants.signals[ran.signal]
+          exitCode = Number.isInteger(signal) ? 128 + signal : 1
+        }
+        try {
+          mkdirSync(join(root, dirname(VERIFY_TIMINGS_PATH)), { recursive: true })
+          appendFileSync(
+            join(root, VERIFY_TIMINGS_PATH),
+            JSON.stringify({ kind, exitCode, durationMs, command, at: new Date().toISOString() }) + '\n'
+          )
+        } catch (err) {
+          // A timing is a budget input, not a gate: losing it costs the budget
+          // its precision (the judge falls back to the round trip, and says
+          // so), never the check its result.
+          process.stderr.write(`interlock: verify timing not recorded: ${(err && err.message) || err}\n`)
+        }
+        process.exit(exitCode)
       } else if (sub === 'cluster') {
         const failures = readInput(flags.failures, '--failures <file|->')
         if (!Array.isArray(failures)) {
@@ -2266,7 +2562,7 @@ async function main() {
         if (action.action === 'halt') process.exit(1)
       } else {
         die(
-          `unknown verify subcommand: ${sub || '(none)'} — expected plan|judge|unit|spill|cluster|repair`
+          `unknown verify subcommand: ${sub || '(none)'} — expected plan|judge|unit|spill|cluster|repair|exec`
         )
       }
       break
@@ -2393,11 +2689,13 @@ async function main() {
                 stdio: ['ignore', 'pipe', 'ignore']
               }).trim() || null
             } catch {
-              // An unreadable base is null, never a guess: `decorate` halts on
-              // it rather than folding a batch against a commit nobody read.
+              // An unreadable base is null, never a guess: `record-batch` halts
+              // on it rather than folding a batch against a commit nobody read.
               return null
             }
           },
+          snapshotTree,
+          worktreeHead,
           logWaveMutation,
           logAgentSpawns,
           observedChangedPaths,
@@ -2429,6 +2727,11 @@ async function main() {
 
       const results = flags.results ? readInput(flags.results, '--results <file|->') : []
       const resultList = Array.isArray(results) ? results : [results]
+      // The host's own observation of each spawn, beside the agents' results and
+      // never inside them: a result is the agent's report, a host record is what
+      // the host saw (design D7). Only the runner sends one; the CLI decides.
+      const records = flags['host-records'] ? readInput(flags['host-records'], '--host-records <file|->') : []
+      const hostRecords = Array.isArray(records) ? records : [records]
 
       let step
       if (sub === 'start') {
@@ -2446,7 +2749,7 @@ async function main() {
                 : ''
             }`
           )
-          emit(json, step, formatRunStep(step))
+          emitRunStep(json, root, step, formatRunStep(step))
           break
         }
         const name = resolved.name
@@ -2462,10 +2765,35 @@ async function main() {
             die(`--host-capabilities must be a JSON object of the host's declared capabilities: ${err.message}`)
           }
         }
+        const hostId = typeof flags.host === 'string' ? flags.host : undefined
+        // The Workflow host used to record `effort: flag` because the runtime's
+        // `agent()` option cannot be watched from this process. The installed
+        // CLI's help can. A caller that already named the capability keeps it.
+        let workflowEffortProbe = null
+        if (
+          hostId === 'workflow' &&
+          !(hostCapabilities && Object.prototype.hasOwnProperty.call(hostCapabilities, 'effort'))
+        ) {
+          workflowEffortProbe = probeClaudeEffort(process.env)
+          hostCapabilities = { ...(hostCapabilities || {}), effort: workflowEffortProbe.capability }
+        }
+        // The model-routing variables, the slot override and the host version,
+        // read from THIS process's environment — the Workflow driver forwards
+        // what `runStart` decides from them and reads none of them itself.
+        let hostEnv
+        if (hostId === 'workflow') {
+          const probed = probeClaudeVersion(process.env)
+          hostEnv = {
+            ...observeClaudeEnv(process.env, { version: probed.version, cpuCount: cpuCount() }),
+            ...(probed.reason ? { versionReason: probed.reason } : {})
+          }
+        }
         step = runStart(ctx, {
           change: name,
-          host: typeof flags.host === 'string' ? flags.host : undefined,
+          host: hostId,
           hostCapabilities,
+          hostEnv,
+          stateHome: startStateHome(root, flags),
           flags: {
             applyOnly: flags['apply-only'] === true,
             noCommit: flags['no-commit'] === true,
@@ -2482,6 +2810,18 @@ async function main() {
             strict: flags.strict !== undefined
           }
         })
+        if (workflowEffortProbe && workflowEffortProbe.capability === 'unsupported') {
+          // Spoken where the assumption used to be silent. The script still
+          // forwards the option: `agent()` does not reject an unknown key the
+          // way the CLI rejects an unknown flag.
+          const banner = `EFFORT ROUTING UNAVAILABLE (workflow): ${workflowEffortProbe.reason}`
+          const manifest = readManifest(root)
+          if (manifest) {
+            manifest.banners = [...(manifest.banners || []), banner]
+            writeManifest(root, manifest)
+          }
+          if (step && typeof step === 'object') step.banners = [...(step.banners || []), banner]
+        }
       } else if (sub === 'classified') {
         const classified =
           typeof flags.classified === 'string' && flags.classified.trim()
@@ -2489,25 +2829,25 @@ async function main() {
             : CLASSIFIED_PATH
         step = runClassified(ctx, { classifiedPath: classified })
       } else if (sub === 'record-batch') {
-        step = runRecordBatch(ctx, { results: resultList })
+        step = runRecordBatch(ctx, { results: resultList, hostRecords })
       } else if (sub === 'judge') {
         const context = flags.context === undefined ? 'final' : String(flags.context)
         if (context !== 'inter-wave' && context !== 'final') {
           die(`--context must be inter-wave|final (got "${context}")`)
         }
-        step = runJudge(ctx, { context, results: resultList })
+        step = runJudge(ctx, { context, results: resultList, hostRecords })
       } else if (sub === 'verify-final') {
         step = runVerifyFinal(ctx)
       } else if (sub === 'reviewed') {
-        step = runReviewed(ctx, { results: resultList })
+        step = runReviewed(ctx, { results: resultList, hostRecords })
       } else if (sub === 'remediated') {
         const roundNum = num(flags, 'round')
         if (!Number.isInteger(roundNum)) die('run remediated requires --round <n>')
-        step = runRemediated(ctx, { round: roundNum, results: resultList })
+        step = runRemediated(ctx, { round: roundNum, results: resultList, hostRecords })
       } else if (sub === 'commit') {
-        step = runCommit(ctx, { results: resultList })
+        step = runCommit(ctx, { results: resultList, hostRecords })
       } else if (sub === 'replan') {
-        step = runReplan(ctx, { results: resultList })
+        step = runReplan(ctx, { results: resultList, hostRecords })
       } else if (sub === 'next') {
         step = runNext(ctx)
       } else if (sub === 'close') {
@@ -2522,8 +2862,12 @@ async function main() {
           halt: typeof flags.halt === 'string' ? flags.halt : null,
           hostBanners: Array.isArray(hostBanners) ? hostBanners : [],
           hostObserved,
+          hostRecords,
           notify: flags.notify === true
         })
+        // Printed plainly, and NOT copied to LAST_STEP_PATH: a halted run closes
+        // through here, and overwriting the file would replace the very step the
+        // halt reason points a reader at with the close's own summary.
         emit(json, step, step.summary + '\n')
         if (step.exitCode !== 0) process.exit(step.exitCode)
         break
@@ -2534,7 +2878,7 @@ async function main() {
         )
       }
 
-      emit(json, step, formatRunStep(step))
+      emitRunStep(json, root, step, formatRunStep(step), { relay: true })
       // A halt step still exits 0: its `then` is the close, and a driver that
       // stopped here would leave the run with no receipt and no terminal event.
       // `run close` is the call that carries the non-zero exit.
@@ -2544,19 +2888,22 @@ async function main() {
     case 'wave-state': {
       const sub = positional[1]
       const change = typeof flags.change === 'string' ? flags.change : undefined
+      // The trajectory this command appends to lives in the state home; the
+      // changed-path read below stays on the working tree.
+      const logRoot = corpusHome(root, flags).home
       if (sub === 'create') {
         const plan = readInput(flags.plan, '--plan <file|->')
         const maxParallel = num(flags, 'max-parallel')
         // The one place the name enters the run: from here it travels on the
         // state, and no later wave-state invocation needs the flag.
         const state = createRunState(plan, { maxParallel, change })
-        const { ok: logOk } = logWaveMutation(root, { source: 'create', change, state })
+        const { ok: logOk } = logWaveMutation(logRoot, { source: 'create', change, state })
         emit(json, state, formatRunState(state))
         if (!logOk) process.exit(1)
       } else if (sub === 'next') {
         const state = readInput(flags.state, '--state <file|->')
-        const { step, ok: logOk } = logWaveMutation(root, { source: 'next', change, state })
-        const spawnOk = logAgentSpawns(root, { state, change, step, source: 'next' })
+        const { step, ok: logOk } = logWaveMutation(logRoot, { source: 'next', change, state })
+        const spawnOk = logAgentSpawns(logRoot, { state, change, step, source: 'next' })
         emit(json, step, formatRunState(state))
         if (step.action === 'halt' || !logOk || !spawnOk) process.exit(1)
       } else if (sub === 'record-batch' || sub === 'record-verify') {
@@ -2569,11 +2916,11 @@ async function main() {
           sub === 'record-batch'
             ? recordBatchResult(state, result, { changedPaths: observedChangedPaths(root) })
             : recordVerifyResult(state, result)
-        const { ok: logOk } = logWaveMutation(root, { source: sub, change, state: next })
+        const { ok: logOk } = logWaveMutation(logRoot, { source: sub, change, state: next })
         // Derived from the two states rather than returned by the recorder, so
         // `recordBatchResult`'s signature and every other caller are untouched.
         const recorded = sub === 'record-batch' ? batchOutcomes(state, next) : undefined
-        emitRecordedState(json, flags, next, { root, change, logOk, source: sub, recorded })
+        emitRecordedState(json, flags, next, { root: logRoot, change, logOk, source: sub, recorded })
       } else if (sub === 'replan') {
         const state = readInput(flags.state, '--state <file|->')
         const groups = readInput(flags.groups, '--groups <file|->')
@@ -2581,7 +2928,7 @@ async function main() {
           die('--groups must be a JSON array of { group, tasks } revisions')
         }
         const next = applyReplan(state, groups)
-        const { ok: logOk } = logWaveMutation(root, { source: 'replan', change, state: next })
+        const { ok: logOk } = logWaveMutation(logRoot, { source: 'replan', change, state: next })
         emitRecordedState(json, flags, next, { root, change, logOk, source: 'replan' })
       } else {
         die(
@@ -2594,7 +2941,8 @@ async function main() {
 
     case 'autonomy': {
       const sub = positional[1]
-      const opts = { root: flags.root ? String(flags.root) : undefined }
+      // The autonomy ledger is a corpus: it lives in the state home (ship/state-home).
+      const opts = { root: corpusHome(root, flags).home }
       if (sub === 'level') {
         const path = positional[2]
         if (!path) die('autonomy level requires a path')