@renzrollon/interlock 1.1.1 → 1.2.0

package/lib/host.mjs

@@ -26,7 +26,7 @@
 // CLI, which is the same split — script versus policy — the repo already had.
 
 import { spawn as spawnProcess } from 'node:child_process'
-import { dirname, join } from 'node:path'
+import { delimiter, dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 /**
@@ -37,6 +37,35 @@ import { fileURLToPath } from 'node:url'
  */
 export const INTERLOCK_BIN = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'interlock')
 
+/**
+ * Environment for a runner lane.
+ *
+ * A briefing names `interlock` bare — `interlock verify exec`, and the same
+ * bare name in the implementer — while `runCli` executes `INTERLOCK_BIN` by
+ * absolute path, so the runner and the CLI that wrote the briefing are one
+ * binary whatever PATH says. A lane is not. A headless `-p --plugin-dir`
+ * session appends each plugin `bin/` after the PATH it inherited (probed
+ * 2026-10-05: this checkout's `bin/` was the last entry), so the directory
+ * placed first is the one the bare name resolves to. This copies `env` with
+ * `dirname(INTERLOCK_BIN)` first and any later copy of that directory removed,
+ * and writes the path back under the key the caller spelled (`Path` on
+ * Windows, `PATH` when the caller named none). Nothing else moves:
+ * `CLAUDE_CODE_EFFORT_LEVEL` stays the operator's.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function laneEnv(env = process.env) {
+  const source = env && typeof env === 'object' ? env : {}
+  const key = Object.prototype.hasOwnProperty.call(source, 'PATH')
+    ? 'PATH'
+    : Object.keys(source).find(name => name.toLowerCase() === 'path') || 'PATH'
+  const binDir = dirname(INTERLOCK_BIN)
+  const current = source[key]
+  const rest = typeof current === 'string' ? current.split(delimiter).filter(entry => entry !== binDir) : []
+  return { ...source, [key]: [binDir, ...rest].join(delimiter) }
+}
+
 /** The three ports a host must provide. Read by `assertWorkflowHost`. */
 export const HOST_PORTS = ['spawn', 'mapPipeline', 'runCli']
 
@@ -70,6 +99,7 @@ export function spawnPrefix(kind) {
  * @property {string} label      stable name for the agent (task id, step name)
  * @property {string} prompt     the full prompt text
  * @property {string} [model]    model slug the planner assigned, if the host can honour it
+ * @property {string} [effort]   effort level the step named; absent means inherit the host's default
  * @property {object} [schema]   JSON Schema the result must satisfy
  * @property {string} [type]     plugin agent id (`interlock:ping` / `interlock:worker`)
  * @property {string[]} [tools]  tools allowlist; omitting it inherits the parent catalog
@@ -200,7 +230,7 @@ export function runCli(argv, { cwd = process.cwd(), env = process.env, input, ti
  * @param {object} [opts.env]
  * @param {string} [opts.input]      the prompt, written to stdin and closed
  * @param {number} [opts.timeoutMs]  0 or absent disables the wall clock
- * @returns {Promise<{code: number|null, stdout: string, stderr: string, signal: string|null, timedOut: boolean}>}
+ * @returns {Promise<{code: number|null, stdout: string, stderr: string, signal: string|null, timedOut: boolean, started: boolean}>}
  */
 export function execCapture(command, args = [], { cwd, env, input, timeoutMs } = {}) {
   return new Promise(resolve => {
@@ -212,7 +242,7 @@ export function execCapture(command, args = [], { cwd, env, input, timeoutMs } =
         stdio: ['pipe', 'pipe', 'pipe']
       })
     } catch (err) {
-      resolve({ code: null, stdout: '', stderr: `${command}: ${(err && err.message) || err}\n`, signal: null, timedOut: false })
+      resolve({ code: null, stdout: '', stderr: `${command}: ${(err && err.message) || err}\n`, signal: null, timedOut: false, started: false })
       return
     }
 
@@ -243,8 +273,18 @@ export function execCapture(command, args = [], { cwd, env, input, timeoutMs } =
     child.stderr.on('data', chunk => {
       stderr += chunk
     })
+    // `started` is whether a process ever existed: a spawn that failed (a
+    // missing binary, a missing cwd) has no pid. An adapter reports what it did
+    // with a spawn's effort only for one that started (run-host-adapters spec).
     child.on('error', err => {
-      done({ code: null, stdout, stderr: `${stderr}${command}: ${(err && err.message) || err}\n`, signal: null, timedOut })
+      done({
+        code: null,
+        stdout,
+        stderr: `${stderr}${command}: ${(err && err.message) || err}\n`,
+        signal: null,
+        timedOut,
+        started: typeof child.pid === 'number'
+      })
     })
     child.on('close', (code, signal) => {
       done({
@@ -252,7 +292,8 @@ export function execCapture(command, args = [], { cwd, env, input, timeoutMs } =
         stdout,
         stderr: timedOut ? `${stderr}${command}: killed after ${budget}ms\n` : stderr,
         signal: signal || null,
-        timedOut
+        timedOut,
+        started: typeof child.pid === 'number'
       })
     })
 

package/lib/interrupted.mjs

@@ -0,0 +1,167 @@
+// The interrupted-run note (design D7) — what a session that ended mid-run
+// leaves behind, since it never reached `run close`.
+//
+// A session that ends while a ship run is live kills the background workflow
+// before its close: no receipt, no resume card, no terminal trajectory event, in
+// exactly the place a reader most needs one. The SessionEnd recorder
+// (`hooks/recorder.mjs`) writes one small note here instead, and three readers
+// speak it from the one text below: `interlock run start`, the SessionStart
+// preflight, and `interlock report`.
+//
+// ONE FILE PER RUN, NEVER DELETED. `.claude/ship/interrupted/<runId>.json`. Keyed
+// by run, not by change, so two interrupted runs of one change do not overwrite
+// each other; marked spoken rather than deleted, so `interlock report` can still
+// join it to its trajectory after `run start` has spoken it.
+//
+// OUTCOME-CLASS, NOT FATAL. A failed write is a stderr line from the hook; an
+// unreadable note or a failed mark is a note on the manifest. Nothing here moves
+// an exit code. That is the opposite of the run trajectory (`.claude/ship/runs`),
+// whose failed append exits 1 — and the difference is deliberate: the note points
+// at records written elsewhere, while the trajectory IS the record. See
+// docs/13-the-guards.md before making the two consistent.
+//
+// Every function collapses a failure to a value and never throws, because two of
+// its callers are hooks, and a hook whose own crash is its output is worse than
+// no hook.
+
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { SHIP_DIR } from './ship-stage.mjs'
+
+export const INTERRUPTED_SCHEMA = 'interlock.interrupted/1'
+
+/** Where the notes live, under the ship directory the doctor already probes. */
+export const INTERRUPTED_DIR = join(SHIP_DIR, 'interrupted')
+
+/**
+ * The host's end reason is stored verbatim but bounded, to the same length the
+ * trajectory bounds its own free text to (`MAX_TEXT` in `lib/run-log.mjs`;
+ * `test/hooks.test.mjs` pins the two equal). Restated rather than imported so a
+ * hook loads two small modules and not the trajectory writer.
+ */
+export const REASON_MAX = 500
+
+function messageOf(err) {
+  return (err && err.message) || String(err)
+}
+
+/** The note's path for a run, rooted at `root`. */
+export function interruptedPath(root, runId) {
+  return join(root, INTERRUPTED_DIR, `${runId}.json`)
+}
+
+/** A run id safe to name a file after: the shape `createRunState` mints, and nothing with a separator. */
+function usableRunId(runId) {
+  return typeof runId === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId) && runId.length <= 200
+}
+
+/**
+ * Write the note for one interrupted run: one `mkdirSync`, one `writeFileSync`,
+ * no subprocess. The reason is the host's, stored as given and bounded; nothing
+ * branches on its value, because the host's enum is not verified.
+ *
+ * @param {string} root
+ * @param {{runId: string, change: string, sessionId: string, reason?: string, stage: string, at?: string}} note
+ * @returns {{written: true, path: string} | {written: false, reason: string}}
+ */
+export function writeInterruptedNote(root, { runId, change, sessionId, reason, stage, at } = {}) {
+  if (!usableRunId(runId)) return { written: false, reason: `not a usable run id: ${JSON.stringify(runId)}` }
+  const text = typeof reason === 'string' ? reason : reason === undefined || reason === null ? null : String(reason)
+  const note = {
+    schema: INTERRUPTED_SCHEMA,
+    runId,
+    change: typeof change === 'string' ? change : null,
+    sessionId: typeof sessionId === 'string' ? sessionId : null,
+    reason: text === null ? null : text.length > REASON_MAX ? `${text.slice(0, REASON_MAX - 1)}…` : text,
+    stage: typeof stage === 'string' ? stage : null,
+    at: typeof at === 'string' ? at : new Date().toISOString(),
+    spokenAt: null
+  }
+  const path = interruptedPath(root, runId)
+  try {
+    mkdirSync(join(root, INTERRUPTED_DIR), { recursive: true })
+    writeFileSync(path, JSON.stringify(note, null, 2) + '\n')
+    return { written: true, path }
+  } catch (err) {
+    return { written: false, reason: `${path}: ${messageOf(err)}` }
+  }
+}
+
+/**
+ * Every note in the root. A note that does not parse, or parses to something
+ * that is not a note, is returned under `unreadable` by name and reason — never
+ * skipped, because a note nobody can read is still a run nobody closed.
+ *
+ * `file` is the note's path relative to `root`, which is how every reader names
+ * it. An absent directory is no notes and no error.
+ *
+ * @returns {{notes: object[], unreadable: Array<{file: string, reason: string}>}}
+ */
+export function readInterruptedNotes(root) {
+  const dir = join(root, INTERRUPTED_DIR)
+  let names
+  try {
+    names = readdirSync(dir).filter(name => name.endsWith('.json')).sort()
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { notes: [], unreadable: [] }
+    return { notes: [], unreadable: [{ file: INTERRUPTED_DIR, reason: messageOf(err) }] }
+  }
+  const notes = []
+  const unreadable = []
+  for (const name of names) {
+    const file = join(INTERRUPTED_DIR, name)
+    let value
+    try {
+      value = JSON.parse(readFileSync(join(root, file), 'utf8'))
+    } catch (err) {
+      unreadable.push({ file, reason: messageOf(err) })
+      continue
+    }
+    if (!value || typeof value !== 'object' || typeof value.runId !== 'string' || !value.runId) {
+      unreadable.push({ file, reason: 'not an interrupted-run note: no runId' })
+      continue
+    }
+    notes.push({ ...value, file })
+  }
+  return { notes, unreadable }
+}
+
+/** A note not yet spoken by a run start. */
+export function isUnspoken(note) {
+  return Boolean(note) && (note.spokenAt === null || note.spokenAt === undefined)
+}
+
+/**
+ * Mark a note spoken, rewriting it in place with `spokenAt` set. A note that
+ * cannot be marked is spoken again at the next run start — the right direction
+ * to fail in — and the caller says so.
+ *
+ * @returns {{marked: true} | {marked: false, reason: string}}
+ */
+export function markSpoken(root, runId, at = new Date().toISOString()) {
+  if (!usableRunId(runId)) return { marked: false, reason: `not a usable run id: ${JSON.stringify(runId)}` }
+  const path = interruptedPath(root, runId)
+  try {
+    const note = JSON.parse(readFileSync(path, 'utf8'))
+    writeFileSync(path, JSON.stringify({ ...note, spokenAt: at }, null, 2) + '\n')
+    return { marked: true }
+  } catch (err) {
+    return { marked: false, reason: `${path}: ${messageOf(err)}` }
+  }
+}
+
+/** The one line every reader prints for a note. */
+export function formatInterruptedBanner(note) {
+  const n = note && typeof note === 'object' ? note : {}
+  const change = typeof n.change === 'string' && n.change ? n.change : '(unnamed change)'
+  const stage = typeof n.stage === 'string' && n.stage ? n.stage : 'unknown'
+  return (
+    `PREVIOUS RUN INTERRUPTED: ${change} run ${n.runId} ended at stage ${stage} — ` +
+    `no resume card was written; interlock run-log show ${n.runId}`
+  )
+}
+
+/** The line a reader prints for a note it could not read. */
+export function formatUnreadableNote(entry) {
+  return `INTERRUPTED NOTE UNREADABLE: ${entry.file}: ${entry.reason}`
+}

package/lib/launch-ledger.mjs

@@ -0,0 +1,198 @@
+// The launch ledger: the file transport of the launch rule, which
+// `hooks/guard-relaunch.mjs` reads to decide whether a ship launch is a
+// relaunch nobody asked for (guard-ship-relaunch design D2, D3).
+//
+// The rule itself — what a ship launch is, what a human prompt is, the
+// decision and its words — lives in `lib/launch-rule.mjs`, which the hooks
+// module imports too (guard-ship-relaunch-in-process design D1). This module
+// re-exports every name of it unchanged, so the settings hook and its tests
+// import what they always imported and one function decides in both forms.
+// What stays here is the file: per session, the ship launches the runtime
+// accepted and the time of the last human prompt.
+//
+// ONE FILE PER SESSION, CREATED ONLY BY AN ACCEPTED LAUNCH.
+// `.claude/ship/launch-ledger/<session_id>.json`. Only the PostToolUse branch
+// creates it. A prompt event records a time only when the file already exists —
+// every plugin hook runs in every session in every repository, and a prompt in a
+// repository that never shipped must write nothing.
+//
+// THE COMPLETION WAKE IS NOT A HUMAN. The host wakes the session when a
+// background workflow finishes by firing `UserPromptSubmit` with the
+// notification as the prompt (captured: test/fixtures/hooks/completion-wake.json).
+// Counted as a human prompt it would reset the clock in exactly the turn the
+// relaunch happens in, so `isHumanPrompt` refuses it by its leading marker.
+//
+// EVERY UNKNOWN READS AS NO LEDGER, and no ledger allows. A missing file, an
+// unsafe session id, malformed JSON, a wrong schema, a launch time that does not
+// parse, a ledger older than `LIMITS.launchLedgerMaxAgeMs`: each is null here,
+// never an exception. A false deny costs one typed message; a guard whose own
+// parse error blocked a launch would be the worse failure.
+//
+// Pure apart from the ledger files themselves. No hook protocol in here — the
+// hook is plumbing over these functions, the way the stage guards are plumbing
+// over `lib/ship-stage.mjs`.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { LIMITS } from './limits.mjs'
+import { LEDGER_SCHEMA, emptyRecord, newestLaunch, promptMs, withLaunch, withPrompt } from './launch-rule.mjs'
+import { SHIP_DIR } from './ship-stage.mjs'
+
+export {
+  LEDGER_SCHEMA,
+  SKILL_QUOTE,
+  WAKE_MARKER,
+  decideLaunch,
+  denyReason,
+  emptyRecord,
+  isAcceptedLaunch,
+  isHumanPrompt,
+  isShipLaunch,
+  newestLaunch,
+  promptMs,
+  withLaunch,
+  withPrompt
+} from './launch-rule.mjs'
+
+/** Where the ledgers live, beside the stage markers and the trajectory. */
+export const LEDGER_DIR = join(SHIP_DIR, 'launch-ledger')
+
+const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const iso = ms => new Date(ms).toISOString()
+const str = value => (typeof value === 'string' && value ? value : null)
+const messageOf = err => (err && err.message) || String(err)
+
+/** Safe as a file name: the trajectory's run-id rule (`lib/run-log.mjs`). */
+function isSafeSessionId(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9._-]{1,128}$/.test(value) && !value.includes('..')
+}
+
+/** The session's ledger path, or null when the session id cannot name a file. */
+export function ledgerPath(root, sessionId) {
+  if (typeof root !== 'string' || !isSafeSessionId(sessionId)) return null
+  return join(root, LEDGER_DIR, `${sessionId}.json`)
+}
+
+function isLedger(value) {
+  if (!isObject(value) || value.schema !== LEDGER_SCHEMA || !Array.isArray(value.launches)) return false
+  const prompt = promptMs(value)
+  return prompt === null || Number.isFinite(prompt)
+}
+
+const isStale = (ledger, now, maxAgeMs) => {
+  const newest = newestLaunch(ledger)
+  return newest !== null && now - newest.ms > maxAgeMs
+}
+
+/**
+ * The session's ledger, or null on every failure. A stale ledger reads as
+ * absent. `onProblem` hears about a ledger that exists and cannot be read — an
+ * absent or stale one is ordinary and says nothing — so the hook can speak the
+ * degradation instead of allowing silently.
+ */
+export function readLedger(root, sessionId, { now = Date.now(), maxAgeMs = LIMITS.launchLedgerMaxAgeMs, onProblem } = {}) {
+  const path = ledgerPath(root, sessionId)
+  if (!path) return null
+  const problem = message => {
+    if (typeof onProblem === 'function') onProblem(message)
+  }
+  let raw
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch (err) {
+    if (err && err.code !== 'ENOENT') problem(`launch ledger unreadable, ignored: ${path}: ${messageOf(err)}`)
+    return null
+  }
+  let value
+  try {
+    value = JSON.parse(raw)
+  } catch {
+    problem(`launch ledger is not valid JSON, ignored: ${path}`)
+    return null
+  }
+  if (!isLedger(value)) {
+    problem(`launch ledger is not an ${LEDGER_SCHEMA} document, ignored: ${path}`)
+    return null
+  }
+  return isStale(value, now, maxAgeMs) ? null : value
+}
+
+function writeLedger(path, ledger) {
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, JSON.stringify(ledger, null, 2) + '\n')
+    return { written: true, path, reason: null }
+  } catch (err) {
+    return { written: false, path, reason: `launch ledger not written: ${path}: ${messageOf(err)}` }
+  }
+}
+
+/**
+ * Record one launch the runtime accepted, with the identity its response
+ * carried. Appends to a readable ledger and keeps its recorded prompt; over a
+ * missing, stale or unreadable one it starts fresh, which is the state "one
+ * launch, no prompt since" — exactly what just happened. The record is changed
+ * by `withLaunch`, the transform the hooks module applies to its state record.
+ */
+export function recordLaunch(root, sessionId, toolResponse, { now = Date.now(), maxAgeMs = LIMITS.launchLedgerMaxAgeMs } = {}) {
+  const path = ledgerPath(root, sessionId)
+  if (!path) return { written: false, path: null, reason: 'session id is not a safe file name' }
+  const response = isObject(toolResponse) ? toolResponse : {}
+  const entry = {
+    at: iso(now),
+    taskId: str(response.taskId),
+    runId: str(response.runId),
+    workflowName: str(response.workflowName),
+    scriptPath: str(response.scriptPath)
+  }
+  const existing = readLedger(root, sessionId, { now, maxAgeMs })
+  return writeLedger(path, withLaunch({ ...(existing || emptyRecord()), sessionId }, entry, maxAgeMs))
+}
+
+/**
+ * Record a human prompt — only when the session already has a readable ledger.
+ * One existence check and out when it does not, so a prompt creates no file and
+ * no directory. Keeps the later of the recorded time and `now`, through
+ * `withPrompt`, the hooks module's transform too.
+ */
+export function recordPrompt(root, sessionId, { now = Date.now(), maxAgeMs = LIMITS.launchLedgerMaxAgeMs } = {}) {
+  const path = ledgerPath(root, sessionId)
+  if (!path) return { written: false, path: null, reason: 'session id is not a safe file name' }
+  if (!existsSync(path)) return { written: false, path, reason: 'no ledger for this session' }
+  const ledger = readLedger(root, sessionId, { now, maxAgeMs })
+  if (!ledger) return { written: false, path, reason: 'ledger unreadable or stale' }
+  const previous = promptMs(ledger)
+  if (previous !== null && previous >= now) return { written: false, path, reason: 'a later prompt is already recorded' }
+  return writeLedger(path, withPrompt(ledger, iso(now)))
+}
+
+/**
+ * Remove sibling ledgers whose file is older than the published age, sparing
+ * `keep` (the session just written). Only `.json` files in the ledger directory
+ * are touched; a missing directory or a failed removal is a no-op.
+ */
+export function sweepStale(root, { now = Date.now(), maxAgeMs = LIMITS.launchLedgerMaxAgeMs, keep } = {}) {
+  const removed = []
+  if (typeof root !== 'string') return { removed }
+  const dir = join(root, LEDGER_DIR)
+  let names
+  try {
+    names = readdirSync(dir).sort()
+  } catch {
+    return { removed }
+  }
+  for (const name of names) {
+    if (!name.endsWith('.json') || (keep && name === `${keep}.json`)) continue
+    try {
+      const path = join(dir, name)
+      const stat = statSync(path)
+      if (stat.isFile() && now - stat.mtimeMs > maxAgeMs) {
+        unlinkSync(path)
+        removed.push(name)
+      }
+    } catch {
+      // Another session may have swept or rewritten it first; nothing to say.
+    }
+  }
+  return { removed }
+}

package/lib/launch-rule.mjs

@@ -0,0 +1,174 @@
+// The launch rule: what a ship launch is, what a human prompt is, and whether
+// the next launch has a human behind it (guard-ship-relaunch design D1, D3;
+// guard-ship-relaunch-in-process design D1).
+//
+// The one recorded twenty-agent mistake was a parent chat calling Workflow again
+// over leftover checkboxes, with no human message in between. The skill forbids
+// it in prose; this is the rule that lets a hook refuse it: a launch newer than
+// the session's last human prompt means the next launch has no human behind it.
+//
+// ONE RULE, TWO TRANSPORTS. Two guards read this module: the settings hook
+// (`hooks/guard-relaunch.mjs`, through `lib/launch-ledger.mjs`, which keeps the
+// record in a file per session and re-exports everything here unchanged) and
+// the hooks module (`hooks/mod.mjs`, which keeps the same record in the
+// engine's session state). The decision and its words are defined once, so a
+// reword of the skill sentence moves both guards and both pins together.
+//
+// NO NODE. The hooks module runs in the engine with no Node, so this file
+// imports nothing but the published age, and `test/spine/launch-ledger.test.mjs`
+// pins that. A record here is plain data: `{ schema, launches: [{ at, runId,
+// workflowName, scriptPath }], lastHumanPromptAt }`, times as ISO strings.
+//
+// EVERY UNKNOWN ALLOWS. A launch time that does not parse is no launch, a
+// record that is not one is empty, an age past `LIMITS.launchLedgerMaxAgeMs` is
+// absent. A false refusal costs one typed message; a rule whose own parse
+// error blocked a launch would be the worse failure.
+
+import { LIMITS } from './limits.mjs'
+
+export const LEDGER_SCHEMA = 'interlock.launch-ledger/1'
+
+/**
+ * The skill sentence the deny quotes, verbatim, so one string is pinned in both
+ * places: `test/hooks.test.mjs` asserts `skills/ship/SKILL.md` still contains it.
+ */
+export const SKILL_QUOTE = 'Leftover `- [ ]` boxes after a run are a report, not authorization to call Workflow again'
+
+/** The leading marker of the host's completion wake (guard-ship-relaunch design D4, task-1 capture). */
+export const WAKE_MARKER = '<task-notification>'
+
+// The plugin's own ship workflow, by either handle the host passes: the script
+// path the skill trampoline names, or the command name the manifest's
+// `workflows` entry registers (`interlock:ship`, possibly marketplace-prefixed).
+const SHIP_SCRIPT = /(^|\/)workflows\/ship\.js$/
+const SHIP_NAME = /(^|[^A-Za-z0-9_])interlock:ship$/
+const LAUNCHED = new Set(['async_launched', 'remote_launched'])
+
+const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const posix = path => path.replace(/\\/g, '/')
+const str = value => (typeof value === 'string' && value ? value : null)
+const timeOf = launch => (isObject(launch) && typeof launch.at === 'string' ? Date.parse(launch.at) : NaN)
+const isRecord = value => isObject(value) && Array.isArray(value.launches)
+
+/**
+ * Is this Workflow input a launch of the plugin's ship workflow? A call
+ * carrying `resumeFromRunId` is still a launch: a resume replays every agent
+ * after the failed one. With the session's record, a call that resumes a run it
+ * recorded — by `runId`, or by the persisted `scriptPath` the completion wake
+ * suggests passing back — is one too, though it names neither handle above.
+ */
+export function isShipLaunch(toolInput, ledger = null) {
+  if (!isObject(toolInput)) return false
+  const scriptPath = typeof toolInput.scriptPath === 'string' ? posix(toolInput.scriptPath) : ''
+  if (scriptPath && SHIP_SCRIPT.test(scriptPath)) return true
+  if (typeof toolInput.name === 'string' && SHIP_NAME.test(toolInput.name)) return true
+  if (!isRecord(ledger)) return false
+  return ledger.launches.some(
+    launch =>
+      isObject(launch) &&
+      ((str(launch.runId) && toolInput.resumeFromRunId === launch.runId) ||
+        (str(launch.scriptPath) && scriptPath && scriptPath === posix(launch.scriptPath)))
+  )
+}
+
+/**
+ * Did the runtime accept this launch? Positive, not negative: only a response
+ * object whose `status` says it launched, carrying no error mark, counts. The
+ * capture found a refused launch never reaches PostToolUse at all — the engine
+ * rejects it at input validation — so this is the second line, and anything it
+ * cannot recognise records nothing, which is the allow direction.
+ */
+export function isAcceptedLaunch(toolResponse) {
+  if (!isObject(toolResponse)) return false
+  if (toolResponse.is_error === true || toolResponse.isError === true || toolResponse.error !== undefined) return false
+  return LAUNCHED.has(toolResponse.status)
+}
+
+/**
+ * A prompt a person sent, as opposed to the host's completion wake, read off
+ * the prompt's text: the settings form's test, which has no origin to read. No
+ * text is still a prompt. The hooks module reads the engine's stamped origin
+ * instead (guard-ship-relaunch-in-process design D3).
+ */
+export function isHumanPrompt(prompt) {
+  if (typeof prompt !== 'string') return true
+  return !prompt.trimStart().startsWith(WAKE_MARKER)
+}
+
+/** The newest launch with a readable time, or null. */
+export function newestLaunch(ledger) {
+  if (!isRecord(ledger)) return null
+  let newest = null
+  for (const launch of ledger.launches) {
+    const ms = timeOf(launch)
+    if (Number.isFinite(ms) && (!newest || ms > newest.ms)) newest = { at: launch.at, ms }
+  }
+  return newest
+}
+
+/** `lastHumanPromptAt` as milliseconds: null when none was recorded, NaN when it cannot be read. */
+export function promptMs(ledger) {
+  if (ledger.lastHumanPromptAt === null || ledger.lastHumanPromptAt === undefined) return null
+  return typeof ledger.lastHumanPromptAt === 'string' ? Date.parse(ledger.lastHumanPromptAt) : NaN
+}
+
+/** A record with no launch and no prompt: what a session starts from. A new object on every call. */
+export function emptyRecord() {
+  return { schema: LEDGER_SCHEMA, launches: [], lastHumanPromptAt: null }
+}
+
+/**
+ * The record with one more launch. Launches older than the published age
+ * (measured back from this one) and launches with no readable time are
+ * dropped, so the record stays bounded in either transport. Anything that is
+ * not a record starts from `emptyRecord()`. The input is never mutated.
+ */
+export function withLaunch(record, launch, maxAgeMs = LIMITS.launchLedgerMaxAgeMs) {
+  const base = isRecord(record) ? record : emptyRecord()
+  const ms = timeOf(launch)
+  const kept = base.launches.filter(prior => {
+    const at = timeOf(prior)
+    return Number.isFinite(at) && (!Number.isFinite(ms) || ms - at <= maxAgeMs)
+  })
+  return { ...base, launches: [...kept, launch] }
+}
+
+/**
+ * The record with a human prompt at `at` (an ISO time). Keeps the later of the
+ * recorded time and `at`: an earlier clock never moves the prompt back. Anything
+ * that is not a record starts from `emptyRecord()`. The input is never mutated.
+ */
+export function withPrompt(record, at) {
+  const base = isRecord(record) ? record : emptyRecord()
+  const next = typeof at === 'string' ? Date.parse(at) : NaN
+  if (!Number.isFinite(next)) return base
+  const previous = promptMs(base)
+  if (previous !== null && Number.isFinite(previous) && previous >= next) return base
+  return { ...base, lastHumanPromptAt: at }
+}
+
+/** The deny's words (guard-ship-relaunch design D3): what happened, the skill's rule, and the remedy. */
+export function denyReason(lastLaunchAt) {
+  return (
+    `guard-relaunch: a ship workflow was already launched in this session at ${lastLaunchAt} ` +
+    `and no human prompt has arrived since. skills/ship/SKILL.md: "${SKILL_QUOTE}." ` +
+    `Send a new message that asks to ship the leftovers, or type /interlock:ship again, ` +
+    `and the next launch is allowed.`
+  )
+}
+
+/**
+ * The rule. No record, or a stale one → allow. A launch newer than the last
+ * human prompt — including every launch when no prompt was recorded → deny.
+ * Anything this cannot read a time from → allow.
+ */
+export function decideLaunch(ledger, now = Date.now(), maxAgeMs = LIMITS.launchLedgerMaxAgeMs) {
+  const allow = { decision: 'allow', reason: null, lastLaunchAt: null, lastHumanPromptAt: null }
+  const newest = newestLaunch(ledger)
+  if (!newest) return allow
+  const prompt = promptMs(ledger)
+  const seen = { lastLaunchAt: newest.at, lastHumanPromptAt: prompt === null ? null : ledger.lastHumanPromptAt }
+  if (now - newest.ms > maxAgeMs) return { ...allow, ...seen }
+  if (prompt !== null && (!Number.isFinite(prompt) || prompt >= newest.ms)) return { ...allow, ...seen }
+  return { decision: 'deny', reason: denyReason(newest.at), ...seen }
+}