@renzrollon/interlock 1.1.1 → 1.2.0

package/lib/eval-history.mjs

@@ -39,6 +39,10 @@
 //
 // Written by `evals/ship/run.mjs`. Read by `lib/report.mjs` as a fourth corpus,
 // under exactly the rules the other three are read by.
+//
+// The cost-per-task sweep's record lives at the end of this module: a separate
+// file under the same directory, with its own schema, written by
+// `evals/ship/matrix.mjs` and read by nothing that promotes, gates or reports.
 
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync } from 'node:fs'
 import { join } from 'node:path'
@@ -302,3 +306,232 @@ export function readShipOutcomes(root) {
     return { ...empty, path, exists: true, reason: messageOf(err) }
   }
 }
+
+// --- the cost-per-task record (spec: evals/cost-per-task) -------------------
+//
+// A SEPARATE FILE AND A SEPARATE SCHEMA, deliberately. The outcome record above
+// holds one model constant across two arms; a cost-per-task row varies model and
+// effort on one arm. Appending one into the other would let a reader of
+// `ship-outcomes.jsonl` compare a model change as though it were a loop change,
+// so nothing below ever opens that file, and `appendShipOutcome` never sees a
+// cost-per-task row.
+//
+// The same three properties hold: fields are copied by name, the instrument
+// travels with the measurement, and a failed append comes back as
+// `written: false` for the sweep to exit non-zero on.
+
+/** The sweep's append-only log, beside the outcome record under `EVAL_HISTORY_DIR`. */
+export const COST_PER_TASK_FILE = 'cost-per-task.jsonl'
+
+/** Distinct from `SHIP_OUTCOME_SCHEMA`, so neither reader ever counts the other's row. */
+export const COST_PER_TASK_SCHEMA = 'interlock.cost-per-task/1'
+
+/** What a cell's graders concluded. A row with neither is refused: it is not a cell that ran. */
+export const JUDGE_RESULTS = Object.freeze(['pass', 'fail'])
+
+/**
+ * The procedure every row ran. Stamped by the writer, never copied: the sweep
+ * runs the control-arm procedure only, and a row must not be readable as a
+ * measurement of the ship loop (design D1).
+ */
+export const COST_PER_TASK_PROCEDURE = 'control'
+
+/**
+ * The prompt-cache lifetime tiers a cache-write count is kept under — the keys
+ * the eval agent's usage record and the price table's write multipliers use.
+ */
+const CACHE_WRITE_TIERS = Object.freeze(['ephemeral_5m', 'ephemeral_1h'])
+
+/**
+ * Every field a cost-per-task row carries, in the order it is written (design
+ * D4, plus the agent identity D3 requires and the procedure label). Nothing else
+ * reaches the file — no transcript, no prompt, no diff, however fat the input.
+ */
+export const COST_PER_TASK_FIELDS = Object.freeze([
+  'schema',
+  'ts',
+  'version',
+  'fixture',
+  'model',
+  'effort',
+  'procedure',
+  'evalAgent',
+  'judge',
+  'inputTokens',
+  'outputTokens',
+  'cacheReadInputTokens',
+  'cacheCreationInputTokens',
+  'usd',
+  'pricesId',
+  'usdReason',
+  'durationMs'
+])
+
+/** Absolute path of the cost-per-task record, from a repository root. */
+export function costPerTaskPath(root) {
+  return join(root, EVAL_HISTORY_DIR, COST_PER_TASK_FILE)
+}
+
+/**
+ * An identifier kept EXACTLY as given, or `null`.
+ *
+ * Unlike `id()`, whitespace is not collapsed: `claude-opus-5-5 ` with a trailing
+ * space is not the model `claude-opus-5-5`, and a writer that trimmed it would
+ * record a cell under a model it never called.
+ */
+function exactId(value, max = MAX_ID) {
+  if (typeof value !== 'string' || !value || value.length > max) return null
+  return /^\S+$/.test(value) ? value : null
+}
+
+/** A finite non-negative count, or `null` — a measured zero stays zero, an absence stays absent. */
+function count(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null
+}
+
+/**
+ * The cache-write tier object, copied tier by tier, or `null` where none was measured.
+ *
+ * Inside a present record a tier the record omits is zero and a tier it carries
+ * as a non-count is `null` — the rule the usage reader and the pricer already
+ * hold, so the row says what the price was computed from.
+ */
+function cacheWrite(value) {
+  if (!isObject(value)) return null
+  const write = {}
+  for (const tier of CACHE_WRITE_TIERS) {
+    write[tier] = tier in value ? count(value[tier]) : 0
+  }
+  return write
+}
+
+/**
+ * Append one cost-per-task row for a cell that ran.
+ *
+ * Never throws. A failure comes back as `{written: false, reason}`, and the
+ * sweep fails on it: the row is the only durable product of a metered cell.
+ *
+ * A previous append torn mid-line is healed at the seam by the same final-byte
+ * check the outcome record carries, so a torn line costs that line and never the
+ * row written after it.
+ *
+ * @param {string} root repository root; `evals/history/` is created beneath it
+ * @param {{
+ *   version?: string, fixture?: string, model?: string, effort?: string,
+ *   evalAgent?: string, judge?: 'pass'|'fail',
+ *   inputTokens?: number|null, outputTokens?: number|null,
+ *   cacheReadInputTokens?: number|null,
+ *   cacheCreationInputTokens?: Record<string, number|null>|null,
+ *   usd?: number|null, pricesId?: string|null, usdReason?: string|null,
+ *   durationMs?: number|null, now?: Date|string
+ * }} [input] anything not named here is ignored, however fat the object is
+ * @returns {{written: boolean, path: string|null, reason: string|null}}
+ */
+export function appendCostPerTask(root, input = {}) {
+  try {
+    if (typeof root !== 'string' || !root.trim()) {
+      return { written: false, path: null, reason: 'no root directory given' }
+    }
+    const source = isObject(input) ? input : {}
+
+    const fixture = id(source.fixture)
+    if (!fixture) return { written: false, path: null, reason: 'a fixture identity is required' }
+    const model = exactId(source.model)
+    if (!model) {
+      return { written: false, path: null, reason: 'an exact API model id is required (no whitespace)' }
+    }
+    const effort = exactId(source.effort, 16)
+    if (!effort) return { written: false, path: null, reason: 'an effort level is required' }
+    const judge = JUDGE_RESULTS.includes(source.judge) ? source.judge : null
+    if (!judge) {
+      // Not defaulted: a row is a cell that ran and was graded. A cell that did
+      // not run is reported by the sweep, never written here as a failure.
+      return { written: false, path: null, reason: `judge must be one of ${JUDGE_RESULTS.join(', ')}` }
+    }
+
+    const when = source.now instanceof Date ? source.now : new Date(source.now || Date.now())
+    const ts = Number.isNaN(when.getTime()) ? new Date().toISOString() : when.toISOString()
+
+    const usd = count(source.usd)
+    const payload = {
+      schema: COST_PER_TASK_SCHEMA,
+      ts,
+      version: id(source.version) || 'unknown',
+      fixture,
+      model,
+      effort,
+      procedure: COST_PER_TASK_PROCEDURE,
+      evalAgent: id(source.evalAgent) || 'unknown',
+      judge,
+      inputTokens: count(source.inputTokens),
+      outputTokens: count(source.outputTokens),
+      cacheReadInputTokens: count(source.cacheReadInputTokens),
+      cacheCreationInputTokens: cacheWrite(source.cacheCreationInputTokens),
+      usd,
+      pricesId: id(source.pricesId),
+      // A figure and its reason are exclusive: a priced row carries no reason,
+      // and an unpriced one always says why.
+      usdReason: usd === null ? reason(source.usdReason) || 'not priced' : null,
+      durationMs: count(source.durationMs)
+    }
+
+    const dir = join(root, EVAL_HISTORY_DIR)
+    mkdirSync(dir, { recursive: true })
+    const file = join(dir, COST_PER_TASK_FILE)
+    const prefix = existsSync(file) && !endsWithNewline(file) ? '\n' : ''
+    appendFileSync(file, `${prefix}${JSON.stringify(payload)}\n`)
+    return { written: true, path: file, reason: null }
+  } catch (err) {
+    return { written: false, path: null, reason: messageOf(err) }
+  }
+}
+
+/**
+ * Read the cost-per-task record back.
+ *
+ * Never throws. A torn line — the tail of a crashed append — is skipped and
+ * counted in `skipped`, never spliced into a record and never fatal to the rows
+ * around it. A line under another schema is counted as unrecognized.
+ *
+ * @param {string} root repository root
+ * @returns {{path: string|null, exists: boolean, records: object[],
+ *   unrecognized: Array<{line: number, schema: string|null}>,
+ *   skipped: Array<{line: number, reason: string}>, reason: string|null}}
+ */
+export function readCostPerTask(root) {
+  const empty = { path: null, exists: false, records: [], unrecognized: [], skipped: [], reason: null }
+  if (typeof root !== 'string' || !root.trim()) {
+    return { ...empty, reason: 'no root directory given' }
+  }
+  const path = costPerTaskPath(root)
+  try {
+    if (!existsSync(path)) return { ...empty, path }
+    const records = []
+    const unrecognized = []
+    const skipped = []
+    readFileSync(path, 'utf8')
+      .split('\n')
+      .forEach((line, i) => {
+        if (!line.trim()) return
+        let parsed
+        try {
+          parsed = JSON.parse(line)
+        } catch (err) {
+          skipped.push({ line: i + 1, reason: messageOf(err) })
+          return
+        }
+        if (!isObject(parsed)) {
+          skipped.push({ line: i + 1, reason: 'line is not a JSON object' })
+          return
+        }
+        if (parsed.schema !== COST_PER_TASK_SCHEMA) {
+          unrecognized.push({ line: i + 1, schema: typeof parsed.schema === 'string' ? parsed.schema : null })
+          return
+        }
+        records.push(parsed)
+      })
+    return { path, exists: true, records, unrecognized, skipped, reason: null }
+  } catch (err) {
+    return { ...empty, path, exists: true, reason: messageOf(err) }
+  }
+}

package/lib/evals-capture.mjs

@@ -227,11 +227,14 @@ export function buildSkeleton(root, opts = {}) {
     const runId = typeof opts.runId === 'string' ? opts.runId.trim() : ''
     const taskId = typeof opts.taskId === 'string' && opts.taskId.trim() ? opts.taskId.trim() : null
     if (!runId) return refuse('no run identifier was given')
+    // The trajectory is a corpus, read from the state home the CLI resolved
+    // (ship/state-home); the eval suite stays under the repository root.
+    const logRoot = typeof opts.stateHome === 'string' && opts.stateHome ? opts.stateHome : root
 
     // The published decision, reused rather than re-derived. Its problems are
     // reported verbatim: the caller learns why the run cannot be cited, not
     // merely that it cannot.
-    const reconstructable = checkRunLog(root, runId)
+    const reconstructable = checkRunLog(logRoot, runId)
     if (!reconstructable.ok) {
       return refuse(
         `run ${runId} is not reconstructable, so nothing may cite it`,
@@ -239,7 +242,7 @@ export function buildSkeleton(root, opts = {}) {
       )
     }
 
-    const read = readRunLog(root, runId)
+    const read = readRunLog(logRoot, runId)
     const cited = citedEvents(read.records, taskId)
     const seqs = cited.events.map(e => Number(e.seq)).filter(n => Number.isFinite(n))
     const first = seqs.length ? Math.min(...seqs) : 1

package/lib/graph/cli.mjs

@@ -14,6 +14,7 @@ import {
 } from './retrieve/docs-index.mjs';
 import { formatDocsResult, retrieveMarkdownSections } from './retrieve/markdown.mjs';
 import { graphPath, reportPath, resolveRoot } from './paths.mjs';
+import { resolveStateHome } from '../state-home.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -33,6 +34,9 @@ Usage:
   interlock-graph docs-index [root]         Deterministic docs/ + openspec/specs TOC → docs-index.json
   interlock-graph which                     Print CLI path (for skills)
 
+Query commands read <root>/.claude/graph/graph.json; in a linked worktree with no
+graph of its own they read the main checkout's and say so on stderr.
+
 Query options:
   --budget <n>     Token budget for output (default 1500; docs=800, context=2000)
   --depth <n>      Traversal depth (default 2)
@@ -57,6 +61,23 @@ Examples:
 `;
 }
 
+/**
+ * Where a query reads the graph from (ship/state-home): the root's own graph
+ * first; else, when the root is a linked worktree with none, the state home's —
+ * said once on stderr, because that graph was built before this worktree's
+ * edits. `build`, `update`, `report` and `docs-index` never come here: they
+ * write under the root they were given, and nothing is written into the home.
+ */
+function graphRootFor(root) {
+  if (fs.existsSync(graphPath(root))) return root;
+  const { home } = resolveStateHome(root);
+  if (home && path.resolve(home) !== path.resolve(root) && fs.existsSync(graphPath(home))) {
+    process.stderr.write(`GRAPH FROM MAIN CHECKOUT: ${graphPath(home)}\n`);
+    return home;
+  }
+  return root;
+}
+
 function parseArgs(argv) {
   const args = {
     _: [],
@@ -174,10 +195,11 @@ function main() {
       case 'query': {
         const q = args._.slice(1).join(' ');
         if (!q) throw new Error('query requires a search string');
-        const graph = loadGraph(root);
+        const from = graphRootFor(root);
+        const graph = loadGraph(from);
         const seeds = findSeedNodes(graph, q);
         if (!seeds.length) {
-          process.stdout.write(`No nodes matched: ${q}\n(graph: ${graphPath(root)})\n`);
+          process.stdout.write(`No nodes matched: ${q}\n(graph: ${graphPath(from)})\n`);
           process.exit(1);
         }
         process.stdout.write(
@@ -192,20 +214,20 @@ function main() {
       case 'consumers': {
         const target = args._.slice(1).join(' ');
         if (!target) throw new Error('consumers requires a symbol or file');
-        process.stdout.write(consumers(loadGraph(root), target));
+        process.stdout.write(consumers(loadGraph(graphRootFor(root)), target));
         break;
       }
       case 'path': {
         const a = args._[1];
         const b = args._[2];
         if (!a || !b) throw new Error('path requires two endpoints');
-        process.stdout.write(shortestPath(loadGraph(root), a, b));
+        process.stdout.write(shortestPath(loadGraph(graphRootFor(root)), a, b));
         break;
       }
       case 'explain': {
         const q = args._.slice(1).join(' ');
         if (!q) throw new Error('explain requires a node query');
-        process.stdout.write(explain(loadGraph(root), q));
+        process.stdout.write(explain(loadGraph(graphRootFor(root)), q));
         break;
       }
       case 'docs': {
@@ -227,6 +249,7 @@ function main() {
           throw new Error('context requires a query, --changed paths, or --commit-subject');
         }
         const result = retrieveContext(root, {
+          graphRoot: graphRootFor(root),
           query: q,
           changedFiles: args.changed,
           commitSubject: args.commitSubject,

package/lib/graph/retrieve/context.mjs

@@ -7,8 +7,13 @@ import { estimateTokens } from '../format.mjs';
 
 /**
  * Build a combined context bundle: structural graph subgraph + ranked doc sections.
+ *
+ * `graphRoot` is where the graph is read from, when it is not `root`: a linked
+ * worktree with no graph of its own reads the main checkout's (ship/state-home),
+ * while its documentation is still read from the worktree itself.
  */
 export function retrieveContext(root, {
+  graphRoot = root,
   query = '',
   changedFiles = [],
   commitSubject = '',
@@ -31,9 +36,9 @@ export function retrieveContext(root, {
   let graphText = '';
   let graphPresent = false;
 
-  if (fs.existsSync(graphPath(root))) {
+  if (fs.existsSync(graphPath(graphRoot))) {
     try {
-      const graph = loadGraph(root);
+      const graph = loadGraph(graphRoot);
       const seeds = findSeedNodes(graph, searchQuery);
       if (seeds.length > 0) {
         graphText = traverse(graph, seeds, { mode: 'bfs', depth: 2, budget: graphShare });
@@ -46,7 +51,7 @@ export function retrieveContext(root, {
     }
   } else {
     graphText =
-      `Structural: no graph at ${graphPath(root)} — run \`interlock-graph build .\` for import/symbol navigation.\n`;
+      `Structural: no graph at ${graphPath(graphRoot)} — run \`interlock-graph build .\` for import/symbol navigation.\n`;
   }
 
   parts.push('## Structural (graph)');

package/lib/host/acp.mjs

@@ -38,6 +38,7 @@ import { spawn as spawnProcess } from 'node:child_process'
 import { basename } from 'node:path'
 import { mapPipeline, parseAgentJson, runCli, assertWorkflowHost } from '../host.mjs'
 import { ACP_MODEL_MAP_ENV, parseModelMap } from './model-map.mjs'
+import { EFFORT_REASONS, findEffortOption, pickEffortValue } from './effort.mjs'
 
 /** Where the user names their ACP agent, e.g. `claude-code-acp` or `gemini --acp`. */
 export const ACP_COMMAND_ENV = 'INTERLOCK_ACP_COMMAND'
@@ -105,17 +106,48 @@ export function parseAcpCommand(raw) {
   return { command: tokens[0], args: tokens.slice(1) }
 }
 
+/** Basename of a command path, without a Windows `.exe` suffix. */
+function commandBasename(command) {
+  if (typeof command !== 'string' || !command) return ''
+  return basename(command).replace(/\.exe$/i, '')
+}
+
+/** The Claude Code CLI. It accepts `--agent` and loads this plugin's hooks. */
+const CLAUDE_BINARIES = new Set(['claude', 'claude-code'])
+
+/**
+ * ACP adapters that are Claude Code under another argv0. They spend the
+ * subscription and inherit `CLAUDE_CODE_EFFORT_LEVEL`. They do not accept
+ * `--agent`, and this plugin's hooks do not fire in them.
+ *
+ * A launcher whose own name is `npx` is not in this set: the command name does
+ * not say what it launches, and guessing from an argument would treat a
+ * coincidental token as Claude.
+ */
+const CLAUDE_ACP_WRAPPERS = new Set(['claude-agent-acp', 'claude-code-acp'])
+
 /**
  * True when `command` is a Claude Code CLI binary that accepts `--agent`.
- * Wrappers (`npx`, `claude-code-acp`) are other ACP agents and are left alone.
+ * Wrappers are other argv0s and are left alone.
  *
  * @param {string} command
  * @returns {boolean}
  */
 export function isClaudeCodeBinary(command) {
-  if (typeof command !== 'string' || !command) return false
-  const base = basename(command).replace(/\.exe$/i, '')
-  return base === 'claude' || base === 'claude-code'
+  return CLAUDE_BINARIES.has(commandBasename(command))
+}
+
+/**
+ * True when `command` is the Claude CLI or a known ACP adapter that wraps it.
+ * The subscription and effort-override banners read this. `--agent` and hooks
+ * stay on {@link isClaudeCodeBinary}.
+ *
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function isClaudeBackedCommand(command) {
+  const base = commandBasename(command)
+  return CLAUDE_BINARIES.has(base) || CLAUDE_ACP_WRAPPERS.has(base)
 }
 
 /**
@@ -232,7 +264,7 @@ export function pickModelValue(slug, option, map = {}) {
  * process would not start, the handshake failed, the timeout fired), which the
  * caller turns into a `null` spawn result exactly as the workflow runtime does.
  */
-async function promptOnce({ command, args, cwd, env, prompt, meta, model, modelMap, timeoutMs, onEvent }) {
+async function promptOnce({ command, args, cwd, env, prompt, meta, model, modelMap, effort, timeoutMs, onEvent }) {
   const child = spawnProcess(command, args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] })
 
   let nextId = 0
@@ -375,6 +407,9 @@ async function promptOnce({ command, args, cwd, env, prompt, meta, model, modelM
    *
    * @returns {Promise<{ applied: boolean, via: string | null, value: string | null, reason: string | null }>}
    */
+  // The config options the agent returned most recently; effort reads these.
+  let latestOptions = null
+
   const negotiateModel = async (sessionId, session) => {
     const option = findModelOption(session && session.configOptions)
 
@@ -394,7 +429,10 @@ async function promptOnce({ command, args, cwd, env, prompt, meta, model, modelM
 
     const configId = typeof option.id === 'string' && option.id ? option.id : 'model'
     try {
-      await request('session/set_config_option', { sessionId, configId, value })
+      const reply = await request('session/set_config_option', { sessionId, configId, value })
+      // The reply carries the full option list, and the levels a session offers
+      // depend on its model, so effort is read from this and not from session/new.
+      if (reply && Array.isArray(reply.configOptions)) latestOptions = reply.configOptions
       return { applied: true, via: 'set_config_option', value, reason: null }
     } catch {
       try {
@@ -411,6 +449,25 @@ async function promptOnce({ command, args, cwd, env, prompt, meta, model, modelM
     }
   }
 
+  /**
+   * Apply the spawn's effort through the agent's own effort option, or say why
+   * not. Never throws: the prompt runs either way. Exact value match only, and
+   * the call goes under the option's own id.
+   */
+  const negotiateEffort = async sessionId => {
+    const option = findEffortOption(latestOptions)
+    const { value, reason } = pickEffortValue(effort, option)
+    if (!value) return { applied: false, via: null, value: null, reason }
+    const configId = typeof option.id === 'string' && option.id ? option.id : 'effort'
+    try {
+      const reply = await request('session/set_config_option', { sessionId, configId, value })
+      if (reply && Array.isArray(reply.configOptions)) latestOptions = reply.configOptions
+      return { applied: true, via: 'set_config_option', value, reason: null }
+    } catch {
+      return { applied: false, via: null, value: null, reason: EFFORT_REASONS.rejected }
+    }
+  }
+
   const turn = async () => {
     const initialized = await request('initialize', {
       protocolVersion: ACP_PROTOCOL_VERSION,
@@ -426,11 +483,16 @@ async function promptOnce({ command, args, cwd, env, prompt, meta, model, modelM
     const sessionId = session && session.sessionId
     if (!sessionId) throw new Error('ACP session/new returned no sessionId')
     emit({ type: 'session', sessionId })
+    latestOptions = session.configOptions
 
     if (typeof model === 'string' && model) {
       emit({ type: 'model-routing', requested: model, ...(await negotiateModel(sessionId, session)) })
     }
 
+    if (typeof effort === 'string' && effort.trim()) {
+      emit({ type: 'effort-routing', requested: effort.trim(), ...(await negotiateEffort(sessionId)) })
+    }
+
     const result = await request('session/prompt', {
       sessionId,
       prompt: [{ type: 'text', text: prompt }],
@@ -480,14 +542,14 @@ export function createAcpHost({ command, cwd = process.cwd(), env = process.env,
   const host = {
     command: [parsed.command, ...parsed.args].join(' '),
 
-    // What this adapter can observe about itself that the registry's static
-    // declaration cannot: an ACP command that IS the Claude binary means the
-    // plugin's hooks fire and the run is spending a Claude subscription through
-    // the programmatic path. Declaring `local`/`false` there would suppress the
-    // two banners that matter most on that path (design D8).
-    capabilities: isClaudeCodeBinary(parsed.command)
-      ? { hooks: true, billing: 'claude-subscription-programmatic' }
-      : {},
+    // Hooks fire only in the Claude binary. A known wrapper still spends the
+    // subscription, so billing is recorded for both; leaving a wrapper at
+    // `local` would let the receipt contradict SUBSCRIPTION PATH. Hooks stay
+    // false on a wrapper, so HOOKS NOT IN FORCE still prints.
+    capabilities: {
+      ...(isClaudeBackedCommand(parsed.command) ? { billing: 'claude-subscription-programmatic' } : {}),
+      ...(isClaudeCodeBinary(parsed.command) ? { hooks: true } : {})
+    },
 
     // The planner's tier ladder — the haiku pings, the opus clamp — is applied
     // per session where the agent advertises a model option, and per spawn the
@@ -518,6 +580,7 @@ export function createAcpHost({ command, cwd = process.cwd(), env = process.env,
             : undefined,
           model: request.model,
           modelMap,
+          effort: request.effort,
           timeoutMs: budget,
           onEvent: event => onEvent && onEvent({ label, ...event })
         })