@renzrollon/interlock 1.2.0 → 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/notify-defaults.mjs

@@ -0,0 +1,6 @@
+// The server used when an operator names a topic and no server.
+// One spelling, imported by the transport, the doctor and the CLI help,
+// so those three cannot drift.
+
+/** The public server, used when no server was configured. */
+export const DEFAULT_NTFY_URL = 'https://ntfy.sh'

package/lib/notify.mjs

@@ -1,6 +1,6 @@
-// The one network call this CLI ever makes: a push to ntfy.sh (or a
-// self-hosted server) so a ship run that stops while nobody is watching can
-// still reach someone.
+// The one network call this CLI ever makes: a push to the configured server
+// (the public default, or a server the operator named) so a ship run that
+// stops while nobody is watching can still reach someone.
 //
 // Three properties are load-bearing, and every one of them exists because
 // this module is the CLI's only exception to "no network":
@@ -11,8 +11,8 @@
 //      so there is no settings file this module could misread in the first
 //      place.
 //
-//   2. THE TOPIC NEVER LEAVES. The topic is the only auth ntfy.sh has on a
-//      public server; it is a capability, not a label. `readNotifyConfig`
+//   2. THE TOPIC NEVER LEAVES. The topic is the only auth the public server
+//      has; it is a capability, not a label. `readNotifyConfig`
 //      never echoes it, `sanitizeReason` strips it (and the server URL) from
 //      every failure reason before that reason reaches a summary line, a
 //      receipt event or the trajectory, because a `fetch` failure's own
@@ -29,15 +29,23 @@
 // design D1, D2, D4, D5, D14 (add-harden-unattended-ship-runs).
 
 import { LIMITS } from './limits.mjs'
+import { DEFAULT_NTFY_URL } from './notify-defaults.mjs'
 
-/** Where the topic is read from. Set by the operator, never by the repo. */
+export { DEFAULT_NTFY_URL }
+
+/** Where the topic is read from. Chosen by the operator, never by the repo. */
 export const NOTIFY_TOPIC_ENV = 'INTERLOCK_NTFY_TOPIC'
 
-/** Where a self-hosted server is read from. Unset means the public default. */
+/** Where a self-hosted server is read from. Absent means the public default. */
 export const NOTIFY_URL_ENV = 'INTERLOCK_NTFY_URL'
 
-/** The public ntfy server, used when `NOTIFY_URL_ENV` is unset. */
-export const DEFAULT_NTFY_URL = 'https://ntfy.sh'
+/**
+ * Plugin options the host injects into a hook process, from `userConfig`
+ * `ntfy_topic` and `ntfy_url`. Preferred over the shell variables when present,
+ * so a value the operator typed into the plugin is the one that is shared.
+ */
+export const NOTIFY_TOPIC_OPTION = 'CLAUDE_PLUGIN_OPTION_NTFY_TOPIC'
+export const NOTIFY_URL_OPTION = 'CLAUDE_PLUGIN_OPTION_NTFY_URL'
 
 function messageOf(err) {
   return (err && err.message) || String(err)
@@ -60,26 +68,34 @@ function urlShapeInvalid(url) {
   }
 }
 
+function trimmed(source, name) {
+  if (!source || typeof source[name] !== 'string') return ''
+  return source[name].trim()
+}
+
 /**
- * Read push configuration from the environment. Never the tree — `INTERLOCK_
- * NTFY_TOPIC` and `INTERLOCK_NTFY_URL` are the whole of it (design D2).
+ * Read push configuration. Never the tree. A plugin option the host injected
+ * wins over the shell variable of the same meaning, and an absent topic is
+ * unconfigured rather than an error (design D2). The shell variables remain
+ * the channel for a terminal, CI, and any host that does not inject options.
  *
- * @param {object} env  environment to read (injected in tests; `process.env` at call sites)
+ * @param {object} source  values to read (injected in tests; the process values at call sites)
  * @returns {{topic: string, url: string} | {topic: null} | {invalid: string}}
  *   `{ topic: null }` when push is simply unconfigured — not an error, the
  *   default and by far the common case. `{ invalid: '<VAR>' }` names the
  *   offending variable and never its value.
  */
-export function readNotifyConfig(env) {
-  const rawTopic = env && typeof env[NOTIFY_TOPIC_ENV] === 'string' ? env[NOTIFY_TOPIC_ENV].trim() : ''
+export function readNotifyConfig(source) {
+  const optionTopic = trimmed(source, NOTIFY_TOPIC_OPTION)
+  const shellTopic = trimmed(source, NOTIFY_TOPIC_ENV)
+  const rawTopic = optionTopic || shellTopic
   if (!rawTopic) return { topic: null }
-  if (topicShapeInvalid(rawTopic)) return { invalid: NOTIFY_TOPIC_ENV }
+  if (topicShapeInvalid(rawTopic)) return { invalid: optionTopic ? NOTIFY_TOPIC_OPTION : NOTIFY_TOPIC_ENV }
 
-  const rawUrl =
-    env && typeof env[NOTIFY_URL_ENV] === 'string' && env[NOTIFY_URL_ENV].trim()
-      ? env[NOTIFY_URL_ENV].trim()
-      : DEFAULT_NTFY_URL
-  if (urlShapeInvalid(rawUrl)) return { invalid: NOTIFY_URL_ENV }
+  const optionUrl = trimmed(source, NOTIFY_URL_OPTION)
+  const shellUrl = trimmed(source, NOTIFY_URL_ENV)
+  const rawUrl = optionUrl || shellUrl || DEFAULT_NTFY_URL
+  if (urlShapeInvalid(rawUrl)) return { invalid: optionUrl ? NOTIFY_URL_OPTION : NOTIFY_URL_ENV }
 
   return { topic: rawTopic, url: rawUrl }
 }
@@ -156,10 +172,10 @@ export function sanitizeReason(reason, { topic, url } = {}) {
  * all: EVERY headline this module sends contains an em dash (`SHIP COMPLETE —
  * <change>`), HTTP header values are ByteStrings, and Node's `fetch` throws
  * `Cannot convert argument to a ByteString` rather than transmitting one. So
- * a non-ASCII value is sent as an RFC 2047 base64 encoded-word, which ntfy
- * documents as the supported encoding for exactly this case (docs.ntfy.sh
- * §Publish → "ntfy supports UTF-8 in HTTP headers, but not every library or
- * programming language does", checked 2026-09-07).
+ * a non-ASCII value is sent as an RFC 2047 base64 encoded-word, which the
+ * server's publish documentation names as the supported encoding for exactly
+ * this case ("UTF-8 in HTTP headers" is not accepted by every client,
+ * checked 2026-09-07).
  *
  * A pure-ASCII value is passed through untouched, so the common `interlock
  * notify --title` case stays readable on the wire.
@@ -175,7 +191,7 @@ export function encodeHeaderValue(value) {
 }
 
 /**
- * Post one ntfy message. Never throws: every failure mode — invalid
+ * Post one message. Never throws: every failure mode — invalid
  * configuration, a non-2xx status, a network error, the timeout — resolves
  * to `{ sent: false, reason }`, sanitized, so the caller can always print
  * something and never has to catch anything.

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 }
+}