ai-runtime-engine 2.7.0 → 2.8.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 } 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';
@@ -855,9 +885,11 @@ 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, partial, planning?.block, this.agentsEnabled ? controller.signal : undefined, { executionId: exec.id, planVersion: exec.planVersion }, sink)));
             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 +897,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 +919,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 +1035,7 @@ export class Runtime {
             clearInterval(timer);
         }
     }
-    orchestrateInput(mode, goal, policy, routing, partial, requiredCapabilities, signal, provenance) {
+    orchestrateInput(mode, goal, policy, routing, partial, requiredCapabilities, signal, provenance, sink, agentResume) {
         return {
             goal,
             mode,
@@ -912,7 +1055,10 @@ 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, signal, provenance, sink?.onRecord, 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 +1326,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 +1351,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 +1381,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, opts.signal ?? controller.signal, { executionId: exec.id, planVersion: exec.planVersion }, sink?.onRecord, 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 +1420,42 @@ 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(), budgetPaused, undefined, this.agentsEnabled ? controller.signal : undefined, { executionId: exec.id, planVersion: exec.planVersion }, sink)));
             }
             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 +1464,7 @@ 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, signal, provenance, onRecord, agentResume) {
         const envelopes = policy ? this.agentEnvelopes(policy) : [];
         const byId = new Map(envelopes.map((e) => [e.agentId, e]));
         return {
@@ -1275,7 +1480,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,
@@ -1295,6 +1504,7 @@ export class Runtime {
                                 }
                             },
                             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 }),
+                            ...(onRecord ? { onRecord } : {}),
                             ...(ctx.signal ?? signal ? { parentSignal: ctx.signal ?? signal } : {}),
                             ...(provenance ? { provenance } : { provenance: { planVersion: 1 } }),
                             abortReason: () => {
@@ -1310,6 +1520,117 @@ 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 };
+        };
+    }
     /** 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 +1648,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 +1662,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;

package/dist/security/redact.js

@@ -37,21 +37,33 @@ export function redactString(input) {
 }
 /** Deep-redact any value, returning a scrubbed clone. Non-plain objects are stringified defensively. */
 export function redact(value) {
-    return redactValue(value, new WeakSet());
+    return redactValue(value, new Set());
 }
-function redactValue(value, seen) {
+/**
+ * The `ancestors` set holds the objects on the CURRENT PATH, and each is removed on the way back out.
+ * A global visited-set would be wrong: it cannot tell a cycle from a DAG, so the second appearance of a
+ * merely SHARED object becomes the string `'[circular]'`. That is not cosmetic — a shared array turning
+ * into a string changes the shape of redacted data, and anything that then validates it (the persisted
+ * agent-task schema does) rejects the whole record. Only a genuine cycle reports `[circular]`.
+ */
+function redactValue(value, ancestors) {
     if (typeof value === 'string')
         return redactString(value);
     if (value === null || typeof value !== 'object')
         return value;
-    if (seen.has(value))
+    if (ancestors.has(value))
         return '[circular]';
-    seen.add(value);
-    if (Array.isArray(value))
-        return value.map((v) => redactValue(v, seen));
-    const out = {};
-    for (const [k, v] of Object.entries(value)) {
-        out[k] = redactValue(v, seen);
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map((v) => redactValue(v, ancestors));
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = redactValue(v, ancestors);
+        }
+        return out;
+    }
+    finally {
+        ancestors.delete(value);
     }
-    return out;
 }

package/dist/util/hash.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One short content hash, shared by everything that needs to ask "is this the same thing it was?".
+ *
+ * Phase 3.5 resume decisions turn on identity comparisons — is this the same agent definition, the same
+ * narrowed envelope, the same step input, the same MCP tool declaration — and each of those was about to
+ * grow its own hashing. They must agree, so there is exactly one implementation and one canonical JSON
+ * form: keys sorted at every depth, so `{a,b}` and `{b,a}` are the same object, which is the whole point
+ * when the thing being hashed came back from `JSON.parse`.
+ */
+/** 16 hex chars — the same width `checkpoint.ts` uses for file hashes. Identity, never security. */
+export declare function hash16(text: string): string;
+/**
+ * Stable JSON: object keys sorted at every depth, `undefined` dropped. Arrays keep their order (order is
+ * meaning in a plan's steps). Cycles are impossible in the persisted shapes this serves, and a stray one
+ * throws rather than hashing something arbitrary.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** `hash16(canonicalJson(value))` — the form every identity check in Phase 3.5 uses. */
+export declare function hashOf(value: unknown): string;

package/dist/util/hash.js

@@ -0,0 +1,39 @@
+/**
+ * One short content hash, shared by everything that needs to ask "is this the same thing it was?".
+ *
+ * Phase 3.5 resume decisions turn on identity comparisons — is this the same agent definition, the same
+ * narrowed envelope, the same step input, the same MCP tool declaration — and each of those was about to
+ * grow its own hashing. They must agree, so there is exactly one implementation and one canonical JSON
+ * form: keys sorted at every depth, so `{a,b}` and `{b,a}` are the same object, which is the whole point
+ * when the thing being hashed came back from `JSON.parse`.
+ */
+import { createHash } from 'node:crypto';
+/** 16 hex chars — the same width `checkpoint.ts` uses for file hashes. Identity, never security. */
+export function hash16(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+/**
+ * Stable JSON: object keys sorted at every depth, `undefined` dropped. Arrays keep their order (order is
+ * meaning in a plan's steps). Cycles are impossible in the persisted shapes this serves, and a stray one
+ * throws rather than hashing something arbitrary.
+ */
+export function canonicalJson(value) {
+    const walk = (v) => {
+        if (v === null || typeof v !== 'object')
+            return v;
+        if (Array.isArray(v))
+            return v.map(walk);
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            const child = v[k];
+            if (child !== undefined)
+                out[k] = walk(child);
+        }
+        return out;
+    };
+    return JSON.stringify(walk(value)) ?? 'null';
+}
+/** `hash16(canonicalJson(value))` — the form every identity check in Phase 3.5 uses. */
+export function hashOf(value) {
+    return hash16(canonicalJson(value));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-runtime-engine",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "AI Runtime \u2014 a provider-agnostic AI runtime and orchestration platform. Point it at whatever AI providers you have; it routes each task to the best available model. Ships the `ai-runtime` CLI and the `Runtime`/`AI` library API.",
   "type": "module",
   "license": "ISC",