@renzrollon/interlock 1.0.2 → 1.1.0

package/lib/run.mjs

@@ -52,6 +52,7 @@ import { planRemediation } from './remediate.mjs'
 import { classifySurface } from './surface.mjs'
 import { buildChecklist } from './conformance.mjs'
 import { record as recordAutonomy } from './autonomy.mjs'
+import { writeResumeCard } from './resume-card.mjs'
 import {
   applyReplan,
   batchOutcomes,
@@ -1449,7 +1450,8 @@ function logSpawns(ctx, manifest, step) {
   // No run identity yet — the classify step runs before there is a wave state,
   // so nothing is owed. The same rule `logVerifyJudgement` follows: a call with
   // no runId is not part of a logged run, and logging is not what should fail it.
-  if (!manifest.runId) return step
+  if (!manifest.runId) return null
+  let failure = null
   for (const s of step.spawns || []) {
     if (s.kind === 'implementer') continue // logged by wave-state, at the lane
     const written = appendRunLogEvent(ctx.root, {
@@ -1460,13 +1462,18 @@ function logSpawns(ctx, manifest, step) {
       model: s.model || undefined,
       kind: s.kind
     })
-    if (!written.written) ctx.warn(`agent-spawn not recorded: ${written.reason}`)
+    if (!written.written) {
+      ctx.warn(`agent-spawn not recorded: ${written.reason}`)
+      // The first failure is the one that opened the gap; the rest of the loop
+      // still runs so the warnings a reader gets are unchanged.
+      if (!failure) failure = `agent-spawn ${s.label}: ${written.reason}`
+    }
   }
-  return step
+  return failure
 }
 
 function logCliExit(ctx, manifest, command, exitCode) {
-  if (!manifest.runId) return
+  if (!manifest.runId) return null
   const written = appendRunLogEvent(ctx.root, {
     runId: manifest.runId,
     change: manifest.change,
@@ -1474,9 +1481,46 @@ function logCliExit(ctx, manifest, command, exitCode) {
     command,
     exitCode
   })
-  if (!written.written) ctx.warn(`cli-exit not recorded: ${written.reason}`)
+  if (written.written) return null
+  ctx.warn(`cli-exit not recorded: ${written.reason}`)
+  return `cli-exit ${command}: ${written.reason}`
+}
+
+/**
+ * The halt a failed run-trajectory append owes the run.
+ *
+ * `.claude/ship/runs` is `fatal: true` in `lib/doctor.mjs`'s STATE_DIRS, and
+ * `wave-state` / `verify judge` in `bin/interlock` already `process.exit(1)`
+ * when their append does not land. The live `interlock run` path used to warn
+ * and walk on — into the task tick and the commit — so a run nobody could
+ * reconstruct still ticked boxes and shipped. A warning is not a gate.
+ *
+ * Caller-side by construction: fatality is a policy of the SITE, not of the
+ * shared writer, which is why `appendRunLogEvent` still just reports. The
+ * outcome corpus and review metrics keep their deliberately different
+ * semantics — a failed write there is reported and never touches the exit code.
+ *
+ * `site` names where the gap is, so the halt reason is enough to find it.
+ */
+function trajectoryHaltStep(site, reason, extra = {}) {
+  return haltStep(`trajectory append failed: ${site}: ${reason}`, extra)
+}
+
+/**
+ * The reason to halt with when `logWaveMutation` failed.
+ *
+ * It returns the filesystem's own reason where it has one. The fallback covers
+ * an injected or older dep that reports only the boolean — better a named site
+ * with a vague cause than a halt that says nothing at all.
+ */
+function waveAppendReason(outcome) {
+  const reason = outcome && typeof outcome.reason === 'string' ? outcome.reason.trim() : ''
+  return reason || 'the wave-action or its paired cli-exit did not land'
 }
 
+/** Same, for `logAgentSpawns` — it returns a boolean and reports its reason to stderr. */
+const LANE_SPAWN_APPEND_FAILED = 'an implementer lane spawn did not land'
+
 /** The shared tree's HEAD. Never throws: an unreadable base is null, never a guess. */
 function headCommit(ctx) {
   return ctx.deps.headCommit(ctx.root)
@@ -1771,15 +1815,29 @@ function adoptPlan(ctx, manifest, plan) {
     // anything, and `run-log check` does not require it.
     sessionId: hostSessionId(manifest, ctx.env) || undefined
   })
-  if (!started.written) ctx.warn(`run-start not recorded: ${started.reason}`)
+  if (!started.written) {
+    ctx.warn(`run-start not recorded: ${started.reason}`)
+    return trajectoryHaltStep('run-start', started.reason)
+  }
 
-  const { step, ok } = ctx.deps.logWaveMutation(root, {
+  const created = ctx.deps.logWaveMutation(root, {
     source: 'create',
     change: manifest.change,
     state
   })
-  if (!ok) ctx.warn('the wave-state trajectory append failed on run start')
-  ctx.deps.logAgentSpawns(root, { state, change: manifest.change, step, source: 'next' })
+  const { step, ok } = created
+  if (!ok) {
+    ctx.warn('the wave-state trajectory append failed on run start')
+    return trajectoryHaltStep('wave-state create', waveAppendReason(created))
+  }
+  // The lane spawns, which `logSpawns` deliberately skips (they are logged at
+  // the lane, by wave-state). Its verdict is read for the same reason every
+  // other append's is: `wave-state next` exits 1 on this exact boolean, and the
+  // live path owes the trajectory the same fatality.
+  if (ctx.deps.logAgentSpawns(root, { state, change: manifest.change, step, source: 'next' }) === false) {
+    ctx.warn('an implementer agent-spawn was not recorded on run start')
+    return trajectoryHaltStep('agent-spawn', LANE_SPAWN_APPEND_FAILED)
+  }
   return decorate(ctx, step, manifest)
 }
 
@@ -2103,18 +2161,43 @@ export function runRecordBatch(ctx, { results }) {
     changedPaths: ctx.deps.observedChangedPaths(root)
   })
   writeState(root, after)
-  const { step: nextRaw, ok: logOk } = ctx.deps.logWaveMutation(root, {
+  const recorded = ctx.deps.logWaveMutation(root, {
     source: 'record-batch',
     change: manifest.change,
     state: after
   })
-  if (!logOk) ctx.warn('the wave-state trajectory append failed on record-batch')
-  ctx.deps.logAgentSpawns(root, {
+  const { step: nextRaw, ok: logOk } = recorded
+  if (!logOk) {
+    // Before the tick and before the commit. The batch result is already on
+    // disk (`writeState` above) and there is no undo API for it, so the halt
+    // names the gap instead of pretending the state never advanced — close's
+    // reconstructability check reads the same trajectory and agrees.
+    ctx.warn('the wave-state trajectory append failed on record-batch')
+    manifest.banners.push(...banners)
+    return finishStep(
+      ctx,
+      manifest,
+      trajectoryHaltStep('wave-state record-batch', waveAppendReason(recorded), { banners })
+    )
+  }
+  // Before the tick and before the commit, exactly like the wave-action above:
+  // a batch whose implementer spawns went unrecorded is a batch nobody can
+  // attribute, and `emitRecordedState` already exits 1 on this same boolean.
+  const laneSpawnsLogged = ctx.deps.logAgentSpawns(root, {
     state: after,
     change: manifest.change,
     step: nextRaw,
     source: 'record-batch'
   })
+  if (laneSpawnsLogged === false) {
+    ctx.warn('an implementer agent-spawn was not recorded on record-batch')
+    manifest.banners.push(...banners)
+    return finishStep(
+      ctx,
+      manifest,
+      trajectoryHaltStep('agent-spawn', LANE_SPAWN_APPEND_FAILED, { banners })
+    )
+  }
 
   // One authority, read once, for the tick and for the tallies alike.
   const verdict = adjudicateBatches([reported], recordedOutcomes(batchOutcomes(state, after)))
@@ -2227,7 +2310,26 @@ export function runJudge(ctx, { context, results }) {
     }
     verdict = judgeVerification(plan, reportedSteps, { context })
     for (const banner of verdict.banners || []) banners.push(banner)
-    logCliExit(ctx, manifest, 'verify judge', verdict.halt ? 1 : 0)
+    const exitFailure = logCliExit(ctx, manifest, 'verify judge', verdict.halt ? 1 : 0)
+    if (exitFailure) {
+      // The judgement happened; the record of it did not. Halting here is what
+      // `verify judge` in bin/interlock already does on the same failure —
+      // before the branch into record-verify, the handoff or the commit.
+      //
+      // A verdict that was ALREADY halting keeps its own reason, the same rule
+      // `finishStep` applies below: this run stopped because verification
+      // failed, and that reason is what reaches the summary, the push and the
+      // resume card. The lost record is a banner beside it, never instead of it.
+      banners.push(`TRAJECTORY APPEND FAILED: ${exitFailure}`)
+      manifest.banners.push(...banners)
+      return finishStep(
+        ctx,
+        manifest,
+        verdict.halt
+          ? haltStep(verdict.reason || 'verification halted the run', { banners })
+          : trajectoryHaltStep('cli-exit', exitFailure.replace(/^cli-exit /, ''), { banners })
+      )
+    }
   } else {
     banners.push(`VERIFICATION SKIPPED: reason=${reason}`)
   }
@@ -2243,13 +2345,21 @@ export function runJudge(ctx, { context, results }) {
         }
     const after = recordVerifyResult(state, record)
     writeState(root, after)
-    const { step: nextRaw, ok } = ctx.deps.logWaveMutation(root, {
+    const verified = ctx.deps.logWaveMutation(root, {
       source: 'record-verify',
       change: manifest.change,
       state: after
     })
-    if (!ok) ctx.warn('the wave-state trajectory append failed on record-verify')
+    const { step: nextRaw, ok } = verified
     manifest.banners.push(...banners)
+    if (!ok) {
+      ctx.warn('the wave-state trajectory append failed on record-verify')
+      return finishStep(
+        ctx,
+        manifest,
+        trajectoryHaltStep('wave-state record-verify', waveAppendReason(verified), { banners })
+      )
+    }
     return finishStep(ctx, manifest, decorate(ctx, nextRaw, manifest, { banners }))
   }
 
@@ -2481,12 +2591,16 @@ export function runReplan(ctx, { results }) {
     return finishStep(ctx, manifest, haltStep(`replan rejected: ${(err && err.message) || String(err)}`))
   }
   writeState(root, after)
-  const { step: nextRaw, ok } = ctx.deps.logWaveMutation(root, {
+  const replanned = ctx.deps.logWaveMutation(root, {
     source: 'replan',
     change: manifest.change,
     state: after
   })
-  if (!ok) ctx.warn('the wave-state trajectory append failed on replan')
+  const { step: nextRaw, ok } = replanned
+  if (!ok) {
+    ctx.warn('the wave-state trajectory append failed on replan')
+    return finishStep(ctx, manifest, trajectoryHaltStep('wave-state replan', waveAppendReason(replanned)))
+  }
   return finishStep(ctx, manifest, decorate(ctx, nextRaw, manifest))
 }
 
@@ -2520,8 +2634,18 @@ function noManifest() {
  * process — each `run` subcommand is its own.
  */
 function finishStep(ctx, manifest, step) {
-  logSpawns(ctx, manifest, step)
-  return recordThen(ctx.root, manifest, step)
+  const failure = logSpawns(ctx, manifest, step)
+  // An agent-spawn nobody recorded is a gap in the trajectory, and the step it
+  // belongs to must not run. A step that was ALREADY halting keeps its own
+  // reason: replacing it would trade why the run stopped for the bookkeeping
+  // failure that followed, and it halts either way.
+  const final =
+    failure && step.action !== 'halt'
+      ? trajectoryHaltStep('agent-spawn', failure.replace(/^agent-spawn /, ''), {
+          ...(Array.isArray(step.banners) ? { banners: step.banners } : {})
+        })
+      : step
+  return recordThen(ctx.root, manifest, final)
 }
 
 // --- run close (design D10) -------------------------------------------------
@@ -2758,13 +2882,23 @@ export async function runClose(
       : undefined
   })
 
+  // The trajectory writes this close owes. A failure here is the same fatal
+  // class as every other `.claude/ship/runs` append — the close has no tick or
+  // commit left to stop, so the halt it can still perform is a spoken
+  // degradation and a non-zero exit, exactly what an unreconstructable run gets
+  // below. Silence would leave a run that reads complete and cannot be replayed.
+  let trajectoryComplete = true
   if (manifest.runId) {
     const written = appendRunLogEvent(root, {
       ...receipt,
       runId: manifest.runId,
       change: manifest.change
     })
-    if (!written.written) ctx.warn(`run-receipt not recorded: ${written.reason}`)
+    if (!written.written) {
+      ctx.warn(`run-receipt not recorded: ${written.reason}`)
+      trajectoryComplete = false
+      degradations.push(`TRAJECTORY APPEND FAILED: run-receipt: ${written.reason}`)
+    }
 
     const terminal = appendRunLogEvent(root, {
       runId: manifest.runId,
@@ -2772,7 +2906,12 @@ export async function runClose(
       type: haltReason ? 'run-halt' : 'run-complete',
       reason: haltReason || undefined
     })
-    if (!terminal.written) ctx.warn(`${haltReason ? 'run-halt' : 'run-complete'} not recorded: ${terminal.reason}`)
+    if (!terminal.written) {
+      const type = haltReason ? 'run-halt' : 'run-complete'
+      ctx.warn(`${type} not recorded: ${terminal.reason}`)
+      trajectoryComplete = false
+      degradations.push(`TRAJECTORY APPEND FAILED: ${type}: ${terminal.reason}`)
+    }
   }
 
   // The outcome corpus. Its own write failure is reported and never touches the
@@ -2821,6 +2960,36 @@ export async function runClose(
     }
   }
 
+  // The halt resume card. Only on a halt: a clean close has nothing to resume,
+  // and its summary already ends in the archive reminder.
+  //
+  // Written last, so the card carries every banner this close raised — the
+  // reconstructability failure and the autonomy one included. Its own failure is
+  // a banner and never an exit code: it is a pointer to records that were
+  // already written, so losing it costs a reader convenience, not evidence. That
+  // is the outcome-corpus class, not the trajectory's.
+  //
+  // Nothing reads it back. The next ship still decides whether to skip the
+  // classifier from the plan fingerprint, so a card that was never written, or
+  // was hand-edited, cannot change what a later run does.
+  let resumeCard = null
+  if (haltReason) {
+    const written = writeResumeCard(root, {
+      change: manifest.change,
+      runId: manifest.runId,
+      halted: haltReason,
+      leftoverTaskIds,
+      plan: manifest.plan,
+      planStored: Boolean(planFingerprint) && existsSync(join(root, PLAN_FILE_PATH)),
+      waves: manifest.waves || [],
+      degradations,
+      projectSlug: slug,
+      cwd: absRoot
+    })
+    if (written.written) resumeCard = written.path
+    else degradations.push(`RESUME CARD NOT WRITTEN: ${written.reason}`)
+  }
+
   manifest.lastThen = null
   writeManifest(root, manifest)
 
@@ -2829,7 +2998,7 @@ export async function runClose(
     action: haltReason ? 'halt' : 'complete',
     then: null,
     spawns: [],
-    exitCode: haltReason || !reconstructable ? 1 : 0,
+    exitCode: haltReason || !reconstructable || !trajectoryComplete ? 1 : 0,
     banners: degradations,
     summary: formatRunSummary({
       change: manifest.change,
@@ -2841,7 +3010,8 @@ export async function runClose(
       root: absRoot,
       projectSlug: slug,
       push,
-      unarchived
+      unarchived,
+      resumeCard
     })
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@renzrollon/interlock",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Autonomous spec-driven development orchestration for Claude Code, layered on OpenSpec",
   "type": "module",
   "engines": {

package/shared/TOOL-ECONOMY.md

@@ -110,10 +110,17 @@ one you need. When Rule 0 applies, graph query/consumers counts as “locate.”
 
 At session start, current-task context comes from a few cheap, authoritative
 sources — `git log --oneline`, `git status --short`, `openspec status --json`,
-an open-task grep over `openspec/changes/*/tasks.md`, and the latest handoff.
+an open-task grep over `openspec/changes/*/tasks.md`, and the latest explore
+brief (`.claude/handoff/explore-*.md`).
 Front-load these in one pass. Read them,
 then act. Do not re-traverse the tree to reconstruct what they already tell you.
 
+The glob is load-bearing, not tidiness. `.claude/handoff/` also holds
+`ship-*.md` halt resume cards, which are records of runs that already stopped —
+nothing reads them, and finding one is not permission to start anything. Reading
+"the latest handoff" unqualified after a halt would hand you one as if it were
+session context.
+
 **Explore brief as Rule-3 state:** when `/interlock:spec` runs after explore
 (especially after `/clear` or prompt-cache expiry), read the latest matching
 `.claude/handoff/explore-*.md` first (see `EXPLORE-BRIEF.md`).