@mcp-abap-adt/llm-agent-server-libs 20.4.0 → 20.6.0

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

@@ -1,12 +1,13 @@
 import { externalToolCallId, McpError, } from '@mcp-abap-adt/llm-agent';
-import { summaryToUsage, } from '@mcp-abap-adt/llm-agent-libs';
+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_MCP, RECALL_K_STEP, RECALL_MAX_CHARS_MCP, RECALL_MAX_CHARS_STEP, relevantExtract, runScopedRecall, } from './recall.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';
@@ -563,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);
+                }
+                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);
                 }
-                const outcome = review.outcome;
+            };
+            // 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,
@@ -748,219 +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');
-            }
-            // 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,
+                catch (e) {
+                    if (budget.signal.aborted)
+                        return cutControlFailure('step-timeout');
+                    throw e;
                 }
-                : (() => {
-                    let iArgs = {};
-                    const raw = 'arguments' in firstCall ? firstCall.arguments : undefined;
-                    if (typeof raw === 'string' && raw.length > 0) {
-                        try {
-                            iArgs = JSON.parse(raw);
-                        }
-                        catch {
-                            iArgs = {};
+                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++;
+                    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;
                     }
-                    return {
+                    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: iArgs,
+                        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,
                     };
-                })();
-            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) {
+                    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('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,
-                    };
+                    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.
-            // 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);
-            }
-            catch (mcpErr) {
-                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';
+                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;
                 }
-                throw mcpErr;
-            }
-            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) },
+                // 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) ----------