copperhead 0.10.0 → 0.11.0

package/src/agent/envelope.ts

@@ -0,0 +1,124 @@
+import { redactSecrets } from '../util/redact.js';
+
+/** Envelope protocol version for the ToolResult shape (design D5). */
+export const PROTOCOL_VERSION = 1;
+
+export type ViewHint = 'diagnostic' | 'mutation' | 'query' | 'export';
+export type ToolErrorKind = 'unavailable' | 'validation' | 'refusal' | 'exception';
+
+export interface ToolResult {
+  ok: boolean;
+  summary: string;
+  detail?: string;
+  data?: unknown;
+  error?: { kind: ToolErrorKind; message: string };
+  viewHint?: ViewHint;
+}
+
+function redactEnvelopeText(text: string): string {
+  let out = redactSecrets(text);
+  for (const [name, val] of Object.entries(process.env)) {
+    if (!val || val.length < 8) continue;
+    if (!/_(KEY|SECRET|TOKEN)$/.test(name)) continue;
+    if (out.includes(val)) out = out.split(val).join('[REDACTED]');
+  }
+  return out;
+}
+
+function redactDeep(value: unknown): unknown {
+  if (typeof value === 'string') return redactEnvelopeText(value);
+  if (Array.isArray(value)) return value.map(redactDeep);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, redactDeep(v)]));
+  }
+  return value;
+}
+
+/** Redact every string field at construction so render/dock never see secrets. */
+export function seal(partial: ToolResult): ToolResult {
+  return {
+    ok: partial.ok,
+    summary: redactEnvelopeText(partial.summary),
+    ...(partial.detail !== undefined ? { detail: redactEnvelopeText(partial.detail) } : {}),
+    ...(partial.data !== undefined ? { data: redactDeep(partial.data) } : {}),
+    ...(partial.error
+      ? { error: { kind: partial.error.kind, message: redactEnvelopeText(partial.error.message) } }
+      : {}),
+    ...(partial.viewHint ? { viewHint: partial.viewHint } : {}),
+  };
+}
+
+export function okResult(text: string, viewHint?: ViewHint, data?: unknown): ToolResult {
+  const first = text.split('\n')[0] ?? text;
+  return seal({
+    ok: true,
+    summary: first,
+    ...(text !== first ? { detail: text } : {}),
+    ...(data !== undefined ? { data } : {}),
+    ...(viewHint ? { viewHint } : {}),
+  });
+}
+
+export function failResult(kind: ToolErrorKind, message: string, viewHint?: ViewHint): ToolResult {
+  const first = message.split('\n')[0] ?? message;
+  return seal({
+    ok: false,
+    summary: first,
+    error: { kind, message },
+    ...(viewHint ? { viewHint } : {}),
+  });
+}
+
+/** Flatten an envelope to the string providers already consume as tool Msg content. */
+export function flatten(result: ToolResult): string {
+  if (result.error) return result.error.message;
+  if (result.detail) {
+    return result.detail.startsWith(result.summary) ? result.detail : `${result.summary}\n${result.detail}`;
+  }
+  return result.summary;
+}
+
+/** Build an envelope from text plus an outcome already known by the handler. */
+export function outcomeResult(text: string, ok: boolean, viewHint?: ViewHint): ToolResult {
+  const first = text.split('\n')[0] ?? text;
+  return seal({
+    ok,
+    summary: first,
+    ...(text !== first ? { detail: text } : {}),
+    ...(viewHint ? { viewHint } : {}),
+  });
+}
+
+/**
+ * Wrap a legacy handler string. Error-shaped prefixes become typed failures so
+ * validation/refusal are not retried; everything else is success. Flattened
+ * text equals the original string.
+ */
+export function textResult(text: string, viewHint: ViewHint): ToolResult {
+  if (
+    /^error:/.test(text) ||
+    text.startsWith('rejected:') ||
+    text.startsWith('edit REVERTED') ||
+    text.startsWith('validation FAILED')
+  ) {
+    return failResult('validation', text, viewHint);
+  }
+  if (
+    text.startsWith('refused:') ||
+    text.startsWith('cannot finish yet') ||
+    text.startsWith('proposal validated but human declined')
+  ) {
+    return failResult('refusal', text, viewHint);
+  }
+  return okResult(text, viewHint);
+}
+
+export function unavailable(name: string, editsUnlocked: boolean, reason?: string): ToolResult {
+  const suffix = reason
+    ? ` (${reason})`
+    : editsUnlocked
+      ? ''
+      : ' (edit tools unlock after the proposal validates)';
+  const message = `tool "${name}" is not available${suffix}`;
+  return failResult('unavailable', message);
+}

package/src/agent/loop.ts

@@ -2,9 +2,10 @@ 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';
@@ -349,7 +350,7 @@ async function runWithProviders(opts: RunOptions, providers: Set<Provider>): Pro
   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,
@@ -500,28 +501,54 @@ async function runWithProviders(opts: RunOptions, providers: Set<Provider>): Pro
         : 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);
@@ -590,9 +617,10 @@ async function runWithProviders(opts: RunOptions, providers: Set<Provider>): Pro
     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 });
     }
 

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/recovery.ts

@@ -4,10 +4,23 @@ import path from 'node:path';
 import type { Msg, Provider } from './types.js';
 import { resolveLibrarySymbol, searchInstalledSymbols, symbolSearchDirs, listInstalledLibraries } from '../kicad/symlib.js';
 
-/** Thrown when a single provider turn blows past its watchdog deadline. */
+/**
+ * How many times a hung provider turn is retried before the run gives up. One
+ * policy, two turn loops: the main agent loop and the nested skill sub-run.
+ */
+export const MAX_TURN_TIMEOUTS = 3;
+
+/**
+ * Thrown when a provider turn trips its watchdog. `idle`: no response or
+ * progress for `ms`, so the call looks hung. `max`: still running at the hard
+ * cap however much progress it reported, so the turn is too large, not hung.
+ */
 export class TurnTimeoutError extends Error {
-  constructor(public readonly ms: number) {
-    super(`turn exceeded ${ms}ms without responding`);
+  constructor(
+    public readonly ms: number,
+    public readonly kind: 'idle' | 'max' = 'idle',
+  ) {
+    super(kind === 'max' ? `turn still running after ${ms}ms (hard cap)` : `turn exceeded ${ms}ms without responding`);
     this.name = 'TurnTimeoutError';
   }
 }
@@ -24,18 +37,81 @@ export async function withTimeout<T>(
   ms: number,
   onTimeout?: () => void | Promise<void>,
 ): Promise<T> {
-  if (!Number.isFinite(ms) || ms <= 0) return fn();
-  let timer: ReturnType<typeof setTimeout> | undefined;
+  return withWatchdog(() => fn(), { idleMs: ms, ...(onTimeout ? { onTimeout } : {}) });
+}
+
+/**
+ * The turn watchdog: `withTimeout` with the deadline measured from the last sign
+ * of progress instead of from the start. `fn` receives an `activity` callback and
+ * each call restarts the `idleMs` deadline, so a long turn that keeps producing
+ * output is never mistaken for a hung one, while a call that reports nothing gets
+ * `idleMs` as a plain whole-call deadline (unchanged for providers that cannot
+ * stream). `maxMs` is a hard cap activity does not extend, so a turn that streams
+ * forever still ends. The cap bounds a call that is producing output, so it only
+ * trips once `fn` has reported progress (a silent call is judged by `idleMs`
+ * alone, exactly as before the cap existed), and it is never shorter than
+ * `idleMs` (a lower cap would cut off a turn the idle deadline alone allows).
+ * `<= 0` (or non-finite) disables either limit; with both disabled this just
+ * awaits `fn`.
+ */
+export async function withWatchdog<T>(
+  fn: (activity: () => void) => Promise<T>,
+  opts: { idleMs: number; maxMs?: number; onTimeout?: () => void | Promise<void> },
+): Promise<T> {
+  const idleOn = Number.isFinite(opts.idleMs) && opts.idleMs > 0;
+  const maxMs = opts.maxMs ?? 0;
+  const maxOn = Number.isFinite(maxMs) && maxMs > 0;
+  if (!idleOn && !maxOn) return fn(() => {});
+  const capMs = idleOn ? Math.max(maxMs, opts.idleMs) : maxMs;
+  let idleTimer: ReturnType<typeof setTimeout> | undefined;
+  let maxTimer: ReturnType<typeof setTimeout> | undefined;
+  // Set once the race is decided either way, so a late activity() from an
+  // abandoned call cannot re-arm a timer after the watchdog is done.
+  let settled = false;
+  // Whether fn has reported progress yet, and whether the cap came due while it
+  // had not (see the cap timer below).
+  let progressed = false;
+  let capPassed = false;
+  let trip!: (err: TurnTimeoutError) => void;
   const timeout = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => {
-      void Promise.resolve(onTimeout?.()).catch(() => {});
-      reject(new TurnTimeoutError(ms));
-    }, ms);
+    trip = (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(idleTimer);
+      clearTimeout(maxTimer);
+      // Reject before tearing down: onTimeout (provider.close()) may reject the
+      // in-flight call synchronously, and the race must settle on the timeout,
+      // not on that teardown error, or the caller never sees TurnTimeoutError.
+      reject(err);
+      void Promise.resolve(opts.onTimeout?.()).catch(() => {});
+    };
   });
+  const armIdle = (): void => {
+    clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => trip(new TurnTimeoutError(opts.idleMs, 'idle')), opts.idleMs);
+  };
+  const activity = (): void => {
+    if (settled) return;
+    progressed = true;
+    if (capPassed) return trip(new TurnTimeoutError(capMs, 'max'));
+    if (idleOn) armIdle();
+  };
+  if (idleOn) armIdle();
+  if (maxOn) {
+    maxTimer = setTimeout(() => {
+      // The cap bounds a turn that is producing output. A call that has reported
+      // nothing yet stays under the idle deadline alone; if it starts reporting
+      // progress later, the cap applies at that moment.
+      if (progressed) trip(new TurnTimeoutError(capMs, 'max'));
+      else capPassed = true;
+    }, capMs);
+  }
   try {
-    return await Promise.race([fn(), timeout]);
+    return await Promise.race([fn(activity), timeout]);
   } finally {
-    if (timer) clearTimeout(timer);
+    settled = true;
+    clearTimeout(idleTimer);
+    clearTimeout(maxTimer);
   }
 }
 
@@ -239,7 +315,8 @@ export async function diagnoseStageFailure(
       : '') +
     'Reply with ONLY a JSON object, no prose:\n' +
     '{"verdict":"retry"|"abort","reason":"<one sentence>","guidance":"<if retry: concrete, specific instructions to prepend to the next attempt so it avoids this failure; otherwise empty>"}\n' +
-    '- "retry" if the failure looks transient or fixable with clearer instructions (a dropped or locked tool call, an empty/no-op edit, a skipped step, a timeout, a formatting slip).\n' +
+    '- "retry" if the failure looks transient or fixable with clearer instructions (a dropped or locked tool call, an empty/no-op edit, a skipped step, a hung provider call that timed out, a formatting slip).\n' +
+    '- a turn stopped at the hard time cap while still producing output (turnMaxMs, "too large, not hung") is NOT transient: repeating it hits the cap again. Retry only with guidance that splits that work into several smaller edits (e.g. one part or one sheet section per edit).\n' +
     '- "abort" if repeating the same attempt will not help and a human should look (missing inputs, a genuine dead-end, or the same failure already seen on a prior attempt).\n' +
     '- an agent\'s claim that a symbol or library is absent is NOT evidence: agents dead-ended by wrong library nicknames routinely conclude whole libraries are missing. If the machine-verified facts contradict the failure\'s premise (a cited-absent lib_id RESOLVES, or the part is installed under another library), the verdict is "retry", with guidance quoting the correct lib_ids.';
   const messages: Msg[] = [

package/src/agent/registry.ts

@@ -0,0 +1,58 @@
+import { catalog } from '../capabilities/index.js';
+import type { CatalogEntry, CatalogSkill } from '../capabilities/define.js';
+import type { RunContext } from './context.js';
+import { PROTOCOL_VERSION } from './envelope.js';
+
+export { PROTOCOL_VERSION };
+
+export class ToolRegistry {
+  private readonly byName = new Map<string, CatalogEntry>();
+
+  constructor(entries: CatalogEntry[]) {
+    for (const source of entries) {
+      const e: CatalogEntry = { ...source };
+      if (this.byName.has(e.name)) throw new Error(`duplicate catalog name "${e.name}"`);
+      this.byName.set(e.name, e);
+    }
+    for (const e of this.byName.values()) {
+      if (e.kind === 'skill' && !e.gateProvided) {
+        const conj = (ctx: RunContext) => this.conjunction(e.tools, ctx);
+        e.gate = conj;
+      }
+    }
+  }
+
+  get protocolVersion(): number {
+    return PROTOCOL_VERSION;
+  }
+
+  get(name: string): CatalogEntry | undefined {
+    return this.byName.get(name);
+  }
+
+  all(): CatalogEntry[] {
+    return [...this.byName.values()];
+  }
+
+  skills(): CatalogSkill[] {
+    return this.all().filter((e): e is CatalogSkill => e.kind === 'skill');
+  }
+
+  /** True when every named tool exists and its gate is open. */
+  conjunction(toolNames: string[], ctx: RunContext): boolean {
+    return toolNames.every((n) => {
+      const t = this.byName.get(n);
+      return t?.kind === 'tool' && t.gate(ctx);
+    });
+  }
+
+  /** Entries whose gate is open. Skills also require every declared tool's gate (D3). */
+  list(ctx: RunContext): CatalogEntry[] {
+    return this.all().filter((e) => {
+      if (e.kind === 'skill' && (e.tools.includes('finish') || !this.conjunction(e.tools, ctx))) return false;
+      return e.gate(ctx);
+    });
+  }
+}
+
+export const registry = new ToolRegistry(catalog);

package/src/agent/render.ts

@@ -9,12 +9,13 @@
  */
 
 import { copper, dim, setColorEnabled, styleOutcome, toolLine, warn } from './theme.js';
+import type { ViewHint } from './envelope.js';
 
 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;
+  toolResult(name: string, firstLine: string, ok?: boolean, viewHint?: ViewHint): void;
   /** Busy text while a provider call is in flight; null when idle. */
   status(text: string | null): void;
   /**
@@ -175,8 +176,8 @@ export class InteractiveRenderer implements ProgressRenderer {
     this.redraw();
   }
 
-  toolResult(name: string, firstLine: string): void {
-    this.log(toolLine(name, firstLine));
+  toolResult(name: string, firstLine: string, ok?: boolean, viewHint?: ViewHint): void {
+    this.log(toolLine(name, firstLine, ok, viewHint));
   }
 
   status(text: string | null): void {