@renzrollon/interlock 1.2.1 → 1.3.0

package/lib/meter-refusals.mjs

@@ -0,0 +1,73 @@
+// The ship meter's refusal words (speak-permission-prompts-and-guard-denials
+// design D4-D6): the four guard names a settings guard's denial is read by,
+// the slice of an errored result's text the meter repeats, and the pane lines.
+//
+// Pure and Node-free: `hooks/mod.mjs` imports it inside the engine, where there
+// is no Node, and `test/spine/mod-pins.test.mjs` walks the import and pins the
+// names against the four guards' own `GUARD` constants. Nothing here judges a
+// denial: the words are the guard's, and the ruling is `lib/launch-rule.mjs`'s.
+
+/** The settings guards whose denials the meter repeats, as each prints its name. */
+export const GUARD_NAMES = Object.freeze(['guard-tests', 'guard-tasks', 'guard-commit', 'guard-relaunch'])
+
+// Anywhere in the text, not only at its start: the engine puts
+// `PreToolUse:<tool> hook error: ` in front of a settings hook's reason (probe 2).
+const NAMED = new RegExp(`\\b(${GUARD_NAMES.join('|')}): `)
+
+/**
+ * The text from the first guard name on, or `null` for a text that names no
+ * guard (another plugin's deny, a command that failed) or is not a string.
+ *
+ * @param {unknown} text an errored tool result's `text`
+ * @returns {string|null}
+ */
+export function guardReason(text) {
+  if (typeof text !== 'string') return null
+  const m = NAMED.exec(text)
+  return m ? text.slice(m.index) : null
+}
+
+/**
+ * The guard that spoke `reason`, as `guardReason` sliced it; `null` for none.
+ *
+ * @param {unknown} reason
+ * @returns {string|null}
+ */
+export function guardOf(reason) {
+  if (typeof reason !== 'string') return null
+  const m = NAMED.exec(reason)
+  return m && m.index === 0 ? m[1] : null
+}
+
+/**
+ * `guard denials: <n> (<guard> <n>, …)` in the order each guard was first
+ * seen, or `null` when none was: the pane draws no line for nothing.
+ *
+ * @param {Map<string, number>|undefined} counts
+ * @returns {string|null}
+ */
+export function guardDenialLine(counts) {
+  if (!(counts instanceof Map) || counts.size === 0) return null
+  let total = 0
+  const parts = []
+  for (const [guard, n] of counts) {
+    total += n
+    parts.push(`${guard} ${n}`)
+  }
+  return `guard denials: ${total} (${parts.join(', ')})`
+}
+
+/**
+ * The launch guard's current ruling over the session's record, in the rule's
+ * own words. `now` is `null` only when the guard's facts could not be read,
+ * which allows the next launch (design D5).
+ *
+ * @param {{ decision: string, reason: string|null }} ruling what `decideLaunch` returned
+ * @param {number|null} now
+ * @returns {string}
+ */
+export function launchGuardLine(ruling, now) {
+  if (now === null) return 'launch guard: facts unreadable; the next launch is allowed'
+  if (ruling && ruling.decision === 'deny' && ruling.reason) return `launch guard: next launch refused: ${ruling.reason}`
+  return 'launch guard: next launch allowed'
+}

package/lib/plan-summary.mjs

@@ -0,0 +1,119 @@
+// The plan summary (draw-the-wave-board-in-the-meter-pane design D3, spec
+// ship/diagrams): the `plan` field the adoption and replan steps carry, so a
+// second reader of the step stream — the ship meter — can draw the wave board
+// without reading a file.
+//
+// The summary is the plan's shape cut to what the board reads: per wave its
+// position, group, kind, red marker and batches; per task its id, tier, model
+// and the words the lane title is built from; and the ordered-after edges as
+// the plan's deferral records. Nothing else rides, because every byte of it is
+// retyped by the Workflow host's relay. `test/spine/plan-summary.test.mjs`
+// draws a plan and its summary through the renderer and compares the lines.
+//
+// Pure and Node-free, so the CLI builds the field with it and the hooks module
+// could read it; its closure is `lib/lane.mjs` and `lib/limits.mjs`.
+
+import { dependsOnIds, titleGist } from './lane.mjs'
+
+const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const list = value => (Array.isArray(value) ? value : [])
+const isText = value => typeof value === 'string' && value !== ''
+
+/** A task as the board reads it; a field the task lacks is left out, never filled. */
+function summarizeTask(task) {
+  const out = { id: task.id }
+  if (Number.isInteger(task.tier)) out.tier = task.tier
+  if (isText(task.model)) out.model = task.model
+  const gist = titleGist(task.description)
+  if (gist) out.description = gist
+  return out
+}
+
+/** A wave's batches as the board draws them: lanes of tasks, empty lanes and batches dropped. */
+function summarizeBatches(wave) {
+  return list(wave.batches)
+    .map(batch =>
+      list(batch)
+        .map(lane => list(lane).filter(task => isObject(task) && isText(task.id)))
+        .filter(lane => lane.length > 0)
+    )
+    .filter(batch => batch.length > 0)
+}
+
+/** A deferral record reduced to the three fields the board reads. */
+const reduceRecord = record => ({
+  id: record.id,
+  group: record.group ?? null,
+  after: list(record.after).filter(isText)
+})
+
+/**
+ * The planner's deferral records, derived from the tasks' own dependency
+ * fields: each id a task depends on that belongs to its own group and is
+ * placed at an earlier position or batch. A run state keeps no deferral list,
+ * and over the real halted run's state this yields its plan's four records.
+ */
+function deriveDeferred(positions) {
+  const placed = new Map()
+  positions.forEach(({ batches }, index) =>
+    batches.forEach((batch, b) => {
+      for (const task of batch.flat()) if (!placed.has(task.id)) placed.set(task.id, { index, b, task })
+    })
+  )
+  const out = []
+  for (const [id, at] of placed) {
+    const group = at.task.group ?? null
+    const after = dependsOnIds(at.task).filter(dep => {
+      const before = placed.get(dep)
+      return (
+        before !== undefined &&
+        (before.task.group ?? null) === group &&
+        (before.index < at.index || (before.index === at.index && before.b < at.b))
+      )
+    })
+    if (after.length) out.push({ id, group, after })
+  }
+  return out
+}
+
+/**
+ * The summary of a plan (`waves` plus `testWave`) or of a run state (`waves`,
+ * the test wave last among them with `kind: 'test'`), in the plan's shape so
+ * the renderer reads either the same way.
+ *
+ * @param {unknown} source a plan or a run state; anything else summarises to no waves
+ * @param {{deferred?: Array}} [opts] the planner's own deferral records, when the caller has them
+ * @returns {{waves: Array, testWave: object|null, deferred: Array}}
+ */
+export function summarizePlan(source, { deferred } = {}) {
+  const from = isObject(source) ? source : {}
+  const waves = list(from.waves).filter(isObject)
+  let impl = waves
+  let test = isObject(from.testWave) ? from.testWave : null
+  if (!test && waves.length && waves.at(-1).kind === 'test') {
+    impl = waves.slice(0, -1)
+    test = waves.at(-1)
+  }
+
+  const positions = impl
+    .map(wave => ({ wave, batches: summarizeBatches(wave) }))
+    .filter(position => position.batches.length > 0)
+  const testBatches = test ? summarizeBatches(test) : []
+  const all = testBatches.length ? [...positions, { wave: test, batches: testBatches }] : positions
+
+  const records = Array.isArray(deferred) ? deferred : Array.isArray(from.deferred) ? from.deferred : null
+  const summarize = batches => batches.map(batch => batch.map(lane => lane.map(summarizeTask)))
+  return {
+    waves: positions.map(({ wave, batches }, index) => ({
+      index,
+      group: wave.group ?? null,
+      kind: wave.kind === 'test' ? 'test' : 'impl',
+      ...(wave.red === true ? { red: true } : {}),
+      batches: summarize(batches)
+    })),
+    testWave: testBatches.length ? { index: positions.length, batches: summarize(testBatches) } : null,
+    deferred: records
+      ? records.filter(record => isObject(record) && isText(record.id)).map(reduceRecord)
+      : deriveDeferred(all)
+  }
+}

package/lib/preflight-file.mjs

@@ -0,0 +1,266 @@
+// The session start's report file: what `hooks/preflight.mjs` leaves in
+// `.claude/ship/preflight.json`, and every line the hooks module draws from it
+// (show-preflight-and-interrupted-runs-at-session-start design D1, D5-D8).
+//
+// Two readers of one shape. The hook builds the report from what it already
+// holds: the doctor's verdict and checks, the interrupted-run notes it spoke
+// and marked, the halt resume cards it listed. The hooks module reads it at a
+// prompt the person submits and draws the `AbovePrompt` band and two panes.
+// Neither side derives a fact the other did not say: every word drawn is the
+// doctor's, the hook's or the card's, and the time is a date, never a
+// staleness verdict.
+//
+// Node-free, and importing only `./limits.mjs`, because the hooks module runs
+// in the engine with no Node (test/spine/mod-pins.test.mjs walks it). The
+// handoff pane's cap is read here and restated nowhere in the module.
+
+import { LIMITS } from './limits.mjs'
+
+/** Bump when the report's shape changes, so a reader can tell an older one. */
+export const PREFLIGHT_SCHEMA = 'interlock.preflight/1'
+
+/** Where the report lands, relative to the working root. Already gitignored with `.claude/ship/`. */
+export const PREFLIGHT_FILE = '.claude/ship/preflight.json'
+
+/** The most characters of a card the handoff pane renders: the `Markdown` element's own bound (design D7). */
+export const HANDOFF_PANE_CHARS = LIMITS.handoffPaneChars
+
+/** The SessionStart sources the host names; anything else is recorded as null. */
+const SOURCES = new Set(['startup', 'resume', 'clear', 'compact'])
+
+const str = v => (typeof v === 'string' && v ? v : null)
+const text = v => (typeof v === 'string' ? v : v === null || v === undefined ? '' : String(v))
+const list = v => (Array.isArray(v) ? v.filter(x => x && typeof x === 'object') : [])
+const count = v => (Number.isInteger(v) && v >= 0 ? v : 0)
+
+/** The report file's path under `cwd`, or the relative path the engine resolves under the session's directory. */
+export function preflightFilePath(cwd) {
+  if (typeof cwd !== 'string' || !cwd) return PREFLIGHT_FILE
+  return `${cwd.endsWith('/') ? cwd.slice(0, -1) : cwd}/${PREFLIGHT_FILE}`
+}
+
+function doctorOf(d) {
+  const doctor = d && typeof d === 'object' ? d : {}
+  const counts =
+    doctor.counts && typeof doctor.counts === 'object'
+      ? Object.fromEntries(['ok', 'warn', 'fail', 'skip'].map(k => [k, count(doctor.counts[k])]))
+      : null
+  return {
+    ran: doctor.ran === true,
+    parsed: doctor.parsed === true,
+    ok: typeof doctor.ok === 'boolean' ? doctor.ok : null,
+    counts,
+    // `evidence` is not copied: no reader draws it, and the module reads the file whole.
+    checks: list(doctor.checks).map(c => ({ id: text(c.id), status: text(c.status), detail: text(c.detail), fix: str(c.fix) }))
+  }
+}
+
+function notesOf(n) {
+  const notes = n && typeof n === 'object' ? n : {}
+  return {
+    spoken: list(notes.spoken).map(s => ({
+      runId: text(s.runId),
+      change: str(s.change),
+      stage: str(s.stage),
+      banner: text(s.banner),
+      marked: s.marked === true,
+      marks: list(s.marks).map(m => ({ root: text(m.root), marked: m.marked === true, reason: str(m.reason) }))
+    })),
+    unreadable: list(notes.unreadable).map(u => ({ file: text(u.file), reason: text(u.reason) }))
+  }
+}
+
+function cardsOf(c) {
+  const cards = c && typeof c === 'object' ? c : {}
+  return {
+    listed: list(cards.listed).map(k => ({ path: text(k.path), change: text(k.change), runId: text(k.runId), writtenAt: str(k.writtenAt) })),
+    archived: count(cards.archived),
+    unreadable: list(cards.unreadable).map(u => ({ path: text(u.path), reason: text(u.reason) })),
+    lookedIn: Array.isArray(cards.lookedIn) ? cards.lookedIn.filter(d => typeof d === 'string' && d) : []
+  }
+}
+
+/**
+ * The report, every field present: an absent fact is `null` or `[]`, never
+ * omitted (design D1). Pure: the caller passes the time it wrote at.
+ */
+export function buildPreflightReport(input) {
+  const i = input && typeof input === 'object' ? input : {}
+  return {
+    schema: PREFLIGHT_SCHEMA,
+    writtenAt: str(i.writtenAt),
+    source: SOURCES.has(i.source) ? i.source : null,
+    root: str(i.root),
+    stateHome: str(i.stateHome),
+    surface: str(i.surface),
+    message: typeof i.message === 'string' ? i.message : null,
+    doctor: doctorOf(i.doctor),
+    notes: notesOf(i.notes),
+    cards: cardsOf(i.cards)
+  }
+}
+
+/** `{ report }` from the file's text, or `{ problem }` naming why there is none. */
+export function readPreflightReport(raw) {
+  if (typeof raw !== 'string') return { problem: `not text: the read returned ${raw === null ? 'null' : typeof raw}` }
+  let value
+  try {
+    value = JSON.parse(raw)
+  } catch (err) {
+    return { problem: `not JSON: ${(err && err.message) || err}` }
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { problem: 'not an object' }
+  if (value.schema !== PREFLIGHT_SCHEMA) return { problem: `stamped ${JSON.stringify(value.schema)}, not ${PREFLIGHT_SCHEMA}` }
+  return { report: buildPreflightReport(value) }
+}
+
+const flagged = report => report.doctor.checks.filter(c => c.status === 'fail' || c.status === 'warn')
+
+/** Whether the band has anything to say: a fail or warn check, a doctor that did not run or parse, a spoken note, a card. */
+export function shouldDraw(report) {
+  return (
+    flagged(report).length > 0 ||
+    !report.doctor.ran ||
+    !report.doctor.parsed ||
+    report.notes.spoken.length > 0 ||
+    report.cards.listed.length > 0
+  )
+}
+
+/** One listed card's line: where it is, which change and run, when it was written. */
+export function cardLine(card) {
+  return `${card.path} · ${card.change} · run ${card.runId} · written ${card.writtenAt || 'at an unknown time'}`
+}
+
+/** The listed cards, newest written first; equal or unknown times keep the listing's order. */
+export function orderCards(report) {
+  const at = c => {
+    const t = Date.parse(c.writtenAt)
+    return Number.isNaN(t) ? -Infinity : t
+  }
+  return report.cards.listed
+    .map((card, i) => ({ card, i }))
+    .sort((a, b) => at(b.card) - at(a.card) || a.i - b.i)
+    .map(x => x.card)
+}
+
+const writtenLine = report => `preflight written ${report.writtenAt || 'at an unknown time'}`
+
+/**
+ * The band's lines, in order (design D6): the message's first line, each
+ * `fail` or `warn` check in the doctor's words, each spoken note's banner,
+ * each card with the command that shows it, and when the report was written.
+ * Empty when there is nothing to say.
+ */
+export function bandLines(report) {
+  if (!shouldDraw(report)) return []
+  const lines = []
+  const first = (report.message || '').split('\n')[0]
+  if (first) lines.push(first)
+  for (const c of flagged(report)) lines.push(`${c.status} ${c.id}: ${c.detail}`)
+  for (const n of report.notes.spoken) lines.push(n.banner)
+  for (const card of orderCards(report)) lines.push(`${cardLine(card)} — /interlock-handoff`)
+  lines.push(`${writtenLine(report)} · /interlock-preflight`)
+  return lines
+}
+
+/**
+ * The `/interlock-preflight` pane's lines: the message verbatim, every check
+ * with its fix lines indented as the hook prints them, the notes spoken at
+ * this session start with each root's mark, the cards and what was not
+ * listed, and every note and card the hook could not read. No empty line.
+ */
+export function preflightPaneLines(report) {
+  const lines = []
+  for (const line of (report.message || '').split('\n')) if (line) lines.push(line)
+  lines.push(writtenLine(report))
+
+  lines.push(report.doctor.ran ? (report.doctor.parsed ? 'checks' : 'checks: the doctor ran and its output could not be parsed') : 'checks: the doctor did not run')
+  for (const c of report.doctor.checks) {
+    lines.push(`${c.status} ${c.id}: ${c.detail}`)
+    if (c.fix) {
+      const [first, ...rest] = c.fix.split('\n')
+      lines.push(`     fix: ${first}`)
+      for (const more of rest) if (more.trim()) lines.push(`          ${more.trim()}`)
+    }
+  }
+
+  lines.push(report.notes.spoken.length ? 'interrupted runs spoken at this session start' : 'no interrupted run was spoken at this session start')
+  for (const n of report.notes.spoken) {
+    lines.push(n.banner)
+    for (const m of n.marks) lines.push(m.marked ? `  marked · ${m.root}` : `  not marked: ${m.reason || 'no reason given'}`)
+  }
+  for (const u of report.notes.unreadable) lines.push(`note unreadable: ${u.file}: ${u.reason}`)
+
+  const ordered = orderCards(report)
+  lines.push(ordered.length ? 'halt resume cards — /interlock-handoff' : 'no halt resume card is on disk for an open change')
+  for (const card of ordered) lines.push(cardLine(card))
+  if (report.cards.archived) lines.push(`${report.cards.archived} card(s) of archived changes not listed`)
+  for (const u of report.cards.unreadable) lines.push(`card unreadable: ${u.path}: ${u.reason}`)
+  for (const dir of report.cards.lookedIn) lines.push(`looked in: ${dir}`)
+  return lines
+}
+
+/** What a pane says with no report held: the file's path and why, or that it has not been read yet. */
+export function noReportText(path, problem) {
+  return `no preflight report is held for this session start: ${path}: ${problem || 'not read yet'}`
+}
+
+/** What the handoff pane says with a report and no card: that, and every directory looked in. */
+export function noCardText(report) {
+  return ['no halt resume card is on disk for an open change', ...report.cards.lookedIn.map(dir => `looked in: ${dir}`)]
+}
+
+// Every control character but tab and newline: the `Markdown` element refuses them.
+const CONTROL = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g
+
+/**
+ * A card's text as the handoff pane renders it: control characters made
+ * spaces, and when longer than `cap`, cut so that the text and a note naming
+ * the characters left out and the card's path fit within `cap` (design D7).
+ */
+export function clampCard(raw, path, cap = LIMITS.handoffPaneChars) {
+  const clean = text(raw).replace(CONTROL, ' ')
+  if (clean.length <= cap) return { text: clean, cut: 0 }
+  const note = n => `\n\n_… ${n} characters left out; the whole card is ${path}_`
+  // The note for the whole text is the longest the note can be, so the kept head plus any shorter note still fits.
+  let keep = Math.max(0, cap - note(clean.length).length)
+  const code = clean.charCodeAt(keep - 1)
+  if (keep > 0 && code >= 0xd800 && code <= 0xdbff) keep -= 1
+  const cut = clean.length - keep
+  return { text: (clean.slice(0, keep) + note(cut)).slice(0, cap), cut }
+}
+
+/** What the module holds between reads (design D8): the report or the problem, the hide flag, whether the problem was named. */
+export function freshStart() {
+  return { report: null, path: null, problem: null, hidden: false, named: false }
+}
+
+/**
+ * The module's next `start` after a read (design D5, D8), whether the band
+ * must be redrawn, and the one debug line to name, if any. A re-read of the
+ * report already held changes nothing, hide flag and all. A new report is
+ * held, and stays hidden only when it continues a report already held across
+ * a compaction. A problem drops the held report, since the file is no longer
+ * this session's, and is named once until a report is held again.
+ *
+ * @param {object} start what `freshStart` returns, as last adopted
+ * @param {{report?: object, problem?: string}} outcome `readPreflightReport`'s result, or a read's rejection as a problem
+ * @param {string} path the file's path, named on the debug line and the panes
+ * @returns {{start: object, changed: boolean, log: string|null}}
+ */
+export function adoptPreflight(start, outcome, path) {
+  const held = start && typeof start === 'object' ? start : freshStart()
+  const report = outcome && outcome.report
+  if (report) {
+    if (held.report && held.report.writtenAt === report.writtenAt && held.report.root === report.root) {
+      return { start: held, changed: false, log: null }
+    }
+    const hidden = held.report !== null && held.hidden && report.source === 'compact'
+    return { start: { report, path, problem: null, hidden, named: false }, changed: true, log: null }
+  }
+  const problem = (outcome && outcome.problem) || 'no report was read'
+  const log = held.named ? null : `interlock meter: no preflight report at ${path}: ${problem}`
+  const changed = held.report !== null || held.problem !== problem || held.path !== path
+  return { start: { report: null, path, problem, hidden: held.hidden, named: true }, changed, log }
+}

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.
  *