@renzrollon/interlock 1.2.0 → 1.3.0

package/lib/resume-card.mjs

@@ -10,12 +10,18 @@
 //
 // Three rules it exists under, and all three are load-bearing:
 //
-// 1. **It is a record, not a trigger.** Nothing reads it back. `/interlock:ship`
-//    still decides whether to skip the classifier from the plan fingerprint, not
-//    from this file, so a stale or hand-edited card cannot make a later run
-//    reuse a plan it should have rebuilt. The card says that about itself, in
-//    the file, because a markdown "resume" artifact that nothing consumes is
-//    exactly the thing a reader would otherwise assume is wired in.
+// 1. **It is a record, not a trigger.** Nothing reads it back to decide.
+//    `/interlock:ship` still decides whether to skip the classifier from the
+//    plan fingerprint, not from this file, so a stale or hand-edited card
+//    cannot make a later run reuse a plan it should have rebuilt. The card says
+//    that about itself, in the file, because a markdown "resume" artifact that
+//    nothing consumes is exactly the thing a reader would otherwise assume is
+//    wired in. Two readers show it and nothing more
+//    (show-preflight-and-interrupted-runs-at-session-start design D4): the
+//    SessionStart preflight lists the cards of open changes from the stamp on
+//    each card's first line (`listResumeCards`, below), and the hooks module's
+//    `/interlock-handoff` renders one verbatim on request. Neither marks,
+//    moves or deletes a card.
 // 2. **It never throws.** A read-only checkout, a full disk, an unwritable
 //    `.claude/` — each degrades to a no-op that *reports* itself through the
 //    return value, and the close turns that into a degradation banner. The run
@@ -29,8 +35,8 @@
 // Only on a halt. A clean run's summary already ends in `ARCHIVE PENDING` and
 // there is nothing to resume.
 
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { closeSync, existsSync, mkdirSync, openSync, readSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
 import { LIMITS } from './limits.mjs'
 
 /** Where the card lands, relative to the repo root. Already gitignored. */
@@ -161,6 +167,7 @@ export function formatResumeCard({
   const elsewhere = typeof stateHome === 'string' && stateHome.length > 0 && !samePath(stateHome, cwd)
   const lines = []
 
+  // The stamp `parseResumeCardStamp` reads back: change it and the parser together.
   lines.push(`<!-- ${RESUME_CARD_SCHEMA} change=${name} run=${hasRun ? runId : NO_RUN_ID} -->`)
   lines.push(`# Ship halted — ${name}`)
   lines.push('')
@@ -375,6 +382,117 @@ export function formatResumeCard({
   return lines.join('\n')
 }
 
+// The writer's first line, read back. Anchored on the schema, so a card of
+// another shape is no card; a change or run carrying a separator is refused.
+const SCHEMA_PATTERN = RESUME_CARD_SCHEMA.replace(/[.\/]/g, '\\$&')
+const STAMP = new RegExp(`^<!-- ${SCHEMA_PATTERN} change=([^\\s/\\\\]+) run=([^\\s/\\\\]+) -->$`)
+
+/**
+ * The change and run id a card's first line names, or `null` when the line is
+ * not this schema's stamp. The inverse of the stamp `formatResumeCard` writes.
+ *
+ * @param {string} line
+ * @returns {{change: string, runId: string} | null}
+ */
+export function parseResumeCardStamp(line) {
+  if (typeof line !== 'string') return null
+  const m = STAMP.exec(line.replace(/\r$/, ''))
+  if (!m || m[1] === '.' || m[1] === '..') return null
+  return { change: m[1], runId: m[2] }
+}
+
+/** How much of a card the listing reads: the stamp line, never the body. */
+const STAMP_BYTES = 512
+
+function firstLine(path) {
+  const fd = openSync(path, 'r')
+  try {
+    const buffer = Buffer.alloc(STAMP_BYTES)
+    const n = readSync(fd, buffer, 0, STAMP_BYTES, 0)
+    return buffer.toString('utf8', 0, n).split('\n')[0]
+  } finally {
+    closeSync(fd)
+  }
+}
+
+const messageOf = err => (err && err.message) || String(err)
+
+/**
+ * The halt resume cards under each root's handoff directory, as the
+ * SessionStart preflight lists them (design D4). A card whose change still has
+ * a directory under `changesDir` is listed with its absolute path, change, run
+ * id and modification time; the cards of other changes are counted under
+ * `archived`; a `ship-*.md` without a readable stamp is named under
+ * `unreadable`. Every handoff directory opened or found absent is recorded
+ * under `lookedIn`, and two roots naming one real directory are read once.
+ *
+ * Reads the first line of each card and nothing past it; marks, moves and
+ * deletes nothing. Never throws.
+ *
+ * @param {{roots?: string[], changesDir?: string}} [input]
+ * @returns {{listed: Array<{path: string, change: string, runId: string, writtenAt: string|null}>, archived: number, unreadable: Array<{path: string, reason: string}>, lookedIn: string[]}}
+ */
+export function listResumeCards({ roots = [], changesDir } = {}) {
+  const out = { listed: [], archived: 0, unreadable: [], lookedIn: [] }
+  try {
+    const seen = new Set()
+    for (const root of Array.isArray(roots) ? roots : []) {
+      if (typeof root !== 'string' || !root) continue
+      const dir = resolve(root, HANDOFF_DIR)
+      let real = dir
+      try {
+        real = realpathSync(dir)
+      } catch {
+        // An absent directory is still one directory, named as given.
+      }
+      if (seen.has(real)) continue
+      seen.add(real)
+      out.lookedIn.push(dir)
+      let names
+      try {
+        names = readdirSync(dir)
+      } catch (err) {
+        if (!(err && err.code === 'ENOENT')) out.unreadable.push({ path: dir, reason: messageOf(err) })
+        continue
+      }
+      for (const name of names.filter(n => n.startsWith('ship-') && n.endsWith('.md')).sort()) {
+        const path = join(dir, name)
+        let stamp
+        try {
+          stamp = parseResumeCardStamp(firstLine(path))
+        } catch (err) {
+          out.unreadable.push({ path, reason: messageOf(err) })
+          continue
+        }
+        if (!stamp) {
+          out.unreadable.push({ path, reason: `the first line is not an ${RESUME_CARD_SCHEMA} stamp` })
+          continue
+        }
+        let open = false
+        try {
+          open = typeof changesDir === 'string' && statSync(join(changesDir, stamp.change)).isDirectory()
+        } catch {
+          open = false
+        }
+        if (!open) {
+          out.archived++
+          continue
+        }
+        let writtenAt = null
+        try {
+          writtenAt = statSync(path).mtime.toISOString()
+        } catch {
+          writtenAt = null
+        }
+        out.listed.push({ path, change: stamp.change, runId: stamp.runId, writtenAt })
+      }
+    }
+  } catch (err) {
+    out.unreadable.push({ path: String(roots), reason: messageOf(err) })
+  }
+  return out
+}
+
 /**
  * Write the card for a halted run.
  *

package/lib/run.mjs

@@ -64,6 +64,7 @@ import { classifySurface } from './surface.mjs'
 import { buildChecklist } from './conformance.mjs'
 import { record as recordAutonomy } from './autonomy.mjs'
 import { writeResumeCard } from './resume-card.mjs'
+import { summarizePlan } from './plan-summary.mjs'
 import {
   applyReplan,
   batchOutcomes,
@@ -439,7 +440,17 @@ export const RELAY_STEP_FIELDS = Object.freeze([
   'reason',
   // The control-plane ping model `run start` decided (design D3). The driver
   // sets its relay pings' model from this field and from nothing else.
-  'pingModel'
+  'pingModel',
+  // For a second reader, the ship meter's wave board, and read by neither
+  // driver (draw-the-wave-board-in-the-meter-pane design D1): the step's wave
+  // and batch positions, a verify step's skip flag, the ids a recorded batch
+  // names, and the plan summary the adoption and replan steps carry.
+  'waveIndex',
+  'batchIndex',
+  'batchCount',
+  'skipped',
+  'recorded',
+  'plan'
 ])
 
 /**
@@ -2582,6 +2593,12 @@ function adoptPlan(ctx, manifest, plan) {
   if (slotsBanner && first && typeof first === 'object') {
     first.banners = [...(Array.isArray(first.banners) ? first.banners : []), slotsBanner]
   }
+  // The waves that will run, once, for the meter's board (design D3): the
+  // state's batches, which a `maxParallel` override re-chunked, with the
+  // planner's own deferral records.
+  if (first && typeof first === 'object' && first.action !== 'halt') {
+    first.plan = summarizePlan(state, { deferred: plan.deferred })
+  }
   return first
 }
 
@@ -3033,6 +3050,13 @@ export function runRecordBatch(ctx, { results, hostRecords }) {
   if (verdict.claimDerived) banners.push(claimDerivedBanner())
   if (verdict.overrides.length) banners.push(overrideBanner(verdict.overrides))
 
+  // The lane that stopped early, plus anything the recorder found no result for
+  // at all. Neither is ticked and neither is a failure. One expression for the
+  // tally and for the step's `recorded`, so the two cannot disagree (design D2).
+  const notAttemptedOf = counts => [
+    ...unattempted,
+    ...counts.recordedNotAttempted.filter(id => !unattempted.includes(id))
+  ]
   verdict.waves.forEach(counts => {
     manifest.waves.push({
       wave: pending.wave,
@@ -3041,12 +3065,7 @@ export function runRecordBatch(ctx, { results, hostRecords }) {
       ok: counts.ok,
       failed: counts.failed,
       failedIds: counts.failedIds,
-      // The lane that stopped early, plus anything the recorder found no result
-      // for at all. Neither is ticked and neither is a failure.
-      notAttempted: [
-        ...unattempted,
-        ...counts.recordedNotAttempted.filter(id => !unattempted.includes(id))
-      ]
+      notAttempted: notAttemptedOf(counts)
     })
   })
 
@@ -3068,7 +3087,17 @@ export function runRecordBatch(ctx, { results, hostRecords }) {
   }
 
   manifest.banners.push(...banners)
-  return finishStep(ctx, manifest, decorate(ctx, nextRaw, manifest, { banners }))
+  const recordedStep = decorate(ctx, nextRaw, manifest, { banners })
+  // What this batch recorded, for the meter's board (design D2): set here, on
+  // the step record-batch returns, so no other subcommand can emit it.
+  if (recordedStep && typeof recordedStep === 'object') {
+    recordedStep.recorded = {
+      ok: verdict.tickIds,
+      failed: verdict.waves.flatMap(counts => counts.failedIds),
+      notAttempted: [...new Set(verdict.waves.flatMap(notAttemptedOf))]
+    }
+  }
+  return finishStep(ctx, manifest, recordedStep)
 }
 
 // --- run judge --------------------------------------------------------------
@@ -3479,7 +3508,12 @@ export function runReplan(ctx, { results, hostRecords }) {
     ctx.warn('an implementer agent-spawn was not recorded on replan')
     return finishStep(ctx, manifest, trajectoryHaltStep('agent-spawn', LANE_SPAWN_APPEND_FAILED))
   }
-  return finishStep(ctx, manifest, decorate(ctx, nextRaw, manifest))
+  const revisedStep = decorate(ctx, nextRaw, manifest)
+  // The revised waves replace the adopted ones on the meter's board (design D3).
+  if (revisedStep && typeof revisedStep === 'object' && revisedStep.action !== 'halt') {
+    revisedStep.plan = summarizePlan(after)
+  }
+  return finishStep(ctx, manifest, revisedStep)
 }
 
 // --- run next ---------------------------------------------------------------