@renzrollon/interlock 1.1.0 → 1.2.0

package/bin/interlock-run

@@ -22,8 +22,10 @@
 //                  this file runs `git worktree add`; `run record-batch` folds
 //                  and removes them, and halts on a real collision (design D7).
 //   the transport  one agent process per lane, prompt inline on stdin.
-//   the banners    which host, which billing path, which guards are absent, and
-//                  which spawns could not have their model applied (design D8).
+//   the banners    which host, which billing path, which guards are absent,
+//                  which spawns could not have their model or their effort
+//                  applied, and whether an exported effort override outranks
+//                  the plan (design D8; dispatch-published-effort D2, D9, D16).
 //
 // Everything else — wave order, caps, verdicts, the review, the receipt — is
 // behind `runCli` on purpose, so a second host cannot quietly grow a second copy
@@ -36,8 +38,10 @@
 import { execFileSync } from 'node:child_process'
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
+import { laneEnv } from '../lib/host.mjs'
 import { createHost, drivesClaudeBinary, HOST_IDS } from '../lib/host/registry.mjs'
 import { MODEL_MAP_ENV } from '../lib/host/model-map.mjs'
+import { EFFORT_LEVEL_ENV, effortLevelOverride } from '../lib/host/effort.mjs'
 import { CODEX_KEY_ENVS, onChatGptPlan } from '../lib/host/codex.mjs'
 
 const WORK = '.claude/ship'
@@ -222,6 +226,41 @@ const hostId =
 // because the adapter is the only party that saw the wire.
 const routing = []
 
+// Every spawn that named an effort, and what the adapter managed to do with it.
+// A list of its own beside `routing`, folded the same way: on a negotiated host
+// the outcome differs per spawn, so the verdict is the adapter's event and never
+// one this file derives from the host id or the step (design D2, D27).
+const effortRouting = []
+
+// What the host observed about each spawn of the CURRENT step, copied off the
+// adapter's `spawn-done` / `spawn-failed` events as `{ label, ...host }` and
+// handed to the CLI on its own channel, `--host-records`, beside — never inside
+// — the results (design D7). This file reads no field of a record: which lane
+// was stopped, denied or served by another model is the CLI's decision. An
+// adapter that reports no host leaves the list empty and every lane unobserved.
+let hostRecords = []
+
+// A runner killed with SIGINT or SIGTERM closes the run through `stop()` like
+// any other halt, so it leaves a receipt, a terminal trajectory event and a
+// resume card instead of a run nobody can reconstruct. Registered before the
+// host is created: a signal that lands during the adapter's synchronous probe is
+// held until the first await — the wait on `run start` — and handled there,
+// rather than killing the process by default. `stopping` makes it one close: a
+// second signal, or a signal during a close already under way, starts nothing.
+// In-flight lane processes are not killed here; each adapter's spawn timeout
+// bounds them.
+let stopping = false
+function onSignal(signal) {
+  if (stopping) return
+  stopping = true
+  stop(`interlock-run received ${signal}`).catch(err => {
+    process.stderr.write(`interlock-run: the close after ${signal} failed: ${(err && err.message) || err}\n`)
+    process.exit(1)
+  })
+}
+process.once('SIGINT', () => onSignal('SIGINT'))
+process.once('SIGTERM', () => onSignal('SIGTERM'))
+
 // Refusal comes BEFORE anything is created or written. A run that started and
 // then discovered it had no host would already have a manifest, a briefing and a
 // trajectory describing a run that never happened.
@@ -234,6 +273,7 @@ try {
     ...(hostId === 'acp' && typeof flags['acp-command'] === 'string'
       ? { command: flags['acp-command'] }
       : {}),
+    env: laneEnv(process.env),
     cwd: root,
     timeoutMs: Number.isInteger(Number.parseInt(String(flags['timeout-ms'] ?? ''), 10))
       ? Number.parseInt(String(flags['timeout-ms']), 10)
@@ -250,6 +290,25 @@ try {
         }
         return
       }
+      if (
+        event &&
+        (event.type === 'spawn-done' || event.type === 'spawn-failed') &&
+        event.host &&
+        typeof event.host === 'object'
+      ) {
+        hostRecords.push({ label: event.label, ...event.host })
+      }
+      if (event && event.type === 'effort-routing') {
+        effortRouting.push(event)
+        if (verbose) {
+          process.stderr.write(
+            `${hostId}: effort routing ${event.label}: ${event.requested} → ` +
+              (event.applied ? `${event.value} via ${event.via}` : `not applied (${event.reason})`) +
+              '\n'
+          )
+        }
+        return
+      }
       if (verbose) process.stderr.write(`${hostId}: ${JSON.stringify(event)}\n`)
     }
   })
@@ -268,13 +327,29 @@ const capabilities = host.capabilities || {}
 // them in one block with everything else the run degraded on (design D8).
 const banners = [`RUNNER HOST: ${hostId} (experimental)`]
 
-if (drivesClaudeBinary(hostId, process.env, typeof flags['acp-command'] === 'string' ? flags['acp-command'] : undefined)) {
+const claudeBinary = drivesClaudeBinary(
+  hostId,
+  process.env,
+  typeof flags['acp-command'] === 'string' ? flags['acp-command'] : undefined
+)
+if (claudeBinary) {
   banners.push(
     `SUBSCRIPTION PATH: programmatic (${hostId}) — claude -p, the Agent SDK and ACP are the usage ` +
       `Anthropic has flagged for separate billing; /interlock:ship on the Workflow runtime is the ` +
       `exempted path, see docs/04-when-it-stops.md`
   )
 }
+// The Claude CLI's effort variable outranks `--effort` and every per-agent
+// effort, so while it is set the plan's effort is not in effect. It means
+// nothing to a host that is not the Claude binary (D22). It is the operator's
+// environment: bannered, never stripped from the child's (D26).
+const effortOverride = claudeBinary ? effortLevelOverride(process.env) : ''
+if (effortOverride) {
+  banners.push(
+    `EFFORT ROUTING OVERRIDDEN: ${EFFORT_LEVEL_ENV}=${effortOverride} — every agent runs at ` +
+      `that effort, so the per-step effort in the plan is not in effect`
+  )
+}
 if (hostId === 'codex' && onChatGptPlan(process.env)) {
   banners.push(
     `CHATGPT PLAN PATH (codex): neither ${CODEX_KEY_ENVS.join(' nor ')} is set, so this run spends ` +
@@ -282,6 +357,12 @@ if (hostId === 'codex' && onChatGptPlan(process.env)) {
       `unattended volume to an API key`
   )
 }
+// Whatever the adapter itself degraded on at creation — on the claude host, a
+// mode that can prompt on a CLI that cannot be told not to (design D10). The
+// adapter wrote the words; this file only carries them to the close.
+for (const banner of Array.isArray(host.banners) ? host.banners : []) {
+  if (typeof banner === 'string' && banner) banners.push(banner)
+}
 if (capabilities.hooks === false) {
   banners.push(
     `HOOKS NOT IN FORCE (${hostId}): this repository's PreToolUse guards are Claude Code's, so ` +
@@ -310,6 +391,27 @@ function routingBanners() {
   ]
 }
 
+/**
+ * What the run has to say about effort routing, read off the adapter's events.
+ *
+ * The model twin's shape, for the same reason: a run on which every named
+ * effort was applied says so, and a run on which none was named says nothing.
+ * Each banner line states the level as requested, taken from the event, so a
+ * host that could not apply an effort cannot be read as one that ran at it.
+ */
+function effortBanners() {
+  if (!effortRouting.length) return []
+  const unapplied = effortRouting.filter(event => event.applied === false)
+  if (!unapplied.length) {
+    return [`effort routing: applied on ${effortRouting.length}/${effortRouting.length} spawns`]
+  }
+  return [
+    `EFFORT ROUTING UNAVAILABLE (${hostId}): the plan's per-step effort assignment is not in effect ` +
+      `for the spawns below — each ran at the host's own default`,
+    ...unapplied.map(event => `  — ${event.label}: ${event.requested} requested, ${event.reason}`)
+  ]
+}
+
 let resolvedChange = changeArg || '(unresolved)'
 let steps = 0
 
@@ -323,6 +425,9 @@ function write(rel, data) {
 
 /** Run the CLI through the host port and parse `--json` stdout when present. */
 async function cli(argv) {
+  // From the first close on, a signal starts no second one — whichever path
+  // reached the close: the loop's own continuation, or `stop()`.
+  if (argv[0] === 'run' && argv[1] === 'close') stopping = true
   const result = await host.runCli([...argv, '--json'])
   if (!result.stdout.trim()) return null
   try {
@@ -389,6 +494,9 @@ function spawnOne(s) {
     prompt: s.prompt,
     schema: s.schema,
     ...(s.model ? { model: s.model } : {}),
+    // Forwarded exactly as the step carries it, and only when it names one: a
+    // null effort reaches the host as no key at all, so it keeps its default.
+    ...(s.effort ? { effort: s.effort } : {}),
     ...(s.worktree && s.worktree.path ? { cwd: join(root, s.worktree.path) } : {}),
     type: s.type,
     tools: s.tools
@@ -442,9 +550,11 @@ while (step && step.then) {
   const worktreeProblem = createWorktrees(step)
   if (worktreeProblem) await stop(worktreeProblem)
 
-  for (const s of step.spawns || []) log(`  ${step.action}: ${s.label}`)
+  for (const s of step.spawns || []) log(`  ${step.action}: ${s.title || s.label}`)
+  hostRecords = []
   const results = await spawnAll(step)
   write(`${WORK}/results.json`, results)
+  write(`${WORK}/host-records.json`, hostRecords)
   // The close is the one continuation that needs more than the spawn results:
   // it reads the banners only this host could raise. Appended here as well as
   // at `stop()`, so a CLEAN run reports them too — the path least likely to
@@ -455,6 +565,8 @@ while (step && step.then) {
     ...(isClose ? closeArgs() : []),
     '--results',
     `${WORK}/results.json`,
+    '--host-records',
+    `${WORK}/host-records.json`,
     '--root',
     '.'
   ])
@@ -488,13 +600,13 @@ async function stop(reason) {
 /** The flags the close reads for what only this host observed. */
 function closeArgs() {
   // Routing is resolved here rather than pushed as it happened, because the
-  // question it answers — did EVERY spawn get its model — is only answerable
-  // once the last spawn has returned.
+  // question it answers — did EVERY spawn get its model, and its effort — is
+  // only answerable once the last spawn has returned.
   //
   // `--notify` is unconditional: this driver knows nothing about topics,
   // servers or notification text. It requests the push; the CLI decides
   // whether one is configured and what it says (design D1).
-  return ['--host-banners', write(`${WORK}/host-banners.json`, [...banners, ...routingBanners()]), '--notify']
+  return ['--host-banners', write(`${WORK}/host-banners.json`, [...banners, ...routingBanners(), ...effortBanners()]), '--notify']
 }
 
 /** Print the close's summary and exit on its status. */

package/hooks/guard-relaunch.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Launch guard: a second ship launch in one session, with no human prompt since
+// the last, is denied (guard-ship-relaunch; spec: hooks/launch-guard).
+//
+// The most expensive recorded mistake was a parent chat calling Workflow again
+// over leftover checkboxes — another 20+ agents, a full review cycle included —
+// and the skill's sentence forbidding it was the only thing in the way. This
+// bounds it outside the model. The prose and `evals/trampoline-launch` stay: the
+// eval measures whether the model obeys, this bounds what happens when it does
+// not.
+//
+// ONE SCRIPT, FOUR REGISTRATIONS, dispatching on `hook_event_name`:
+//
+//   PreToolUse   (Workflow)  the only branch that may deny: a ship launch whose
+//                            session ledger holds a launch newer than the last
+//                            human prompt.
+//   PostToolUse  (Workflow)  records a ship launch the runtime accepted, then
+//                            sweeps ledgers past the published age.
+//   UserPromptSubmit,        record the time of a human prompt — only when the
+//   UserPromptExpansion      session already has a ledger. The host's completion
+//                            wake fires UserPromptSubmit too; it is not a human
+//                            and is not counted (lib/launch-ledger.mjs).
+//
+// EVERY UNKNOWN ALLOWS: no session id, an unsafe one, a missing, malformed or
+// stale ledger, a tool input that is not a ship launch, a tool that is not
+// Workflow, an event with no branch, and the guard's own crash. A false deny
+// costs one typed message; that is still a denial, so it is the only branch that
+// can speak one. The recorder branches print no decision on any path; a ledger
+// write that fails is a stderr line, because a guard that silently stopped
+// recording is a guard that silently stopped denying.
+//
+// The rule and its words live in lib/launch-ledger.mjs. This file is plumbing.
+
+import {
+  decideLaunch,
+  isAcceptedLaunch,
+  isHumanPrompt,
+  isShipLaunch,
+  readLedger,
+  recordLaunch,
+  recordPrompt,
+  sweepStale
+} from '../lib/launch-ledger.mjs'
+import { readEvent, allow, deny, toolName, toolInput, projectRoot } from './_shared.mjs'
+
+const GUARD = 'guard-relaunch'
+
+/** The session id as the host sent it, or '' — an unsafe one is refused by the ledger module. */
+const sessionOf = event => (typeof event.session_id === 'string' ? event.session_id.trim() : '')
+
+function onPreToolUse(event) {
+  if (toolName(event) !== 'Workflow') allow()
+  const sessionId = sessionOf(event)
+  if (!sessionId) allow()
+  const root = projectRoot(event)
+
+  const problems = []
+  const ledger = readLedger(root, sessionId, { onProblem: message => problems.push(message) })
+  if (!isShipLaunch(toolInput(event), ledger)) allow()
+  if (problems.length) allow(`${GUARD}: ${problems.join('; ')} — allowing`)
+
+  const verdict = decideLaunch(ledger)
+  if (verdict.decision !== 'deny') allow()
+  deny(verdict.reason, {
+    guard: GUARD,
+    sessionId,
+    lastLaunchAt: verdict.lastLaunchAt,
+    lastHumanPromptAt: verdict.lastHumanPromptAt
+  })
+}
+
+function onPostToolUse(event) {
+  if (toolName(event) !== 'Workflow') return
+  const sessionId = sessionOf(event)
+  if (!sessionId) return
+  const root = projectRoot(event)
+
+  if (!isShipLaunch(toolInput(event), readLedger(root, sessionId))) return
+  if (!isAcceptedLaunch(event.tool_response)) return
+  const written = recordLaunch(root, sessionId, event.tool_response)
+  if (!written.written) {
+    process.stderr.write(`${GUARD}: ${written.reason}\n`)
+    return
+  }
+  sweepStale(root, { keep: sessionId })
+}
+
+function onPrompt(event) {
+  const sessionId = sessionOf(event)
+  if (!sessionId || !isHumanPrompt(event.prompt)) return
+  const written = recordPrompt(projectRoot(event), sessionId)
+  // Only a ledger that exists and failed to take the write is worth a line;
+  // "no ledger for this session" is every prompt in every repository.
+  if (!written.written && written.reason && written.reason.startsWith('launch ledger not written')) {
+    process.stderr.write(`${GUARD}: ${written.reason}\n`)
+  }
+}
+
+const BRANCHES = {
+  PreToolUse: onPreToolUse,
+  PostToolUse: onPostToolUse,
+  UserPromptSubmit: onPrompt,
+  UserPromptExpansion: onPrompt
+}
+
+try {
+  const event = await readEvent()
+  const branch = BRANCHES[event.hook_event_name]
+  if (branch) branch(event)
+} catch (err) {
+  // The guard's own crash must never block a launch or a prompt. Allow, and
+  // leave a diagnostic on stderr rather than a wedged session.
+  allow(`${GUARD}: internal error, allowing by default: ${(err && err.message) || String(err)}`)
+}
+process.exit(0)

package/hooks/guard-tests.mjs

@@ -14,8 +14,19 @@
 // whenever the marker is missing would break ordinary TDD the moment the plugin
 // is installed — a cost strictly larger than the guard's benefit, which exists
 // only inside a ship run's remediation window.
+//
+// A linked worktree has no test profile of its own. `run start` records the one
+// it found — the root's, else the main checkout's — as the manifest's
+// `testProfilePath`, and when the root has none the guard reads that file, so a
+// worktree run keeps its profile-derived test roots. It is read from the
+// manifest, never found by running version control. A recorded path that cannot
+// be read leaves the `.test.`/`.spec.` filename rule alone: the run had a
+// profile, so test files exist, and the filename shape needs no roots. A
+// manifest that records no path changes nothing.
 
-import { readStage } from '../lib/ship-stage.mjs'
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { readStage, SHIP_DIR } from '../lib/ship-stage.mjs'
 import {
   readEvent,
   allow,
@@ -32,6 +43,33 @@ import {
 const GUARD = 'guard-tests'
 const BLOCKED_STAGES = new Set(['remediation', 'fix-tests'])
 
+/**
+ * The test profile the run recorded at start, read through the manifest's
+ * `testProfilePath`. `recorded: false` when there is no manifest or it records
+ * no path — the guard then behaves exactly as it did without one. `profile:
+ * null` with `recorded: true`, and the reason, when the path names nothing
+ * readable as JSON.
+ *
+ * @returns {{ recorded: boolean, profile: object|null, reason?: string }}
+ */
+function recordedTestProfile(root) {
+  let manifest
+  try {
+    manifest = JSON.parse(readFileSync(join(root, SHIP_DIR, 'run.json'), 'utf8'))
+  } catch {
+    return { recorded: false, profile: null }
+  }
+  const path = manifest && typeof manifest === 'object' ? manifest.testProfilePath : null
+  if (typeof path !== 'string' || !path) return { recorded: false, profile: null }
+  try {
+    const value = JSON.parse(readFileSync(resolve(root, path), 'utf8'))
+    if (value && typeof value === 'object') return { recorded: true, profile: value }
+    return { recorded: true, profile: null, reason: `${path}: not a profile object` }
+  } catch (err) {
+    return { recorded: true, profile: null, reason: `${path}: ${(err && err.message) || String(err)}` }
+  }
+}
+
 try {
   const event = await readEvent()
   const tool = toolName(event)
@@ -44,8 +82,18 @@ try {
   const target = editTargetPath(event)
   if (!target) allow() // no concrete path to protect
 
-  const { roots, hasProfile } = testRootsFromProfile(loadTestProfile(root))
-  if (!hasProfile) allow() // no profile → nothing names where tests live → allow
+  const fromRoot = testRootsFromProfile(loadTestProfile(root))
+  let roots = fromRoot.roots
+  if (!fromRoot.hasProfile) {
+    const recorded = recordedTestProfile(root)
+    if (!recorded.recorded) allow() // no profile, none recorded → nothing names where tests live → allow
+    // The run's profile, derived exactly as a root profile is; unreadable → no
+    // roots, and the filename rule alone — said, not silent.
+    if (!recorded.profile) {
+      process.stderr.write(`${GUARD}: the test profile the run recorded could not be read, so only the filename rule applies: ${recorded.reason}\n`)
+    }
+    roots = testRootsFromProfile(recorded.profile).roots
+  }
 
   if (!isTestPath(target, roots, root)) allow() // not a test file → allow (source repair is expected)
 

package/hooks/hooks.json

@@ -0,0 +1 @@
+{ "hooks": {}, "modules": ["./mod.mjs"] }