copperhead 0.9.0 → 0.11.0

package/src/agent/loop.ts

@@ -2,11 +2,13 @@ import path from 'node:path';
 import { readFile, writeFile } from 'node:fs/promises';
 import { execa } from 'execa';
 import type { Msg, Provider, Turn } from './types.js';
-import { availableTools, dispatchTool, type RunContext } from './tools.js';
+import { availableTools, dispatchToolResult, type RunContext } from './tools.js';
+import { flatten } from './envelope.js';
 import { CachingProvider } from './response-cache.js';
-import { withTimeout, TurnTimeoutError } from './recovery.js';
+import { withWatchdog, TurnTimeoutError, MAX_TURN_TIMEOUTS } from './recovery.js';
 import { buildSystemPrompt } from './prompts.js';
 import { loadConstraints, reopenDeferredAffects } from '../memory/constraints.js';
+import { isCreateProducedRepo, isEngineAuthoredSchematic } from '../kicad/fab.js';
 import {
   loadConfig,
   CONFIG_DIR,
@@ -30,7 +32,6 @@ import { AnthropicProvider } from './providers/anthropic.js';
 import { CodexProvider } from './providers/codex.js';
 import { ClaudeCodeProvider } from './providers/claude-code.js';
 import { CursorProvider } from './providers/cursor.js';
-import { openSynapMemory, type RunRecord, type SynapMemory } from '../memory/synap.js';
 
 /** What the user sees at the moment they decide whether to keep going. */
 export interface BudgetExhaustedStats {
@@ -202,16 +203,10 @@ async function appendChangelog(
   await writeFile(p, lines.join('\n'), 'utf8');
 }
 
-/**
- * Owns the Synap session for one run. The bridge is a subprocess, so the
- * shutdown in `finally` is what lets the CLI exit; without it the process
- * hangs after a successful run.
- */
 export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
-  const memory = await openSynapMemory({ repoRoot: opts.repoRoot, log: opts.log });
   const providers = new Set<Provider>();
   try {
-    return await runWithMemory(opts, memory, providers);
+    return await runWithProviders(opts, providers);
   } finally {
     for (const provider of providers) {
       try {
@@ -220,15 +215,10 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
         opts.log?.(`warning: ${provider.name} provider cleanup failed (${(err as Error).message})`);
       }
     }
-    await memory?.close();
   }
 }
 
-async function runWithMemory(
-  opts: RunOptions,
-  memory: SynapMemory | null,
-  providers: Set<Provider>,
-): Promise<RunResult> {
+async function runWithProviders(opts: RunOptions, providers: Set<Provider>): Promise<RunResult> {
   const r = opts.renderer ?? plainRenderer(opts.log ?? ((l: string) => console.log(l)));
   const log = (l: string): void => r.log(l);
   const repoRoot = opts.repoRoot;
@@ -240,11 +230,28 @@ async function runWithMemory(
 
   const transcript = new Transcript(repoRoot);
   await transcript.init();
+  // Legibility gates finish only where copperhead authored the sheet; a
+  // hand-drawn repo gets findings as information, never as a wedge (C6).
+  // Both conditions matter: the create-origin marker scopes the gate to repos
+  // this tool produced, and the generator stamp scopes it to sheets copperhead
+  // still owns. A human taking the sheet over in KiCad re-saves it under
+  // KiCad's generator, and from then on the gate must not defend a drawing
+  // the engine can no longer regenerate. A create repo whose schematic is not
+  // yet scaffolded keeps the gate: the sheet stage 4 will produce is
+  // copperhead-authored by construction.
+  let gateLegibility = isCreateProducedRepo(config);
+  if (gateLegibility && config.schematic) {
+    try {
+      gateLegibility = isEngineAuthoredSchematic(await readFile(path.join(repoRoot, config.schematic), 'utf8'));
+    } catch {
+      // schematic configured but absent (pre-scaffold): keep the gate
+    }
+  }
   const ctx: RunContext = {
     repoRoot,
     config,
     transcript,
-    ledger: new ObligationsLedger(),
+    ledger: new ObligationsLedger(gateLegibility),
     runId: path.basename(transcript.dir),
     interactive: opts.interactive ?? false,
     confirm: opts.confirm ?? (async () => true),
@@ -254,6 +261,8 @@ async function runWithMemory(
     filesTouched: new Set(),
     decisions: [],
     lastErc: null,
+    lastLegibility: null,
+    lastScore: null,
     lastDrc: null,
     repairCycles: 0,
     finishRequest: null,
@@ -328,37 +337,12 @@ async function runWithMemory(
       ...reopened.map((r) => `- ${r.key} affects ${r.item}`),
     ].join('\n');
   }
-  // Cross-run memory is appended after the repo's own docs and constraints so
-  // that the in-repo sources of truth are what the model reads first.
-  const recalled = memory ? await memory.recall(opts.request) : null;
-  if (recalled) {
-    await transcript.event('synap-recall', { chars: recalled.length });
-    log('recalled prior context from Synap memory');
-  }
-  const system = recalled ? `${basePrompt}\n\n${recalled}` : basePrompt;
   const messages: Msg[] = [
-    { role: 'system', content: system },
+    { role: 'system', content: basePrompt },
     { role: 'user', content: opts.stagePrompt ? `${opts.stagePrompt}\n\nRequest: ${opts.request}` : opts.request },
   ];
   await transcript.event('run-start', meta);
 
-  /**
-   * A memory write that fails is reported rather than swallowed, but it does
-   * not change the run's outcome: discarding a verified commit because a
-   * third-party write failed would be the worse trade.
-   */
-  const remember = async (run: RunRecord): Promise<void> => {
-    if (!memory) return;
-    try {
-      await memory.record(run);
-      await transcript.event('synap-record', { outcome: run.outcome });
-    } catch (err) {
-      const message = (err as Error).message;
-      log(`warning: Synap memory write failed (${message}); this run was not recorded`);
-      await transcript.event('synap-record-failed', { error: message });
-    }
-  };
-
   let tokensIn = 0;
   let tokensOut = 0;
   let turnsUsed = 0;
@@ -366,7 +350,7 @@ async function runWithMemory(
   let plan: string | null = null;
   let nudges = 0;
   let turnTimeouts = 0;
-  const maxTurnTimeouts = 3;
+  const maxTurnTimeouts = MAX_TURN_TIMEOUTS;
 
   const stats = (exitPath: ExitPath): RunStats => ({
     exitPath,
@@ -416,6 +400,8 @@ async function runWithMemory(
       filesTouched: [...ctx.filesTouched],
       ercResult: ctx.lastErc ? (ctx.lastErc.ok ? 'clean' : `${ctx.lastErc.violations.length} violations`) : null,
       drcResult: ctx.lastDrc ? (ctx.lastDrc.ok ? 'clean' : `${ctx.lastDrc.violations.length} violations`) : null,
+      legibilityResult: ctx.lastLegibility ? `${ctx.lastLegibility.error} error, ${ctx.lastLegibility.advisory} advisory` : null,
+      scoreResult: ctx.lastScore !== null ? `${ctx.lastScore}/100` : null,
       decisions: ctx.decisions,
       tokensIn,
       tokensOut,
@@ -515,28 +501,54 @@ async function runWithMemory(
         : null;
     heartbeat?.unref?.();
     try {
+      // Inactivity watchdog plus hard cap: every onStream call is progress and
+      // restarts the idle deadline, so a turn that legitimately runs past
+      // turnTimeoutMs survives while it keeps producing output. A provider that
+      // never streams gets turnTimeoutMs as a whole-turn deadline, as before.
       res = await withRetry(
         () =>
-          withTimeout(
-            () => provider.chat(messages, tools, { onStream: (chars) => (streamedChars = chars) }),
-            config.turnTimeoutMs,
-            () => provider.close?.(),
+          withWatchdog(
+            (activity) =>
+              provider.chat(messages, tools, {
+                onStream: (chars) => {
+                  streamedChars = chars;
+                  activity();
+                },
+              }),
+            { idleMs: config.turnTimeoutMs, maxMs: config.turnMaxMs, onTimeout: () => provider.close?.() },
           ),
         { onRetry: (attempt) => log(`rate limited; retry ${attempt}`) },
       );
     } catch (err) {
+      if (err instanceof TurnTimeoutError && err.kind === 'max') {
+        // Still producing output at the hard cap: the turn is too large, not
+        // hung. Resending the identical request would stream just as long and
+        // hit the cap again, so fail now with a reason that says so; the create
+        // pipeline hands it to the diagnosis, which can split the work.
+        await transcript.event('turn-timeout', { kind: 'max', ms: err.ms, streamedChars });
+        return fail(
+          `a single provider turn was still producing output after ${fmtDuration(err.ms)} (turnMaxMs) and was stopped — ` +
+            'the turn is too large, not hung; split the work into smaller steps, or raise turnMaxMs',
+          'provider-error',
+        );
+      }
       if (err instanceof TurnTimeoutError) {
-        // A hung provider turn: the watchdog aborted the in-flight call and tore
-        // down its subprocess. Retry the same turn a bounded number of times
-        // before giving up, so a transient hang self-heals instead of stalling
-        // the run forever.
+        // A hung provider turn: no response or progress for turnTimeoutMs. The
+        // watchdog aborted the in-flight call and tore down its subprocess.
+        // Retry the same turn a bounded number of times before giving up, so a
+        // transient hang self-heals instead of stalling the run forever.
         if (turnTimeouts++ < maxTurnTimeouts) {
-          log(`turn exceeded ${config.turnTimeoutMs}ms; aborted the hung call and retrying (${turnTimeouts}/${maxTurnTimeouts})`);
-          await transcript.event('turn-timeout', { ms: config.turnTimeoutMs, attempt: turnTimeouts });
+          log(
+            `turn went ${fmtDuration(err.ms)} without a response or progress (turnTimeoutMs); aborted the hung call and retrying (${turnTimeouts}/${maxTurnTimeouts})`,
+          );
+          await transcript.event('turn-timeout', { kind: 'idle', ms: err.ms, attempt: turnTimeouts });
           turn--;
           continue;
         }
-        return fail(`provider turns timed out ${turnTimeouts}× (>${config.turnTimeoutMs}ms each)`, 'provider-error');
+        return fail(
+          `provider turns timed out ${turnTimeouts}× (no response or progress for ${fmtDuration(err.ms)} each)`,
+          'provider-error',
+        );
       }
       if (isRateLimit(err)) {
         const fallback = otherProvider(provider);
@@ -605,9 +617,10 @@ async function runWithMemory(
     nudges = 0;
 
     for (const call of res.toolCalls) {
-      const result = await dispatchTool(ctx, call.name, call.args);
-      await transcript.event('tool', { name: call.name, args: call.args, result });
-      r.toolResult(call.name, result.split('\n')[0] ?? '');
+      const envelope = await dispatchToolResult(ctx, call.name, call.args, { provider });
+      const result = flatten(envelope);
+      await transcript.event('tool', { name: call.name, args: call.args, result, envelope });
+      r.toolResult(call.name, envelope.summary, envelope.ok, envelope.viewHint);
       messages.push({ role: 'tool', toolCallId: call.id, content: result });
     }
 
@@ -648,17 +661,6 @@ async function runWithMemory(
           env: meta,
           stats: runStats,
         });
-        // Refusals are the most valuable thing to remember: they encode a budget
-        // or constraint that this user's designs keep running into.
-        await remember({
-          request: opts.request,
-          outcome: 'refused',
-          summary,
-          changeId: ctx.changeId,
-          filesTouched: [],
-          decisions: ctx.decisions,
-          verification: 'n/a (refused before verification)',
-        });
         log(`refused: ${summary}`);
         r.finish(outcomeLine(runStats));
         return {
@@ -777,6 +779,8 @@ async function runWithMemory(
         filesTouched: files,
         ercResult: ctx.lastErc ? (ctx.lastErc.ok ? 'clean' : 'FAILING') : 'not run',
         drcResult: ctx.lastDrc ? (ctx.lastDrc.ok ? 'clean' : 'FAILING') : 'not run',
+        legibilityResult: ctx.lastLegibility ? `${ctx.lastLegibility.error} error, ${ctx.lastLegibility.advisory} advisory` : null,
+        scoreResult: ctx.lastScore !== null ? `${ctx.lastScore}/100` : null,
         decisions: ctx.decisions,
         tokensIn,
         tokensOut,
@@ -785,15 +789,6 @@ async function runWithMemory(
         env: meta,
         stats: runStats,
       });
-      await remember({
-        request: opts.request,
-        outcome: 'success',
-        summary,
-        changeId: ctx.changeId,
-        filesTouched: files,
-        decisions: ctx.decisions,
-        verification,
-      });
       log(`committed ${commit.slice(0, 10)} (${files.length} file(s))`);
       r.finish(outcomeLine(runStats, `committed ${commit.slice(0, 10)}`));
       return {

package/src/agent/prompts.ts

@@ -19,9 +19,10 @@ const WORKFLOW = `Workflow for every run:
 2. Call propose_change with a change id (kebab-case), why, what changes, and tasks. Then call validate_change. Edit tools (edit_file, write_file) unlock only after validation passes.
 3. Make the edits. Use the exact same net names and refdes everywhere. For .kicad_sch/.kicad_pcb use edit_file with unique anchors from the actual file text (read the file first). For renaming a net or refdes across a file, one edit_file call with replace_all: true beats many small edits.
 4. Run run_erc after schematic edits (and run_drc after board edits). If violations: read them, fix, re-run.
-5. Run check_drift; update any doc that references a changed value/part/pin in the same run.
-6. Record every non-trivial decision with record_decision, and every stated/assumed/discovered constraint with record_constraint.
-7. Call finish with outcome "done" when everything is verified, or outcome "refuse" (citing the violated budget/constraint) if the request should not be done. finish will list any unmet obligations; resolve them and call it again.
+5. After schematic edits also run check_legibility and reconcile every error-severity finding (advisories inform, they do not block). An electrically correct sheet that reads badly is not done: finish refuses while error findings are outstanding, the same way it refuses on a failing ERC.
+6. Run check_drift; update any doc that references a changed value/part/pin in the same run.
+7. Record every non-trivial decision with record_decision, and every stated/assumed/discovered constraint with record_constraint.
+8. Call finish with outcome "done" when everything is verified, or outcome "refuse" (citing the violated budget/constraint) if the request should not be done. finish will list any unmet obligations; resolve them and call it again.
 
 Turns are the scarce resource, not tool calls: the run has a hard turn budget, and every tool call in one reply executes in the same turn. When calls are independent — multiple record_constraint or resolve_affected calls (use resolutions: [...] to clear a backlog in one call), several read_file calls — issue them together in a single reply instead of one per turn.
 Always send a populated \`args\` object that matches the tool's JSON Schema (e.g. read_file needs {"path": "..."}). Never open a stage with an empty-args call to probe a tool — it only returns an error and burns a whole turn.`;

package/src/agent/providers/claude-code.ts

@@ -62,6 +62,11 @@ export interface QueryOptions {
    * turns itself instead of us re-sending the whole conversation each turn (1.1,
    * `Options.resume`). Only set in the opt-in session-resume mode. */
   resume?: string;
+  /** Emit `stream_event` messages as the model generates, on top of the
+   * complete `assistant` message (Agent SDK `Options.includePartialMessages`).
+   * Used only as a progress signal for the turn watchdog and heartbeat; the
+   * reply is still read from the complete message. */
+  includePartialMessages?: boolean;
 }
 export interface QueryArgs {
   prompt: string;
@@ -73,6 +78,8 @@ export interface QueryMessage {
   session_id?: string;
   message?: { content?: Array<{ type: string; text?: string }> };
   usage?: { input_tokens?: number; output_tokens?: number };
+  /** On a `stream_event` message: the raw Messages-API stream event. */
+  event?: { type: string; delta?: { type: string; text?: string } };
 }
 export type QueryLike = (args: QueryArgs) => AsyncIterable<QueryMessage>;
 
@@ -153,6 +160,8 @@ export class ClaudeCodeProvider implements Provider {
     let text: string | null = null;
     let inputTokens = 0;
     let outputTokens = 0;
+    // Visible text streamed so far, for the heartbeat's count (see stream_event).
+    let streamedChars = 0;
     // One aborter per turn: close() aborts it to kill a hung subprocess.
     const aborter = new AbortController();
     this.inFlight.add(aborter);
@@ -163,6 +172,10 @@ export class ClaudeCodeProvider implements Provider {
           systemPrompt,
           ...(this.model ? { model: this.model } : {}),
           abortController: aborter,
+          // Partial-message events are the turn's progress signal: without them
+          // the SDK yields nothing until the reply is complete, so a turn that is
+          // still generating looks exactly like a hung one to the watchdog.
+          includePartialMessages: true,
           // Layered "the SDK executes nothing" defense (D1/D5):
           //  1. `tools: []` disables ALL built-in tools (Agent SDK 0.3.x docs:
           //     "[] (empty array) - Disable all built-in tools").
@@ -189,7 +202,15 @@ export class ClaudeCodeProvider implements Provider {
           maxTurns: 1,
         },
       })) {
-        if (msg.type === 'assistant') {
+        if (msg.type === 'stream_event') {
+          // Every partial event is progress (thinking and block boundaries too),
+          // and reporting it restarts the loop's inactivity watchdog; only text
+          // deltas grow the count. The reply itself is still read from the
+          // complete `assistant` message below, never reassembled from deltas.
+          const delta = msg.event?.delta;
+          if (delta?.type === 'text_delta' && delta.text) streamedChars += delta.text.length;
+          opts.onStream?.(streamedChars);
+        } else if (msg.type === 'assistant') {
           for (const block of msg.message?.content ?? []) {
             if (block.type === 'text' && block.text) {
               text = (text ?? '') + block.text;

package/src/agent/providers/codex.ts

@@ -15,7 +15,7 @@ type CodexThreadOptions = Pick<
   | 'networkAccessEnabled'
   | 'webSearchMode'
 >;
-type CodexTurnOptions = Pick<TurnOptions, 'outputSchema'>;
+type CodexTurnOptions = Pick<TurnOptions, 'outputSchema' | 'signal'>;
 
 interface CodexTurnLike {
   finalResponse: string;
@@ -58,6 +58,13 @@ export class CodexProvider implements Provider {
   private readonly client: CodexClientLike;
   private thread: CodexThreadLike | null = null;
   private messageCursor = 0;
+  /** In-flight turn aborters, so close() (called by the turn watchdog on a hung
+   * turn) kills the `codex exec` subprocess instead of orphaning it. */
+  private readonly inFlight = new Set<AbortController>();
+  /** Bumped by close(). A turn begun under an earlier generation was abandoned;
+   * if it settles late it must not touch the thread or cursor that replaced it,
+   * or it would mark messages seen that the fresh thread never received. */
+  private generation = 0;
 
   constructor(options: CodexProviderOptions) {
     this.model = options.model;
@@ -67,53 +74,88 @@ export class CodexProvider implements Provider {
   }
 
   async chat(messages: Msg[], tools: ToolSchema[], _opts: ChatOpts = {}): Promise<Turn> {
-    const workingDirectory = await this.ensureWorkingDirectory();
-    if (!this.thread) {
-      this.thread = this.client.startThread({
-        ...(this.model ? { model: this.model } : {}),
-        workingDirectory,
-        skipGitRepoCheck: true,
-        sandboxMode: 'read-only',
-        approvalPolicy: 'never',
-        networkAccessEnabled: false,
-        webSearchMode: 'disabled',
-      });
-    }
-
-    const cursor = this.messageCursor;
-    const schema = turnSchema(tools);
-    const toolCatalog = new Map(tools.map((tool) => [tool.name, tool]));
-    const attempts: CodexTurnLike[] = [];
-    let result = await this.runThread(renderTurnPrompt(messages, cursor, tools), schema);
-    attempts.push(result);
-
-    let parsed: ReturnType<typeof parseStructuredTurn>;
+    const generation = this.generation;
+    const aborter = new AbortController();
+    this.inFlight.add(aborter);
     try {
-      parsed = parseStructuredTurn(result.finalResponse, toolCatalog);
-    } catch (err) {
-      const validationError = (err as Error).message;
-      result = await this.runThread(renderCorrectionPrompt(tools, validationError), schema);
+      const workingDirectory = await this.ensureWorkingDirectory();
+      this.assertCurrent(generation);
+      if (!this.thread) {
+        this.thread = this.client.startThread({
+          ...(this.model ? { model: this.model } : {}),
+          workingDirectory,
+          skipGitRepoCheck: true,
+          sandboxMode: 'read-only',
+          approvalPolicy: 'never',
+          networkAccessEnabled: false,
+          webSearchMode: 'disabled',
+        });
+      }
+      const thread = this.thread;
+
+      const cursor = this.messageCursor;
+      const schema = turnSchema(tools);
+      const toolCatalog = new Map(tools.map((tool) => [tool.name, tool]));
+      const attempts: CodexTurnLike[] = [];
+      let result = await this.runThread(thread, renderTurnPrompt(messages, cursor, tools), schema, aborter.signal);
+      this.assertCurrent(generation);
       attempts.push(result);
-      parsed = parseStructuredTurn(result.finalResponse, toolCatalog);
-    }
 
-    // The input remains unseen until Copperhead accepts a structured turn.
-    this.messageCursor = messages.length;
-    return {
-      text: parsed.text.trim() || null,
-      toolCalls: parsed.toolCalls,
-      usage: {
-        inputTokens: attempts.reduce((sum, attempt) => sum + (attempt.usage?.input_tokens ?? 0), 0),
-        outputTokens: attempts.reduce((sum, attempt) => sum + (attempt.usage?.output_tokens ?? 0), 0),
-      },
-    };
+      let parsed: ReturnType<typeof parseStructuredTurn>;
+      try {
+        parsed = parseStructuredTurn(result.finalResponse, toolCatalog);
+      } catch (err) {
+        const validationError = (err as Error).message;
+        result = await this.runThread(thread, renderCorrectionPrompt(tools, validationError), schema, aborter.signal);
+        this.assertCurrent(generation);
+        attempts.push(result);
+        parsed = parseStructuredTurn(result.finalResponse, toolCatalog);
+      }
+
+      // The input remains unseen until Copperhead accepts a structured turn.
+      this.messageCursor = messages.length;
+      return {
+        text: parsed.text.trim() || null,
+        toolCalls: parsed.toolCalls,
+        usage: {
+          inputTokens: attempts.reduce((sum, attempt) => sum + (attempt.usage?.input_tokens ?? 0), 0),
+          outputTokens: attempts.reduce((sum, attempt) => sum + (attempt.usage?.output_tokens ?? 0), 0),
+        },
+      };
+    } finally {
+      this.inFlight.delete(aborter);
+    }
   }
 
   async close(): Promise<void> {
+    this.generation++;
+    for (const aborter of this.inFlight) {
+      try {
+        aborter.abort();
+      } catch {
+        // best effort: a turn that already settled has nothing to tear down
+      }
+    }
+    this.inFlight.clear();
+    // A fresh thread has seen nothing, so the next turn must send the full
+    // history (system prompt and request included), not the delta meant for the
+    // thread being discarded; otherwise a retried turn runs without context.
     this.thread = null;
-    if (this.ownsWorkingDirectory && this.workingDirectory) {
-      await rm(this.workingDirectory, { recursive: true, force: true });
+    this.messageCursor = 0;
+    // Forget the directory before deleting it: the watchdog does not await
+    // close(), so a retried turn can start while rm is still running, and it must
+    // create a fresh directory rather than reuse the one being deleted.
+    const dir = this.workingDirectory;
+    if (this.ownsWorkingDirectory && dir) {
       this.workingDirectory = null;
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+
+  /** Throw if close() ran since the turn began (see `generation`). */
+  private assertCurrent(generation: number): void {
+    if (generation !== this.generation) {
+      throw new Error('codex: turn abandoned because the provider was closed while it ran');
     }
   }
 
@@ -126,9 +168,16 @@ export class CodexProvider implements Provider {
     return this.workingDirectory;
   }
 
-  private async runThread(prompt: string, outputSchema: Record<string, unknown>): Promise<CodexTurnLike> {
+  private async runThread(
+    thread: CodexThreadLike,
+    prompt: string,
+    outputSchema: Record<string, unknown>,
+    signal: AbortSignal,
+  ): Promise<CodexTurnLike> {
     try {
-      return await this.thread!.run(prompt, { outputSchema });
+      // The turn's own thread, not `this.thread`, which close() may have
+      // replaced; the signal lets close() kill the `codex exec` subprocess.
+      return await thread.run(prompt, { outputSchema, signal });
     } catch (err) {
       const original = err as Error & { status?: number; statusCode?: number };
       const setupHint = isCliSetupError(original)

package/src/agent/providers/tool-protocol.ts

@@ -85,9 +85,14 @@ export interface ParsedToolTurn {
  * split so only an inner `{args}` with no `tool` key balanced), not the tool
  * being broken. Returns a one-line steer to re-emit it, or undefined when the
  * absence of a call is genuine (plain prose, no tool named).
+ *
+ * Also covers the mirror case (I18): well-formed JSON naming a tool that is NOT in
+ * the catalog — withheld by the edit lock, or invented. That call is correctly not
+ * dispatched, but it must not be silent either.
  */
 function detectMalformedCall(text: string, catalog: Set<string>): string | undefined {
   const re = /"tool"\s*:\s*"([^"]+)"/g;
+  const offCatalog: string[] = [];
   let m: RegExpExecArray | null;
   while ((m = re.exec(text)) !== null) {
     const name = m[1]!;
@@ -98,6 +103,23 @@ function detectMalformedCall(text: string, catalog: Set<string>): string | undef
         'Re-emit it as exactly one complete JSON object: {"tool": "...", "args": { ... }}.'
       );
     }
+    if (!offCatalog.includes(name)) offCatalog.push(name);
+  }
+  // A well-formed call naming a tool the turn did not advertise — a locked edit or
+  // drafting tool before propose_change/validate_change, or an invented name.
+  // `toToolCall` is right to refuse it (the lock is structural, D2), but dropping it
+  // to prose tells the model NOTHING, and it fills that silence: fabricating the
+  // result it never got (I15), or concluding the engine is absent from the build and
+  // refusing the stage outright (I18). Withholding the tool is the invariant; hiding
+  // the reason never was, so name it and print the real catalog.
+  if (offCatalog.length) {
+    const named = offCatalog.map((n) => `"${n}"`).join(', ');
+    return (
+      `No call ran: ${named} ${offCatalog.length > 1 ? 'are' : 'is'} not in this turn's tool ` +
+      'catalog. Edit and drafting tools are withheld until a proposal validates — call ' +
+      'propose_change, then validate_change, and they appear. Do not conclude a tool is ' +
+      `missing from the build. Available this turn: ${[...catalog].join(', ')}.`
+    );
   }
   return undefined;
 }