@renzrollon/interlock 1.1.1 → 1.2.1

package/hooks/preflight.mjs

@@ -12,10 +12,20 @@
 // It NEVER blocks. `interlock doctor` is non-mutating, and a preflight that
 // aborted the session because its own binary was missing would be worse than no
 // preflight. Every path here exits 0.
+//
+// It also surfaces any interrupted-run note a previous session left — a run
+// that ended with its session and never reached its close (lib/interrupted.mjs).
+// It marks nothing: the next `interlock run start`, where the reader is about to
+// spend agents, is the moment that marks a note spoken. A linked worktree's run
+// writes its note into the state home — the main checkout — so the notes are
+// read from the home the doctor resolved AND from the working directory (a run
+// whose manifest recorded no home wrote there), each run spoken once. When the
+// doctor gave no home — it could not run, or predates the field — the working
+// directory alone, as before.
 
 import { execFileSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { appendFileSync, existsSync, realpathSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const PLUGIN_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
@@ -27,6 +37,12 @@ function interlockBin() {
   return 'interlock' // let PATH resolution decide; a miss throws ENOENT below
 }
 
+/**
+ * The preflight's own report, as one message, and the state home the doctor
+ * resolved — `null` when its output carried none or could not be read.
+ *
+ * @returns {{ message: string, stateHome: string|null }}
+ */
 function run() {
   let raw
   try {
@@ -43,13 +59,14 @@ function run() {
     if (err && typeof err.stdout === 'string' && err.stdout.trim()) {
       raw = err.stdout
     } else {
-      report(
-        `interlock preflight could not run: ${(err && err.message) || String(err)}\n` +
+      return {
+        message:
+          `interlock preflight could not run: ${(err && err.message) || String(err)}\n` +
           `The \`interlock\` binary is not resolvable from this session. Inside Claude Code the ` +
           `plugin's bin/ is normally injected; if you see this, reinstall the plugin. The session ` +
-          `continues — this preflight is advisory.`
-      )
-      return
+          `continues — this preflight is advisory.`,
+        stateHome: null
+      }
     }
   }
 
@@ -57,17 +74,23 @@ function run() {
   try {
     doctor = JSON.parse(raw)
   } catch {
-    report('interlock preflight ran but its output could not be parsed; skipping. The session continues.')
-    return
+    doctor = null
+  }
+  if (!doctor || typeof doctor !== 'object') {
+    return {
+      message: 'interlock preflight ran but its output could not be parsed; skipping. The session continues.',
+      stateHome: null
+    }
   }
+  const stateHome =
+    typeof doctor.stateHome === 'string' && doctor.stateHome ? resolve(process.cwd(), doctor.stateHome) : null
 
   const checks = Array.isArray(doctor.checks) ? doctor.checks : []
   const failures = checks.filter(c => c && c.status === 'fail')
   if (!failures.length) {
     const warns = (doctor.counts && doctor.counts.warn) || 0
     // A clean preflight is quiet, not a wall of output — one confirming line.
-    report(`interlock preflight OK${warns ? ` (${warns} warning${warns === 1 ? '' : 's'})` : ''}.`)
-    return
+    return { message: `interlock preflight OK${warns ? ` (${warns} warning${warns === 1 ? '' : 's'})` : ''}.`, stateHome }
   }
 
   const lines = ['interlock preflight found issues that can stall an unattended ship run:']
@@ -80,7 +103,52 @@ function run() {
     }
   }
   lines.push('The session still starts — apply the fixes above before /interlock:ship.')
-  report(lines.join('\n'))
+  return { message: lines.join('\n'), stateHome }
+}
+
+/** Two paths naming one directory — through a symlink too — so one directory is read once. */
+function sameDirectory(a, b) {
+  const canonical = p => {
+    try {
+      return realpathSync(p)
+    } catch {
+      return resolve(p)
+    }
+  }
+  return canonical(a) === canonical(b)
+}
+
+/**
+ * One line per interrupted-run note not yet spoken, and one per note that
+ * could not be read, from the state home and then the working directory. A run
+ * whose note is in both is one interrupted run, spoken once. Loaded on demand
+ * rather than imported, so a hook that finds its library missing still exits 0
+ * — and says so instead of falling silent.
+ */
+async function interruptedLines(cwd, stateHome) {
+  let lib
+  try {
+    lib = await import(new URL('../lib/interrupted.mjs', import.meta.url).href)
+  } catch (err) {
+    return [`interrupted-run notes could not be read: ${(err && err.message) || String(err)}`]
+  }
+  const roots = stateHome && !sameDirectory(stateHome, cwd) ? [stateHome, cwd] : [cwd]
+  const spoken = new Set()
+  const banners = []
+  const unreadableLines = []
+  for (const root of roots) {
+    const { notes, unreadable } = lib.readInterruptedNotes(root)
+    for (const note of notes.filter(lib.isUnspoken)) {
+      if (spoken.has(note.runId)) continue
+      spoken.add(note.runId)
+      banners.push(lib.formatInterruptedBanner(note))
+    }
+    // The working directory's notes keep their root-relative names; the home's are named in full.
+    for (const u of unreadable) {
+      unreadableLines.push(`An interrupted-run note could not be read: ${root === cwd ? u.file : join(root, u.file)}: ${u.reason}`)
+    }
+  }
+  return [...banners, ...unreadableLines]
 }
 
 /**
@@ -98,8 +166,51 @@ function report(message) {
   process.stdout.write(JSON.stringify(out) + '\n')
 }
 
+/** A single-quoted shell word. A value with a newline or a NUL is refused. */
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+function publishable(value) {
+  return typeof value === 'string' && value.trim() && !/[\0\r\n]/.test(value)
+}
+
+/**
+ * Copy a plugin option into the session so `interlock notify` can see it.
+ *
+ * The host injects `userConfig` into hook processes only. A ship run's notify
+ * call is not a hook, so without this copy a topic typed into the plugin
+ * options would never reach the CLI. An operator who already provided the
+ * shell variable keeps that value. Nothing is printed, and a failure here
+ * does not change the preflight.
+ */
+function publishNotifyOptions() {
+  const file = process.env.CLAUDE_ENV_FILE
+  if (typeof file !== 'string' || !file) return
+  const lines = []
+  const topic = process.env.CLAUDE_PLUGIN_OPTION_NTFY_TOPIC
+  const url = process.env.CLAUDE_PLUGIN_OPTION_NTFY_URL
+  if (publishable(topic) && !publishable(process.env.INTERLOCK_NTFY_TOPIC)) {
+    lines.push(`export INTERLOCK_NTFY_TOPIC=${shellQuote(topic.trim())}`)
+  }
+  if (publishable(url) && !publishable(process.env.INTERLOCK_NTFY_URL)) {
+    lines.push(`export INTERLOCK_NTFY_URL=${shellQuote(url.trim())}`)
+  }
+  if (!lines.length) return
+  appendFileSync(file, lines.join('\n') + '\n')
+}
+
 try {
-  run()
+  try {
+    publishNotifyOptions()
+  } catch (err) {
+    process.stderr.write(
+      `interlock preflight could not publish notify options (ignored): ${(err && err.message) || err}\n`
+    )
+  }
+  const { message, stateHome } = run()
+  const lines = [message, ...(await interruptedLines(process.cwd(), stateHome))].filter(Boolean)
+  if (lines.length) report(lines.join('\n'))
 } catch (err) {
   // Belt and suspenders: nothing this hook does may abort the session.
   process.stderr.write(`interlock preflight hook error (ignored): ${(err && err.message) || String(err)}\n`)

package/hooks/recorder.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// The recorder: a hook that REPORTS what a ship run cannot see about itself, and
+// never decides anything.
+//
+// The guards beside it return a decision; this returns none. It prints nothing
+// on stdout on any path, and it exits 0 on every path — a valid event, malformed
+// input, an event it has no branch for, and its own crash. A recorder that could
+// block would be a guard nobody reviewed as one. A subagent hook that exited
+// non-zero could keep the agent it reports on running.
+//
+// ONE FILE FOR EVERY REPORTING BRANCH. It dispatches on `hook_event_name`; a new
+// reporting branch joins this file rather than adding a second recorder. Five
+// branches today:
+//
+//   SessionEnd — a session that ends while its own ship run is live kills the
+//   background workflow before `run close`: no receipt, no resume card, no
+//   terminal trajectory event. This writes one small note under the state
+//   home's `.claude/ship/interrupted/` so the next `interlock run start`, the
+//   next SessionStart preflight and `interlock report` can say so
+//   (lib/interrupted.mjs). The home is the one the manifest records — a linked
+//   worktree's run writes into its main checkout — else the working root. It is
+//   read from the manifest, never found by running version control.
+//
+//   SubagentStart, SubagentStop — a Workflow script's `agent()` returns its
+//   result and nothing else. The start records the agent once (the resume and
+//   teammate-message firings change nothing); the stop sums the agent's own
+//   transcript — usage per turn, the models that served it, the briefing sha it
+//   was spawned with — into the same file (lib/agent-usage.mjs). `run close`
+//   joins those files to the spawns it dispatched.
+//
+//   PermissionDenied, PermissionRequest — a permission event that interrupted
+//   the run, one file per event: its kind, the time, the agent, the tool name and
+//   the host's reason. Never the tool input, never the host's suggestions.
+//
+// EVERY PLUGIN HOOK RUNS IN EVERY SESSION, in every repository. So every branch
+// passes one gate, in this order, and otherwise creates no file and no
+// directory:
+//
+//   - a stage marker is live: its pid — the session process, which is still
+//     alive while its own hooks run — is a running process. A marker whose
+//     process is gone is an orphan and means nothing;
+//   - the run manifest names that marker's change and carries a run id;
+//   - SessionEnd only: the manifest's session is the one ending. A session that
+//     does not own the run, or a run with no session (the runner host), never
+//     matches — the runner's own signal trap is its receipt instead;
+//   - the two subagent branches only: the event's agent type is exactly the one
+//     the host reports for every agent a Workflow script spawns, whatever type
+//     the script named. The registration's matcher says the same, and the
+//     branch checks again: an internal agent of a `claude --agent
+//     interlock:worker` session reports `interlock:worker`, and writes nothing.
+//
+// It never reads or writes the run trajectory, and it starts no process: one
+// `mkdirSync` and one write per record. A failed write is a line on stderr, never
+// an exit code (the note and the agent-usage sidecar are outcome-class;
+// docs/13-the-guards.md says why that differs from the trajectory's rule).
+
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { readStage, SHIP_DIR } from '../lib/ship-stage.mjs'
+import { writeInterruptedNote } from '../lib/interrupted.mjs'
+import { WORKFLOW_AGENT_TYPE, writeAgentStart, writeAgentStop, writePermissionEvent } from '../lib/agent-usage.mjs'
+import { projectRoot, readEvent } from './_shared.mjs'
+
+/** The run manifest, read raw: the run program is not loaded into a hook. */
+function readRunManifest(root) {
+  try {
+    const value = JSON.parse(readFileSync(join(root, SHIP_DIR, 'run.json'), 'utf8'))
+    return value && typeof value === 'object' ? value : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The gate every branch passes before it touches the filesystem: a live marker,
+ * and a manifest for that marker's change carrying a run id. `null` otherwise.
+ */
+function liveRun(root) {
+  const marker = readStage({ root })
+  if (marker.stage === 'unknown' || typeof marker.change !== 'string') return null
+
+  const manifest = readRunManifest(root)
+  if (!manifest) return null
+  if (manifest.change !== marker.change) return null
+  if (typeof manifest.runId !== 'string' || !manifest.runId) return null
+  return { marker, manifest, runId: manifest.runId }
+}
+
+/** The gate, plus the agent-type re-check the two subagent branches add. */
+function liveRunForAgent(root, event) {
+  const run = liveRun(root)
+  if (!run) return null
+  if (event.agent_type !== WORKFLOW_AGENT_TYPE) return null
+  return run
+}
+
+/** A record that did not land is one line on stderr, and nothing more. */
+function speak(what, result) {
+  if (!result.written) process.stderr.write(`interlock recorder: ${what} not written: ${result.reason}\n`)
+}
+
+/** A session that ended while its own run was live leaves a note. Anything else, nothing. */
+function onSessionEnd(event) {
+  const root = projectRoot(event)
+  const sessionId = typeof event.session_id === 'string' ? event.session_id.trim() : ''
+  if (!sessionId) return
+
+  const run = liveRun(root)
+  if (!run) return
+  const { marker, manifest } = run
+  if (typeof manifest.sessionId !== 'string' || manifest.sessionId !== sessionId) return
+
+  // The home `run start` resolved and recorded; a manifest without one is a run
+  // in the main checkout, or one written before the field existed.
+  const home = typeof manifest.stateHome === 'string' && manifest.stateHome ? resolve(root, manifest.stateHome) : root
+  speak(
+    'interrupted-run note',
+    writeInterruptedNote(home, {
+      runId: run.runId,
+      change: manifest.change,
+      sessionId,
+      reason: event.reason,
+      stage: marker.stage
+    })
+  )
+}
+
+/** A Workflow agent started: its record, once. */
+function onSubagentStart(event) {
+  const root = projectRoot(event)
+  const run = liveRunForAgent(root, event)
+  if (!run) return
+  speak('agent start', writeAgentStart(root, { runId: run.runId, agentId: event.agent_id, agentType: event.agent_type }))
+}
+
+/** A Workflow agent stopped: its transcript, summed into the same record. */
+function onSubagentStop(event) {
+  const root = projectRoot(event)
+  const run = liveRunForAgent(root, event)
+  if (!run) return
+  speak(
+    'agent stop',
+    writeAgentStop(root, {
+      runId: run.runId,
+      agentId: event.agent_id,
+      agentType: event.agent_type,
+      transcriptPath: event.agent_transcript_path
+    })
+  )
+}
+
+/** One permission event, one file — the fields by name, and nothing the tool was given. */
+function permissionBranch(kind) {
+  return event => {
+    const root = projectRoot(event)
+    const run = liveRun(root)
+    if (!run) return
+    speak(
+      `permission ${kind} event`,
+      writePermissionEvent(root, {
+        runId: run.runId,
+        kind,
+        agentId: event.agent_id ?? null,
+        tool: event.tool_name,
+        reason: event.reason ?? null
+      })
+    )
+  }
+}
+
+const BRANCHES = {
+  SessionEnd: onSessionEnd,
+  SubagentStart: onSubagentStart,
+  SubagentStop: onSubagentStop,
+  PermissionDenied: permissionBranch('denied'),
+  PermissionRequest: permissionBranch('request')
+}
+
+try {
+  const event = await readEvent()
+  const name = event && event.hook_event_name
+  // Own keys only: an event named after an Object.prototype member is no branch.
+  if (typeof name === 'string' && Object.hasOwn(BRANCHES, name)) BRANCHES[name](event)
+} catch (err) {
+  // Nothing this hook does may stop a session from ending, keep an agent
+  // running, or speak a decision.
+  process.stderr.write(`interlock recorder hook error (ignored): ${(err && err.message) || String(err)}\n`)
+}
+process.exit(0)