@renzrollon/interlock 1.0.0

package/lib/host/claude-cli.mjs

@@ -0,0 +1,285 @@
+// The `claude` host adapter (design D3).
+//
+// Interlock's default host is the Claude Code Workflow runtime, reached through
+// `/interlock:ship`. This adapter is the other way to reach the same model: the
+// installed `claude` binary in headless print mode, one process per spawn.
+//
+// The contract, verified against Claude Code's own `--help` and one live probe
+// on 2026-09-05:
+//
+//   claude -p --output-format json --json-schema <schema>   envelope on stdout
+//   envelope.structured_output   the schema-validated object (schemaEnforced)
+//   envelope.usage               { input_tokens, output_tokens, ... }
+//   --agent <id> --model <slug> --permission-mode <mode> --allowedTools <list>
+//   prompt on stdin
+//
+// Two things are worth stating because they are not obvious:
+//
+//   1. `--permission-mode bypassPermissions` does NOT disarm this repository's
+//      guards. A live probe (a PreToolUse hook returning `permissionDecision:
+//      "deny"` under that mode) confirmed the tool call was blocked and recorded
+//      in `permission_denials`. So the unattended default stays
+//      `bypassPermissions` and `hooks` stays declared `true`; the fallback D3
+//      named — `dontAsk` plus `--allowedTools` — was not needed. The finding is
+//      recorded in the change's design.md.
+//
+//   2. The plugin's agents (`interlock:worker`, `interlock:ping`) and its hooks
+//      only exist in a session that loaded the plugin. A headless `claude` in a
+//      lane worktree has loaded nothing, so the adapter passes `--plugin-dir`
+//      naming this checkout. That is what makes `--agent` resolvable and `hooks:
+//      true` an honest declaration rather than an assumption about the operator's
+//      installation. If the checkout does not look like the plugin, no `--agent`
+//      is passed and the host declares `hooks: false` — spoken, never silent.
+//
+// Billing: this is `claude -p`, which is the programmatic path Anthropic flagged
+// for separate metered credit. The runner banners it (design D8); the adapter
+// only declares which path it is on.
+
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { assertWorkflowHost, execCapture, mapPipeline, runCli } from '../host.mjs'
+import { parseModelMap, resolveModel } from './model-map.mjs'
+
+/** Override the binary, for a wrapper or a fixture. */
+export const CLAUDE_COMMAND_ENV = 'INTERLOCK_CLAUDE_COMMAND'
+
+/** Override the unattended permission mode. */
+export const CLAUDE_PERMISSION_MODE_ENV = 'INTERLOCK_CLAUDE_PERMISSION_MODE'
+
+/** Optional per-spawn wall clock, in ms. 0 disables it. */
+export const CLAUDE_TIMEOUT_ENV = 'INTERLOCK_CLAUDE_TIMEOUT_MS'
+
+/**
+ * A transport timeout, not a loop cap — the same distinction the ACP adapter
+ * draws. Every number the LOOP obeys is published by `interlock limits`.
+ */
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000
+
+/**
+ * The unattended default, kept on the strength of the live probe above: a
+ * PreToolUse `deny` still blocks under it, so the guards this repository ships
+ * are in force and the run does not stall on a prompt nobody can answer.
+ */
+export const DEFAULT_PERMISSION_MODE = 'bypassPermissions'
+
+/** This checkout, if it is the Interlock plugin — the directory `--plugin-dir` names. */
+export function pluginRoot() {
+  const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+  return existsSync(join(root, '.claude-plugin', 'plugin.json')) && existsSync(join(root, 'agents'))
+    ? root
+    : null
+}
+
+/**
+ * The exact argv one spawn sends. One function, so a drifted vendor flag is one
+ * edit and one pinned test rather than a scattered rewrite.
+ *
+ * @param {object} req                      the step's spawn request
+ * @param {object} opts
+ * @param {string|null} opts.model          the resolved model id, or null
+ * @param {string} opts.permissionMode
+ * @param {string|null} opts.plugin         `--plugin-dir` target, or null
+ * @returns {string[]}
+ */
+export function claudeArgs(req, { model, permissionMode, plugin } = {}) {
+  const request = req && typeof req === 'object' ? req : {}
+  const args = ['-p', '--output-format', 'json']
+  if (request.schema) args.push('--json-schema', JSON.stringify(request.schema))
+  if (plugin) args.push('--plugin-dir', plugin)
+  // Only with the plugin loaded: an `--agent` naming a type the session cannot
+  // resolve is an invocation error, and an invocation error reads as a model
+  // that failed rather than as a host that was misconfigured.
+  if (plugin && typeof request.type === 'string' && request.type.trim()) {
+    args.push('--agent', request.type.trim())
+  }
+  if (typeof model === 'string' && model) args.push('--model', model)
+  args.push('--permission-mode', permissionMode || DEFAULT_PERMISSION_MODE)
+  if (Array.isArray(request.tools) && request.tools.length) {
+    args.push('--allowedTools', request.tools.join(','))
+  }
+  return args
+}
+
+/**
+ * The prompt-cache lifetime tiers the vendor's usage envelope reports cache
+ * creation under, and the envelope field each one arrives in.
+ *
+ * Facts about the host's wire format, not Interlock thresholds, so they are
+ * named constants in the module that reads them — the convention every
+ * `INTERLOCK_*` reader above already follows.
+ *
+ * They are kept APART, never summed (design D7). A prefix written for five
+ * minutes and one written for an hour are different prices; a single total
+ * cannot be priced and the flattening cannot be undone by any later reader.
+ */
+export const CACHE_TIER_FIELDS = Object.freeze({
+  ephemeral_5m: 'ephemeral_5m_input_tokens',
+  ephemeral_1h: 'ephemeral_1h_input_tokens'
+})
+
+/** A finite non-negative count from the envelope, or `undefined` for a field it omitted. */
+function envelopeCount(value) {
+  return Number.isFinite(value) && value >= 0 ? value : undefined
+}
+
+/**
+ * The cache half of a usage envelope, or `null` where it carries none.
+ *
+ * `undefined` for an omitted field, NEVER `0`: a host that did not report a
+ * figure and a host that measured none are different facts, and substituting a
+ * zero would make the second out of the first everywhere downstream. A tier the
+ * envelope omits is absent; a tier it reports as zero is a measured zero.
+ */
+function readCacheUsage(usage) {
+  const read = envelopeCount(usage.cache_read_input_tokens)
+  const creation =
+    usage.cache_creation && typeof usage.cache_creation === 'object' ? usage.cache_creation : null
+  const write = {}
+  for (const [tier, field] of Object.entries(CACHE_TIER_FIELDS)) {
+    const value = creation ? envelopeCount(creation[field]) : undefined
+    if (value !== undefined) write[tier] = value
+  }
+  const hasWrite = Object.keys(write).length > 0
+  if (read === undefined && !hasWrite) return null
+  return {
+    ...(read === undefined ? {} : { cacheReadInputTokens: read }),
+    ...(hasWrite ? { cacheCreationInputTokens: write } : {})
+  }
+}
+
+/**
+ * The result and the usage out of the CLI's JSON envelope.
+ *
+ * `structured_output` is the whole result: the CLI validated it against the
+ * schema, so there is nothing to recover from prose the way the ACP adapter has
+ * to. An envelope without it is a spawn that produced no result — `null`, and
+ * the CLI decides what a null costs.
+ *
+ * An envelope that is PRESENT AND UNPARSEABLE is a host that did not report,
+ * not a host that reported nothing: both halves come back `null` and every
+ * downstream figure is absent rather than zero.
+ *
+ * @param {string} stdout
+ * @returns {{result: object|null, usage: object|null}}
+ */
+export function readClaudeEnvelope(stdout) {
+  let envelope
+  try {
+    envelope = JSON.parse(typeof stdout === 'string' ? stdout : '')
+  } catch {
+    return { result: null, usage: null }
+  }
+  if (!envelope || typeof envelope !== 'object') return { result: null, usage: null }
+  const structured = envelope.structured_output
+  const result =
+    structured && typeof structured === 'object' && !Array.isArray(structured) ? structured : null
+  const usage = envelope.usage && typeof envelope.usage === 'object' ? envelope.usage : null
+  if (!usage) return { result, usage: null }
+  const cache = readCacheUsage(usage)
+  return {
+    result,
+    usage: {
+      inputTokens: envelopeCount(usage.input_tokens),
+      outputTokens: envelopeCount(usage.output_tokens),
+      // Spread, so an envelope with no cache fields carries no cache keys at all
+      // — absent, which is what "this spawn was not measured for cache" means.
+      ...(cache || {})
+    }
+  }
+}
+
+/**
+ * Build a {@link import('../host.mjs').WorkflowHost} backed by `claude -p`.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.command]  defaults to `$INTERLOCK_CLAUDE_COMMAND` or `claude`
+ * @param {string} [opts.cwd]      repo root; a spawn's own `cwd` overrides it per lane
+ * @param {object} [opts.env]
+ * @param {number} [opts.timeoutMs]
+ * @param {(event: object) => void} [opts.onEvent]
+ */
+export function createClaudeHost({ command, cwd = process.cwd(), env = process.env, timeoutMs, onEvent } = {}) {
+  const source = env && typeof env === 'object' ? env : {}
+  const raw = (typeof command === 'string' && command.trim()) || source[CLAUDE_COMMAND_ENV] || 'claude'
+  const argv = String(raw).trim().split(/\s+/)
+  const bin = argv[0]
+  const fixedArgs = argv.slice(1)
+  const permissionMode = source[CLAUDE_PERMISSION_MODE_ENV] || DEFAULT_PERMISSION_MODE
+  const budget = Number.isInteger(timeoutMs)
+    ? timeoutMs
+    : Number.parseInt(source[CLAUDE_TIMEOUT_ENV] || '', 10) || DEFAULT_TIMEOUT_MS
+  // Parsed once, here: a malformed map fails host creation rather than a wave.
+  const modelMap = parseModelMap(source)
+  const plugin = pluginRoot()
+
+  const host = {
+    command: [bin, ...fixedArgs].join(' '),
+    // The only capability this adapter can observe about itself. Everything else
+    // is the registry's static declaration.
+    capabilities: plugin ? {} : { hooks: false },
+
+    async spawn(req) {
+      const request = req && typeof req === 'object' ? req : {}
+      const label = typeof request.label === 'string' ? request.label : 'agent'
+      const started = Date.now()
+      const routed = resolveModel('claude', request.model, modelMap, { modelSelect: 'flag' })
+      if (typeof request.model === 'string' && request.model && onEvent) {
+        onEvent({
+          type: 'model-routing',
+          label,
+          requested: request.model,
+          applied: routed.applied,
+          value: routed.value,
+          via: routed.applied ? 'flag' : null,
+          reason: routed.reason
+        })
+      }
+      if (!plugin && onEvent) {
+        onEvent({ type: 'agent-prefix-skipped', label, reason: 'this checkout is not the interlock plugin' })
+      }
+
+      const { code, stdout, stderr, timedOut } = await execCapture(
+        bin,
+        [...fixedArgs, ...claudeArgs(request, { model: routed.value, permissionMode, plugin })],
+        {
+          cwd: typeof request.cwd === 'string' && request.cwd ? request.cwd : cwd,
+          env: source,
+          input: request.prompt,
+          timeoutMs: budget
+        }
+      )
+
+      if (code !== 0) {
+        if (onEvent) {
+          onEvent({
+            type: 'spawn-failed',
+            label,
+            code,
+            timedOut,
+            error: stderr.trim().slice(-500) || `claude exited ${code}`
+          })
+        }
+        return null
+      }
+
+      const { result, usage } = readClaudeEnvelope(stdout)
+      if (onEvent) {
+        onEvent({ type: 'spawn-done', label, ms: Date.now() - started, parsed: Boolean(result), usage })
+      }
+      if (!result) return null
+      // Usage rides beside the result rather than inside it: the result's shape
+      // is the step's schema, and an extra field there would fail a strict
+      // consumer. `run close` reads this key by name (design D9).
+      return usage ? { ...result, usage } : result
+    },
+
+    mapPipeline,
+
+    runCli(argv2, opts = {}) {
+      return runCli(argv2, { cwd, env: source, ...opts })
+    }
+  }
+
+  return assertWorkflowHost(host, 'claude host')
+}

package/lib/host/codex.mjs

@@ -0,0 +1,231 @@
+// The `codex` host adapter (design D4).
+//
+// OpenAI's Codex CLI in its non-interactive mode. One `codex exec` per spawn,
+// prompt on stdin, result in a file the CLI writes.
+//
+// The contract, verified against `codex exec --help` on codex-cli 0.145.0:
+//
+//   --output-schema <FILE>        JSON Schema the final response must satisfy
+//   -o, --output-last-message <FILE>   where the final message is written
+//   --json                        events to stdout as JSONL
+//   -C, --cd <DIR>                the agent's working root
+//   -s, --sandbox <MODE>          read-only | workspace-write | danger-full-access
+//   -m, --model <MODEL>
+//   prompt on stdin (or `-`)
+//
+// One flag design D4 named does NOT exist on this version: `--ask-for-approval`
+// is rejected by `codex exec` with "unexpected argument". `exec` is the
+// non-interactive mode and never prompts, so the flag was redundant as well as
+// wrong; it is dropped and the finding is recorded in the change's design.md.
+// `--dangerously-bypass-approvals-and-sandbox` is deliberately NOT used in its
+// place — it removes the sandbox, and `workspace-write` is the posture a ship
+// lane wants.
+//
+// Two degradations this host carries, both declared and both bannered by the
+// runner rather than discovered later:
+//
+//   hooks: false   Codex has no equivalent of this repository's PreToolUse
+//                  guards, so nothing stops a repair step from weakening a test
+//                  except the CLI's own unit-suite shrink check.
+//   modelSelect: 'map-only'   the planner's slugs (`haiku`/`sonnet`/`opus`) mean
+//                  nothing here, so a spawn with no INTERLOCK_MODEL_MAP entry
+//                  runs on whatever the operator configured, and says so.
+
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { assertWorkflowHost, execCapture, mapPipeline, runCli } from '../host.mjs'
+import { parseModelMap, resolveModel } from './model-map.mjs'
+
+/** Override the binary, for a wrapper or a fixture. */
+export const CODEX_COMMAND_ENV = 'INTERLOCK_CODEX_COMMAND'
+
+/** Optional per-spawn wall clock, in ms. 0 disables it. */
+export const CODEX_TIMEOUT_ENV = 'INTERLOCK_CODEX_TIMEOUT_MS'
+
+/**
+ * The two variables whose ABSENCE means the run is spending a ChatGPT plan's
+ * device-auth session rather than an API key. Named here because the runner
+ * banners the condition and the docs explain it (design D8).
+ */
+export const CODEX_KEY_ENVS = Object.freeze(['CODEX_API_KEY', 'OPENAI_API_KEY'])
+
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000
+
+/** True when neither key is set, i.e. the run is on a ChatGPT login. */
+export function onChatGptPlan(env = {}) {
+  return CODEX_KEY_ENVS.every(name => !(env && typeof env[name] === 'string' && env[name].trim()))
+}
+
+/**
+ * The exact argv one spawn sends. One function, pinned by a test against the
+ * fixture, so a vendor flag change is one edit.
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd            the lane's worktree, or the repo root
+ * @param {string} opts.schemaPath     the `--output-schema` file
+ * @param {string} opts.outputPath     the `-o` file
+ * @param {string|null} opts.model     resolved model id, or null for unrouted
+ * @returns {string[]}
+ */
+export function codexArgs({ cwd, schemaPath, outputPath, model } = {}) {
+  const args = ['exec', '--json']
+  if (schemaPath) args.push('--output-schema', schemaPath)
+  args.push('-o', outputPath, '-C', cwd, '--sandbox', 'workspace-write')
+  if (typeof model === 'string' && model) args.push('--model', model)
+  return args
+}
+
+/**
+ * The last token count the JSONL event stream reported, in the receipt's units.
+ *
+ * Best-effort by construction: the event stream is a vendor surface with no
+ * stability promise, so an unrecognised stream yields `null` — unknown — rather
+ * than a zero that would read as a run that produced no tokens.
+ *
+ * @param {string} stdout the JSONL on stdout
+ * @returns {{inputTokens?: number, outputTokens?: number}|null}
+ */
+export function readCodexUsage(stdout) {
+  const lines = (typeof stdout === 'string' ? stdout : '').split('\n')
+  let latest = null
+  for (const line of lines) {
+    const text = line.trim()
+    if (!text || text[0] !== '{') continue
+    let event
+    try {
+      event = JSON.parse(text)
+    } catch {
+      continue
+    }
+    const found = findUsage(event, 0)
+    if (found) latest = found
+  }
+  return latest
+}
+
+/** The first `{input_tokens, output_tokens}`-shaped object anywhere in an event. */
+function findUsage(value, depth) {
+  if (!value || typeof value !== 'object' || depth > 6) return null
+  if (Number.isFinite(value.output_tokens) || Number.isFinite(value.input_tokens)) {
+    return {
+      inputTokens: Number.isFinite(value.input_tokens) ? value.input_tokens : undefined,
+      outputTokens: Number.isFinite(value.output_tokens) ? value.output_tokens : undefined
+    }
+  }
+  for (const nested of Object.values(value)) {
+    const found = findUsage(nested, depth + 1)
+    if (found) return found
+  }
+  return null
+}
+
+/**
+ * Build a {@link import('../host.mjs').WorkflowHost} backed by `codex exec`.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.command]  defaults to `$INTERLOCK_CODEX_COMMAND` or `codex`
+ * @param {string} [opts.cwd]
+ * @param {object} [opts.env]
+ * @param {number} [opts.timeoutMs]
+ * @param {(event: object) => void} [opts.onEvent]
+ */
+export function createCodexHost({ command, cwd = process.cwd(), env = process.env, timeoutMs, onEvent } = {}) {
+  const source = env && typeof env === 'object' ? env : {}
+  const raw = (typeof command === 'string' && command.trim()) || source[CODEX_COMMAND_ENV] || 'codex'
+  const argv = String(raw).trim().split(/\s+/)
+  const bin = argv[0]
+  const fixedArgs = argv.slice(1)
+  const budget = Number.isInteger(timeoutMs)
+    ? timeoutMs
+    : Number.parseInt(source[CODEX_TIMEOUT_ENV] || '', 10) || DEFAULT_TIMEOUT_MS
+  const modelMap = parseModelMap(source)
+
+  const host = {
+    command: [bin, ...fixedArgs].join(' '),
+    chatGptPlan: onChatGptPlan(source),
+
+    async spawn(req) {
+      const request = req && typeof req === 'object' ? req : {}
+      const label = typeof request.label === 'string' ? request.label : 'agent'
+      const started = Date.now()
+      const routed = resolveModel('codex', request.model, modelMap, { modelSelect: 'map-only' })
+      if (typeof request.model === 'string' && request.model && onEvent) {
+        onEvent({
+          type: 'model-routing',
+          label,
+          requested: request.model,
+          applied: routed.applied,
+          value: routed.value,
+          via: routed.applied ? 'flag' : null,
+          reason: routed.reason
+        })
+      }
+
+      const scratch = mkdtempSync(join(tmpdir(), 'interlock-codex-'))
+      const outputPath = join(scratch, 'last-message.json')
+      const schemaPath = request.schema ? join(scratch, 'schema.json') : null
+      try {
+        // Written rather than passed inline: `--output-schema` takes a path.
+        if (schemaPath) writeFileSync(schemaPath, JSON.stringify(request.schema))
+        const { code, stdout, stderr, timedOut } = await execCapture(
+          bin,
+          [
+            ...fixedArgs,
+            ...codexArgs({
+              cwd: typeof request.cwd === 'string' && request.cwd ? request.cwd : cwd,
+              schemaPath,
+              outputPath,
+              model: routed.value
+            })
+          ],
+          {
+            cwd: typeof request.cwd === 'string' && request.cwd ? request.cwd : cwd,
+            env: source,
+            input: request.prompt,
+            timeoutMs: budget
+          }
+        )
+
+        if (code !== 0) {
+          if (onEvent) {
+            onEvent({
+              type: 'spawn-failed',
+              label,
+              code,
+              timedOut,
+              // The stderr tail is the whole diagnostic on this host: a stale
+              // device-auth token surfaces here and nowhere else.
+              error: stderr.trim().slice(-500) || `codex exited ${code}`
+            })
+          }
+          return null
+        }
+
+        let result = null
+        try {
+          const parsed = JSON.parse(readFileSync(outputPath, 'utf8'))
+          if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) result = parsed
+        } catch {
+          result = null
+        }
+        const usage = readCodexUsage(stdout)
+        if (onEvent) {
+          onEvent({ type: 'spawn-done', label, ms: Date.now() - started, parsed: Boolean(result), usage })
+        }
+        if (!result) return null
+        return usage ? { ...result, usage } : result
+      } finally {
+        rmSync(scratch, { recursive: true, force: true })
+      }
+    },
+
+    mapPipeline,
+
+    runCli(argv2, opts = {}) {
+      return runCli(argv2, { cwd, env: source, ...opts })
+    }
+  }
+
+  return assertWorkflowHost(host, 'codex host')
+}

package/lib/host/model-map.mjs

@@ -0,0 +1,129 @@
+// One published model map, read once, for every host (design D6).
+//
+// The planner assigns a tier slug — `haiku`, `sonnet`, `opus` — and that slug is
+// a statement about how much judgement a lane needs, not about a vendor's
+// catalogue. Every host has to answer the same question from it: which model id
+// does this slug mean HERE. Four adapters answering it four ways is four places
+// for a tier ladder to quietly stop applying, and a run whose cost profile was
+// never applied looks exactly like one where it was.
+//
+// So the mapping is one environment variable, parsed once at startup, and the
+// resolution is one function whose answer carries its own reason:
+//
+//   INTERLOCK_MODEL_MAP={"codex":{"sonnet":"gpt-5-codex"},"qwen":{"opus":"qwen3-max"}}
+//
+// `INTERLOCK_ACP_MODEL_MAP` predates it (`close-acp-model-routing`) and is
+// folded in as the `acp` entry, so an operator who set it keeps working.
+//
+// Malformed is fatal at creation, never at wave three: a typo that surfaced
+// halfway through a run would have already spent the tier ladder it broke.
+
+/** The published map: host id → slug → that host's model id. */
+export const MODEL_MAP_ENV = 'INTERLOCK_MODEL_MAP'
+
+/** The ACP-only predecessor, folded in as the `acp` entry. */
+export const ACP_MODEL_MAP_ENV = 'INTERLOCK_ACP_MODEL_MAP'
+
+/**
+ * Parse one host's slug → value object, from an already-parsed JSON value.
+ *
+ * @param {unknown} value
+ * @param {string} where the variable path to name in an error
+ * @returns {Record<string, string>}
+ */
+function parseHostEntry(value, where) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${where} must be a JSON object of model slug to that host's model id`)
+  }
+  for (const [slug, model] of Object.entries(value)) {
+    if (typeof model !== 'string' || !model.trim()) {
+      throw new Error(`${where}.${slug} must be a non-empty string`)
+    }
+  }
+  return { ...value }
+}
+
+/**
+ * Parse {@link MODEL_MAP_ENV} (and the ACP alias) into a host → slug → value map.
+ *
+ * Throws on anything that is not a JSON object of objects of non-empty strings.
+ * The throw is the point: the runner parses this before its first step, so a
+ * typo fails the invocation rather than three waves in.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {Record<string, Record<string, string>>}
+ */
+export function parseModelMap(env = {}) {
+  const source = env && typeof env === 'object' ? env : {}
+  const out = {}
+
+  const raw = typeof source[MODEL_MAP_ENV] === 'string' ? source[MODEL_MAP_ENV].trim() : ''
+  if (raw) {
+    let parsed
+    try {
+      parsed = JSON.parse(raw)
+    } catch (err) {
+      throw new Error(`${MODEL_MAP_ENV} is not valid JSON: ${err.message}`)
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error(`${MODEL_MAP_ENV} must be a JSON object keyed by host id`)
+    }
+    for (const [hostId, entry] of Object.entries(parsed)) {
+      out[hostId] = parseHostEntry(entry, `${MODEL_MAP_ENV}.${hostId}`)
+    }
+  }
+
+  // The alias wins for `acp` only where the newer variable said nothing about
+  // that host: an operator mid-migration has both set, and silently discarding
+  // the one they most recently wrote is the confusing half of either order.
+  const legacy = typeof source[ACP_MODEL_MAP_ENV] === 'string' ? source[ACP_MODEL_MAP_ENV].trim() : ''
+  if (legacy) {
+    let parsed
+    try {
+      parsed = JSON.parse(legacy)
+    } catch (err) {
+      throw new Error(`${ACP_MODEL_MAP_ENV} is not valid JSON: ${err.message}`)
+    }
+    const entry = parseHostEntry(parsed, ACP_MODEL_MAP_ENV)
+    out.acp = { ...entry, ...(out.acp || {}) }
+  }
+
+  return out
+}
+
+/**
+ * What one host should do with one planner slug.
+ *
+ * Never guesses a nearest model and never substitutes a default: a wrong model
+ * that ran is invisible in a summary, and an unapplied one that was bannered is
+ * not. `applied: false` always carries the reason the runner prints.
+ *
+ * @param {string} hostId
+ * @param {string} [slug]                     the planner's model, e.g. `sonnet`
+ * @param {Record<string, Record<string, string>>} [map] {@link parseModelMap}'s output
+ * @param {{modelSelect?: string}} [capabilities]
+ * @returns {{value: string|null, applied: boolean, reason: string|null}}
+ */
+export function resolveModel(hostId, slug, map = {}, capabilities = {}) {
+  const wanted = typeof slug === 'string' ? slug.trim() : ''
+  if (!wanted) return { value: null, applied: false, reason: 'no model requested' }
+
+  const forHost = map && typeof map === 'object' ? map[hostId] : undefined
+  const mapped = forHost && typeof forHost === 'object' ? forHost[wanted] : undefined
+  if (typeof mapped === 'string' && mapped) return { value: mapped, applied: true, reason: null }
+
+  const kind = capabilities && typeof capabilities.modelSelect === 'string' ? capabilities.modelSelect : ''
+
+  // The host's own CLI accepts the slug (Claude's `--model haiku`), so an
+  // unmapped slug is routed rather than dropped.
+  if (kind === 'flag') return { value: wanted, applied: true, reason: null }
+
+  // The agent advertises its models and the adapter negotiates on the wire; the
+  // map only supplies a preference. Whether it landed is the adapter's to say,
+  // so nothing is claimed here.
+  if (kind === 'negotiated') {
+    return { value: null, applied: false, reason: 'negotiated with the agent at session creation' }
+  }
+
+  return { value: null, applied: false, reason: `no mapping for ${wanted}` }
+}