ai-runtime-engine 2.7.0 → 2.9.0

package/dist/runtime/runtime.js

@@ -31,6 +31,8 @@ import { TokenEstimator } from '../context/tokens.js';
 import { ToolRegistry } from '../tools/registry.js';
 import { resolvePermissions, clampMcpPermissions } from '../tools/permissions.js';
 import { flattenClamp } from '../util/flatten.js';
+import { wrapUntrusted } from '../tools/untrusted.js';
+import { redact } from '../security/redact.js';
 import { McpManager } from '../mcp/manager.js';
 import { mcpTool, mcpToolId } from '../mcp/toolAdapter.js';
 import { StaticMcpSource } from '../mcp/mcp.js';
@@ -52,6 +54,34 @@ import { executePlan } from '../orchestration/executor.js';
 import { ExecutionStore } from '../executions/store.js';
 import { RESUMABLE, TERMINAL } from '../executions/execution.js';
 import { captureCheckpoint, reconcile } from '../executions/checkpoint.js';
+import { AGENT_TERMINAL, AGENT_RESUMABLE, agentTaskView } from '../agents/task.js';
+import { parseAgentTasks } from '../executions/agentTasks.js';
+import { stepIdentity } from '../agents/worker.js';
+import { hashOf } from '../util/hash.js';
+/** Checkpoints kept per execution. Only the newest is ever read; the rest are audit trail, and the
+ *  record is rewritten on every commit, so this is a file-size bound (Phase 3.5). */
+const CHECKPOINTS_MAX = 5;
+/** Findings carried into a replan prompt. Bounded because they are rendered into a model call. */
+const FINDINGS_BRIEF_MAX = 10;
+/**
+ * What an observation looks like ON DISK (Phase 3.5).
+ *
+ * Two jobs, both at the persistence boundary. REDACTION: an observation carries tool output, which is
+ * arbitrary text from outside the process — a tool that prints a token would otherwise write it into
+ * the execution file verbatim, where it survives every later read. Every other egress (logs, telemetry,
+ * CLI) already redacts; the store did not, and Phase 3.5 writes far more of this content far more often.
+ * SLIMMING: findings already live on the agent task record in the same file, so keeping only their ids
+ * here stops every finding being stored twice and rewritten on every commit.
+ *
+ * The live observation is untouched — callers still receive full findings from the run itself.
+ */
+function persistableObservation(obs) {
+    const data = obs.data;
+    const slimmed = data && Array.isArray(data.findings)
+        ? { ...obs, data: { ...(({ findings: _drop, ...rest }) => rest)(data), findingIds: data.findings.map((f) => f?.id).filter((id) => typeof id === 'string') } }
+        : obs;
+    return redact(slimmed);
+}
 import { ArtifactStore } from '../artifacts/artifacts.js';
 import { compare } from '../comparison/comparator.js';
 import { renderComparison } from '../comparison/render.js';
@@ -129,6 +159,8 @@ export class Runtime {
     /** Live runs, so a pause/cancel can abort the agent tasks actually in flight. Only ever populated
      *  when agents are enabled, so pause/cancel are unchanged with the flag off. */
     liveRuns = new Map();
+    /** Phase 3.6: agent tasks running RIGHT NOW in this process, and how to stop each one on its own. */
+    liveAgentTasks = new Map();
     /** The config file's `budget:` ceilings, kept only so the 3.3 pre-pass can decline a model call. */
     _configBudget;
     approval;
@@ -824,7 +856,14 @@ export class Runtime {
             // entire flag-off delta on this path.
             const planning = await this.capabilityPlanning(effectiveGoal, policy, routing);
             try {
-                const outcome = await orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, routing, partial, planning?.block, this.agentsEnabled ? controller.signal : undefined, { planVersion: 1 }));
+                const outcome = await orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, {
+                    ...(routing ? { routing } : {}),
+                    ...(partial ? { partial } : {}),
+                    ...(planning?.block ? { requiredCapabilities: planning.block } : {}),
+                    ...(this.agentsEnabled ? { signal: controller.signal } : {}),
+                    provenance: { planVersion: 1 },
+                    runId,
+                }));
                 this.recordOrchestration(mode, goal, outcome);
                 return this.mapOutcome(outcome, resolution, runId, undefined, planning);
             }
@@ -855,9 +894,19 @@ export class Runtime {
             // Renew the lease while the (possibly long) run is in flight so it can't expire mid-run.
             if (this.agentsEnabled)
                 this.liveRuns.set(exec.id, { controller });
-            const outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, routing, partial, planning?.block, this.agentsEnabled ? controller.signal : undefined, { executionId: exec.id, planVersion: exec.planVersion })));
+            // Phase 3.5: only when there is a store to write to — a stateless run keeps the 2.7.0 shape.
+            const sink = this._executions.enabled ? this.runPersistence(exec, controller) : undefined;
+            const outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, {
+                ...(routing ? { routing } : {}),
+                ...(partial ? { partial } : {}),
+                ...(planning?.block ? { requiredCapabilities: planning.block } : {}),
+                ...(this.agentsEnabled ? { signal: controller.signal } : {}),
+                provenance: { executionId: exec.id, planVersion: exec.planVersion },
+                ...(sink ? { sink } : {}),
+                runId,
+            })));
             exec.status = this.execStatus(outcome.status);
-            exec.observations = outcome.observations;
+            exec.observations = outcome.observations.map(persistableObservation);
             if (outcome.plan) {
                 exec.plan = outcome.plan;
                 exec.planVersion = outcome.plan.version;
@@ -865,12 +914,19 @@ export class Runtime {
             }
             if (outcome.status === 'waiting_for_approval')
                 exec.pending = { kind: 'approval', action: goal };
-            else if (outcome.status === 'waiting_for_clarification' && outcome.clarification)
-                exec.pending = { kind: 'clarification', question: outcome.clarification };
+            else if (outcome.status === 'waiting_for_clarification' && outcome.clarification) {
+                // First-wins: if an AGENT is what is waiting, the pending slot records which one, so the answer
+                // is routed into that task's inner resume instead of being appended to the outer goal.
+                const waiter = this.electWaitingAgent(exec);
+                exec.pending = { kind: 'clarification', question: outcome.clarification, ...(waiter ? { agentTaskId: waiter.agentTaskId } : {}) };
+            }
             else if (outcome.status === 'waiting_for_budget' && outcome.budget)
                 exec.pending = { kind: 'budget', budget: outcome.budget };
-            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps }));
-            this._executions.commit(exec); // ownership-checked: never clobber a newer owner
+            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps, mcpTools: this.mcpToolHashes(exec.plan) }));
+            if (sink)
+                sink.finalize();
+            else
+                this._executions.commit(exec); // ownership-checked: never clobber a newer owner
             this.recordOrchestration(mode, goal, outcome);
             return this.mapOutcome(outcome, resolution, runId, exec.id, planning);
         }
@@ -880,6 +936,110 @@ export class Runtime {
             this._executions.release(exec.id);
         }
     }
+    /**
+     * THE mid-run persistence sink (Phase 3.5) — the only thing that writes an execution while it runs.
+     *
+     * Invariant 18 says everything needed for resume is on disk before the next wave starts, and the
+     * non-obvious part is WHAT that includes. Committing the plan, the completed steps and the agent
+     * records is not enough: the resume gate is `!recon.drifted && !!exec.plan`, and `recon` defaults to
+     * DRIFTED whenever `checkpoints` is empty. Since checkpoints were captured only after orchestration
+     * returned, a crash mid-run always drifted, always replanned, and re-ran every completed agent task —
+     * the exact thing this phase exists to prevent. So the sink captures a checkpoint too.
+     *
+     * Every refusal from the funnel ABORTS the run. A refused commit means another owner now owns this
+     * execution's fate; carrying on would call the same tools and burn the same model calls twice while
+     * that owner re-runs the identical steps, and every result would be discarded at the end anyway.
+     */
+    runPersistence(exec, controller) {
+        // Fixed for each executePlan call: its `callsUsed` is cumulative for that call, so the pool must be
+        // `priorCalls + thisCall`, and `priorCalls` advances only when the call ends. Adding a per-fire delta
+        // instead would let the total go BACKWARDS across replan iterations and over-grant the resume pool.
+        let priorCalls = exec.callsUsed ?? 0;
+        let lastCheckpointed = '';
+        let stopped = false;
+        const commit = () => {
+            if (stopped)
+                return;
+            const outcome = this._executions.commitProgress(exec);
+            if (outcome === 'ok')
+                return;
+            // Stop trying to write, and stop the run itself.
+            stopped = true;
+            this.abortLiveRun(exec.id, outcome === 'paused' ? 'pause' : 'parent-cancel');
+            controller.abort();
+        };
+        /** Capture only when the completed set moved: `captureCheckpoint` hashes files and shells git. */
+        const checkpointIfMoved = () => {
+            const key = exec.completedSteps.join('\u0000');
+            if (key === lastCheckpointed)
+                return;
+            lastCheckpointed = key;
+            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps, mcpTools: this.mcpToolHashes(exec.plan) }));
+            if (exec.checkpoints.length > CHECKPOINTS_MAX)
+                exec.checkpoints.splice(0, exec.checkpoints.length - CHECKPOINTS_MAX);
+        };
+        return {
+            /** The plan is settled and nothing has run: a crash in wave 1 must still resume against a plan. */
+            onPlan: (plan) => {
+                exec.plan = plan;
+                exec.planVersion = plan.version;
+                exec.completedSteps = plan.steps.filter((st) => st.status === 'succeeded').map((st) => st.id);
+                checkpointIfMoved();
+                commit();
+            },
+            onProgress: (snap) => {
+                exec.plan = snap.plan;
+                exec.completedSteps = snap.plan.steps.filter((st) => st.status === 'succeeded').map((st) => st.id);
+                if (snap.observations.length)
+                    exec.observations = [...exec.observations, ...snap.observations.map(persistableObservation)];
+                exec.callsUsed = priorCalls + snap.callsUsed;
+                checkpointIfMoved();
+                commit();
+                // One executePlan call is over; its spend is now part of the floor for the next one.
+                if (snap.at === 'plan-end')
+                    priorCalls = exec.callsUsed ?? priorCalls;
+            },
+            onRecord: (record) => {
+                const tasks = (exec.agentTasks ??= []);
+                const at = tasks.findIndex((t) => t.agentTaskId === record.agentTaskId);
+                // TERMINAL is sticky for a TASK too. A late write from an aborted worker must not reopen a task
+                // that already completed, failed or was cancelled.
+                if (at >= 0 && AGENT_TERMINAL.has(tasks[at].state) && !AGENT_TERMINAL.has(record.state))
+                    return;
+                // Redacted at the boundary: findings, inner observations and diagnostics all carry text that
+                // came from tools and models, and this record is about to become a durable file.
+                // The inner workspace fingerprint. The OUTER checkpoint cannot stand in for it: `planPaths`
+                // reads the outer plan's step inputs, so files an agent touched through its own inner steps are
+                // invisible to it. Captured here because the worker has no workspace root — it is deliberately
+                // not given one.
+                if (record.innerPlan) {
+                    record.innerCheckpoint = captureCheckpoint({ root: this.workspaceRoot, plan: record.innerPlan, skills: this.skills(), completedSteps: record.innerCompletedSteps });
+                }
+                const snapshot = redact({ ...record });
+                if (at >= 0)
+                    tasks[at] = snapshot;
+                else
+                    tasks.push(snapshot);
+                // A task that FINISHED means its step succeeded. Waiting for the batch commit to record that
+                // leaves a window where a crash finds a `completed` record — which is not resumable, so no
+                // record is offered — and a step not in `completedSteps`, so the agent is simply re-run: a
+                // second paid planning call, the tools fired twice, and two records for one step.
+                if (record.state === 'completed' && !exec.completedSteps.includes(record.stepId)) {
+                    exec.completedSteps = [...exec.completedSteps, record.stepId];
+                    checkpointIfMoved();
+                }
+                commit();
+            },
+            /**
+             * The terminal write. It goes through the SAME funnel as every mid-run commit, so a pause or a
+             * cancel that landed while the run was finishing is not overwritten by its result: the plain
+             * `commit()` only refuses a live FOREIGN lease, and pause/cancel release the lease as this very
+             * owner — so nothing stopped the final write from resurrecting a cancelled run as `completed`.
+             */
+            finalize: () => (stopped ? 'terminal' : this._executions.commitProgress(exec)),
+            stopped: () => stopped,
+        };
+    }
     /** Run `fn` while heartbeating the execution lease so a long run never lets the lease expire. */
     async withHeartbeat(id, fn) {
         const timer = setInterval(() => this._executions.heartbeat(id), this._executions.heartbeatMs);
@@ -892,7 +1052,14 @@ export class Runtime {
             clearInterval(timer);
         }
     }
-    orchestrateInput(mode, goal, policy, routing, partial, requiredCapabilities, signal, provenance) {
+    /**
+     * Build the OrchestrateInput. The optional half is an OBJECT, not a positional tail: this function
+     * grew to ten parameters and a caller that passed five of them silently got no sink, no signal and no
+     * provenance — a replan that persisted nothing and could not be cancelled. Named fields cannot be
+     * short-counted.
+     */
+    orchestrateInput(mode, goal, policy, opts = {}) {
+        const { routing, partial, requiredCapabilities, signal, provenance, sink, agentResume, runId } = opts;
         return {
             goal,
             mode,
@@ -912,7 +1079,16 @@ export class Runtime {
             resolveGaps: (missing) => this.resolveMissingRefs(missing, policy),
             // Phase 3.4: ONE runner source. `agents`, `runAgent` and `reserve` ride along only when agents are
             // enabled AND a definition exists, so with the flag off this object is KEY-identical to 2.6.0.
-            ...this.orchestrateRunners(policy, signal, provenance),
+            ...this.orchestrateRunners(policy, {
+                runId: runId ?? 'unknown',
+                ...(signal ? { signal } : {}),
+                ...(provenance ? { provenance } : {}),
+                ...(sink?.onRecord ? { onRecord: sink.onRecord } : {}),
+                ...(agentResume ? { agentResume } : {}),
+            }),
+            // Phase 3.5: the commit points. Present ONLY when there is a store to commit to, so a stateless
+            // Runtime builds an OrchestrateInput key-identical to 2.7.0.
+            ...(sink ? { onPlan: sink.onPlan, onProgress: sink.onProgress } : {}),
             ...(signal ? { signal } : {}),
         };
     }
@@ -1180,6 +1356,13 @@ export class Runtime {
             return { ok: false, runId, mode: resolution, status: 'failed', response: { text: `cannot resume ${id}: ${acq.reason ?? 'unavailable'}` }, artifacts: [] };
         }
         const exec = acq.execution;
+        // A resumed run is a live run: pause/cancel must be able to abort it, and a refused commit must be
+        // able to stop it — both of which need a controller registered under this execution's id.
+        const controller = new AbortController();
+        // What was on the record BEFORE this resume. The terminal write rebuilds from here rather than
+        // appending: the sink has already been appending this run's observations as they happened, so
+        // appending the outcome's copy too would store every step of a resumed run twice.
+        const observationsBefore = [...exec.observations];
         try {
             if (TERMINAL.has(exec.status))
                 return this.resultFromExecution(exec, resolution, runId);
@@ -1198,12 +1381,28 @@ export class Runtime {
                     return this.resultFromExecution(exec, resolution, runId);
                 }
             }
+            // An INNER wait needs its answer, exactly as an approval needs a decision. Without this gate the
+            // ordinary `resume-execution <id>` (the CLI makes --answer optional) falls through to the replan
+            // branch, which replaces the plan and orphans every sibling agent's completed work — destroying
+            // progress in the one situation the wait exists to protect.
+            if (exec.pending?.kind === 'clarification' && exec.pending.agentTaskId && !opts.clarificationAnswer) {
+                return this.resultFromExecution(exec, resolution, runId);
+            }
+            // Phase 3.5: whoever was mid-flight when this execution stopped is gone. Put those records back in
+            // `queued` with the reason BEFORE anything is scheduled against them.
+            if (this.reconcileAgentTasks(exec, 'crash') > 0)
+                this._executions.commit(exec);
             // Reconcile against the checkpoint — drift forces a replan rather than a blind continue.
             const checkpoint = exec.checkpoints[exec.checkpoints.length - 1];
-            const recon = checkpoint ? reconcile(checkpoint, this.workspaceRoot, this.skills()) : { drifted: true, reasons: ['no checkpoint'] };
-            const goal = exec.pending?.kind === 'clarification' && opts.clarificationAnswer ? `${exec.goal}\n\nClarification: ${opts.clarificationAnswer}` : exec.goal;
+            const recon = checkpoint ? reconcile(checkpoint, this.workspaceRoot, this.skills(), this.mcpToolHashes(exec.plan)) : { drifted: true, reasons: ['no checkpoint'] };
+            // An INNER answer belongs to one agent task, never to the outer goal: appending it here would
+            // replan the whole plan and discard every sibling agent's completed work.
+            const innerAnswered = exec.pending?.kind === 'clarification' && !!exec.pending.agentTaskId && !!opts.clarificationAnswer;
+            const goal = exec.pending?.kind === 'clarification' && opts.clarificationAnswer && !innerAnswered ? `${exec.goal}\n\nClarification: ${opts.clarificationAnswer}` : exec.goal;
             // Re-read the budget from env so raising AI_MAX_CALLS before resuming actually takes effect (Phase 22).
             const policy = resolvePolicy({ mode: 'orchestrate', overrides: { autonomy: 'autonomous', approval: 'none', ...(this.configPermissions ? { permissions: this.configPermissions } : {}) }, settings: this.settingsValue, env: { maxCostUsd: numFromEnv(this.env, 'AI_MAX_COST_USD'), maxCalls: numFromEnv(this.env, 'AI_MAX_CALLS') } });
+            if (this.agentsEnabled)
+                this.liveRuns.set(exec.id, { controller });
             // A resumed run is never re-DERIVED — no surprise second model call on work already approved and
             // mid-flight — but it does get the FREE post-plan check: a grant may have changed since it started.
             const planning = this.settingsValue.capabilities?.planning
@@ -1212,18 +1411,37 @@ export class Runtime {
             // Continue (skip completed steps) for an approved plan, a budget pause, or partial progress.
             const approvedNow = exec.pending?.kind === 'approval';
             const budgetPaused = exec.pending?.kind === 'budget';
-            const canContinue = !recon.drifted && !!exec.plan && (approvedNow || budgetPaused || (exec.completedSteps.length > 0 && !exec.pending));
+            // `innerAnswered` is its own arm: the plan is intact and one agent step needs re-running with its
+            // answer. The partial-progress arm cannot cover it — a run where every agent asked before doing
+            // anything has NO completed steps, which is precisely the two-waiting-agents case.
+            const canContinue = !recon.drifted && !!exec.plan && (approvedNow || budgetPaused || innerAnswered || (exec.completedSteps.length > 0 && !exec.pending));
+            const sink = this._executions.enabled ? this.runPersistence(exec, controller) : undefined;
             let outcome;
             if (canContinue && exec.plan) {
                 // Continue the plan, skipping completed steps. The call budget is ALWAYS enforced on the continue
                 // path (whether the pause was approval, budget, or partial-progress) so an approved-but-over-budget
                 // plan pauses for budget rather than silently exceeding it; a raised budget re-applies here.
-                const exe = await this.withHeartbeat(exec.id, () => executePlan(exec.plan, { ...this.orchestrateRunners(policy, opts.signal, { executionId: exec.id, planVersion: exec.planVersion }), maxParallelSteps: policy.maxParallelSteps ?? 2, ...(policy.limits ? { limits: policy.limits } : {}), skip: new Set(exec.completedSteps), ...(policy.maxCalls !== undefined ? { callBudget: policy.maxCalls } : {}), ...(opts.signal ? { signal: opts.signal } : {}) }));
+                const resumeLookup = this.agentResumeLookup(exec, opts.clarificationAnswer);
+                const exe = await this.withHeartbeat(exec.id, () => executePlan(exec.plan, { ...this.orchestrateRunners(policy, { runId, signal: opts.signal ?? controller.signal, provenance: { executionId: exec.id, planVersion: exec.planVersion }, ...(sink?.onRecord ? { onRecord: sink.onRecord } : {}), agentResume: resumeLookup }), ...(sink ? { onProgress: sink.onProgress } : {}), maxParallelSteps: policy.maxParallelSteps ?? 2, ...(policy.limits ? { limits: policy.limits } : {}), skip: new Set(exec.completedSteps), ...(policy.maxCalls !== undefined ? { callBudget: policy.maxCalls } : {}), ...(opts.signal ? { signal: opts.signal } : {}) }));
                 if (exe.stoppedForBudget) {
                     const done = exe.plan.steps.filter((s) => s.status === 'succeeded').length;
                     const total = exe.plan.steps.length;
                     outcome = { status: 'waiting_for_budget', plan: exe.plan, planHistory: [exe.plan], observations: exe.observations, budget: { estCalls: foldCalls(exe.plan.steps, policy.maxCalls), maxCalls: policy.maxCalls, completedSteps: done, totalSteps: total }, summary: `Ran ${done} of ${total} step(s) within the ${policy.maxCalls}-call budget. Raise the budget (AI_MAX_CALLS) and resume to continue.` };
                 }
+                else if (exe.waiting?.length) {
+                    // Answering one agent can simply reveal the next one. Reporting `failed` here (the pre-3.5
+                    // shape, which read `ok` alone) would mark a perfectly resumable run as dead and lie in the
+                    // summary while doing it.
+                    const asked = exe.observations.find((o) => o.code === 'agent-waiting');
+                    outcome = {
+                        status: 'waiting_for_clarification',
+                        plan: exe.plan,
+                        planHistory: [exe.plan],
+                        observations: exe.observations,
+                        clarification: asked?.error ?? 'an agent needs more information to continue',
+                        summary: `Still waiting: ${exe.waiting.length} agent step(s) need an answer.`,
+                    };
+                }
                 else {
                     outcome = { status: exe.ok ? 'completed' : 'failed', plan: exe.plan, planHistory: [exe.plan], observations: exe.observations, summary: exe.ok ? `resumed and completed "${exec.goal}"` : `resume did not complete "${exec.goal}"` };
                 }
@@ -1232,25 +1450,49 @@ export class Runtime {
                 // Drift, or a pending clarification answer, or no partial progress → replan from the goal. Re-resolve
                 // routing so env/config excludes (and learned prefer) still apply. A budget-paused replan stays
                 // partial so it keeps running-what-fits instead of reverting to notify-and-wait.
-                outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput('orchestrate', goal, policy, this.effectiveRouting(), budgetPaused)));
+                // Drift replaces the PLAN, not the facts. What the agents proved before the drift is carried
+                // into the new planning context rather than silently orphaned.
+                const brief = this.findingsBrief(exec);
+                // The full argument list. Passing five positionals to a ten-parameter function silently left
+                // this arm with no signal, no provenance, no sink and no resume lookup — so a replan persisted
+                // no agent record AT ALL (onRecord is the only writer of `agentTasks`), could not be paused or
+                // cancelled, and elected `pending` from stale records.
+                outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput('orchestrate', brief ? `${goal}\n\n${brief}` : goal, policy, {
+                    ...(this.effectiveRouting() ? { routing: this.effectiveRouting() } : {}),
+                    ...(budgetPaused ? { partial: true } : {}),
+                    ...(this.agentsEnabled ? { signal: controller.signal } : {}),
+                    provenance: { executionId: exec.id, planVersion: exec.planVersion },
+                    ...(sink ? { sink } : {}),
+                    runId,
+                })));
             }
             exec.status = this.execStatus(outcome.status);
-            exec.observations = [...exec.observations, ...outcome.observations];
+            exec.observations = [...observationsBefore, ...outcome.observations.map(persistableObservation)];
             if (outcome.plan) {
                 exec.plan = outcome.plan;
                 exec.planVersion = outcome.plan.version;
                 exec.completedSteps = outcome.plan.steps.filter((s) => s.status === 'succeeded').map((s) => s.id);
             }
-            // Preserve a fresh budget pause; otherwise the pending state is resolved.
+            // Preserve a fresh budget pause; otherwise the pending state is resolved — except that answering
+            // one agent's question may simply have revealed the NEXT one (rediscovery: the records are the
+            // source of truth, so a second waiting task is re-elected rather than queued somewhere).
             if (outcome.status === 'waiting_for_budget' && outcome.budget)
                 exec.pending = { kind: 'budget', budget: outcome.budget };
+            else if (outcome.status === 'waiting_for_clarification' && outcome.clarification) {
+                const waiter = this.electWaitingAgent(exec);
+                exec.pending = { kind: 'clarification', question: outcome.clarification, ...(waiter ? { agentTaskId: waiter.agentTaskId } : {}) };
+            }
             else
                 delete exec.pending;
-            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps }));
-            this._executions.commit(exec);
+            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps, mcpTools: this.mcpToolHashes(exec.plan) }));
+            if (sink)
+                sink.finalize();
+            else
+                this._executions.commit(exec);
             return this.mapOutcome(outcome, resolution, runId, exec.id, planning);
         }
         finally {
+            this.liveRuns.delete(exec.id);
             this._executions.release(id);
         }
     }
@@ -1259,7 +1501,8 @@ export class Runtime {
      * They used to drift: resume built its own pair with no agent runner, so a persisted plan containing
      * an agent step would have failed every one of those steps.
      */
-    orchestrateRunners(policy, signal, provenance) {
+    orchestrateRunners(policy, opts) {
+        const { runId, signal, provenance, onRecord, agentResume } = opts;
         const envelopes = policy ? this.agentEnvelopes(policy) : [];
         const byId = new Map(envelopes.map((e) => [e.agentId, e]));
         return {
@@ -1275,7 +1518,11 @@ export class Runtime {
                         if (!envelope || !definition)
                             return { stepId: step.id, ok: false, code: 'agent-not-enabled', error: `no agent definition '${step.agent ?? ''}'` };
                         const innerSkills = this._skills.list().filter((sk) => envelope.skills.includes(sk.id));
+                        // Phase 3.5: continue a persisted task for THIS step, if one exists.
+                        const prior = agentResume?.(step);
                         const out = await runAgentTask(step, envelope, definition, {
+                            ...(prior?.record ? { resume: prior.record } : {}),
+                            ...(prior?.answer ? { resumeAnswer: prior.answer } : {}),
                             ai: this._ai,
                             clock: this.clock,
                             skills: innerSkills,
@@ -1294,7 +1541,29 @@ export class Runtime {
                                     return { unavailable: true };
                                 }
                             },
-                            emit: (e) => this.emitter.emit({ type: e.type, agentTaskId: e.record.agentTaskId, agentId: e.record.agentId, stepId: e.record.stepId, state: e.record.state, innerSteps: e.record.innerSteps, callsUsed: e.record.callsUsed, toolCallsUsed: e.record.toolCallsUsed, findings: e.record.findings.length }),
+                            // METADATA ONLY, and ONE BRANCH PER ARM. Building a single object with a union-typed
+                            // `type` compiles while carrying properties from every constituent — TypeScript's
+                            // excess-property check against a union admits anything present in SOME arm — so
+                            // `agent.task.started` was shipping innerSteps/callsUsed/findings it does not declare.
+                            // Narrowing to a literal first makes an extra property a compile error again; the
+                            // key-set test covers what the type system still cannot.
+                            emit: (e) => {
+                                const base = { runId, agentTaskId: e.record.agentTaskId, agentId: e.record.agentId, stepId: e.record.stepId };
+                                if (e.type === 'agent.task.started') {
+                                    this.emitter.emit({ type: 'agent.task.started', ...base, state: e.record.state });
+                                    return;
+                                }
+                                if (e.type === 'agent.task.progress') {
+                                    this.emitter.emit({ type: 'agent.task.progress', ...base, innerSteps: e.record.innerSteps, callsUsed: e.record.callsUsed, toolCallsUsed: e.record.toolCallsUsed });
+                                    return;
+                                }
+                                // `findings` is a COUNT: a claim is agent-authored text and an event is the one
+                                // surface a host may forward anywhere, so no content crosses it.
+                                this.emitter.emit({ type: 'agent.task.completed', ...base, state: e.record.state, innerSteps: e.record.innerSteps, callsUsed: e.record.callsUsed, toolCallsUsed: e.record.toolCallsUsed, findings: e.record.findings.length });
+                            },
+                            ...(onRecord ? { onRecord } : {}),
+                            registerAbort: (id, abort) => this.liveAgentTasks.set(id, { abort, agentId: envelope.agentId, stepId: step.id, ...(provenance?.executionId ? { executionId: provenance.executionId } : {}) }),
+                            releaseAbort: (id) => this.liveAgentTasks.delete(id),
                             ...(ctx.signal ?? signal ? { parentSignal: ctx.signal ?? signal } : {}),
                             ...(provenance ? { provenance } : { provenance: { planVersion: 1 } }),
                             abortReason: () => {
@@ -1310,6 +1579,221 @@ export class Runtime {
                 : {}),
         };
     }
+    /**
+     * A bounded, fenced brief of what the agents have already established (Phase 3.5).
+     *
+     * On drift the plan is thrown away and the goal is replanned — but validated findings are facts about
+     * the WORKSPACE, not about the plan's structure, so discarding them silently would make the run redo
+     * work it had already proved. They are agent-authored text, so they cross a prompt boundary fenced,
+     * exactly like every other untrusted string.
+     */
+    findingsBrief(exec) {
+        const active = parseAgentTasks(exec)
+            .tasks.flatMap((t) => t.findings)
+            .filter((f) => f.status === 'active')
+            .slice(0, FINDINGS_BRIEF_MAX);
+        if (!active.length)
+            return undefined;
+        const lines = active.map((f) => `- [${flattenClamp(f.type, 40)}] ${flattenClamp(f.subject ?? '', 60)}: ${flattenClamp(f.claim, 160)}`);
+        return wrapUntrusted('prior-findings', `Already established by earlier agent work:\n${lines.join('\n')}`);
+    }
+    /**
+     * Fingerprint the MCP tools a plan actually references (Phase 3.5). An MCP server is remote and
+     * mutable: while a plan sits paused it can change a tool's input schema, change what it does, or drop
+     * it entirely — and the plan would then be resumed against a tool that is no longer the tool it was
+     * planned for. Hashing the live declaration makes that visible as ordinary drift.
+     *
+     * Non-MCP tools are deliberately absent: they are in-tree code covered by the config/skill hashes.
+     */
+    mcpToolHashes(plan) {
+        const out = {};
+        if (!plan)
+            return out;
+        for (const step of plan.steps) {
+            if (!step.tool || !step.tool.startsWith('mcp:') || out[step.tool])
+                continue;
+            const tool = this._tools.get(step.tool);
+            // A missing tool hashes to a sentinel rather than being skipped — "gone" must be comparable, or a
+            // removed server would silently look like no drift at all.
+            out[step.tool] = tool ? hashOf({ description: tool.description, parameters: tool.parameters ?? null }) : 'absent';
+        }
+        return out;
+    }
+    /**
+     * Crash / pause / cancel reconciliation (Phase 3.5). A record left `running` or `created` describes a
+     * worker that no longer exists — the process died, or the parent stopped it — so it goes back to
+     * `queued` with an auditable reason. An interruption is deliberately NOT a state: the lifecycle does
+     * not grow, only the explanation does.
+     *
+     * This runs on the RESUME path and inside pause/cancel. Resume alone is not enough: `cancelExecution`
+     * writes a terminal status and resume early-returns on terminal, so a cancelled execution's `running`
+     * records would stay `running` on disk forever, unstamped and unexplained.
+     *
+     * Records that fail validation are preserved in place, never dropped — reconciling is not a licence to
+     * delete what this version could not parse.
+     */
+    reconcileAgentTasks(exec, kind) {
+        const raw = exec.agentTasks;
+        if (!Array.isArray(raw) || raw.length === 0)
+            return 0;
+        const { tasks, dropped } = parseAgentTasks(exec);
+        const now = this.clock.now();
+        const fixed = new Map();
+        for (const t of tasks) {
+            if (t.state !== 'running' && t.state !== 'created')
+                continue;
+            fixed.set(t.agentTaskId, { ...t, state: 'queued', interruption: { kind, at: now }, updatedAt: now });
+        }
+        if (dropped)
+            exec.agentTasksDropped = dropped;
+        if (fixed.size === 0)
+            return 0;
+        exec.agentTasks = raw.map((entry) => fixed.get(entry.agentTaskId ?? '') ?? entry);
+        return fixed.size;
+    }
+    /**
+     * FIRST-WINS PENDING. `Execution.pending` is a single slot but two agents can be waiting at once, so
+     * the earliest-created waiting task claims it. The others are not lost: once this one is answered and
+     * the run continues, the next resume re-elects whichever task is still waiting — rediscovery, rather
+     * than a queue that has to be kept in sync with the records that are already the source of truth.
+     */
+    electWaitingAgent(exec) {
+        return parseAgentTasks(exec).tasks.find((t) => t.state === 'waiting_for_clarification' && t.pendingInner);
+    }
+    /**
+     * Which persisted task, if any, a plan step should CONTINUE. Bound by step-input hash, never by step
+     * id: plan step ids (`s1`, `auto1`) are model-authored and recur across replans, so an id match would
+     * hand one step's completed inner work to a different step with the same id and a different input.
+     */
+    agentResumeLookup(exec, answer) {
+        const tasks = parseAgentTasks(exec).tasks.filter((t) => AGENT_RESUMABLE.has(t.state));
+        const answeringId = exec.pending?.agentTaskId;
+        // A plan may legitimately contain two steps with identical identity (same agent, same input) — a
+        // retry, or genuinely duplicated work. Without claiming, both would resolve to the SAME record and
+        // the second would resume, and then overwrite, the first's inner work.
+        const claimed = new Set();
+        return (step) => {
+            if (!step.agent)
+                return undefined;
+            const hash = stepIdentity(step);
+            const record = tasks.find((t) => t.agentId === step.agent && t.stepInputHash === hash && !claimed.has(t.agentTaskId));
+            if (!record)
+                return undefined;
+            claimed.add(record.agentTaskId);
+            // If the files this agent worked on changed while the run was stopped, its completed inner steps
+            // are no longer safe to skip — the same rule the outer plan already lives by.
+            if (record.innerCheckpoint && reconcile(record.innerCheckpoint, this.workspaceRoot, this.skills()).drifted) {
+                const { innerPlan: _drop, ...rest } = record;
+                return { record: { ...rest, innerCompletedSteps: [], innerObservations: [], innerObservationsOmitted: 0 } };
+            }
+            // The answer belongs to exactly ONE task — the one that asked.
+            return answer && record.agentTaskId === answeringId ? { record, answer } : { record };
+        };
+    }
+    /**
+     * Every agent task this Runtime can see, newest execution first (Phase 3.6). Live ones (running in
+     * this process) and persisted ones are the same list: a task's record IS its status, so there is no
+     * second source to disagree with.
+     */
+    agentTasks(executionId) {
+        const executions = executionId ? this._executions.list().filter((e) => e.id === executionId) : this._executions.list();
+        return executions.flatMap((e) => parseAgentTasks(e).tasks.map(agentTaskView));
+    }
+    /**
+     * Stop one agent task. Four cases, and NONE of them is a silent no-op — a `stop` that appears to do
+     * nothing is indistinguishable from a bug:
+     *
+     *  - running in this process: abort it, then let the worker record `cancelled` as it unwinds;
+     *  - persisted and not finished (another process, or a dead one): write `cancelled` with a
+     *    `parent-cancel` interruption, so the record stops claiming it is queued or running;
+     *  - already finished: report that, and change nothing — a terminal state is sticky;
+     *  - unknown id: say so.
+     */
+    stopAgentTask(agentTaskId) {
+        const live = this.liveAgentTasks.get(agentTaskId);
+        if (live) {
+            live.abort();
+            // Deliberately no `state`: the abort is cooperative and the worker has not unwound yet, so
+            // claiming `cancelled` here would report a state that has not happened.
+            return { ok: true, reason: 'aborted a task running in this process' };
+        }
+        const owning = this._executions.list().find((e) => parseAgentTasks(e).tasks.some((t) => t.agentTaskId === agentTaskId));
+        if (!owning)
+            return { ok: false, reason: 'no such agent task' };
+        // A run this process is executing owns its own record. Writing it from the side would fight the
+        // run's sink, and TAKING ITS LEASE would be worse: the sink refuses a leaseless commit and treats
+        // the refusal as a stop signal, so releasing here would abort the entire run to stop one task.
+        if (this.liveRuns.has(owning.id)) {
+            return { ok: false, reason: `that task belongs to a run in flight — /cancel ${owning.id} stops the whole run` };
+        }
+        // Claim the execution properly. A live lease held elsewhere means another process is mid-run: its
+        // next commit would rewrite the file from its own memory and silently drop this edit, so refuse
+        // rather than pretend.
+        const acq = this._executions.acquire(owning.id);
+        if (!acq.ok || !acq.execution)
+            return { ok: false, reason: `the execution is busy elsewhere (${acq.reason ?? 'unavailable'})` };
+        const exec = acq.execution;
+        try {
+            // Re-read EVERYTHING from the claimed copy. The listing was a snapshot: the task may have
+            // finished since, and writing the snapshot back would revert its own counters and findings.
+            const fresh = parseAgentTasks(exec).tasks.find((t) => t.agentTaskId === agentTaskId);
+            if (!fresh)
+                return { ok: false, reason: 'the task is no longer on the record' };
+            if (AGENT_TERMINAL.has(fresh.state))
+                return { ok: false, state: fresh.state, reason: `already ${fresh.state}` };
+            const now = this.clock.now();
+            const stopped = { ...fresh, state: 'cancelled', interruption: { kind: 'parent-cancel', at: now }, endedAt: now, updatedAt: now };
+            // A cancelled task is not asking anything any more; leaving the question on it would keep
+            // advertising a prompt nobody can answer.
+            delete stopped.pendingInner;
+            exec.agentTasks = (exec.agentTasks ?? []).map((entry) => (entry.agentTaskId === agentTaskId ? stopped : entry));
+            // WITHOUT THIS THE COMMAND IS COSMETIC. `AGENT_RESUMABLE` excludes `cancelled`, so a resume
+            // offers no record for this step and the executor runs the agent again from scratch — a second
+            // paid planning call and the tools fired again, after a human asked it to stop.
+            //
+            // But mark the step done only when the CURRENT plan still contains that exact step. Step ids
+            // recur across replans, so an id from a retired plan could name a completely different step,
+            // and marking it done would silently skip work that was never even started.
+            const stepStillThere = exec.plan?.steps.some((st) => st.id === stopped.stepId && stepIdentity(st) === stopped.stepInputHash);
+            if (stepStillThere && !exec.completedSteps.includes(stopped.stepId))
+                exec.completedSteps = [...exec.completedSteps, stopped.stepId];
+            // A stopped task cannot answer, so a pending wait belonging to it would strand the execution:
+            // resume early-returns on an unanswered inner clarification, and re-election only considers
+            // tasks that are still waiting. Hand the slot to another waiter, or clear it.
+            if (exec.pending?.kind === 'clarification' && exec.pending.agentTaskId === agentTaskId) {
+                const next = this.electWaitingAgent(exec);
+                if (next?.pendingInner)
+                    exec.pending = { kind: 'clarification', question: next.pendingInner.question, agentTaskId: next.agentTaskId };
+                else
+                    delete exec.pending;
+            }
+            // `commit`, not `commitProgress`. The funnel's rules exist to stop an IN-FLIGHT RUN overwriting
+            // a decision made while it was finishing — terminal is sticky, a pause is not the runner's to
+            // erase. This is not a run: it holds the lease it just acquired, it changes one task record, and
+            // it never touches `exec.status`, so a completed execution stays completed. Refusing here would
+            // instead make a stale non-terminal task on a finished execution permanently unstoppable.
+            if (!this._executions.commit(exec))
+                return { ok: false, reason: 'another owner holds this execution' };
+            this.emitter.emit({
+                type: 'agent.task.completed',
+                // A stop is out-of-band: it belongs to no run, so this id identifies the OPERATION. It is
+                // deliberately fresh rather than an execution id borrowed to look like a run id.
+                runId: nextRunId(),
+                agentTaskId,
+                agentId: stopped.agentId,
+                stepId: stopped.stepId,
+                state: 'cancelled',
+                innerSteps: stopped.innerSteps,
+                callsUsed: stopped.callsUsed,
+                toolCallsUsed: stopped.toolCallsUsed,
+                findings: stopped.findings.length,
+            });
+            return { ok: true, state: 'cancelled', reason: stepStillThere ? 'marked a persisted task cancelled' : 'marked a persisted task cancelled (its step is no longer in the plan)' };
+        }
+        finally {
+            this._executions.release(owning.id);
+        }
+    }
     /** Abort a run that is in flight, recording WHY so a task can tell a pause from a cancellation. */
     abortLiveRun(id, reason) {
         const live = this.liveRuns.get(id);
@@ -1327,6 +1811,9 @@ export class Runtime {
         // Phase 3.4: abort whatever is actually in flight, so a pause stops live agent work instead of only
         // flipping a stored status. A no-op with agents disabled — `liveRuns` is empty then.
         this.abortLiveRun(id, 'pause');
+        // Phase 3.5: stamp whatever was mid-flight. Doing it here rather than only on resume is what stops a
+        // record sitting at `running` with no worker behind it.
+        this.reconcileAgentTasks(exec, 'pause');
         this._executions.save(exec);
         this._executions.release(id);
         return true;
@@ -1338,6 +1825,9 @@ export class Runtime {
             return false;
         exec.status = 'cancelled';
         this.abortLiveRun(id, 'parent-cancel'); // parent cancelled ⇒ every live agent controller aborted
+        // Cancel is TERMINAL and resume early-returns on terminal, so if this did not reconcile here those
+        // `running` records would stay `running` on disk forever, unstamped and unexplained.
+        this.reconcileAgentTasks(exec, 'parent-cancel');
         this._executions.save(exec);
         this._executions.release(id);
         return true;