@mcp-abap-adt/llm-agent-server-libs 19.1.2 → 19.2.0

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

@@ -1,11 +1,16 @@
 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 { writeArtifact } from './memorizer.js';
-import { resolveNeed } from './need-resolver.js';
+import { resolveByPrecedence } from './outcome.js';
 import { makePlanner } from './planner.js';
 import { appendHint } from './prompts.js';
-import { hydrateBundle, persistBundle } from './session-bundle.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';
 // ---------------------------------------------------------------------------
 // Debug logging — gated behind DEBUG_CONTROLLER (e.g. DEBUG_CONTROLLER=1).
 // Surfaces the steps the planner delegates and per-role/total token usage to
@@ -27,10 +32,12 @@ export function makeLogUsage(requestLogger, requestId, models) {
         if (!u)
             return;
         const model = role === 'finalizer'
-            ? models.planner
-            : role === 'embedding'
-                ? 'embedder'
-                : (models[role] ?? 'unknown');
+            ? (models.finalizer ?? models.planner)
+            : role === 'reviewer'
+                ? (models.reviewer ?? models.planner)
+                : role === 'embedding'
+                    ? 'embedder'
+                    : (models[role] ?? 'unknown');
         requestLogger.logLlmCall({
             component: role,
             model,
@@ -73,6 +80,11 @@ export class ControllerCoordinatorHandler {
     }
     async execute(ctx, _config, _span) {
         const deps = this.deps;
+        // Seams resolved once per execute(); consumed by Task 11+ (reviewer/finalizer/run-scope).
+        const now = deps.now ?? (() => new Date().toISOString());
+        const mintRunId = deps.runIdMinter ??
+            (() => `run-${now()}-${Math.round(Math.random() * 1e9)}`);
+        const terminalTtlMs = deps.terminalTtlMs ?? 24 * 60 * 60 * 1000;
         const sessionId = ctx.sessionId;
         const prompt = extractPrompt(ctx.textOrMessages);
         const rag = await deps.knowledgeRagFor(sessionId);
@@ -98,30 +110,196 @@ export class ControllerCoordinatorHandler {
         // with it rather than blindly re-running the suspended step. Set in the
         // external-tool resume branch below.
         let resumedExternal = false;
+        // Marks a LIVE external-tool continuation (the result is injected into the
+        // in-flight step's transcript and the step re-runs, bounded by toolCallCount —
+        // NOT charged to resumeCount). Block (A) consumes it; Task 14 SETS it from the
+        // artifact-first external-resume path. Until then it stays false and every
+        // re-run of an in-flight executing step is charged as a crash-replay (correct).
+        let externalContinuation = false;
+        // -- Classification + three-stage recovery ------------------------------
+        // Strict ordered classification (newRun > explicit-key strict > fingerprint of
+        // an in-flight active run). STAGE 1 of recovery is the terminal-store check for
+        // the resolved runId, run for ANY phase BEFORE consuming pending or routing by
+        // runPhase — so a crash between the store-first terminal write and the bundle
+        // flip can never re-run an already-finished run. A 'fresh' classification wipes
+        // all run-scoped state and mints a new runId; a 'resume' keeps everything and
+        // falls through to the pending/phase routing below.
+        const explicitKey = ctx.options?.runId;
+        const newRun = ctx.options?.newRun ?? false;
+        const keyForTerminal = explicitKey ?? bundle.runId;
+        const terminalExists = keyForTerminal
+            ? (await readTerminal(deps.backend, sessionId, keyForTerminal, now())) !==
+                undefined
+            : false;
+        const cls = classifyRequest({
+            bundle,
+            incomingRequest: prompt,
+            explicitKey,
+            newRun,
+            terminalExists,
+        });
+        if (cls.kind === 'replay') {
+            const out = await readTerminal(deps.backend, sessionId, cls.runId, now());
+            if (out) {
+                if (out.kind === 'success')
+                    this.surfaceFinal(ctx, out.answer, usageNow());
+                else
+                    this.surfaceFinal(ctx, `Error: ${out.error}`, usageNow());
+                return true;
+            }
+            // Expired between classify and read → fall through to a fresh run.
+            resetRun(bundle, prompt);
+            bundle.runId = mintRunId();
+            await persistBundle(deps.backend, sessionId, bundle);
+        }
+        else if (cls.kind === 'not-found') {
+            return this.escalate(ctx, sessionId, bundle, 'this run is no longer resumable — start a new request', usageNow());
+        }
+        else if (cls.kind === 'fresh') {
+            resetRun(bundle, prompt);
+            bundle.runId = mintRunId();
+            await persistBundle(deps.backend, sessionId, bundle);
+        }
+        else if (cls.kind === 'resume' && bundle.runId) {
+            // STAGE 1 (terminal-first, any phase): a stored terminal outcome wins over the
+            // persisted runPhase — adopt it and STOP, never re-run the phase.
+            const term = await readTerminal(deps.backend, sessionId, bundle.runId, now());
+            if (term) {
+                bundle.runState = 'terminal';
+                await persistBundle(deps.backend, sessionId, bundle);
+                if (term.kind === 'success')
+                    this.surfaceFinal(ctx, term.answer, usageNow());
+                else
+                    this.surfaceFinal(ctx, `Error: ${term.error}`, usageNow());
+                return true;
+            }
+            // No terminal → STAGE 2 (consume pending) / STAGE 3 (route by phase) are the
+            // existing pending-resume block + the main loop's block (A) below.
+        }
+        // Finalizing-phase crash recovery: a resume in runPhase 'finalizing' with NO
+        // terminal entry (stage-1 above already checked) means the finalizer never
+        // completed → re-run it (finalize() charges finalizeAttempt under
+        // finalizeCallInFlight, checks the cap, applies onFinalizeExhausted).
+        if (cls.kind === 'resume' &&
+            bundle.runState === 'active' &&
+            bundle.runPhase === 'finalizing') {
+            return this.finalize(ctx, sessionId, bundle, rag, prompt, logUsage, usageNow, now, terminalTtlMs);
+        }
         // -- Resume from a persisted pending marker -----------------------------
+        // Planner is constructed BEFORE the resume preamble: the artifact-first
+        // external-resume adopt below calls planner.commit() to keep the adaptive
+        // planCursor in lockstep with nextSeq. Stateless construction; the main loop
+        // reuses this same instance.
+        const planner = makePlanner(deps.config.planner ?? 'incremental', deps.planner, deps.config.subagents.planner?.hint, deps.skillsRecall);
         if (bundle.pending?.kind === 'external-tool') {
             const { extId, toolName } = bundle.pending;
-            const result = ctx.externalResults?.get(extId);
-            if (result === undefined) {
-                // No result yet → re-surface the same external tool call and suspend.
-                this.surfaceToolCall(ctx, {
-                    id: extId,
-                    name: toolName,
-                    arguments: (bundle.pending.args ?? {}),
-                }, usageNow());
-                return true;
+            const seq = bundle.inFlightStep?.seq;
+            const attempt = bundle.inFlightStep?.attempt;
+            // STAGE 1 — artifact-first: did THIS attempt already commit a result (e.g.
+            // a crash AFTER the step finished but BEFORE the bundle flip)? Adopt it and
+            // skip the re-call entirely.
+            if (bundle.runId !== undefined &&
+                seq !== undefined &&
+                attempt !== undefined) {
+                const existing = await rag.list({
+                    runId: bundle.runId,
+                    seq,
+                    attempt,
+                    artifactType: 'step-result',
+                });
+                const resolved = resolveByPrecedence(existing.map((e) => ({
+                    status: (e.metadata.status ?? 'failed'),
+                    approved: e.content,
+                    remainder: e.metadata.remainder ?? '',
+                    note: e.metadata.note ?? '',
+                })));
+                if (resolved) {
+                    bundle.pending = undefined;
+                    bundle.runState = 'active';
+                    // Same commit side effects as settle(), incl. planner.commit() so the
+                    // adaptive planCursor advances with nextSeq.
+                    const mapped = mapOutcome(resolved.status);
+                    bundle.lastOutcome = mapped;
+                    planner.commit?.(bundle, mapped);
+                    recordStepControl(bundle, {
+                        seq,
+                        name: bundle.inFlightStep?.step.name ?? 'step',
+                        status: resolved.status,
+                        note: resolved.note,
+                        remainder: resolved.remainder,
+                    });
+                    if (resolved.status === 'failed') {
+                        if (bundle.inFlightStep)
+                            bundle.inFlightStep.phase = 'awaiting-replan';
+                    }
+                    else {
+                        bundle.nextSeq = (bundle.nextSeq ?? 0) + 1;
+                        bundle.inFlightStep = undefined;
+                        bundle.runPhase = 'planning';
+                    }
+                    await persistBundle(deps.backend, sessionId, bundle);
+                }
+            }
+            // STAGE 2 — no adopted artifact: route by the external result.
+            if (bundle.pending?.kind === 'external-tool') {
+                const result = ctx.externalResults?.get(extId);
+                if (result === undefined) {
+                    // No result yet → re-surface the same external tool call and suspend.
+                    this.surfaceToolCall(ctx, {
+                        id: extId,
+                        name: toolName,
+                        arguments: (bundle.pending.args ?? {}),
+                    }, usageNow());
+                    return true;
+                }
+                bundle.writeOrdinal = (bundle.writeOrdinal ?? 0) + 1;
+                await writeArtifact(rag, {
+                    ...meta,
+                    artifactType: 'mcp-result',
+                    toolName,
+                    task: bundle.pending.position,
+                    runId: bundle.runId,
+                    seq: bundle.inFlightStep?.seq,
+                    attempt: bundle.inFlightStep?.attempt,
+                    // Stable fetch identity (tool+args) so run-scoped recall dedups
+                    // duplicate fetches of the same object across attempts.
+                    identityKey: extId,
+                    writeOrdinal: bundle.writeOrdinal,
+                    content: result,
+                }, ctx.options);
+                if (bundle.inFlightStep) {
+                    // External CONTINUATION: inject the tool result into the durable
+                    // transcript so the loop RE-RUNS the in-flight step (the executor
+                    // continues from its own tool call). Bounded by toolCallCount, NOT a
+                    // crash-replay — externalContinuation tells block (A) not to charge
+                    // resumeCount when it re-runs the step this invocation.
+                    bundle.inFlightStep.transcript.push({
+                        role: 'assistant',
+                        content: null,
+                        tool_calls: [
+                            {
+                                id: extId,
+                                type: 'function',
+                                function: {
+                                    name: toolName,
+                                    arguments: JSON.stringify(bundle.pending.args ?? {}),
+                                },
+                            },
+                        ],
+                    }, { role: 'tool', tool_call_id: extId, content: result });
+                    bundle.pending = undefined;
+                    bundle.runState = 'active';
+                    externalContinuation = true;
+                }
+                else {
+                    // Legacy path (no inFlightStep — e.g. a seeded adaptive bundle): feed the
+                    // result via plannerPrivate and let the planner replan.
+                    bundle.plannerPrivate += `\n[external tool ${toolName} result] ${result}`;
+                    bundle.pending = undefined;
+                    resumedExternal = true;
+                }
+                await persistBundle(deps.backend, sessionId, bundle);
             }
-            // Tool result arrived — record it and let the loop continue planning.
-            await writeArtifact(rag, {
-                ...meta,
-                artifactType: 'mcp-result',
-                toolName,
-                task: bundle.pending.position,
-                content: result,
-            });
-            bundle.plannerPrivate += `\n[external tool ${toolName} result] ${result}`;
-            bundle.pending = undefined;
-            resumedExternal = true;
         }
         else if (bundle.pending?.kind === 'clarify') {
             // The incoming prompt is the human's answer to the clarify question.
@@ -132,15 +310,41 @@ export class ControllerCoordinatorHandler {
             // treated as a refinement and becomes the goal verbatim.
             if (bundle.pending.position === 'goal') {
                 const answer = prompt.trim();
+                if (answer.length === 0) {
+                    // Empty/whitespace is not an established goal — stay suspended, re-ask
+                    // (deterministic clarify-resume: never commit an empty goal).
+                    this.surfaceClarify(ctx, bundle.pending.question, usageNow());
+                    return true;
+                }
                 const proposed = bundle.pending.proposedTarget;
                 bundle.goal = proposed && isAffirmation(answer) ? proposed : answer;
+                bundle.runState = 'active';
+                bundle.runPhase = 'planning';
             }
             bundle.plannerPrivate += `\n[clarify answer] ${prompt}`;
             bundle.pending = undefined;
+            await persistBundle(deps.backend, sessionId, bundle);
         }
         // -- Establish the goal (evaluator) -------------------------------------
         if (!bundle.goal) {
+            // Evaluator crash-guard: a prior crash mid-call left evalCallInFlight set →
+            // charge evalResumeCount; exhausting maxEvalResumes is a TERMINAL abort
+            // (store-first), NOT an escalate — a durable resume budget, like the planner.
+            if (bundle.evalCallInFlight) {
+                bundle.evalResumeCount = (bundle.evalResumeCount ?? 0) + 1;
+                if (bundle.evalResumeCount > (deps.config.budgets.maxEvalResumes ?? 3)) {
+                    await this.abortTerminal(ctx, sessionId, bundle, 'evaluator resume budget exhausted', now, terminalTtlMs, usageNow());
+                    return true;
+                }
+            }
+            bundle.evalCallInFlight = true;
+            bundle.runPhase = 'evaluating';
+            await persistBundle(deps.backend, sessionId, bundle);
             const outcome = await establishTargetState({ evaluator: deps.evaluator, embedder: deps.embedder }, prompt, deps.config.targetState, ctx.options, deps.config.subagents.evaluator?.hint);
+            // The call completed (a malformed/needs-confirmation result is still a
+            // completed call) → clear the in-flight marker + reset the resume counter.
+            bundle.evalCallInFlight = false;
+            bundle.evalResumeCount = 0;
             logUsage('evaluator', outcome.usage);
             if (outcome.kind === 'needs-confirmation') {
                 // Persist the proposed target with the pending marker so a confirmation
@@ -151,12 +355,15 @@ export class ControllerCoordinatorHandler {
                     position: 'goal',
                     proposedTarget: outcome.proposedTarget,
                 };
+                bundle.runState = 'suspended';
                 await persistBundle(deps.backend, sessionId, bundle);
                 this.surfaceClarify(ctx, outcome.question, usageNow());
                 return true;
             }
             bundle.goal = outcome.goal;
         }
+        // (runId is guaranteed by the classification preamble: a fresh/expired-replay
+        // run mints one, a resume already has one — so no separate mint guard here.)
         // -- Main loop ----------------------------------------------------------
         // The planner plans by INTENT — it is NOT shown a tool catalog. A prompt-level
         // catalog (selected once from goal+prompt) was too coarse: it mis-surfaced
@@ -166,14 +373,111 @@ export class ControllerCoordinatorHandler {
         // runs (see runStep → selectTools). The agnostic planner prompt already tells
         // it to plan fetch steps ("the executor picks the exact one").
         const cfg = deps.config.budgets;
+        const boardBudget = {
+            maxDigestChars: cfg.maxDigestChars ?? 500,
+            maxIntentChars: cfg.maxIntentChars ?? 120,
+            maxActiveSteps: cfg.maxActiveSteps ?? 16,
+            maxBoardChars: cfg.maxBoardChars ?? 12000,
+            keepRecentDigests: cfg.keepRecentDigests ?? 8,
+        };
         let planParseRetries = 0;
-        const planner = makePlanner(deps.config.planner ?? 'incremental', deps.planner, deps.config.subagents.planner?.hint);
         // bundle.lastOutcome is the SINGLE source of truth for the last step's
         // outcome — durable, so a resume after a FAILED step replans instead of
         // repeating it. runStep.settle() sets it; the adaptive replan branch clears it
         // once the failure has been consumed into a new plan (so a crash after the
         // replan, or a finalizer retry after an empty replan, does NOT replan again).
         while (bundle.budgets.stepsUsed < cfg.maxSteps) {
+            const inf = bundle.inFlightStep;
+            if (inf && inf.phase === 'executing' && !resumedExternal) {
+                // Reconcile by THIS attempt's resolved artifact first.
+                const committed = await rag.list({
+                    runId: bundle.runId,
+                    seq: inf.seq,
+                    attempt: inf.attempt,
+                    artifactType: 'step-result',
+                });
+                const resolved = resolveByPrecedence(committed.map((e) => ({
+                    status: (e.metadata.status ?? 'failed'),
+                    approved: e.content,
+                    remainder: e.metadata.remainder ?? '',
+                    note: e.metadata.note ?? '',
+                })));
+                if (resolved) {
+                    // Already committed → adopt, do NOT re-run. Same commit side effects as
+                    // settle(), including planner.commit() so the adaptive planCursor advances
+                    // in lockstep with nextSeq.
+                    const mapped = mapOutcome(resolved.status);
+                    bundle.lastOutcome = mapped;
+                    planner.commit?.(bundle, mapped);
+                    recordStepControl(bundle, {
+                        seq: inf.seq,
+                        name: inf.step.name,
+                        status: resolved.status,
+                        note: resolved.note,
+                        remainder: resolved.remainder,
+                    });
+                    if (resolved.status === 'failed') {
+                        inf.phase = 'awaiting-replan';
+                    }
+                    else {
+                        bundle.nextSeq = inf.seq + 1;
+                        bundle.inFlightStep = undefined;
+                        bundle.runPhase = 'planning';
+                    }
+                    await persistBundle(deps.backend, sessionId, bundle);
+                    continue;
+                }
+                // No artifact for this attempt → re-run the SAME step directly. Distinguish a
+                // live external CONTINUATION (bounded by toolCallCount) from a crash-replay
+                // (charged to resumeCount).
+                if (externalContinuation) {
+                    externalContinuation = false;
+                }
+                else {
+                    inf.resumeCount += 1;
+                    if (inf.resumeCount > (cfg.maxStepResumes ?? 3)) {
+                        await this.abortTerminal(ctx, sessionId, bundle, `step "${inf.step.name}" exceeded maxStepResumes`, now, terminalTtlMs, usageNow());
+                        return true;
+                    }
+                }
+                await persistBundle(deps.backend, sessionId, bundle);
+                // COORDINATOR OVERRIDE — use the ACTUAL runStep param order (now/terminalTtlMs
+                // BEFORE logUsage). The plan example shows them last; that is WRONG.
+                const completed = await this.runStep(ctx, sessionId, bundle, rag, meta, inf.step, isExternalTool, logUsage, usageNow, (o) => planner.commit?.(bundle, o));
+                if (completed === 'suspended' || completed === 'aborted')
+                    return true;
+                continue;
+            }
+            // Planner crash-guard: a prior crash mid-call left plannerCallInFlight set →
+            // charge plannerResumeCount; exhausting maxPlannerResumes is a TERMINAL abort
+            // (store-first). The adaptive replan runs through planner.next too, so this one
+            // guard covers the awaiting-replan replan with no separate site.
+            if (bundle.plannerCallInFlight) {
+                bundle.plannerResumeCount = (bundle.plannerResumeCount ?? 0) + 1;
+                if (bundle.plannerResumeCount > (cfg.maxPlannerResumes ?? 3)) {
+                    await this.abortTerminal(ctx, sessionId, bundle, 'planner resume budget exhausted', now, terminalTtlMs, usageNow());
+                    return true;
+                }
+            }
+            bundle.plannerCallInFlight = true;
+            // Reaching the planner guard means we are about to plan (block (A) handles
+            // any in-flight executing step earlier and continues), so the phase is
+            // 'planning' regardless of the prior 'evaluating'/'executing' value.
+            bundle.runPhase = 'planning';
+            await persistBundle(deps.backend, sessionId, bundle);
+            // (B) Render the live board BEFORE the planner call (fail-loud on over-budget).
+            let boardText;
+            try {
+                boardText = await renderLiveBoard(rag, bundle, boardBudget);
+            }
+            catch (err) {
+                if (err instanceof BoardOverBudgetError) {
+                    bundle.plannerPrivate += `\n[board over budget] ${err.message}`;
+                    await this.abortTerminal(ctx, sessionId, bundle, `board exceeds maxBoardChars: ${err.message}`, now, terminalTtlMs, usageNow());
+                    return true;
+                }
+                throw err;
+            }
             const next = await planner.next({
                 bundle,
                 prompt,
@@ -181,7 +485,23 @@ export class ControllerCoordinatorHandler {
                 resumedExternal,
                 retrying: planParseRetries > 0,
                 logUsage,
+                // Same request CallOptions the handler threads into every other LLM/RAG
+                // call (subagents, knowledgeRagFor, target-state) so the skills-recall
+                // embedding is metered, cancellable, and joins the request trace.
+                options: ctx.options,
+                boardText,
             });
+            // (A) Drain + persist plan decisions the planner queued during next().
+            const drained = bundle.pendingPlanDecisions ?? [];
+            bundle.pendingPlanDecisions = [];
+            for (const decision of drained) {
+                bundle.writeOrdinal = (bundle.writeOrdinal ?? 0) + 1;
+                await writePlanDecision(deps.backend, sessionId, decision, JSON.stringify(decision.steps), now(), bundle.writeOrdinal);
+            }
+            // The call completed → clear the in-flight marker + reset the resume counter
+            // (a malformed reply is still a completed call; parse-retry is handled below).
+            bundle.plannerCallInFlight = false;
+            bundle.plannerResumeCount = 0;
             // NB: do NOT reset resumedExternal here — if this replan reply was malformed
             // (next === null), the parse-retry below must keep replanning. It is reset
             // only after a VALID decision (beside planParseRetries = 0;).
@@ -201,10 +521,9 @@ export class ControllerCoordinatorHandler {
             planParseRetries = 0;
             resumedExternal = false; // a valid decision consumed any external-resume replan
             if (next.kind === 'done') {
-                bundle.pending = undefined;
-                await persistBundle(deps.backend, sessionId, bundle);
-                this.surfaceFinal(ctx, next.result, usageNow());
-                return true;
+                // Pass next.result as the legacy answer: used only when no finalizer is
+                // injected (3-role config) — the adaptive planner already composed it.
+                return this.finalize(ctx, sessionId, bundle, rag, prompt, logUsage, usageNow, now, terminalTtlMs, next.result);
             }
             if (next.kind === 'rewind') {
                 bundle.budgets.rewindsUsed++;
@@ -216,10 +535,33 @@ export class ControllerCoordinatorHandler {
                 await persistBundle(deps.backend, sessionId, bundle);
                 continue;
             }
-            // next.kind === 'next' → execute the step.
+            // next.kind === 'next' → open a fresh attempt and run it. Crash-replay/
+            // continuation of an executing step is handled by block (A), so this site only
+            // opens a NEW seq (attempt 0) or a revised step after awaiting-replan (attempt+1).
             dlog(`delegate step "${next.step.name}"${next.step.type ? ` (${next.step.type})` : ''}: ${next.step.instructions}`);
+            const seq = bundle.nextSeq ?? 0;
+            // Usually phase 'awaiting-replan' (a revised step after a failed attempt);
+            // on an external resume it may still be 'executing' (block (A) was skipped
+            // while resumedExternal). Same-seq → attempt+1 either way.
+            const prev = bundle.inFlightStep;
+            const attempt = prev && prev.seq === seq ? prev.attempt + 1 : 0;
+            if (attempt >= (cfg.maxStepAttempts ?? 5)) {
+                await this.abortTerminal(ctx, sessionId, bundle, `step "${next.step.name}" exceeded maxStepAttempts`, now, terminalTtlMs, usageNow());
+                return true;
+            }
+            bundle.inFlightStep = {
+                seq,
+                step: next.step,
+                attempt,
+                resumeCount: 0,
+                phase: 'executing',
+                transcript: [],
+                toolCallCount: 0,
+            };
+            bundle.runPhase = 'executing';
+            await persistBundle(deps.backend, sessionId, bundle);
             const completed = await this.runStep(ctx, sessionId, bundle, rag, meta, next.step, isExternalTool, logUsage, usageNow, (o) => planner.commit?.(bundle, o));
-            if (completed === 'suspended')
+            if (completed === 'suspended' || completed === 'aborted')
                 return true;
             // runStep.settle() already persisted the outcome ATOMICALLY (bundle.lastOutcome
             // + cursor advance via onCommit + step result, in one persistBundle). The next
@@ -231,14 +573,17 @@ export class ControllerCoordinatorHandler {
     }
     // -- Step execution -----------------------------------------------------
     /** Returns 'advanced' (step succeeded — continue loop), 'failed' (retries/
-     *  tool-call budget exhausted; the failure note is in plannerPrivate so the
-     *  planner can replan), or 'suspended' (external round-trip surfaced — caller
-     *  must return true). */
+     *  tool-call budget OR reviewer-unverifiable budget exhausted; the failure note
+     *  is in plannerPrivate so the planner can replan), 'partial' (reviewer approved
+     *  part, remainder replans), or 'suspended' (external round-trip surfaced — caller
+     *  must return true). ('aborted' remains in the return union for the caller's
+     *  guard but is no longer produced here — a judge-failure now degrades to 'failed'
+     *  rather than aborting the run.) */
     async runStep(ctx, sessionId, bundle, rag, meta, step, isExternalTool, logUsage, usageNow, onCommit) {
         const deps = this.deps;
         const cfg = deps.config.budgets;
         const maxToolCalls = cfg.maxToolCalls ?? 10;
-        let toolCalls = 0;
+        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
@@ -246,6 +591,18 @@ export class ControllerCoordinatorHandler {
         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;
         };
@@ -264,13 +621,61 @@ export class ControllerCoordinatorHandler {
         // 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 recalled = await resolveNeed(rag, recallText, RECALL_K, {
-            artifactType: RECALL_ARTIFACT_TYPES,
-        });
-        const recallBlock = buildRecallBlock(recalled);
+        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 () => {
+            if (inFlight) {
+                inFlight.transcript = messages.slice(staticLen);
+                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
@@ -283,21 +688,105 @@ export class ControllerCoordinatorHandler {
         // 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');
+                    }
+                    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,
-                    content: res.content,
-                });
+                    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++;
-                bundle.plannerPrivate += `\n[step ${step.name}] ${res.content}`;
-                return settle('advanced');
+                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++;
@@ -306,11 +795,13 @@ export class ControllerCoordinatorHandler {
                         role: 'user',
                         content: `The previous attempt failed: ${res.error}. Retry the step.`,
                     });
+                    await syncTranscript();
                     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');
             }
@@ -324,9 +815,11 @@ export class ControllerCoordinatorHandler {
                         role: 'user',
                         content: 'The previous attempt produced an empty tool call. Retry the step.',
                     });
+                    await syncTranscript();
                     continue;
                 }
                 bundle.budgets.stepsUsed++;
+                await writeControlFailure('empty tool call');
                 bundle.plannerPrivate += `\n[step ${step.name} failed] empty tool call`;
                 return settle('failed');
             }
@@ -334,7 +827,27 @@ export class ControllerCoordinatorHandler {
             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.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,
+                    };
+                    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)
+                    inFlight.toolCallCount += 1;
+                // The new marker REPLACES any prior pending (a fresh extId).
                 bundle.pending = {
                     kind: 'external-tool',
                     extId,
@@ -342,6 +855,7 @@ export class ControllerCoordinatorHandler {
                     args,
                     position: step.name,
                 };
+                bundle.runState = 'suspended';
                 await persistBundle(deps.backend, sessionId, bundle);
                 this.surfaceToolCall(ctx, { id: extId, name, arguments: args }, usageNow?.());
                 return 'suspended';
@@ -357,29 +871,50 @@ export class ControllerCoordinatorHandler {
                         role: 'user',
                         content: `Tool "${name}" is not available for this step. Use only the tools provided to you.`,
                     });
+                    await syncTranscript();
                     continue;
                 }
                 bundle.budgets.stepsUsed++;
+                await writeControlFailure(`requested unavailable tool ${name}`);
                 bundle.plannerPrivate += `\n[step ${step.name} failed] requested unavailable tool ${name}`;
                 return settle('failed');
             }
-            // Internal MCP tool — bound the inner loop so a stuck executor cannot
-            // spin forever issuing unbounded callMcp iterations.
-            toolCalls++;
-            if (toolCalls > maxToolCalls) {
+            // 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++;
-                bundle.plannerPrivate += `\n[step ${step.name} aborted] tool-call budget exhausted`;
+                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,
+                    };
+                }
                 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;
@@ -400,6 +935,8 @@ export class ControllerCoordinatorHandler {
                 tool_call_id: call.id,
                 content: result,
             });
+            // The executor saw these turns → make them durable before the next round.
+            await syncTranscript();
         }
     }
     // -- Escalation & surfacing (mirror StepperCoordinatorHandler) ----------
@@ -409,6 +946,110 @@ export class ControllerCoordinatorHandler {
         this.surfaceClarify(ctx, question, usage);
         return true;
     }
+    /** Store-first terminal ERROR: write the terminal outcome to the TTL store
+     *  FIRST (keyed by runId), THEN flip the bundle terminal and surface the error.
+     *  Store-first makes the abort idempotent across a crash between the two writes. */
+    async abortTerminal(ctx, sessionId, bundle, error, now, terminalTtlMs, usage) {
+        await writeTerminal(this.deps.backend, sessionId, bundle.runId ?? sessionId, { kind: 'error', error }, terminalTtlMs, now());
+        bundle.pending = undefined;
+        bundle.inFlightStep = undefined;
+        bundle.finalizeCallInFlight = false;
+        bundle.runState = 'terminal';
+        await persistBundle(this.deps.backend, sessionId, bundle);
+        this.surfaceFinal(ctx, `Error: ${error}`, usage);
+    }
+    async finalize(ctx, sessionId, bundle, rag, prompt, logUsage, usageNow, now, terminalTtlMs, 
+    /** Used ONLY when no finalizer is injected (3-role config): the adaptive
+     *  planner's already-composed done.result. */
+    legacyAnswer) {
+        const deps = this.deps;
+        const cfg = deps.config.budgets;
+        const maxFinalizeRetries = cfg.maxFinalizeRetries ?? 2;
+        // The finalizer reads the run's approved results + the DURABLE originalRequest
+        // (the verbatim request that started the run), never the live resume prompt.
+        const request = bundle.originalRequest ?? prompt;
+        const approved = deps.finalizer && bundle.runId
+            ? await collectApproved(rag, bundle.runId)
+            : [];
+        // Shared exhaustion handler (pre-call AND in-catch): apply onFinalizeExhausted.
+        const onExhausted = async (reason) => {
+            if ((deps.config.onFinalizeExhausted ?? 'error') === 'best-effort') {
+                return (approved.map((a) => `[#${a.seq}] ${a.content}`).join('\n\n') +
+                    '\n\n[incomplete: the final answer could not be composed]');
+            }
+            await this.abortTerminal(ctx, sessionId, bundle, reason, now, terminalTtlMs, usageNow());
+            return null;
+        };
+        // Crash-replay charge: a prior finalize call in flight → this re-entry is a
+        // replay; charge finalizeAttempt and CHECK the cap BEFORE re-invoking.
+        if (bundle.finalizeCallInFlight) {
+            bundle.finalizeAttempt = (bundle.finalizeAttempt ?? 0) + 1;
+            if ((bundle.finalizeAttempt ?? 0) > maxFinalizeRetries) {
+                const best = await onExhausted('finalizer retry budget exhausted on recovery');
+                if (best === null)
+                    return true;
+                await this.commitTerminalSuccess(ctx, sessionId, bundle, best, now, terminalTtlMs, usageNow());
+                return true;
+            }
+        }
+        // Legacy (no-finalizer) path: persist the planner's composed answer DURABLY in
+        // the SAME write that enters 'finalizing', so a crash before the terminal write
+        // can recover it rather than emitting empty.
+        if (!deps.finalizer && legacyAnswer !== undefined) {
+            bundle.legacyFinalAnswer = legacyAnswer;
+        }
+        bundle.runPhase = 'finalizing';
+        bundle.finalizeCallInFlight = true;
+        await persistBundle(deps.backend, sessionId, bundle);
+        let answer;
+        if (deps.finalizer && bundle.runId) {
+            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),
+                    });
+                    // Empty-but-ok finalizer output is a JUDGE failure (spec), not a valid
+                    // answer → throw so it retries within maxFinalizeRetries.
+                    if (composed.trim().length === 0) {
+                        throw new Error('finalizer returned an empty answer');
+                    }
+                    answer = composed;
+                }
+                catch (e) {
+                    bundle.finalizeAttempt = (bundle.finalizeAttempt ?? 0) + 1;
+                    await persistBundle(deps.backend, sessionId, bundle);
+                    if ((bundle.finalizeAttempt ?? 0) > maxFinalizeRetries) {
+                        const best = await onExhausted(`finalizer failed after ${maxFinalizeRetries} retries: ${String(e)}`);
+                        if (best === null)
+                            return true; // 'error' policy aborted terminally
+                        answer = best; // 'best-effort'
+                        break;
+                    }
+                    // else: loop and retry the finalizer.
+                }
+            }
+        }
+        else {
+            // Legacy: the adaptive planner already composed the answer in done.result.
+            // Prefer the live param, else the durable copy persisted on finalizing-entry.
+            answer = legacyAnswer ?? bundle.legacyFinalAnswer ?? '';
+        }
+        await this.commitTerminalSuccess(ctx, sessionId, bundle, answer ?? '', now, terminalTtlMs, usageNow());
+        return true;
+    }
+    /** Store-first terminal SUCCESS: write the terminal store FIRST, then flip the
+     *  bundle to terminal and surface the answer (mirror of abortTerminal). */
+    async commitTerminalSuccess(ctx, sessionId, bundle, answer, now, terminalTtlMs, usage) {
+        await writeTerminal(this.deps.backend, sessionId, bundle.runId ?? sessionId, { kind: 'success', answer }, terminalTtlMs, now());
+        bundle.pending = undefined;
+        bundle.finalizeCallInFlight = false;
+        bundle.runState = 'terminal';
+        bundle.inFlightStep = undefined;
+        await persistBundle(this.deps.backend, sessionId, bundle);
+        this.surfaceFinal(ctx, answer, usage);
+    }
     surfaceClarify(ctx, question, usage) {
         ctx.yield({
             ok: true,
@@ -484,18 +1125,23 @@ const EXECUTOR_SYSTEM = 'You are the executor. You have tools that read the live
     'for per-item details.';
 const TOOL_SELECT_K = 20;
 /** Top-k recalled artifacts injected into the executor context per step. */
-const RECALL_K = 5;
 /** Artifact types eligible for recall (excludes the 'controller-bundle' record
  *  that shares the same backend). */
 const RECALL_ARTIFACT_TYPES = ['step-result', 'mcp-result'];
-/** Hard cap on the total injected recall length (chars). */
-const RECALL_MAX_CHARS = 4000;
+/** 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, or
- *  undefined when there is nothing to inject. */
-function buildRecallBlock(hits) {
+/** 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 = [];
@@ -504,8 +1150,8 @@ function buildRecallBlock(hits) {
         const c = h.content ?? '';
         if (c.length === 0)
             continue;
-        if (used + c.length > RECALL_MAX_CHARS) {
-            parts.push(c.slice(0, RECALL_MAX_CHARS - used));
+        if (used + c.length > maxChars) {
+            parts.push(c.slice(0, maxChars - used));
             break;
         }
         parts.push(c);
@@ -540,8 +1186,26 @@ export function parseNextStep(content) {
             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')
-            return { kind: 'next', step: obj.step };
+        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
@@ -612,6 +1276,26 @@ function toLlmToolCall(c) {
         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;
@@ -624,4 +1308,182 @@ function synthMeta(ctx, sessionId) {
         createdAt: new Date().toISOString(),
     };
 }
+/** Map a reviewer status to the planner transition. ok/exists advance; partial
+ *  advances the accepted part AND forces a remainder replan; failed replans. */
+function mapOutcome(status) {
+    if (status === 'ok' || status === 'exists')
+        return 'advanced';
+    if (status === 'partial')
+        return 'partial';
+    return 'failed';
+}
+/** Append ONE payload-free control record to plannerPrivate (the cache holds
+ *  {seq,status,note,remainder}, never the approved content). Used by both normal
+ *  settle and crash/external reconciliation so plannerPrivate is identical
+ *  whichever path committed the step. */
+function recordStepControl(bundle, rec) {
+    bundle.plannerPrivate +=
+        `\n[seq ${rec.seq} ${rec.name} ${rec.status}]` +
+            (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