copperhead 0.3.0 → 0.4.0

package/src/agent/render.ts

@@ -0,0 +1,194 @@
+/**
+ * Live progress rendering for agent-loop runs (design D7). Two modes chosen
+ * once at startup: interactive (TTY, no --json/--plain) pins a status line to
+ * the bottom of the terminal and redraws it in place; plain emits line-oriented
+ * output with zero ANSI escapes — the mode CI, pipes, and tests see.
+ */
+
+export interface ProgressRenderer {
+  log(line: string): void;
+  /** Called at the start of each turn with cumulative token totals so far. */
+  turnStart(turn: number, maxTurns: number, tokensIn: number, tokensOut: number): void;
+  toolResult(name: string, firstLine: string): void;
+  /** Busy text while a provider call is in flight; null when idle. */
+  status(text: string | null): void;
+  /** Final outcome line; replaces the status line in interactive mode. */
+  finish(line: string): void;
+}
+
+/** Compact token count: 850 -> "850", 12300 -> "12.3k". */
+export function fmtTokens(n: number): string {
+  return n < 1000 ? String(n) : `${(n / 1000).toFixed(1)}k`;
+}
+
+/** Compact duration: 42s, 1m32s, 1h04m. */
+export function fmtDuration(ms: number): string {
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m${String(s % 60).padStart(2, '0')}s`;
+  return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, '0')}m`;
+}
+
+export function turnMarker(turn: number, maxTurns: number, tokensIn: number, tokensOut: number): string {
+  return `[turn ${turn}/${maxTurns} · ${fmtTokens(tokensIn)} in / ${fmtTokens(tokensOut)} out]`;
+}
+
+/** Wrap a bare log function into the plain (non-interactive) renderer. */
+export function plainRenderer(log: (line: string) => void): ProgressRenderer {
+  return {
+    log,
+    turnStart: (turn, maxTurns, tokensIn, tokensOut) => log(turnMarker(turn, maxTurns, tokensIn, tokensOut)),
+    toolResult: (name, firstLine) => log(`  [${name}] ${firstLine}`),
+    status: () => {},
+    finish: (line) => log(line),
+  };
+}
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const CLEAR_LINE = '\r\x1b[2K';
+
+/** Minimal writable surface so tests can drive a fake TTY. */
+export interface TtyLike {
+  write(chunk: string): unknown;
+  columns?: number;
+}
+
+/**
+ * The interactive renderer. Everything printed goes above the status line
+ * (clear -> print -> redraw) so the scrollback stays a complete log; only the
+ * status line itself is ever redrawn in place (AC-8.8).
+ */
+export class InteractiveRenderer implements ProgressRenderer {
+  private readonly out: TtyLike;
+  private startMs = Date.now();
+  private turn = 0;
+  private maxTurns = 0;
+  private tokensIn = 0;
+  private tokensOut = 0;
+  private busy: string | null = null;
+  private frame = 0;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private statusShown = false;
+  /**
+   * True between runs: no status line is owned and log lines pass straight
+   * through. finish() suspends rather than destroys, because a multi-stage
+   * `create` pipeline reuses one renderer across its stages; the next
+   * turnStart() re-arms it.
+   */
+  private idle = true;
+  private readonly cleanup = (): void => this.teardown();
+  private readonly onSigint = (): void => {
+    this.teardown();
+    process.exit(130);
+  };
+
+  constructor(out: TtyLike = process.stdout) {
+    this.out = out;
+    process.on('exit', this.cleanup);
+    process.on('SIGINT', this.onSigint);
+  }
+
+  private statusText(): string {
+    const parts = [
+      `turn ${this.turn}/${this.maxTurns}`,
+      `${fmtTokens(this.tokensIn)} in / ${fmtTokens(this.tokensOut)} out`,
+      fmtDuration(Date.now() - this.startMs),
+    ];
+    if (this.busy) parts.push(this.busy);
+    const spinner = this.busy ? FRAMES[this.frame % FRAMES.length] : '·';
+    const line = `${spinner} ${parts.join(' · ')}`;
+    const width = this.out.columns ?? 80;
+    return line.length > width ? line.slice(0, width - 1) : line;
+  }
+
+  private redraw(): void {
+    if (this.idle) return;
+    if (!this.statusShown) {
+      this.out.write(HIDE_CURSOR);
+      this.statusShown = true;
+    }
+    this.out.write(CLEAR_LINE + this.statusText());
+  }
+
+  private ensureTimer(): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      this.frame++;
+      this.redraw();
+    }, 80);
+    this.timer.unref?.();
+  }
+
+  /** Print above the status line: clear it, write, redraw it. */
+  log(line: string): void {
+    if (this.statusShown) this.out.write(CLEAR_LINE);
+    this.out.write(line + '\n');
+    this.redraw();
+  }
+
+  turnStart(turn: number, maxTurns: number, tokensIn: number, tokensOut: number): void {
+    if (this.idle) {
+      this.idle = false;
+      this.startMs = Date.now(); // elapsed time is per run, not per renderer
+    }
+    this.turn = turn;
+    this.maxTurns = maxTurns;
+    this.tokensIn = tokensIn;
+    this.tokensOut = tokensOut;
+    this.ensureTimer();
+    this.redraw();
+  }
+
+  toolResult(name: string, firstLine: string): void {
+    this.log(`  [${name}] ${firstLine}`);
+  }
+
+  status(text: string | null): void {
+    this.busy = text;
+    if (text && !this.idle) this.ensureTimer();
+    this.redraw();
+  }
+
+  finish(line: string): void {
+    if (this.statusShown) this.out.write(CLEAR_LINE);
+    this.out.write(line + '\n');
+    this.suspend();
+  }
+
+  /** Release the status line (stop the spinner, restore the cursor) but stay usable. */
+  private suspend(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.statusShown) {
+      this.out.write(CLEAR_LINE + SHOW_CURSOR);
+      this.statusShown = false;
+    }
+    this.busy = null;
+    this.frame = 0;
+    this.idle = true;
+  }
+
+  /** Process is going away (exit/SIGINT): suspend and drop the listeners. */
+  private teardown(): void {
+    this.suspend();
+    process.removeListener('exit', this.cleanup);
+    process.removeListener('SIGINT', this.onSigint);
+  }
+}
+
+/**
+ * Pick the renderer for a CLI invocation: interactive only on a real TTY with
+ * neither --json nor --plain (AC-8.8/8.9); plain mode is the safe fallback.
+ * Under --json, progress goes to stderr so stdout stays machine-parseable
+ * (AC-2.4): the only thing a --json invocation writes to stdout is its JSON.
+ */
+export function makeRenderer(opts: { json: boolean; plain: boolean }): ProgressRenderer {
+  if (opts.json) return plainRenderer((line) => console.error(line));
+  if (!opts.plain && process.stdout.isTTY) return new InteractiveRenderer();
+  return plainRenderer((line) => console.log(line));
+}

package/src/agent/runmeta.ts

@@ -0,0 +1,198 @@
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { readFile, readdir } from 'node:fs/promises';
+import { loadConstraints } from '../memory/constraints.js';
+import { kicadCliVersion } from '../kicad/cli.js';
+import { branchName, headCommit, uncommittedCount } from '../util/git.js';
+import type { CopperheadConfig, ModelSource } from '../config.js';
+
+/** Caller-supplied run identity: facts the loop cannot probe for itself. */
+export interface RunMetaInput {
+  command?: 'do' | 'create' | 'sync';
+  modelSource?: ModelSource;
+  version?: string;
+  kicadCliVersion?: string;
+  stage?: { name: string; index: number; total: number };
+  brief?: { path: string; sha256: string };
+}
+
+/**
+ * Everything a run needs to be self-describing (AC-8.1). Collected once,
+ * rendered onto three surfaces: run-start event, summary.md ## Environment,
+ * and the live CLI header. Probe failures are nulls, never errors (AC-8.3).
+ */
+export interface RunMeta {
+  request: string;
+  model: string;
+  provider: string;
+  modelSource: ModelSource | null;
+  runId: string;
+  startedAt: string;
+  command: 'do' | 'create' | 'sync' | null;
+  interactive: boolean;
+  stage: { name: string; index: number; total: number } | null;
+  brief: { path: string; sha256: string } | null;
+  versions: {
+    copperhead: string | null;
+    installPath: string | null;
+    kicadCli: string | null;
+    node: string;
+    platform: string;
+  };
+  config: {
+    schematic: string | null;
+    board: string | null;
+    docs: string;
+    maxTurns: number;
+    maxRepairCycles: number;
+    budgets: Record<string, number>;
+  };
+  git: {
+    commit: string | null;
+    branch: string | null;
+    dirty: boolean | null;
+    uncommittedFiles: number | null;
+    preCommitHookInstalled: boolean | null;
+  };
+  openConstraints: number | null;
+  priorRuns: number | null;
+}
+
+/** A metadata probe must never fail the run it describes (design D4). */
+async function probe<T>(fn: () => Promise<T> | T): Promise<T | null> {
+  try {
+    return await fn();
+  } catch {
+    return null;
+  }
+}
+
+function packageRoot(): string {
+  // src/agent/ and dist/agent/ both sit two levels below the package root.
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+function ownVersion(): string {
+  const { version } = createRequire(import.meta.url)('../../package.json') as { version: string };
+  return version;
+}
+
+export interface CollectRunMetaOptions {
+  repoRoot: string;
+  config: CopperheadConfig;
+  /** Effective turn budget for this run (flag override already applied). */
+  maxTurns: number;
+  runId: string;
+  request: string;
+  model: string;
+  provider: string;
+  interactive: boolean;
+  input?: RunMetaInput | undefined;
+}
+
+export async function collectRunMeta(opts: CollectRunMetaOptions): Promise<RunMeta> {
+  const { repoRoot, config, input } = opts;
+  const [copperhead, kicadCli, commit, branch, uncommitted, hook, openConstraints, priorRuns] = await Promise.all([
+    probe(() => input?.version ?? ownVersion()),
+    probe(() => input?.kicadCliVersion ?? kicadCliVersion()),
+    probe(() => headCommit(repoRoot)),
+    probe(() => branchName(repoRoot)),
+    probe(() => uncommittedCount(repoRoot)),
+    probe(async () => {
+      const hookText = await readFile(path.join(repoRoot, '.git', 'hooks', 'pre-commit'), 'utf8');
+      return hookText.includes('copperhead');
+    }).then((v) => v ?? false),
+    probe(async () => Object.keys(await loadConstraints(repoRoot)).length),
+    probe(async () => {
+      const entries = await readdir(path.join(repoRoot, '.copperhead', 'runs'));
+      return entries.filter((e) => e !== opts.runId).length;
+    }).then((v) => v ?? 0),
+  ]);
+
+  return {
+    request: opts.request,
+    model: opts.model,
+    provider: opts.provider,
+    modelSource: input?.modelSource ?? null,
+    runId: opts.runId,
+    startedAt: new Date().toISOString(),
+    command: input?.command ?? null,
+    interactive: opts.interactive,
+    stage: input?.stage ?? null,
+    brief: input?.brief ?? null,
+    versions: {
+      copperhead,
+      installPath: await probe(packageRoot),
+      kicadCli,
+      node: process.version,
+      platform: `${process.platform}-${process.arch}`,
+    },
+    config: {
+      schematic: config.schematic,
+      board: config.board,
+      docs: config.docs,
+      maxTurns: opts.maxTurns,
+      maxRepairCycles: config.maxRepairCycles,
+      budgets: config.budgets,
+    },
+    git: {
+      commit,
+      branch,
+      dirty: uncommitted === null ? null : uncommitted > 0,
+      uncommittedFiles: uncommitted,
+      preCommitHookInstalled: hook,
+    },
+    openConstraints,
+    priorRuns,
+  };
+}
+
+const unk = (v: string | null | undefined): string => v ?? 'unknown';
+
+/** ≤ 2 lines, printed before the first turn (AC-8.4). */
+export function renderCliHeader(meta: RunMeta): string[] {
+  const v = meta.versions;
+  const line1 = [
+    `copperhead v${unk(v.copperhead)}${v.installPath ? ` (${v.installPath})` : ''}`,
+    `kicad-cli ${unk(v.kicadCli)}`,
+    `node ${v.node}`,
+    v.platform,
+  ].join(' · ');
+
+  const repoState =
+    meta.git.dirty === null
+      ? 'unknown'
+      : meta.git.dirty
+        ? `dirty(${meta.git.uncommittedFiles})`
+        : 'clean';
+  const line2 = [
+    `run ${meta.runId}`,
+    unk(meta.command),
+    ...(meta.stage ? [`stage ${meta.stage.name} (${meta.stage.index}/${meta.stage.total})`] : []),
+    `model ${meta.model} (${meta.provider}, via ${unk(meta.modelSource)})`,
+    `turns ≤${meta.config.maxTurns}`,
+    `repo ${unk(meta.git.branch)}@${meta.git.commit?.slice(0, 7) ?? 'unknown'} ${repoState}`,
+  ].join(' · ');
+  return [line1, line2];
+}
+
+/** The `## Environment` section of summary.md; values mirror the run-start event (AC-8.4). */
+export function renderEnvironmentSection(meta: RunMeta): string[] {
+  const v = meta.versions;
+  const c = meta.config;
+  const g = meta.git;
+  return [
+    `## Environment`,
+    ``,
+    `- **Run:** ${meta.runId} · ${unk(meta.command)} · started ${meta.startedAt} · ${meta.interactive ? 'interactive' : 'autonomous'}`,
+    ...(meta.stage ? [`- **Stage:** ${meta.stage.name} (${meta.stage.index}/${meta.stage.total})`] : []),
+    ...(meta.brief ? [`- **Brief:** ${meta.brief.path} (sha256 ${meta.brief.sha256.slice(0, 12)}…)`] : []),
+    `- **Model:** ${meta.model} (${meta.provider}, via ${unk(meta.modelSource)})`,
+    `- **copperhead:** v${unk(v.copperhead)}${v.installPath ? ` at ${v.installPath}` : ''}`,
+    `- **Tooling:** kicad-cli ${unk(v.kicadCli)} · node ${v.node} · ${v.platform}`,
+    `- **Config:** schematic ${c.schematic ?? 'null'} · board ${c.board ?? 'null'} · docs ${c.docs} · maxTurns ${c.maxTurns} · maxRepairCycles ${c.maxRepairCycles} · budgets ${JSON.stringify(c.budgets)}`,
+    `- **Repo:** ${unk(g.branch)}@${g.commit ?? 'unknown'} · ${g.dirty === null ? 'unknown' : g.dirty ? `dirty (${g.uncommittedFiles} uncommitted)` : 'clean'} · pre-commit hook ${g.preCommitHookInstalled === null ? 'unknown' : g.preCommitHookInstalled ? 'installed' : 'absent'}`,
+    `- **Memory:** ${meta.openConstraints ?? 'unknown'} open constraint(s) · ${meta.priorRuns ?? 'unknown'} prior run(s)`,
+  ];
+}

package/src/agent/tools.ts

@@ -1,13 +1,13 @@
 import path from 'node:path';
-import { writeFile, mkdir, appendFile } from 'node:fs/promises';
+import { writeFile, mkdir, appendFile, readFile } from 'node:fs/promises';
 import type { ToolSchema } from './types.js';
 import { toolReadFile, toolWriteFile, toolEditFile, toolSearch } from './filetools.js';
 import { resolveInRepo, isKicadFile } from '../util/paths.js';
-import { runErc, runDrc, exportSvg, exportFab } from '../kicad/cli.js';
+import { runErc, runDrc, exportSvg, exportFab, kicadLoadError, isProbeableKicadFile } from '../kicad/cli.js';
 import { formatViolations, type CheckReport } from '../kicad/report.js';
 import { listSymbols, listNets } from '../kicad/sexp.js';
 import { checkDrift } from '../memory/drift.js';
-import { saveConstraint } from '../memory/constraints.js';
+import { saveConstraint, classifyAffectsTarget, affectsTargetExists } from '../memory/constraints.js';
 import { openspecValidate } from '../openspec/cli.js';
 import { existsSync } from 'node:fs';
 import type { CopperheadConfig } from '../config.js';
@@ -99,7 +99,11 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: false,
     handler: async (ctx, args) => {
-      const matches = await toolSearch(ctx.repoRoot, str(args, 'pattern'), args.glob as string | undefined);
+      const pattern = args.pattern;
+      if (typeof pattern !== 'string' || pattern.trim() === '') {
+        return 'error: search requires a non-empty regex in "pattern" (narrow by file with "glob", e.g. {"pattern": "GPIO", "glob": "**/*.md"}); to list files, use a broad pattern like "." with a glob';
+      }
+      const matches = await toolSearch(ctx.repoRoot, pattern, args.glob as string | undefined);
       if (!matches.length) return 'no matches';
       return matches.map((m) => `${m.file}:${m.line}: ${m.text}`).join('\n');
     },
@@ -213,6 +217,14 @@ export const TOOLS: ToolDef[] = [
     requiresUnlock: true,
     handler: async (ctx, args) => {
       const rel = str(args, 'path');
+      const abs = resolveInRepo(ctx.repoRoot, rel);
+      // Text edits can corrupt an s-expression file in ways the editor cannot
+      // see; a corrupted file then fails every later ERC/DRC with an opaque
+      // error. Validate loadability with KiCad itself and roll the edit back
+      // rather than letting the file drift unusable. Only schematics and
+      // boards are probeable; .kicad_pro/.kicad_sym/.kicad_mod edits must not
+      // be probed (a sch/pcb probe rejects them wholesale).
+      const before = isProbeableKicadFile(rel) ? await readFile(abs, 'utf8') : null;
       const res = await toolEditFile(
         ctx.repoRoot,
         rel,
@@ -220,6 +232,23 @@ export const TOOLS: ToolDef[] = [
         args.new_string as string,
         args.replace_all === true,
       );
+      if (before !== null) {
+        const loadErr = await kicadLoadError(abs);
+        if (loadErr) {
+          const after = await readFile(abs, 'utf8');
+          await writeFile(abs, before, 'utf8');
+          if (await kicadLoadError(abs)) {
+            // The file was already unloadable before this edit. Reverting
+            // would deadlock incremental repair (every partial fix undone
+            // unless one edit fixes the whole file), so keep the edit and
+            // keep the pressure on with the probe output.
+            await writeFile(abs, after, 'utf8');
+            markTouched(ctx, rel);
+            return `${res}\nnote: ${rel} was already unloadable before this edit, so the edit is KEPT. Keep repairing until it loads. kicad-cli says:\n${loadErr}`;
+          }
+          return `edit REVERTED: it would make ${rel} unloadable in KiCad. kicad-cli says:\n${loadErr}\nRe-read the surrounding file text and make a smaller, syntactically complete edit.`;
+        }
+      }
       markTouched(ctx, rel);
       return res;
     },
@@ -250,7 +279,8 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: false,
     handler: async (ctx) => {
-      if (!ctx.config.schematic) return 'no schematic configured';
+      if (!ctx.config.schematic)
+        return 'no schematic configured; ERC does not apply yet — skip it until a schematic exists and is set in .copperhead/config.json';
       const report = await runErc(path.join(ctx.repoRoot, ctx.config.schematic));
       ctx.lastErc = report;
       if (report.ok) ctx.ledger.clear('erc');
@@ -266,7 +296,8 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: false,
     handler: async (ctx) => {
-      if (!ctx.config.board) return 'no board configured';
+      if (!ctx.config.board)
+        return 'no board configured; DRC does not apply yet — skip it until a board exists and is set in .copperhead/config.json';
       const report = await runDrc(path.join(ctx.repoRoot, ctx.config.board));
       ctx.lastDrc = report;
       if (report.ok) ctx.ledger.clear('drc');
@@ -325,7 +356,16 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: false,
     handler: async (ctx) => {
-      if (!ctx.config.schematic) return 'no schematic configured';
+      // No schematic yet means there is nothing for the docs to drift against,
+      // so the obligation is vacuously satisfied and must be cleared. Returning
+      // without clearing deadlocks every docs-only stage of the create pipeline
+      // (spec-seed, architecture, part-selection all run before the schematic
+      // exists): a doc edit opens the drift obligation, this is the only tool
+      // that clears it, and finish refuses while any obligation is open.
+      if (!ctx.config.schematic) {
+        ctx.ledger.clear('drift');
+        return 'no schematic configured; drift vacuously clean';
+      }
       const mismatches = await checkDrift(ctx.repoRoot, ctx.config.docs, ctx.config.schematic);
       if (!mismatches.length) {
         ctx.ledger.clear('drift');
@@ -357,6 +397,19 @@ export const TOOLS: ToolDef[] = [
     handler: async (ctx, args) => {
       const key = str(args, 'key');
       const affects = (args.affects as string[]) ?? [];
+      // An affects item whose target artifact is not built yet (no schematic or
+      // board configured, no BOM.md) has nothing to revisit; opening an
+      // obligation now only forces a ceremonial "not yet created" resolution.
+      // Defer it in the registry instead — reopenDeferredAffects re-opens it at
+      // the start of the first run where the artifact exists, which is when the
+      // revisit actually means something.
+      const deferred: string[] = [];
+      const openNow: string[] = [];
+      for (const item of affects) {
+        const target = classifyAffectsTarget(item);
+        if (target && !affectsTargetExists(target, ctx.repoRoot, ctx.config)) deferred.push(item);
+        else openNow.push(item);
+      }
       await saveConstraint(ctx.repoRoot, key, {
         ...(args.min !== undefined ? { min: args.min as number } : {}),
         ...(args.max !== undefined ? { max: args.max as number } : {}),
@@ -364,33 +417,84 @@ export const TOOLS: ToolDef[] = [
         ...(args.value !== undefined ? { value: args.value as string } : {}),
         source: str(args, 'source'),
         affects,
+        ...(deferred.length ? { deferred } : {}),
       });
-      ctx.ledger.onConstraintChange(key, affects);
+      ctx.ledger.onConstraintChange(key, openNow);
       ctx.ledger.clear('constraint-dual-write', key);
-      return `constraint ${key} recorded; revisit obligations opened for: ${affects.join(', ') || '(none)'}`;
+      const parts = [`constraint ${key} recorded`];
+      parts.push(`revisit obligations opened for: ${openNow.join(', ') || '(none)'}`);
+      if (deferred.length) {
+        parts.push(
+          `deferred until the target artifact exists (no resolve_affected needed now): ${deferred.join(', ')}`,
+        );
+      }
+      return parts.join('; ');
     },
   },
   {
     schema: {
       name: 'resolve_affected',
       description:
-        'Explicitly resolve an affects-revisit obligation: state whether the affected item changed or why no change is needed.',
+        'Explicitly resolve affects-revisit obligations: state whether each affected item changed or why no change is needed. Pass resolutions[] to clear many in one call, or the single constraint_key/item/resolution form.',
       parameters: {
         type: 'object',
         properties: {
           constraint_key: { type: 'string' },
           item: { type: 'string' },
           resolution: { type: 'string', description: '"changed: ..." or "no change needed: <reason>"' },
+          resolutions: {
+            type: 'array',
+            description: 'batch form: resolve many obligations in one call',
+            items: {
+              type: 'object',
+              properties: {
+                constraint_key: { type: 'string' },
+                item: { type: 'string' },
+                resolution: { type: 'string' },
+              },
+              required: ['constraint_key', 'item', 'resolution'],
+            },
+          },
         },
-        required: ['constraint_key', 'item', 'resolution'],
+        required: [],
       },
     },
     requiresUnlock: true,
     handler: async (ctx, args) => {
-      const detail = `${str(args, 'constraint_key')} affects ${str(args, 'item')}`;
-      ctx.ledger.clear('affects-revisit', detail);
-      ctx.decisions.push(`[affects] ${detail}: ${str(args, 'resolution')}`);
-      return `resolved: ${detail}`;
+      // An item that matches nothing must not read as success: the model would
+      // move on believing the obligation closed, and only find out at finish.
+      const resolveOne = (constraintKey: string, item: string, resolution: string): string => {
+        const detail = `${constraintKey} affects ${item}`;
+        if (!ctx.ledger.clear('affects-revisit', detail)) {
+          const open = ctx.ledger.openOfKind('affects-revisit');
+          if (!open.length) return `error: no open affects-revisit obligation matches "${detail}"`;
+          return [
+            `error: no open affects-revisit obligation matches "${detail}".`,
+            'Match these exactly:',
+            ...open.map((o) => `  - ${o.detail}`),
+          ].join('\n');
+        }
+        ctx.decisions.push(`[affects] ${detail}: ${resolution}`);
+        return `resolved: ${detail}`;
+      };
+
+      const batch = args.resolutions;
+      if (Array.isArray(batch) && batch.length) {
+        // Entries resolve independently: one bad key must not waste the call.
+        return batch
+          .map((entry, i) => {
+            const e = entry as Record<string, unknown>;
+            if (typeof e?.constraint_key !== 'string' || typeof e?.item !== 'string' || typeof e?.resolution !== 'string') {
+              return `error: resolutions[${i}] needs string constraint_key, item, and resolution`;
+            }
+            return resolveOne(e.constraint_key, e.item, e.resolution);
+          })
+          .join('\n');
+      }
+      if (typeof args.constraint_key === 'string' && typeof args.item === 'string' && typeof args.resolution === 'string') {
+        return resolveOne(args.constraint_key, args.item, args.resolution);
+      }
+      return 'error: pass either resolutions: [{constraint_key, item, resolution}, ...] or the single form constraint_key + item + resolution';
     },
   },
   {