@mcp-abap-adt/llm-agent-server-libs 20.0.0 → 20.5.0

package/dist/smart-agent/controller/controller-coordinator-handler.js

@@ -1,55 +1,34 @@
-import { externalToolCallId, } from '@mcp-abap-adt/llm-agent';
-import { summaryToUsage, } from '@mcp-abap-adt/llm-agent-libs';
-import { cosine } from '../embedder-knowledge-index.js';
-import { readClaims, readPlanDecisions, writePlanDecision, } from './artifacts.js';
-import { BoardOverBudgetError, reconstructBoard, renderBoard, } from './board.js';
+import { externalToolCallId, McpError, } from '@mcp-abap-adt/llm-agent';
+import { LegacyAccumulateContextStrategy, LegacyTranscriptContextStrategy, summaryToUsage, } from '@mcp-abap-adt/llm-agent-libs';
+import { writePlanDecision } from './artifacts.js';
+import { BoardOverBudgetError, renderLiveBoard, } from './board.js';
+import { DefaultStepExecutionControl } from './default-step-execution-control.js';
 import { writeArtifact } from './memorizer.js';
 import { resolveByPrecedence } from './outcome.js';
 import { makeControllerPlanner } from './planner.js';
 import { appendHint } from './prompts.js';
+import { buildRecallBlock, collectApproved, RECALL_ARTIFACT_TYPES, RECALL_EVIDENCE_CHARS, RECALL_K_STEP, RECALL_MAX_CHARS_STEP, relevantExtract, runScopedRecall, } from './recall.js';
 import { classifyRequest, readTerminal, writeTerminal } from './run-scope.js';
 import { hydrateBundle, persistBundle, resetRun } from './session-bundle.js';
 import { establishTargetState } from './target-state.js';
-import { validateRequires, } from './types.js';
+import { makeLogUsage } from './usage-logging.js';
 // ---------------------------------------------------------------------------
 // Debug logging — gated behind DEBUG_CONTROLLER (e.g. DEBUG_CONTROLLER=1).
 // Surfaces the steps the planner delegates and per-role/total token usage to
 // stderr, for tuning step granularity and watching token spend. Off by default.
+// (Also in usage-logging.ts — intentional small duplication; no 3rd copy exists.)
 // ---------------------------------------------------------------------------
 function dlog(msg) {
     if (process.env.DEBUG_CONTROLLER)
         console.error(`[controller] ${msg}`);
 }
-/**
- * Build a request-time `logUsage(role, usage)` that writes each subagent call
- * into the per-request `IRequestLogger` (the single aggregator), attributing the
- * role's configured model. The role is explicit at the call site, so the shared
- * planner/finalizer client is attributed correctly. `durationMs: 0` — the seam
- * carries no timing (matches the rag-query precedent).
- */
-export function makeLogUsage(requestLogger, requestId, models) {
-    return (role, u) => {
-        if (!u)
-            return;
-        const model = role === 'finalizer'
-            ? (models.finalizer ?? models.planner)
-            : role === 'reviewer'
-                ? (models.reviewer ?? models.planner)
-                : role === 'embedding'
-                    ? 'embedder'
-                    : (models[role] ?? 'unknown');
-        requestLogger.logLlmCall({
-            component: role,
-            model,
-            promptTokens: u.promptTokens ?? 0,
-            completionTokens: u.completionTokens ?? 0,
-            totalTokens: u.totalTokens ?? 0,
-            durationMs: 0,
-            requestId,
-        });
-        dlog(`tokens ${role}: prompt=${u.promptTokens} completion=${u.completionTokens} total=${u.totalTokens}`);
-    };
-}
+// ---------------------------------------------------------------------------
+// Re-exported for import-path stability (helpers moved to sibling modules).
+// ---------------------------------------------------------------------------
+export { renderLiveBoard } from './board.js';
+export { parseNextStep } from './parser.js';
+export { relevantExtract, runScopedRecall } from './recall.js';
+export { makeLogUsage } from './usage-logging.js';
 // ---------------------------------------------------------------------------
 // Handler
 // ---------------------------------------------------------------------------
@@ -585,183 +564,222 @@ export class ControllerCoordinatorHandler {
         const cfg = deps.config.budgets;
         const maxToolCalls = cfg.maxToolCalls ?? 10;
         const inFlight = bundle.inFlightStep; // set by the caller (block A or B)
-        // Persist the step outcome ATOMICALLY: record lastOutcome (durable, so a
-        // resume after a failed step replans instead of repeating it) AND advance the
-        // planner cursor (onCommit) in the SAME persistBundle that records the step
-        // result — never in a separate write, so a crash cannot replay a completed step.
-        const settle = async (outcome) => {
-            bundle.lastOutcome = outcome;
-            onCommit?.(outcome);
-            if (outcome === 'advanced' || outcome === 'partial') {
-                bundle.nextSeq = (bundle.nextSeq ?? 0) + 1;
-                bundle.inFlightStep = undefined;
-                bundle.runPhase = 'planning';
+        // Per-step execution control: a wall-clock time budget (perStepTimeoutMs) +
+        // the prospective maxToolCalls gate, consumer-swappable via deps. Its signal
+        // is merged with the caller's cancel signal (below) and fed into both the
+        // executor.send and callMcp so a non-converging / hung step is CUT rather than
+        // livelocking. Absent perStepTimeoutMs → time never fires → count-only bound.
+        const stepControl = deps.stepExecutionControl ?? new DefaultStepExecutionControl();
+        const budget = stepControl.beginStep({
+            stepName: step.name,
+            seq: inFlight?.seq ?? 0,
+            attempt: inFlight?.attempt ?? 0,
+            budgets: { maxToolCalls, perStepTimeoutMs: cfg.perStepTimeoutMs },
+        });
+        // The budget owns a wall-clock timer that is NOT unref'd — it MUST be disposed
+        // on every step exit. Open the try IMMEDIATELY after beginStep so the
+        // budget-dependent pre-loop (recall / evidence embed / selectTools /
+        // strategy.record) is inside the SAME try…finally; a throw from any of those
+        // documented-fallible awaits (e.g. an embedder 429) would otherwise leak the
+        // timer and later fire controller.abort() on an orphaned signal.
+        try {
+            const stepStartedAt = Date.now();
+            // Merge the caller's request/cancel signal with the step budget: an inner call
+            // is cancelled by EITHER. The step-timeout DISCRIMINATOR remains
+            // budget.signal.aborted SPECIFICALLY, so a pure caller-cancel is NOT mis-mapped
+            // to a step-timeout control-failure.
+            const callSignal = ctx.options?.signal
+                ? AbortSignal.any([ctx.options.signal, budget.signal])
+                : budget.signal;
+            // Typed reason code (StepControlDecision.reason) → human note. Preserves
+            // today's exact wording so existing suites stay byte-identical.
+            const noteFor = (r) => r === 'maxToolCalls'
+                ? 'tool-call budget exhausted (maxToolCalls)'
+                : r === 'step-timeout'
+                    ? 'step time budget exhausted (step-timeout)'
+                    : r;
+            let roundNo = 0;
+            const state = () => ({
+                round: roundNo,
+                toolCallCount: inFlight?.toolCallCount ?? 0,
+                elapsedMs: Date.now() - stepStartedAt,
+            });
+            // Persist the step outcome ATOMICALLY: record lastOutcome (durable, so a
+            // resume after a failed step replans instead of repeating it) AND advance the
+            // planner cursor (onCommit) in the SAME persistBundle that records the step
+            // result — never in a separate write, so a crash cannot replay a completed step.
+            const settle = async (outcome) => {
+                bundle.lastOutcome = outcome;
+                onCommit?.(outcome);
+                if (outcome === 'advanced' || outcome === 'partial') {
+                    bundle.nextSeq = (bundle.nextSeq ?? 0) + 1;
+                    bundle.inFlightStep = undefined;
+                    bundle.runPhase = 'planning';
+                }
+                else {
+                    // 'failed' — keep the same seq, mark awaiting-replan in the SAME persist so
+                    // recovery routes by durable phase.
+                    if (bundle.inFlightStep)
+                        bundle.inFlightStep.phase = 'awaiting-replan';
+                    bundle.runPhase = 'executing';
+                }
+                await persistBundle(deps.backend, sessionId, bundle);
+                return outcome;
+            };
+            // The IMMUTABLE per-round prefix: system + step user message + the step-result
+            // recall block. Re-emitted verbatim every round via strategy.form(); the dynamic
+            // tool rounds are owned by the injected context strategy, NOT accumulated here.
+            const staticPrefix = [
+                {
+                    role: 'system',
+                    content: appendHint(EXECUTOR_SYSTEM, deps.config.subagents.executor?.hint),
+                },
+                {
+                    role: 'user',
+                    content: `Goal: ${bundle.goal}\nStep: ${step.name}\nInstructions: ${step.instructions}`,
+                },
+            ];
+            // Episodic recall: pull prior STEP-RESULT artifacts relevant to this step from
+            // session-memory and inject them as static context. The session-memory rag shares
+            // the bundle backend, so restrict to 'step-result' (excludes the
+            // 'controller-bundle' infrastructure record). Bounded by k and length. The
+            // per-round MCP context is now the context strategy's job (its form() supplies
+            // the mcp-result rounds — the Window keeps its own buffer, RagRecall recalls),
+            // so it is NOT part of the handler-built static prefix.
+            const recallText = step.instructions || step.name;
+            const maxAttempts = cfg.maxStepAttempts ?? 5;
+            const recalledSteps = await runScopedRecall(rag, recallText, RECALL_K_STEP, bundle.runId, RECALL_K_STEP * (maxAttempts + 1), ['step-result'], ctx.options);
+            const stepBlock = buildRecallBlock(recalledSteps, RECALL_MAX_CHARS_STEP);
+            if (stepBlock) {
+                staticPrefix.push({ role: 'user', content: stepBlock });
+            }
+            // Per-step tool-loop context strategy (record/form). Absent factory →
+            // LegacyAccumulateContextStrategy (byte-identical to the historical growing
+            // transcript).
+            const makeStrategy = () => (deps.toolLoopContextStrategyFactory ??
+                (() => new LegacyAccumulateContextStrategy()))({
+                run: { rag, runId: bundle.runId, meta, stepName: step.name },
+            });
+            // Resume / migration selection (Task 12). A step that suspended under the new
+            // design carries a serialized `contextStrategyState` → RESTORE it so the
+            // pre-suspend rounds (including any INTERNAL tool rounds before an external
+            // suspend) come back exactly as the executor last saw them. A PRE-RELEASE
+            // in-flight step carries only a raw `transcript` (no snapshot) → migrate it
+            // verbatim via the migration-only LegacyTranscriptContextStrategy (one release).
+            // Otherwise a fresh step.
+            let strategy;
+            if (inFlight?.contextStrategyState !== undefined) {
+                const state = inFlight.contextStrategyState;
+                // A migrated step persisted a LegacyTranscript snapshot ({rawMessages,
+                // newRounds}). Restore it through the SAME strategy type so its raw history
+                // + post-migration rounds survive a SECOND resume; a normal snapshot
+                // restores via the injected/default strategy. Discriminate on shape.
+                strategy =
+                    state.rawMessages !== undefined
+                        ? new LegacyTranscriptContextStrategy({ rawMessages: [] })
+                        : makeStrategy();
+                strategy.restore(state);
+            }
+            else if (inFlight?.transcript?.length) {
+                strategy = new LegacyTranscriptContextStrategy({
+                    rawMessages: inFlight.transcript,
+                });
+                // Adopted verbatim (rawMessages is copied) → clear the durable transcript so
+                // it only ever carries UN-recorded external-continuation pairs from here on.
+                // The next suspend snapshots this strategy → subsequent resumes take the
+                // restore branch above, so the raw history is never re-injected (no double).
+                inFlight.transcript.length = 0;
             }
             else {
-                // 'failed' — keep the same seq, mark awaiting-replan in the SAME persist so
-                // recovery routes by durable phase.
-                if (bundle.inFlightStep)
-                    bundle.inFlightStep.phase = 'awaiting-replan';
-                bundle.runPhase = 'executing';
+                strategy = makeStrategy(); // fresh step
             }
-            await persistBundle(deps.backend, sessionId, bundle);
-            return outcome;
-        };
-        const messages = [
-            {
-                role: 'system',
-                content: appendHint(EXECUTOR_SYSTEM, deps.config.subagents.executor?.hint),
-            },
-            {
-                role: 'user',
-                content: `Goal: ${bundle.goal}\nStep: ${step.name}\nInstructions: ${step.instructions}`,
-            },
-        ];
-        // Episodic recall: pull prior artifacts relevant to this step from
-        // session-memory and inject them as context. The session-memory rag shares
-        // the bundle backend, so restrict to artifact types (excludes the
-        // 'controller-bundle' infrastructure record). Bounded by k and length.
-        const recallText = step.instructions || step.name;
-        const maxAttempts = cfg.maxStepAttempts ?? 5;
-        const maxTool = cfg.maxToolCalls ?? 10;
-        // Per-kind run-scoped recall with GUARANTEED over-fetch bounds: step-result
-        // retries are bounded by maxStepAttempts (k×(maxStepAttempts+1)); mcp-results
-        // are NOT deduped on re-fetch here and toolCallCount RESETS per attempt, so one
-        // run can emit up to maxSteps × maxStepAttempts × maxToolCalls of them — over-
-        // fetch that full run bound so every distinct identityKey is seen before the cap.
-        const mcpBound = cfg.maxSteps * maxAttempts * maxTool;
-        const recalledSteps = await runScopedRecall(rag, recallText, RECALL_K_STEP, bundle.runId, RECALL_K_STEP * (maxAttempts + 1), ['step-result'], ctx.options);
-        const recalledMcp = await runScopedRecall(rag, recallText, RECALL_K_MCP, bundle.runId, mcpBound, ['mcp-result'], ctx.options);
-        // SEPARATE character budgets per kind: a single huge step-result cannot consume
-        // the whole budget and starve the MCP context (and vice-versa).
-        const stepBlock = buildRecallBlock(recalledSteps, RECALL_MAX_CHARS_STEP);
-        const mcpBlock = buildRecallBlock(recalledMcp, RECALL_MAX_CHARS_MCP);
-        const recallBlock = [stepBlock, mcpBlock].filter(Boolean).join('\n\n');
-        if (recallBlock) {
-            messages.push({ role: 'user', content: recallBlock });
-        }
-        // Durable transcript = static prefix (system/user/recall) + the dynamic
-        // executor/tool turns. On a resume/continuation the dynamic tail is rebuilt
-        // from inFlightStep.transcript so the executor sees the FULL exchange it had
-        // (prior tool rounds + the injected external result), not just a fragment.
-        const staticLen = messages.length;
-        if (inFlight && inFlight.transcript.length > 0) {
-            messages.push(...inFlight.transcript);
-        }
-        // Persist the dynamic tail after every executor/tool exchange so a suspend or
-        // crash never rebuilds with a shorter conversation than the executor saw.
-        const syncTranscript = async () => {
+            // Durable, bounded control-message tail (retries only). Aliased IN PLACE so
+            // push/prune mutate the persisted field; a legacy call with no inFlightStep gets
+            // an ephemeral local (no durable tail to persist).
+            let controlTail;
             if (inFlight) {
-                inFlight.transcript = messages.slice(staticLen);
-                await persistBundle(deps.backend, sessionId, bundle);
+                inFlight.controlTail = inFlight.controlTail ?? [];
+                controlTail = inFlight.controlTail;
             }
-        };
-        // Per-reference evidence: one recall per requires[] reference. A non-empty
-        // top-K does NOT prove the dependency is present — semantic recall returns the
-        // NEAREST artifact even at low relevance — so we hand the reviewer the TOP
-        // artifact's relevant fragment (Evidence.topArtifact) and let IT (the judging
-        // role) decide whether the ref is actually satisfied. `hit` is a coarse
-        // any-candidate flag. Gathered SEQUENTIALLY (NOT Promise.all): each
-        // relevantExtract is itself bounded-sequential, so the outer sequential loop
-        // keeps at most ONE embed request in flight at a time (rate-limit-safe).
-        const refs = step.requires && step.requires.length > 0 ? step.requires : [recallText];
-        const evBound = RECALL_K_STEP * (maxAttempts + 1) +
-            cfg.maxSteps * maxAttempts * (cfg.maxToolCalls ?? 10);
-        const evidence = [];
-        for (const ref of refs) {
-            const hits = await runScopedRecall(rag, ref, 1, bundle.runId, evBound, RECALL_ARTIFACT_TYPES, ctx.options);
-            const topArtifact = hits[0]
-                ? await relevantExtract(hits[0].content, ref, RECALL_EVIDENCE_CHARS, 
-                // biome-ignore lint/style/noNonNullAssertion: distance strategies require an embedder; the factory enforces it (Task 17).
-                deps.embedder, ctx.options)
-                : undefined;
-            evidence.push({ ref, hit: hits.length > 0, topArtifact });
-        }
-        // Tools offered to the executor = the INTERNAL (MCP) tools semantically
-        // relevant to THIS step (top-K from toolsRag) PLUS the per-request external
-        // (consumer-supplied) tools. The executor decides which to call; internal
-        // calls route through `callMcp`, external calls round-trip via `isExternalTool`.
-        const relevant = await deps.selectTools(step.instructions || step.name, TOOL_SELECT_K, ctx.options);
-        const offeredTools = [...relevant, ...(ctx.externalTools ?? [])];
-        // The executor may ONLY call a tool that was offered to it: an internal tool
-        // selected for this step, or a per-request external tool. Any other name
-        // (hallucinated / stale / not in the top-K) is rejected — never executed —
-        // so the semantic exposure boundary actually bounds what runs.
-        const offeredInternalNames = new Set(relevant.map((t) => t.name));
-        let retries = 0;
-        // (D) Persist a 'failed' step-result artifact for controller-level failures
-        // (reviewer unverifiable, executor error exhausted, maxToolCalls, unavailable
-        // tool) so the board can project the step's terminal state from artifacts alone.
-        const writeControlFailure = async (reason) => {
-            const seq = bundle.inFlightStep?.seq ?? bundle.nextSeq ?? 0;
-            const attempt = bundle.inFlightStep?.attempt ?? 0;
-            bundle.writeOrdinal = (bundle.writeOrdinal ?? 0) + 1;
-            await writeArtifact(rag, {
-                ...meta,
-                artifactType: 'step-result',
-                task: step.name,
-                runId: bundle.runId,
-                seq,
-                attempt,
-                status: 'failed',
-                note: reason,
-                remainder: '',
-                stepId: step.stepId,
-                digest: reason.slice(0, cfg.maxDigestChars ?? 500),
-                writeOrdinal: bundle.writeOrdinal,
-                content: '',
-            }, ctx.options);
-        };
-        // Inner loop handles tool routing / error retries until the executor
-        // produces content for this step (or the step suspends on an external tool).
-        while (true) {
-            const res = await deps.executor.send(messages, offeredTools);
-            logUsage?.('executor', res.usage);
-            if (res.kind === 'content') {
-                // Hold the executor's result; the reviewer (NOT the executor) decides the
-                // outcome. Default reviewer (no deps.reviewer) approves as 'ok' (legacy).
-                let review = deps.reviewer
-                    ? await deps.reviewer.review(step, evidence, res.content, {
-                        hint: deps.config.subagents.reviewer?.hint,
-                        logUsage,
-                        maxDigestChars: cfg.maxDigestChars ?? 500,
-                    })
-                    : {
-                        kind: 'outcome',
-                        outcome: {
-                            status: 'ok',
-                            approved: res.content,
-                            remainder: '',
-                            note: '',
-                            digest: res.content.slice(0, cfg.maxDigestChars ?? 500),
-                        },
-                    };
-                // Judge failure (provider error / malformed / contradictory ok-with-empty)
-                // is NOT a step failure: re-ask within maxReviewRetries, then ABORT (the
-                // outcome is unverifiable). Never mapped to settle('failed')/replan.
-                let reviewRetries = 0;
-                while (review.kind === 'judge-failure') {
-                    reviewRetries++;
-                    if (reviewRetries > (cfg.maxReviewRetries ?? 2)) {
-                        // The reviewer could not produce a usable verdict within the retry
-                        // budget (provider error / unparsable). DEGRADE to a failed step so the
-                        // planner replans, rather than aborting the whole run — the terminal
-                        // backstop is maxStepAttempts/maxSteps, not a single unverifiable verdict.
-                        bundle.budgets.stepsUsed++;
-                        await writeControlFailure(`reviewer unverifiable after ${cfg.maxReviewRetries ?? 2} retries: ${review.reason}`);
-                        bundle.plannerPrivate += `\n[seq ${bundle.inFlightStep?.seq ?? bundle.nextSeq ?? 0} ${step.name} failed] reviewer unverifiable after ${cfg.maxReviewRetries ?? 2} retries: ${review.reason}`;
-                        return settle('failed');
+            else {
+                controlTail = [];
+            }
+            // External CONTINUATION bridge: the resume preamble APPENDS the freshly
+            // resolved external assistant/tool pair(s) to inFlight.transcript. Record them
+            // as rounds ON TOP of the restored strategy so the executor continues from its
+            // own tool call, then CLEAR the transcript — they now live in the strategy, so
+            // leaving them would double-record on the next external round-trip. (The
+            // LegacyTranscript migration above already adopted AND cleared its transcript,
+            // so here the transcript holds ONLY the just-injected external pair — never the
+            // migrated raw history; the two never double-inject the same rounds.)
+            if (inFlight && inFlight.transcript.length > 0) {
+                const t = inFlight.transcript;
+                let i = 0;
+                while (i < t.length) {
+                    const assistant = t[i];
+                    i++;
+                    const results = [];
+                    while (i < t.length && t[i]?.role === 'tool') {
+                        results.push(t[i]);
+                        i++;
                     }
-                    review = await deps.reviewer.review(step, evidence, res.content, {
-                        hint: deps.config.subagents.reviewer?.hint,
-                        logUsage,
-                        maxDigestChars: cfg.maxDigestChars ?? 500,
-                    });
+                    if (assistant)
+                        await strategy.record({ assistant, results }, ctx.options);
                 }
-                const outcome = review.outcome;
+                inFlight.transcript.length = 0;
+            }
+            // Snapshot the strategy state + persist the bundle after every executor/tool
+            // exchange so a suspend or crash resumes with the same context the executor saw.
+            const persistExchange = async () => {
+                if (inFlight) {
+                    inFlight.contextStrategyState = strategy.snapshot();
+                    await persistBundle(deps.backend, sessionId, bundle);
+                }
+            };
+            // Per-reference evidence: one recall per requires[] reference. A non-empty
+            // top-K does NOT prove the dependency is present — semantic recall returns the
+            // NEAREST artifact even at low relevance — so we hand the reviewer the TOP
+            // artifact's relevant fragment (Evidence.topArtifact) and let IT (the judging
+            // role) decide whether the ref is actually satisfied. `hit` is a coarse
+            // any-candidate flag. Gathered SEQUENTIALLY (NOT Promise.all): each
+            // relevantExtract is itself bounded-sequential, so the outer sequential loop
+            // keeps at most ONE embed request in flight at a time (rate-limit-safe).
+            const refs = step.requires && step.requires.length > 0
+                ? step.requires
+                : [recallText];
+            const evBound = RECALL_K_STEP * (maxAttempts + 1) +
+                cfg.maxSteps * maxAttempts * (cfg.maxToolCalls ?? 10);
+            const evidence = [];
+            for (const ref of refs) {
+                const hits = await runScopedRecall(rag, ref, 1, bundle.runId, evBound, RECALL_ARTIFACT_TYPES, ctx.options);
+                const topArtifact = hits[0]
+                    ? await relevantExtract(hits[0].content, ref, RECALL_EVIDENCE_CHARS, 
+                    // biome-ignore lint/style/noNonNullAssertion: distance strategies require an embedder; the factory enforces it (Task 17).
+                    deps.embedder, ctx.options)
+                    : undefined;
+                evidence.push({ ref, hit: hits.length > 0, topArtifact });
+            }
+            // Tools offered to the executor = the INTERNAL (MCP) tools semantically
+            // relevant to THIS step (top-K from toolsRag) PLUS the per-request external
+            // (consumer-supplied) tools. The executor decides which to call; internal
+            // calls route through `callMcp`, external calls round-trip via `isExternalTool`.
+            const relevant = await deps.selectTools(step.instructions || step.name, TOOL_SELECT_K, ctx.options);
+            const offeredTools = [
+                ...relevant,
+                ...(ctx.externalTools ?? []),
+            ];
+            // The executor may ONLY call a tool that was offered to it: an internal tool
+            // selected for this step, or a per-request external tool. Any other name
+            // (hallucinated / stale / not in the top-K) is rejected — never executed —
+            // so the semantic exposure boundary actually bounds what runs.
+            const offeredInternalNames = new Set(relevant.map((t) => t.name));
+            let retries = 0;
+            // (D) Persist a 'failed' step-result artifact for controller-level failures
+            // (reviewer unverifiable, executor error exhausted, maxToolCalls, unavailable
+            // tool) so the board can project the step's terminal state from artifacts alone.
+            const writeControlFailure = async (reason) => {
                 const seq = bundle.inFlightStep?.seq ?? bundle.nextSeq ?? 0;
                 const attempt = bundle.inFlightStep?.attempt ?? 0;
-                // ONE post-review write carrying the COMPLETE Outcome + identity.
                 bundle.writeOrdinal = (bundle.writeOrdinal ?? 0) + 1;
                 await writeArtifact(rag, {
                     ...meta,
@@ -770,174 +788,334 @@ export class ControllerCoordinatorHandler {
                     runId: bundle.runId,
                     seq,
                     attempt,
-                    status: outcome.status,
-                    note: outcome.note,
-                    remainder: outcome.remainder,
+                    status: 'failed',
+                    note: reason,
+                    remainder: '',
                     stepId: step.stepId,
-                    digest: outcome.digest,
+                    digest: reason.slice(0, cfg.maxDigestChars ?? 500),
                     writeOrdinal: bundle.writeOrdinal,
-                    content: outcome.approved,
+                    content: '',
                 }, ctx.options);
+            };
+            // A controller-level (non-reviewer) cut: persist a 'failed' step-result +
+            // planner note (preserving today's wording via noteFor) + the TYPED durable
+            // ControlFailure, then settle('failed') so the planner replans at this seq.
+            const cutControlFailure = async (reason) => {
                 bundle.budgets.stepsUsed++;
-                const mapped = mapOutcome(outcome.status);
-                recordStepControl(bundle, {
-                    seq: bundle.inFlightStep?.seq ?? seq,
-                    name: step.name,
-                    status: outcome.status,
-                    note: outcome.note,
-                    remainder: outcome.remainder,
-                });
-                return settle(mapped);
-            }
-            if (res.kind === 'error') {
-                retries++;
-                if (retries <= cfg.maxRetries) {
-                    messages.push({
-                        role: 'user',
-                        content: `The previous attempt failed: ${res.error}. Retry the step.`,
-                    });
-                    await syncTranscript();
-                    continue;
+                await writeControlFailure(noteFor(reason));
+                bundle.plannerPrivate += `\n[seq ${inFlight?.seq ?? bundle.nextSeq ?? 0} ${step.name} control-failed] ${noteFor(reason)}`;
+                if (inFlight) {
+                    inFlight.phase = 'awaiting-replan';
+                    const typedReason = reason === 'maxToolCalls' || reason === 'step-timeout'
+                        ? reason
+                        : 'control-failure';
+                    inFlight.controlFailure = {
+                        reason: typedReason,
+                        seq: inFlight.seq,
+                    };
                 }
-                // Retries exhausted — feed the error back as the step result so the
-                // planner can replan on the next iteration.
-                bundle.budgets.stepsUsed++;
-                await writeControlFailure(`executor error: ${res.error}`);
-                bundle.plannerPrivate += `\n[step ${step.name} failed] ${res.error}`;
                 return settle('failed');
-            }
-            // res.kind === 'tool_call' → route the FIRST tool call.
-            const firstCall = res.toolCalls[0];
-            if (firstCall === undefined) {
-                // Empty tool-call array → treat as an executor error (retry/replan).
-                retries++;
-                if (retries <= cfg.maxRetries) {
-                    messages.push({
-                        role: 'user',
-                        content: 'The previous attempt produced an empty tool call. Retry the step.',
+            };
+            // Inner loop handles tool routing / error retries until the executor
+            // produces content for this step (or the step suspends on an external tool).
+            // The whole loop is wrapped so the step budget's timer is disposed on EVERY
+            // exit (settle / cut / suspend / abort / throw).
+            while (true) {
+                roundNo++;
+                // TIME/abort gate BEFORE each executor round (count is gated per tool call).
+                const rc = budget.shouldContinueRound(state());
+                if (!rc.continue)
+                    return cutControlFailure(rc.reason);
+                // Form the per-round executor context: the immutable prefix + the strategy's
+                // rounds, then the bounded control tail (retries). NEVER a growing raw array.
+                const messages = (await strategy.form({ prefix: staticPrefix, queryText: step.instructions }, ctx.options)).concat(controlTail);
+                // Merged signal into the executor call. A reject WHILE the step budget is
+                // aborted is a step-timeout cut (NOT the executor-error retry); a normal
+                // return after the budget fired is ALSO a step-timeout cut.
+                let res;
+                try {
+                    res = await deps.executor.send(messages, offeredTools, {
+                        ...ctx.options,
+                        signal: callSignal,
                     });
-                    await syncTranscript();
-                    continue;
                 }
-                bundle.budgets.stepsUsed++;
-                await writeControlFailure('empty tool call');
-                bundle.plannerPrivate += `\n[step ${step.name} failed] empty tool call`;
-                return settle('failed');
-            }
-            const call = toLlmToolCall(firstCall);
-            const name = call.name;
-            const args = call.arguments;
-            if (isExternalTool(name)) {
-                // External round-trips share the SAME durable toolCallCount/maxToolCalls
-                // bound as internal calls; check BEFORE surfacing so an external tool
-                // cannot exceed the cap. Exhausted → control-failed replan at the same seq.
-                if (inFlight && inFlight.toolCallCount + 1 > maxToolCalls) {
+                catch (e) {
+                    if (budget.signal.aborted)
+                        return cutControlFailure('step-timeout');
+                    throw e;
+                }
+                if (budget.signal.aborted)
+                    return cutControlFailure('step-timeout');
+                logUsage?.('executor', res.usage);
+                if (res.kind === 'content') {
+                    // Hold the executor's result; the reviewer (NOT the executor) decides the
+                    // outcome. Default reviewer (no deps.reviewer) approves as 'ok' (legacy).
+                    let review = deps.reviewer
+                        ? await deps.reviewer.review(step, evidence, res.content, {
+                            hint: deps.config.subagents.reviewer?.hint,
+                            logUsage,
+                            maxDigestChars: cfg.maxDigestChars ?? 500,
+                        })
+                        : {
+                            kind: 'outcome',
+                            outcome: {
+                                status: 'ok',
+                                approved: res.content,
+                                remainder: '',
+                                note: '',
+                                digest: res.content.slice(0, cfg.maxDigestChars ?? 500),
+                            },
+                        };
+                    // Judge failure (provider error / malformed / contradictory ok-with-empty)
+                    // is NOT a step failure: re-ask within maxReviewRetries, then ABORT (the
+                    // outcome is unverifiable). Never mapped to settle('failed')/replan.
+                    let reviewRetries = 0;
+                    while (review.kind === 'judge-failure') {
+                        reviewRetries++;
+                        if (reviewRetries > (cfg.maxReviewRetries ?? 2)) {
+                            // The reviewer could not produce a usable verdict within the retry
+                            // budget (provider error / unparsable). DEGRADE to a failed step so the
+                            // planner replans, rather than aborting the whole run — the terminal
+                            // backstop is maxStepAttempts/maxSteps, not a single unverifiable verdict.
+                            bundle.budgets.stepsUsed++;
+                            await writeControlFailure(`reviewer unverifiable after ${cfg.maxReviewRetries ?? 2} retries: ${review.reason}`);
+                            bundle.plannerPrivate += `\n[seq ${bundle.inFlightStep?.seq ?? bundle.nextSeq ?? 0} ${step.name} failed] reviewer unverifiable after ${cfg.maxReviewRetries ?? 2} retries: ${review.reason}`;
+                            return settle('failed');
+                        }
+                        review = await deps.reviewer.review(step, evidence, res.content, {
+                            hint: deps.config.subagents.reviewer?.hint,
+                            logUsage,
+                            maxDigestChars: cfg.maxDigestChars ?? 500,
+                        });
+                    }
+                    const outcome = review.outcome;
+                    const seq = bundle.inFlightStep?.seq ?? bundle.nextSeq ?? 0;
+                    const attempt = bundle.inFlightStep?.attempt ?? 0;
+                    // ONE post-review write carrying the COMPLETE Outcome + identity.
+                    bundle.writeOrdinal = (bundle.writeOrdinal ?? 0) + 1;
+                    await writeArtifact(rag, {
+                        ...meta,
+                        artifactType: 'step-result',
+                        task: step.name,
+                        runId: bundle.runId,
+                        seq,
+                        attempt,
+                        status: outcome.status,
+                        note: outcome.note,
+                        remainder: outcome.remainder,
+                        stepId: step.stepId,
+                        digest: outcome.digest,
+                        writeOrdinal: bundle.writeOrdinal,
+                        content: outcome.approved,
+                    }, ctx.options);
                     bundle.budgets.stepsUsed++;
-                    await writeControlFailure('tool-call budget exhausted (maxToolCalls)');
-                    bundle.plannerPrivate += `\n[seq ${inFlight.seq} ${step.name} control-failed] tool-call budget exhausted (maxToolCalls)`;
-                    inFlight.phase = 'awaiting-replan';
-                    inFlight.controlFailure = {
-                        reason: 'maxToolCalls',
-                        seq: inFlight.seq,
+                    const mapped = mapOutcome(outcome.status);
+                    recordStepControl(bundle, {
+                        seq: bundle.inFlightStep?.seq ?? seq,
+                        name: step.name,
+                        status: outcome.status,
+                        note: outcome.note,
+                        remainder: outcome.remainder,
+                    });
+                    return settle(mapped);
+                }
+                if (res.kind === 'error') {
+                    retries++;
+                    if (retries <= cfg.maxRetries) {
+                        controlTail.push({
+                            role: 'user',
+                            content: `The previous attempt failed: ${res.error}. Retry the step.`,
+                        });
+                        await persistExchange();
+                        continue;
+                    }
+                    // Retries exhausted — feed the error back as the step result so the
+                    // planner can replan on the next iteration.
+                    bundle.budgets.stepsUsed++;
+                    await writeControlFailure(`executor error: ${res.error}`);
+                    bundle.plannerPrivate += `\n[step ${step.name} failed] ${res.error}`;
+                    return settle('failed');
+                }
+                // res.kind === 'tool_call' → route the FIRST tool call.
+                const firstCall = res.toolCalls[0];
+                if (firstCall === undefined) {
+                    // Empty tool-call array → treat as an executor error (retry/replan).
+                    retries++;
+                    if (retries <= cfg.maxRetries) {
+                        controlTail.push({
+                            role: 'user',
+                            content: 'The previous attempt produced an empty tool call. Retry the step.',
+                        });
+                        await persistExchange();
+                        continue;
+                    }
+                    bundle.budgets.stepsUsed++;
+                    await writeControlFailure('empty tool call');
+                    bundle.plannerPrivate += `\n[step ${step.name} failed] empty tool call`;
+                    return settle('failed');
+                }
+                // Normalize the StreamToolCall (full or delta) into an LlmToolCall inline.
+                const call = 'arguments' in firstCall &&
+                    typeof firstCall.arguments === 'object' &&
+                    firstCall.arguments !== null
+                    ? {
+                        id: ('id' in firstCall && firstCall.id) || 'call',
+                        name: ('name' in firstCall && firstCall.name) || '',
+                        arguments: firstCall.arguments,
+                    }
+                    : (() => {
+                        let iArgs = {};
+                        const raw = 'arguments' in firstCall ? firstCall.arguments : undefined;
+                        if (typeof raw === 'string' && raw.length > 0) {
+                            try {
+                                iArgs = JSON.parse(raw);
+                            }
+                            catch {
+                                iArgs = {};
+                            }
+                        }
+                        return {
+                            id: ('id' in firstCall && firstCall.id) || 'call',
+                            name: ('name' in firstCall && firstCall.name) || '',
+                            arguments: iArgs,
+                        };
+                    })();
+                const name = call.name;
+                const args = call.arguments;
+                if (isExternalTool(name)) {
+                    // External round-trips share the SAME budget as internal calls; the
+                    // prospective count gate is consulted BEFORE the increment so an external
+                    // tool cannot exceed the cap. Cut → control-failed replan at the same seq.
+                    const g = budget.canExecuteTool(state());
+                    if (!g.continue)
+                        return cutControlFailure(g.reason);
+                    // Snapshot the strategy state SO FAR before we suspend (the resume injection
+                    // appends the external assistant/tool pair, recorded on the next invocation).
+                    if (inFlight)
+                        inFlight.contextStrategyState = strategy.snapshot();
+                    const extId = externalToolCallId(name, args);
+                    if (inFlight)
+                        inFlight.toolCallCount += 1;
+                    // The new marker REPLACES any prior pending (a fresh extId).
+                    bundle.pending = {
+                        kind: 'external-tool',
+                        extId,
+                        toolName: name,
+                        args,
+                        position: step.name,
                     };
+                    bundle.runState = 'suspended';
+                    await persistBundle(deps.backend, sessionId, bundle);
+                    this.surfaceToolCall(ctx, { id: extId, name, arguments: args }, usageNow?.());
+                    return 'suspended';
+                }
+                // The executor may only call a tool that was OFFERED to it this step. A
+                // name that is neither external nor in the internal top-K (hallucinated /
+                // stale / out-of-scope) is rejected — NOT executed — and fed back as a
+                // tool-not-available error so the executor retries with an offered tool.
+                if (!offeredInternalNames.has(name)) {
+                    retries++;
+                    if (retries <= cfg.maxRetries) {
+                        controlTail.push({
+                            role: 'user',
+                            content: `Tool "${name}" is not available for this step. Use only the tools provided to you.`,
+                        });
+                        await persistExchange();
+                        continue;
+                    }
+                    bundle.budgets.stepsUsed++;
+                    await writeControlFailure(`requested unavailable tool ${name}`);
+                    bundle.plannerPrivate += `\n[step ${step.name} failed] requested unavailable tool ${name}`;
                     return settle('failed');
                 }
-                // Sync the executor turns SO FAR into the durable transcript before we
-                // suspend (the resume injection appends the external assistant/tool pair).
-                await syncTranscript();
-                const extId = externalToolCallId(name, args);
-                if (inFlight)
+                // Prospective count gate BEFORE the increment (the before-increment model:
+                // the increment happens only after canExecuteTool allows the call).
+                const g = budget.canExecuteTool(state());
+                if (!g.continue)
+                    return cutControlFailure(g.reason);
+                // Durable round-trip count: ++ and persist BEFORE surfacing so it survives a
+                // resume (never a per-resume local).
+                if (inFlight) {
                     inFlight.toolCallCount += 1;
-                // The new marker REPLACES any prior pending (a fresh extId).
-                bundle.pending = {
-                    kind: 'external-tool',
-                    extId,
-                    toolName: name,
-                    args,
-                    position: step.name,
-                };
-                bundle.runState = 'suspended';
-                await persistBundle(deps.backend, sessionId, bundle);
-                this.surfaceToolCall(ctx, { id: extId, name, arguments: args }, usageNow?.());
-                return 'suspended';
-            }
-            // The executor may only call a tool that was OFFERED to it this step. A
-            // name that is neither external nor in the internal top-K (hallucinated /
-            // stale / out-of-scope) is rejected — NOT executed — and fed back as a
-            // tool-not-available error so the executor retries with an offered tool.
-            if (!offeredInternalNames.has(name)) {
-                retries++;
-                if (retries <= cfg.maxRetries) {
-                    messages.push({
-                        role: 'user',
-                        content: `Tool "${name}" is not available for this step. Use only the tools provided to you.`,
-                    });
-                    await syncTranscript();
-                    continue;
+                    await persistBundle(deps.backend, sessionId, bundle);
                 }
-                bundle.budgets.stepsUsed++;
-                await writeControlFailure(`requested unavailable tool ${name}`);
-                bundle.plannerPrivate += `\n[step ${step.name} failed] requested unavailable tool ${name}`;
-                return settle('failed');
-            }
-            // Durable round-trip count: ++ and persist BEFORE surfacing so it survives a
-            // resume (never a per-resume local).
-            if (inFlight) {
-                inFlight.toolCallCount += 1;
-                await persistBundle(deps.backend, sessionId, bundle);
-            }
-            if ((inFlight?.toolCallCount ?? 0) > maxToolCalls) {
-                // Controller-level failure (NOT a reviewer status): record durably and replan.
-                bundle.budgets.stepsUsed++;
-                await writeControlFailure('tool-call budget exhausted (maxToolCalls)');
-                bundle.plannerPrivate += `\n[seq ${inFlight?.seq ?? bundle.nextSeq ?? 0} ${step.name} control-failed] tool-call budget exhausted (maxToolCalls)`;
-                if (inFlight) {
-                    inFlight.phase = 'awaiting-replan';
-                    inFlight.controlFailure = {
-                        reason: 'maxToolCalls',
-                        seq: inFlight.seq,
-                    };
+                // Execute locally, memorize, re-send to the executor.
+                // FAIL LOUD: surface an MCP-unavailable failure as a terminal abort (not a
+                // silent empty response). The bridge (buildMcpBridge) throws an McpError
+                // IFF the injected classifier deemed it 'unavailable'; a tool-level error
+                // is returned as TEXT, never thrown. So ANY McpError reaching this catch is
+                // already a classifier-unavailable verdict — trust that throw-contract
+                // rather than re-checking the code (which would drop a CUSTOM classifier's
+                // decision → rethrow → outer catch swallow → (no response)). A non-McpError
+                // is a genuine unexpected error and is re-thrown for the outer handler.
+                let result;
+                try {
+                    result = await deps.callMcp(name, args, callSignal);
                 }
-                return settle('failed');
-            }
-            // Execute locally, memorize, re-send to the executor.
-            const result = await deps.callMcp(name, args);
-            bundle.writeOrdinal = (bundle.writeOrdinal ?? 0) + 1;
-            await writeArtifact(rag, {
-                ...meta,
-                artifactType: 'mcp-result',
-                toolName: name,
-                task: step.name,
-                runId: bundle.runId,
-                seq: inFlight?.seq,
-                attempt: inFlight?.attempt,
-                // Stable fetch identity (tool+args) for run-scoped recall dedup.
-                identityKey: externalToolCallId(name, args),
-                writeOrdinal: bundle.writeOrdinal,
-                content: result,
-            }, ctx.options);
-            // Feed the result back as a coherent assistant→tool turn (OpenAI protocol)
-            // so the executor LLM continues from its own tool call rather than seeing a
-            // bare user message. The assistant message carries the tool_call it made;
-            // the tool message carries the result keyed by the same id.
-            messages.push({
-                role: 'assistant',
-                content: null,
-                tool_calls: [
-                    {
-                        id: call.id,
-                        type: 'function',
-                        function: { name, arguments: JSON.stringify(args) },
+                catch (mcpErr) {
+                    // A step-timeout cancellation aborts the merged signal → the bridge rejects.
+                    // Map that to a step-timeout control-failure BEFORE the McpError escalate so
+                    // it is NOT mis-classified as MCP-unavailable (20.4.0 escalate order is
+                    // otherwise unchanged).
+                    if (budget.signal.aborted)
+                        return cutControlFailure('step-timeout');
+                    if (mcpErr instanceof McpError) {
+                        const now = deps.now ?? (() => new Date().toISOString());
+                        const terminalTtlMs = deps.terminalTtlMs ?? 24 * 60 * 60 * 1000;
+                        await this.abortTerminal(ctx, sessionId, bundle, `MCP server unavailable: ${mcpErr.message}`, now, terminalTtlMs, usageNow?.());
+                        return 'aborted';
+                    }
+                    throw mcpErr;
+                }
+                // Record this exchange as a coherent assistant→tool ROUND (OpenAI protocol)
+                // via the context strategy so the executor LLM continues from its own tool
+                // call. The strategy owns the per-round context (Window keeps a bounded
+                // buffer; RagRecall (Task 13) persists the mcp-result + recalls it) — the
+                // handler no longer writes the mcp-result artifact or grows a raw transcript.
+                // Durable monotonic write ordinal for this mcp-result write. RagRecall's
+                // run-scoped dedup (isBetterMcp) tie-breaks on writeOrdinal FIRST (then
+                // createdAt); since all mcp-result writes in a step share createdAt, a later
+                // same-identityKey fetch only wins with a strictly-higher ordinal. Increment
+                // BEFORE building the round so the value rides on it into strategy.record.
+                bundle.writeOrdinal = (bundle.writeOrdinal ?? 0) + 1;
+                const round = {
+                    assistant: {
+                        role: 'assistant',
+                        content: null,
+                        tool_calls: [
+                            {
+                                id: call.id,
+                                type: 'function',
+                                function: { name, arguments: JSON.stringify(args) },
+                            },
+                        ],
                     },
-                ],
-            });
-            messages.push({
-                role: 'tool',
-                tool_call_id: call.id,
-                content: result,
-            });
-            // The executor saw these turns → make them durable before the next round.
-            await syncTranscript();
+                    results: [
+                        {
+                            role: 'tool',
+                            tool_call_id: call.id,
+                            content: result,
+                        },
+                    ],
+                    // Stable fetch identity (tool+args) for run-scoped recall dedup. The
+                    // controller has no tool-level error classifier here — an unavailable MCP
+                    // server aborts BEFORE record; a returned string is a delivered result.
+                    meta: [
+                        { identityKey: externalToolCallId(name, args), isError: false },
+                    ],
+                    ordinal: bundle.writeOrdinal,
+                    roundId: undefined,
+                };
+                await strategy.record(round, ctx.options);
+                // A recorded round supersedes any pending control retry → prune the tail.
+                controlTail.length = 0;
+                // The executor saw this round → make the strategy state durable before next.
+                await persistExchange();
+            }
+        }
+        finally {
+            // Dispose the step budget (clears its wall-clock timer) on EVERY exit.
+            budget.dispose();
         }
     }
     // -- Escalation & surfacing (mirror StepperCoordinatorHandler) ----------
@@ -1004,12 +1182,18 @@ export class ControllerCoordinatorHandler {
         await persistBundle(deps.backend, sessionId, bundle);
         let answer;
         if (deps.finalizer && bundle.runId) {
+            // Recall the skills block ONCE (not per finalize retry — re-embedding on
+            // every attempt is wasteful; the recall is invariant across retries).
+            const skillsBlock = deps.skillsRecall
+                ? await deps.skillsRecall(bundle.goal, ctx.options)
+                : undefined;
             while (answer === undefined) {
                 try {
                     const composed = await deps.finalizer.finalize(bundle.goal, request, approved, {
                         hint: deps.config.subagents.finalizer?.hint,
                         logUsage,
                         log: (m) => dlog(m),
+                        skillsBlock,
                     });
                     // Empty-but-ok finalizer output is a JUDGE failure (spec), not a valid
                     // answer → throw so it retries within maxFinalizeRetries.
@@ -1080,7 +1264,7 @@ export class ControllerCoordinatorHandler {
     }
 }
 // ---------------------------------------------------------------------------
-// Episodic recall tuning
+// Goal-clarification helpers
 // ---------------------------------------------------------------------------
 /** Bare confirmations that, on a goal clarify, commit the evaluator's proposed
  *  target rather than the literal answer. Anything else = a refinement. */
@@ -1111,7 +1295,6 @@ function isAffirmation(answer) {
         .replace(/[.!]+$/, '');
     return AFFIRMATIONS.has(t);
 }
-/** Top-K tools surfaced from toolsRag per planner/step query. */
 /** Agnostic executor system prompt. Domain specifics (e.g. SAP/ABAP fact kinds)
  *  are layered on via `subagents.executor.hint` (see {@link appendHint}). */
 const EXECUTOR_SYSTEM = 'You are the executor. You have tools that read the live target system. ' +
@@ -1124,44 +1307,11 @@ const EXECUTOR_SYSTEM = 'You are the executor. You have tools that read the live
     'if the step asks for a LIST or overview, return the list; do NOT then go and ' +
     'fetch the full details of every listed item unless the step explicitly asks ' +
     'for per-item details.';
+/** Top-K tools surfaced from toolsRag per planner/step query. */
 const TOOL_SELECT_K = 20;
-/** Top-k recalled artifacts injected into the executor context per step. */
-/** Artifact types eligible for recall (excludes the 'controller-bundle' record
- *  that shares the same backend). */
-const RECALL_ARTIFACT_TYPES = ['step-result', 'mcp-result'];
-/** Per-kind recall counts (distinct artifacts kept after dedup + cap). */
-const RECALL_K_STEP = 4;
-const RECALL_K_MCP = 4;
-/** SEPARATE char budgets per kind, so a huge step-result cannot starve MCP context. */
-const RECALL_MAX_CHARS_STEP = 2000;
-const RECALL_MAX_CHARS_MCP = 2000;
-/** Char budget for a single per-`requires` evidence extract handed to the reviewer. */
-const RECALL_EVIDENCE_CHARS = 800;
 // ---------------------------------------------------------------------------
 // Pure helpers
 // ---------------------------------------------------------------------------
-/** Build a bounded "Relevant prior context" block from recalled artifacts under
- *  the given char budget, or undefined when there is nothing to inject. */
-function buildRecallBlock(hits, maxChars) {
-    if (hits.length === 0)
-        return undefined;
-    const parts = [];
-    let used = 0;
-    for (const h of hits) {
-        const c = h.content ?? '';
-        if (c.length === 0)
-            continue;
-        if (used + c.length > maxChars) {
-            parts.push(c.slice(0, maxChars - used));
-            break;
-        }
-        parts.push(c);
-        used += c.length;
-    }
-    if (parts.length === 0)
-        return undefined;
-    return `Relevant prior context:\n${parts.join('\n')}`;
-}
 /** Extract the user prompt from the request's textOrMessages. */
 function extractPrompt(textOrMessages) {
     if (typeof textOrMessages === 'string')
@@ -1172,131 +1322,6 @@ function extractPrompt(textOrMessages) {
     }
     return '';
 }
-/** Parse a planner content string into a NextStep, defensively. */
-/** Parse the planner's reply into a NextStep, tolerating ```json fences and
- *  surrounding prose. Returns null when no valid decision can be extracted — the
- *  caller treats that as a FORMAT error (re-ask the planner), NOT a rewind, so a
- *  badly-formatted reply never silently burns the rewind budget. */
-export function parseNextStep(content) {
-    const json = extractJsonObject(content);
-    if (json === null)
-        return null;
-    try {
-        const obj = JSON.parse(json);
-        if (obj.kind === 'done' && typeof obj.result === 'string')
-            return { kind: 'done', result: obj.result };
-        if (obj.kind === 'rewind' && typeof obj.reason === 'string')
-            return { kind: 'rewind', reason: obj.reason };
-        if (obj.kind === 'next' &&
-            obj.step &&
-            typeof obj.step.name === 'string' &&
-            typeof obj.step.instructions === 'string') {
-            // Validate requires[] so a non-string / empty / oversized reference never
-            // reaches the semantic query / embedder; a malformed value is a parse
-            // failure that drives the existing parse-retry.
-            const req = validateRequires(obj.step.requires);
-            if (req === false)
-                return null;
-            return {
-                kind: 'next',
-                step: {
-                    name: obj.step.name,
-                    instructions: obj.step.instructions,
-                    ...(obj.step.type ? { type: obj.step.type } : {}),
-                    ...(req ? { requires: req } : {}),
-                },
-            };
-        }
-    }
-    catch {
-        // fall through
-    }
-    return null;
-}
-/** Extract the first balanced JSON object from a planner reply, ignoring ```json
- *  fences and prose around it. String-aware (braces inside strings don't count).
- *  Returns null if no balanced object is present. */
-export function extractJsonObject(raw) {
-    const fence = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
-    const body = fence ? fence[1] : raw;
-    const start = body.indexOf('{');
-    if (start < 0)
-        return null;
-    let depth = 0;
-    let inStr = false;
-    let esc = false;
-    for (let i = start; i < body.length; i++) {
-        const ch = body[i];
-        if (inStr) {
-            if (esc)
-                esc = false;
-            else if (ch === '\\')
-                esc = true;
-            else if (ch === '"')
-                inStr = false;
-            continue;
-        }
-        if (ch === '"')
-            inStr = true;
-        else if (ch === '{')
-            depth++;
-        else if (ch === '}') {
-            depth--;
-            if (depth === 0)
-                return body.slice(start, i + 1);
-        }
-    }
-    return null;
-}
-/** Normalize a StreamToolCall (full or delta) into an LlmToolCall. */
-function toLlmToolCall(c) {
-    if ('arguments' in c &&
-        typeof c.arguments === 'object' &&
-        c.arguments !== null) {
-        // Full LlmToolCall: arguments is already a parsed object.
-        return {
-            id: ('id' in c && c.id) || 'call',
-            name: ('name' in c && c.name) || '',
-            arguments: c.arguments,
-        };
-    }
-    // Delta: arguments is a (possibly partial) JSON string.
-    let args = {};
-    const raw = 'arguments' in c ? c.arguments : undefined;
-    if (typeof raw === 'string' && raw.length > 0) {
-        try {
-            args = JSON.parse(raw);
-        }
-        catch {
-            args = {};
-        }
-    }
-    return {
-        id: ('id' in c && c.id) || 'call',
-        name: ('name' in c && c.name) || '',
-        arguments: args,
-    };
-}
-/** Reconstruct and render the live step-state board from artifacts.
- *  Returns '' when there is no runId (the board has nothing to show yet). */
-async function renderLiveBoard(rag, bundle, budget) {
-    const runId = bundle.runId;
-    if (!runId)
-        return '';
-    const [structure, claims] = await Promise.all([
-        readPlanDecisions(rag, runId),
-        readClaims(rag, runId),
-    ]);
-    const stepResults = await rag.list({ runId, artifactType: 'step-result' });
-    const board = reconstructBoard({
-        structure,
-        stepResults,
-        claims,
-        inFlight: bundle.inFlightStep,
-        pending: bundle.pending,
-    });
-    return renderBoard(board, budget);
-}
 /** Synthesize the strict KnowledgeEntryMetadata for controller artifacts. */
 function synthMeta(ctx, sessionId) {
     const traceId = ctx.options?.trace?.traceId ?? sessionId;
@@ -1328,163 +1353,4 @@ function recordStepControl(bundle, rec) {
             (rec.note ? ` ${rec.note}` : '') +
             (rec.remainder ? ` remainder: ${rec.remainder}` : '');
 }
-/** Gather the run's approved results, one per seq, resolved by outcome precedence
- *  (ok/exists > partial > failed), ordered by seq. Reconstructs the complete
- *  Outcome from artifact metadata (status/note/remainder) + content. */
-async function collectApproved(rag, runId) {
-    const all = await rag.list({ runId, artifactType: 'step-result' });
-    const bySeq = new Map();
-    for (const e of all) {
-        const seq = e.metadata.seq ?? 0;
-        const o = {
-            status: (e.metadata.status ?? 'failed'),
-            approved: e.content,
-            remainder: e.metadata.remainder ?? '',
-            note: e.metadata.note ?? '',
-        };
-        const arr = bySeq.get(seq);
-        if (arr)
-            arr.push(o);
-        else
-            bySeq.set(seq, [o]);
-    }
-    const out = [];
-    for (const [seq, outcomes] of [...bySeq.entries()].sort((a, b) => a[0] - b[0])) {
-        const resolved = resolveByPrecedence(outcomes);
-        if (resolved && resolved.status !== 'failed')
-            out.push({ seq, content: resolved.approved });
-    }
-    return out;
-}
-/** The ONE run-scoped results-RAG recall primitive — used by BOTH the whole-step
- *  recall AND the per-`requires` evidence. EMBEDDING-based similarity via the
- *  backend's semantic query (NO homemade lexical scoring): the backend embeds the
- *  query + ranks by vector similarity, with the `runId` filter applied PRE-cap.
- *  Over-fetch `kPrime` (caller-supplied so the duplication bound is justified PER
- *  KIND), then dedup and cap to `k`. Dedup: step-results (have `seq`) →
- *  precedence-winner per seq; mcp-results → by `identityKey`. Embedding rank order
- *  is preserved through the dedup.
- *  `options` is forwarded into the embedder so recall-time embeds are metered. */
-export async function runScopedRecall(rag, text, k, runId, kPrime, artifactType, options) {
-    const hits = await rag.query(text, {
-        k: kPrime,
-        filter: { runId, artifactType },
-        options,
-    });
-    const bestStep = new Map();
-    const bestMcp = new Map();
-    for (const e of hits) {
-        if (e.metadata.seq !== undefined && e.metadata.status !== undefined) {
-            const prev = bestStep.get(e.metadata.seq);
-            if (!prev || isBetterStep(e, prev))
-                bestStep.set(e.metadata.seq, e);
-        }
-        else if (e.metadata.identityKey) {
-            const prev = bestMcp.get(e.metadata.identityKey);
-            if (!prev || isBetterMcp(e, prev))
-                bestMcp.set(e.metadata.identityKey, e);
-        }
-    }
-    // Walk hits in embedding-rank order; emit each (runId,seq) / identityKey once.
-    const out = [];
-    const seenSeq = new Set();
-    const seenMcp = new Set();
-    for (const e of hits) {
-        if (e.metadata.seq !== undefined && e.metadata.status !== undefined) {
-            if (seenSeq.has(e.metadata.seq))
-                continue;
-            seenSeq.add(e.metadata.seq);
-            // biome-ignore lint/style/noNonNullAssertion: bestStep has this seq (set above).
-            out.push(bestStep.get(e.metadata.seq));
-        }
-        else if (e.metadata.identityKey) {
-            if (seenMcp.has(e.metadata.identityKey))
-                continue;
-            seenMcp.add(e.metadata.identityKey);
-            // biome-ignore lint/style/noNonNullAssertion: bestMcp has this key (set above).
-            out.push(bestMcp.get(e.metadata.identityKey));
-        }
-        else {
-            out.push(e);
-        }
-        if (out.length >= k)
-            break;
-    }
-    return out.slice(0, k);
-}
-/** Outcome-precedence rank for step-result dedup (ok/exists > partial > failed). */
-function rankStatus(s) {
-    return s === 'ok' || s === 'exists'
-        ? 3
-        : s === 'partial'
-            ? 2
-            : s === 'failed'
-                ? 1
-                : 0;
-}
-/** True when candidate `a` is a better winner than current `b` for step-result
- *  dedup. Latest-wins by EXECUTION IDENTITY, not by semantic-rank position:
- *  1. Higher status rank wins; on tie →
- *  2. Higher attempt wins; on further tie →
- *  3. Higher writeOrdinal wins (tie-breaks same-timestamp artifacts from one run); on tie →
- *  4. Later createdAt wins (missing = older: compare with '' as sentinel). */
-function isBetterStep(a, b) {
-    const ra = rankStatus(a.metadata.status);
-    const rb = rankStatus(b.metadata.status);
-    if (ra !== rb)
-        return ra > rb;
-    const aa = a.metadata.attempt ?? 0;
-    const ba = b.metadata.attempt ?? 0;
-    if (aa !== ba)
-        return aa > ba;
-    const ao = a.metadata.writeOrdinal ?? -1;
-    const bo = b.metadata.writeOrdinal ?? -1;
-    if (ao !== bo)
-        return ao > bo;
-    return (a.metadata.createdAt ?? '') > (b.metadata.createdAt ?? '');
-}
-/** True when candidate `a` is a better winner than current `b` for mcp-result
- *  dedup. Latest-fetch wins by writeOrdinal first (handles same-timestamp), then
- *  falls back to createdAt (missing = older). */
-function isBetterMcp(a, b) {
-    const ao = a.metadata.writeOrdinal ?? -1;
-    const bo = b.metadata.writeOrdinal ?? -1;
-    if (ao !== bo)
-        return ao > bo;
-    return (a.metadata.createdAt ?? '') > (b.metadata.createdAt ?? '');
-}
-const MAX_EXTRACT_WINDOWS = 64;
-/** Return the ≤`maxChars` fragment of `content` most similar to `ref` by EMBEDDING
- *  (NOT ASCII lexical overlap). DIRECT single-pass ranking: every candidate is
- *  scored on its own. The SCORED window IS the RETURNED body: candidates are
- *  `body = maxChars - 2` chars (head+tail '…' reserved up front), so the
- *  highest-scoring fragment is never truncated by the markers. Stride is 50%
- *  overlap, widened to span the whole content within MAX_EXTRACT_WINDOWS windows
- *  (point coverage for content ≤ MAX_EXTRACT_WINDOWS×maxChars; larger thins to
- *  non-overlapping, best-effort). Embeds are SEQUENTIAL and BOUNDED to ≤
- *  MAX_EXTRACT_WINDOWS + 1 — touches NO public embedder API (batch is a deferred
- *  optimization). Result STRICTLY ≤ maxChars; tiny maxChars (< 3) → bare slice.
- *  The `requires` ref is English (planner invariant) → a normal embedder suffices. */
-export async function relevantExtract(content, ref, maxChars, embedder, options) {
-    if (content.length <= maxChars)
-        return content;
-    if (maxChars < 3)
-        return content.slice(0, Math.max(0, maxChars));
-    const body = maxChars - 2;
-    const stride = Math.max(Math.floor(body / 2), Math.ceil(content.length / MAX_EXTRACT_WINDOWS));
-    const { vector: q } = await embedder.embed(ref, options);
-    let bestStart = 0;
-    let bestScore = Number.NEGATIVE_INFINITY;
-    for (let s = 0; s < content.length; s += stride) {
-        const { vector } = await embedder.embed(content.slice(s, s + body), options);
-        const score = cosine(q, vector);
-        if (score > bestScore) {
-            bestScore = score;
-            bestStart = s;
-        }
-    }
-    const head = bestStart > 0 ? '…' : '';
-    const tail = bestStart + body < content.length ? '…' : '';
-    return head + content.slice(bestStart, bestStart + body) + tail;
-}
 //# sourceMappingURL=controller-coordinator-handler.js.map