ai-runtime-engine 2.7.0 → 2.9.0

package/dist/executions/agentTasks.js

@@ -0,0 +1,149 @@
+/**
+ * Persisted agent tasks (Phase 3.5) — the schema, and the ONE way anything reads them back.
+ *
+ * An `Execution` is a JSON file in the user's home. Invariant 21 says persisted agent state is
+ * schema-validated on read, and the reason is concrete: a record's `innerPlan` is EXECUTED on resume and
+ * its hashes decide whether completed work may be reused, so a malformed record is not a display problem
+ * — it is an execution problem. Validation is fail-closed per record: anything that does not parse is
+ * dropped whole and counted, never coerced or half-read.
+ *
+ * READING IS NOT WRITING. `parseAgentTasks` returns a filtered VIEW and never touches the stored record,
+ * so merely listing or acquiring an execution cannot destroy tasks it could not parse. The dropped count
+ * travels with the view so a silently shrinking list is visible instead of inferred.
+ */
+import { z } from 'zod';
+/** Structural only. A persisted inner plan still faces `validatePlan` against the envelope before it runs. */
+const planStep = z
+    .object({
+    id: z.string().min(1),
+    description: z.string(),
+    skill: z.string().optional(),
+    tool: z.string().optional(),
+    agent: z.string().optional(),
+    motivatedBy: z.array(z.string()).optional(),
+    input: z.unknown().optional(),
+    dependsOn: z.array(z.string()).optional(),
+    status: z.enum(['pending', 'running', 'succeeded', 'failed', 'skipped']),
+})
+    .strict();
+const executionPlan = z.object({ id: z.string(), goal: z.string(), version: z.number(), steps: z.array(planStep), reason: z.string().optional() }).strict();
+const observation = z
+    .object({
+    stepId: z.string(),
+    skill: z.string().optional(),
+    tool: z.string().optional(),
+    agent: z.string().optional(),
+    agentTaskId: z.string().optional(),
+    ok: z.boolean(),
+    output: z.string().optional(),
+    error: z.string().optional(),
+    code: z.string().optional(),
+    data: z.unknown().optional(),
+    artifacts: z.array(z.unknown()).optional(),
+    callsUsed: z.number().optional(),
+})
+    .passthrough();
+const evidence = z.object({ kind: z.string(), ref: z.string().optional(), detail: z.string().optional(), stepId: z.string().optional() }).passthrough();
+const finding = z
+    .object({
+    id: z.string().min(1),
+    agentId: z.string(),
+    agentTaskId: z.string(),
+    type: z.string(),
+    subject: z.string().optional(),
+    claim: z.string(),
+    verdict: z.string().optional(),
+    executionCoverage: z.number().min(0).max(1),
+    confidence: z.number().min(0).max(1),
+    evidence: z.array(evidence),
+    artifacts: z.array(z.unknown()),
+    sourceSteps: z.array(z.string()),
+    provenance: z.object({ executionId: z.string().optional(), planVersion: z.number() }).passthrough(),
+    status: z.enum(['active', 'superseded', 'contradicted']),
+    supersededBy: z.string().optional(),
+    createdAt: z.number(),
+})
+    .passthrough();
+const checkpoint = z
+    .object({
+    at: z.number(),
+    planVersion: z.number(),
+    gitHead: z.string().optional(),
+    fileHashes: z.record(z.string(), z.string()),
+    configHash: z.string().optional(),
+    skillVersions: z.record(z.string(), z.string()),
+    completedSteps: z.array(z.string()),
+    mcpTools: z.record(z.string(), z.string()).optional(),
+})
+    .passthrough();
+/** A counter read back into arithmetic: a whole number, never negative, never absurd. */
+const count = z.number().int().min(0).max(1_000_000);
+/** Bounds on the per-record collections, so one task cannot make an execution file unreadable. */
+const FINDINGS_MAX = 200;
+const DIAGNOSTICS_MAX = 200;
+const AGENT_STATES = ['created', 'queued', 'running', 'completed', 'failed', 'cancelled', 'waiting_for_input', 'waiting_for_clarification', 'paused'];
+/**
+ * The record schema. `v` is a LITERAL: a record written by a future, wider version is dropped rather
+ * than parsed as this shape — reinterpreting an unknown layout is how a resume executes something its
+ * author never wrote.
+ */
+export const persistedAgentTask = z
+    .object({
+    v: z.literal(1),
+    agentTaskId: z.string().min(1),
+    agentId: z.string().min(1),
+    stepId: z.string().min(1),
+    state: z.enum(AGENT_STATES),
+    createdAt: z.number(),
+    updatedAt: z.number(),
+    startedAt: z.number().optional(),
+    endedAt: z.number().optional(),
+    interruption: z.object({ kind: z.enum(['crash', 'pause', 'parent-cancel']), at: z.number(), detail: z.string().optional() }).strict().optional(),
+    provenance: z.object({ executionId: z.string().optional(), planVersion: z.number() }).strict(),
+    agentDefHash: z.string().min(1),
+    envelopeHash: z.string().min(1),
+    stepInputHash: z.string().min(1),
+    attempt: z.number().int().min(1),
+    innerPlanVersion: z.number().optional(),
+    innerPlan: executionPlan.optional(),
+    innerCompletedSteps: z.array(z.string()),
+    innerObservations: z.array(observation),
+    innerObservationsOmitted: z.number().int().min(0),
+    innerCheckpoint: checkpoint.optional(),
+    pendingInner: z.object({ kind: z.literal('clarification'), question: z.string(), at: z.number() }).strict().optional(),
+    // Bounded and non-negative. These are read back into budget arithmetic and into rendered status
+    // lines, so a tampered or corrupted file must not be able to inject a negative or absurd count.
+    innerSteps: z.object({ total: count, succeeded: count }).strict(),
+    callsReserved: count,
+    callsUsed: count,
+    callsRefunded: count,
+    toolCallsUsed: count,
+    findings: z.array(finding).max(FINDINGS_MAX),
+    diagnostics: z.array(z.unknown()).max(DIAGNOSTICS_MAX),
+    failure: z.object({ code: z.string(), message: z.string() }).passthrough().optional(),
+})
+    .strict();
+/**
+ * Validate the agent tasks on an execution. Pure: it reads, it never writes. Callers that then persist
+ * the execution are choosing to drop the unparseable records — reading alone never does.
+ */
+export function parseAgentTasks(exec) {
+    const raw = exec.agentTasks;
+    if (!Array.isArray(raw))
+        return { tasks: [], dropped: 0 };
+    const tasks = [];
+    let dropped = 0;
+    for (const entry of raw) {
+        const parsed = persistedAgentTask.safeParse(entry);
+        if (!parsed.success) {
+            dropped += 1;
+            continue;
+        }
+        tasks.push(parsed.data);
+    }
+    return { tasks, dropped };
+}
+/** One task by id, validated — the lookup every resume path uses. */
+export function findAgentTask(exec, agentTaskId) {
+    return parseAgentTasks(exec).tasks.find((t) => t.agentTaskId === agentTaskId);
+}

package/dist/executions/checkpoint.d.ts

@@ -16,6 +16,10 @@ export interface CaptureInput {
     skills: Skill[];
     completedSteps: string[];
     clock?: Clock;
+    /** Phase 3.5: plan-referenced MCP tool id → a hash of its live declaration. An MCP server is remote
+     *  and mutable: it can change a tool's schema, or drop it, while a plan sits paused. That is drift in
+     *  exactly the same sense as an edited file, and it was invisible before. */
+    mcpTools?: Record<string, string>;
 }
 export declare function captureCheckpoint(input: CaptureInput): Checkpoint;
 export interface Reconciliation {
@@ -23,4 +27,4 @@ export interface Reconciliation {
     reasons: string[];
 }
 /** Recompute the fingerprint and compare to a checkpoint. Any difference is drift. */
-export declare function reconcile(checkpoint: Checkpoint, root: string, skills: Skill[]): Reconciliation;
+export declare function reconcile(checkpoint: Checkpoint, root: string, skills: Skill[], mcpTools?: Record<string, string>): Reconciliation;

package/dist/executions/checkpoint.js

@@ -85,10 +85,11 @@ export function captureCheckpoint(input) {
         ...(cfg !== undefined ? { configHash: cfg } : {}),
         skillVersions,
         completedSteps: [...input.completedSteps],
+        ...(input.mcpTools && Object.keys(input.mcpTools).length ? { mcpTools: input.mcpTools } : {}),
     };
 }
 /** Recompute the fingerprint and compare to a checkpoint. Any difference is drift. */
-export function reconcile(checkpoint, root, skills) {
+export function reconcile(checkpoint, root, skills, mcpTools) {
     const reasons = [];
     // Compare directly so an ADDITION (absent at capture, present now — e.g. git initialized, config
     // added) also counts as drift, not just a change to something already captured.
@@ -110,5 +111,16 @@ export function reconcile(checkpoint, root, skills) {
         else if (cur !== ver)
             reasons.push(`skill ${id} version changed (${ver} → ${cur})`);
     }
+    // Phase 3.5: an absent `mcpTools` means the checkpoint predates this dimension — "nothing to
+    // compare", never "everything changed". A tool that vanished is drift: the plan references it.
+    if (checkpoint.mcpTools) {
+        for (const [id, hash] of Object.entries(checkpoint.mcpTools)) {
+            const cur = mcpTools?.[id];
+            if (cur === undefined)
+                reasons.push(`MCP tool ${id} is no longer available`);
+            else if (cur !== hash)
+                reasons.push(`MCP tool ${id} changed shape`);
+        }
+    }
     return { drifted: reasons.length > 0, reasons };
 }

package/dist/executions/execution.d.ts

@@ -7,6 +7,7 @@
 import type { ExecutionPlan } from '../orchestration/plan.js';
 import type { StepObservation } from '../orchestration/executor.js';
 import type { ArtifactRef } from '../runtime/types.js';
+import type { AgentTaskRecord } from '../agents/task.js';
 export type ExecutionStatus = 'planned' | 'running' | 'paused' | 'waiting_for_input' | 'waiting_for_clarification' | 'completed' | 'failed' | 'cancelled';
 /** A time-boxed claim on an execution by one process. */
 export interface Lease {
@@ -23,6 +24,10 @@ export interface Checkpoint {
     configHash?: string;
     skillVersions: Record<string, string>;
     completedSteps: string[];
+    /** Phase 3.5: plan-referenced MCP tool id → a hash of its declaration at plan time. A server that
+     *  changed a tool's shape under a paused plan is drift, exactly like an edited file. Absent on every
+     *  pre-3.5 checkpoint, which reconcile must read as "nothing to compare", never as "everything changed". */
+    mcpTools?: Record<string, string>;
 }
 /** A plan's estimated vs available model-call budget (Phase 22), carried on a budget-paused execution. */
 export interface BudgetInfo {
@@ -40,6 +45,10 @@ export interface PendingInput {
     question?: string;
     action?: string;
     budget?: BudgetInfo;
+    /** Phase 3.5: set when the wait belongs to an AGENT's inner run. The answer is then routed into that
+     *  task's inner resume — appending it to the OUTER goal would replan and destroy every sibling's
+     *  progress. Absent ⇒ the wait is the outer run's, which is the pre-3.5 behaviour unchanged. */
+    agentTaskId?: string;
 }
 export interface Execution {
     id: string;
@@ -57,6 +66,20 @@ export interface Execution {
     createdAt: number;
     updatedAt: number;
     lease?: Lease;
+    /** Phase 3.5: budgeted step-calls charged across every run AND resume of this execution — the unit
+     *  `foldCalls` counts, NOT provider requests (planning calls are deliberately outside the pool).
+     *
+     *  ACCOUNTING, NOT A CAP. It is deliberately not subtracted from `maxCalls` on resume: `AI_MAX_CALLS`
+     *  bounds a RUN, and "raise it and resume" is how a partially-budgeted plan makes progress (Phase 22).
+     *  Treating it as a cumulative task ceiling would make `AI_MAX_CALLS=1` un-resumable — the first run
+     *  spends the whole allowance and every resume gets a budget of zero. See DECISIONS D132.
+     *  Optional because records written before 3.5 do not have it: always read `?? 0`. */
+    callsUsed?: number;
+    /** Phase 3.5: the agent tasks this execution owns, in creation order. Schema-validated on read. */
+    agentTasks?: AgentTaskRecord[];
+    /** Phase 3.5, diagnostic: how many persisted agent tasks failed validation on the last read. Counted
+     *  so a silently shrinking list is visible; the dropped records are never rendered as content. */
+    agentTasksDropped?: number;
 }
 export declare const RESUMABLE: ReadonlySet<ExecutionStatus>;
 export declare const TERMINAL: ReadonlySet<ExecutionStatus>;

package/dist/executions/store.d.ts

@@ -21,6 +21,26 @@ export interface AcquireResult {
     execution?: Execution;
     reason?: string;
 }
+/**
+ * Why a mid-run progress commit was accepted or refused (Phase 3.5).
+ *
+ * Every refusal means the same thing to the caller: SOMEONE ELSE now owns this execution's fate, and
+ * this process must stop — not retry, not carry on discarding writes. A run that keeps executing after a
+ * refused commit doubles every tool side effect and every model call while another owner re-runs the
+ * same steps, so the caller is required to abort. That is why this is an enum and not a boolean: a
+ * boolean invites an ignored return value at the call site, which is exactly the bug.
+ */
+export type CommitOutcome = 'ok'
+/** The record is gone from disk (deleted under us). */
+ | 'missing'
+/** Another owner holds the lease, or ours is gone — writing would clobber a live run. */
+ | 'foreign-lease'
+/** The lease was released out from under us. Never write leaseless: an unleased record is claimable. */
+ | 'released'
+/** Disk reached a terminal status. TERMINAL IS STICKY — a snapshot from before it may not undo it. */
+ | 'terminal'
+/** Someone paused us. `paused` is not terminal, but this owner cannot produce it, so it is not ours to overwrite. */
+ | 'paused';
 export declare class ExecutionStore {
     private readonly area;
     readonly owner: string;
@@ -42,6 +62,23 @@ export declare class ExecutionStore {
     /** Claim an execution. Fails if a DIFFERENT owner holds a live lease; steals an expired one. Re-reads
      * after writing to detect losing a concurrent steal (best-effort — no OS lock). */
     acquire(id: string): AcquireResult;
+    /**
+     * THE mid-run write (Phase 3.5). Every incremental commit point goes through here and nothing else
+     * writes an execution while a run is in flight, so all four ordering rules live in one place:
+     *
+     *  1. TERMINAL IS STICKY. A commit carries a snapshot taken before it was built; if the record reached
+     *     `completed`/`failed`/`cancelled` in the meantime, that verdict stands. Without this, a cancel is
+     *     undone by the next in-flight wave's commit milliseconds later.
+     *  2. `paused` IS NOT OURS TO OVERWRITE. A running owner never writes `paused`, so finding it on disk
+     *     means someone else did — and the pre-3.5 behaviour (clobber it at end of run) is far worse here,
+     *     because commits are frequent: the pause would be erased within one batch, before any heartbeat
+     *     tick could observe it.
+     *  3. NEVER WRITE LEASELESS. An unleased record is claimable by any process; writing one back without
+     *     a lease invites a second owner to acquire and re-run everything this owner is still doing.
+     *  4. THE DISK LEASE WINS. Lease bookkeeping belongs to acquire/heartbeat; a progress commit carries a
+     *     possibly-stale copy and must not push it back.
+     */
+    commitProgress(exec: Execution): CommitOutcome;
     /** Write only if we still hold the lease (or it's free/expired) — never clobber a live different owner. */
     commit(exec: Execution): boolean;
     /** Renew this owner's lease. Returns false if we no longer hold it. */

package/dist/executions/store.js

@@ -9,6 +9,7 @@
  */
 import { hostname } from 'node:os';
 import { systemClock } from '../util/clock.js';
+import { TERMINAL } from './execution.js';
 export class ExecutionStore {
     area;
     owner;
@@ -85,6 +86,38 @@ export class ExecutionStore {
             return { ok: false, reason: 'lost the acquire race' };
         return { ok: true, execution: confirmed };
     }
+    /**
+     * THE mid-run write (Phase 3.5). Every incremental commit point goes through here and nothing else
+     * writes an execution while a run is in flight, so all four ordering rules live in one place:
+     *
+     *  1. TERMINAL IS STICKY. A commit carries a snapshot taken before it was built; if the record reached
+     *     `completed`/`failed`/`cancelled` in the meantime, that verdict stands. Without this, a cancel is
+     *     undone by the next in-flight wave's commit milliseconds later.
+     *  2. `paused` IS NOT OURS TO OVERWRITE. A running owner never writes `paused`, so finding it on disk
+     *     means someone else did — and the pre-3.5 behaviour (clobber it at end of run) is far worse here,
+     *     because commits are frequent: the pause would be erased within one batch, before any heartbeat
+     *     tick could observe it.
+     *  3. NEVER WRITE LEASELESS. An unleased record is claimable by any process; writing one back without
+     *     a lease invites a second owner to acquire and re-run everything this owner is still doing.
+     *  4. THE DISK LEASE WINS. Lease bookkeeping belongs to acquire/heartbeat; a progress commit carries a
+     *     possibly-stale copy and must not push it back.
+     */
+    commitProgress(exec) {
+        const disk = this.get(exec.id);
+        if (!disk)
+            return 'missing';
+        if (TERMINAL.has(disk.status))
+            return 'terminal';
+        if (disk.status === 'paused' && exec.status !== 'paused')
+            return 'paused';
+        if (!disk.lease)
+            return 'released';
+        if (disk.lease.owner !== this.owner)
+            return 'foreign-lease';
+        exec.lease = disk.lease;
+        this.save(exec);
+        return 'ok';
+    }
     /** Write only if we still hold the lease (or it's free/expired) — never clobber a live different owner. */
     commit(exec) {
         const disk = this.get(exec.id);

package/dist/index.d.ts

@@ -101,6 +101,11 @@ export type { Finding, FindingEvidence, FindingEvidenceKind, FindingStatus } fro
 export type { AdmissionRejection, AdmissionResult } from './agents/admit.js';
 export type { StepObservationCode } from './orchestration/executor.js';
 export { PLAN_STEP_STATUSES } from './orchestration/plan.js';
+export { parseAgentTasks, findAgentTask } from './executions/agentTasks.js';
+export type { AgentTasksRead } from './executions/agentTasks.js';
+export { AGENT_TERMINAL, AGENT_RESUMABLE, agentTaskView } from './agents/task.js';
+export type { AgentTaskView } from './agents/task.js';
+export type { ProgressSnapshot } from './orchestration/executor.js';
 export { mcpToolId } from './mcp/toolAdapter.js';
 export { MCP_PROTOCOL_VERSION } from './mcp/protocol.js';
 export type { McpServerConfig, McpServerState, McpServerStatus, McpTransportKind } from './mcp/manager.js';

package/dist/index.js

@@ -74,6 +74,13 @@ export { deriveCapabilities, deriveCapabilitiesOffline, candidatesFrom, candidat
 export { ActionCapabilityRegistry, capabilityReportFrom } from './capabilities/registry.js';
 export { CURATED_VOCABULARY, curated, isCurated } from './capabilities/vocabulary.js';
 export { PLAN_STEP_STATUSES } from './orchestration/plan.js';
+// ── Agent persistence (Phase 3.5) — reading back what a run left on disk ──
+// `parseAgentTasks` is exported because it is the ONLY correct way to read agent tasks off an
+// Execution: the raw array is unvalidated JSON from a file, and a host that reads it directly would
+// trust records this version cannot parse. The state sets are exported with it because "is this task
+// finished?" must have one answer, not one per caller.
+export { parseAgentTasks, findAgentTask } from './executions/agentTasks.js';
+export { AGENT_TERMINAL, AGENT_RESUMABLE, agentTaskView } from './agents/task.js';
 // ── MCP connectivity (Phase 3.2) — external servers as ordinary Runtime tools ──
 // The CONFIG + STATUS surface is public; the client, transports, and manager internals are not, so the
 // wire implementation stays free to change without a breaking release.

package/dist/orchestration/executor.d.ts

@@ -10,7 +10,10 @@ import type { ExecutionPlan, PlanStep } from './plan.js';
 import type { ReserveAgentCalls } from './budget.js';
 import type { ArtifactRef } from '../runtime/types.js';
 /** Why a step ended the way it did, when the reason is not simply "the skill/tool said so". */
-export type StepObservationCode = 'cancelled' | 'agent-failed' | 'agent-timeout' | 'agent-call-budget' | 'agent-tool-budget' | 'finding-contract' | 'agent-not-enabled';
+export type StepObservationCode = 'cancelled' | 'agent-failed' | 'agent-timeout' | 'agent-call-budget' | 'agent-tool-budget' | 'finding-contract' | 'agent-not-enabled'
+/** Phase 3.5: the agent's inner run needs an answer. NOT a failure — the step stays `pending` so a
+ *  resume re-runs it rather than skipping its dependents. */
+ | 'agent-waiting';
 export interface StepObservation {
     stepId: string;
     skill?: string;
@@ -31,6 +34,22 @@ export interface StepObservation {
     /** Phase 3.4, agent steps only: METERED inner model calls. Charging the actual is the refund. */
     callsUsed?: number;
 }
+/**
+ * A quiescent moment in `executePlan`, handed to `ExecuteDeps.onProgress` (Phase 3.5).
+ *
+ * Every fire point is between awaits — no `Promise.all` is in flight and every semaphore slot has been
+ * released — so the plan's step statuses are consistent and the snapshot describes a state the run could
+ * legitimately be resumed from. `observations` is a DELTA (what appeared since the previous fire), so a
+ * sink appends rather than de-duplicating; `callsUsed` is cumulative for this `executePlan` call.
+ */
+export interface ProgressSnapshot {
+    at: 'wave-partition' | 'batch' | 'budget-stop' | 'plan-end';
+    plan: ExecutionPlan;
+    observations: StepObservation[];
+    callsUsed: number;
+    /** Step ids whose agent is waiting for input. Non-empty ⇒ the run is resumable, NOT failed. */
+    waiting: string[];
+}
 export interface ExecuteResult {
     ok: boolean;
     plan: ExecutionPlan;
@@ -38,6 +57,8 @@ export interface ExecuteResult {
     /** Phase 22: true when execution paused BEFORE a wave because running it would exceed `callBudget`.
      *  Not a failure — the completed steps stand and the rest can resume with a raised budget. */
     stoppedForBudget?: boolean;
+    /** Phase 3.5: steps left waiting for input. Non-empty ⇒ resumable; callers must not report `failed`. */
+    waiting?: string[];
     /** Model calls (skill steps) actually executed this run. */
     callsUsed?: number;
 }
@@ -68,6 +89,10 @@ export interface ExecuteDeps {
     }) => Promise<StepObservation>;
     /** Phase 3.4: what an agent step reserves. The SAME function the pre-flight estimate uses. */
     reserve?: ReserveAgentCalls;
+    /** Phase 3.5: called at each quiescent point so progress reaches disk BEFORE the next wave starts
+     *  (invariant 18). Synchronous and must not throw — the executor does not own persistence policy and
+     *  will not try to recover from a sink that fails. */
+    onProgress?: (snapshot: ProgressSnapshot) => void;
 }
 /** Execute a plan. Runs DAG waves; within a wave, batches of at most maxParallelSteps run concurrently. */
 export declare function executePlan(plan: ExecutionPlan, deps: ExecuteDeps): Promise<ExecuteResult>;

package/dist/orchestration/executor.js

@@ -34,7 +34,11 @@ async function runStepInner(step, deps) {
         if (step.agent) {
             if (!deps.runAgent)
                 return { stepId: step.id, agent: step.agent, ok: false, code: 'agent-not-enabled', error: 'agent execution is not enabled' };
-            return deps.runAgent(step, { reservation: stepCalls(step, Number.POSITIVE_INFINITY, deps.reserve), ...(deps.signal ? { signal: deps.signal } : {}) });
+            // `return await`, NOT a bare return. In an async function a returned promise is ADOPTED, not
+            // caught, so a bare return here escapes this try/catch entirely: a throwing agent rejected the
+            // whole executePlan instead of failing its own step, and left its wave-mates running unawaited.
+            // The skill and tool branches above both await, which is why only agents had this hole.
+            return await deps.runAgent(step, { reservation: stepCalls(step, Number.POSITIVE_INFINITY, deps.reserve), ...(deps.signal ? { signal: deps.signal } : {}) });
         }
         return { stepId: step.id, ok: false, error: 'step names neither a skill nor a tool' };
     }
@@ -55,8 +59,20 @@ export async function executePlan(plan, deps) {
     // a step carrying `agent` can enter this set, so with agents disabled it is provably empty and both
     // branches below render exactly as 2.6.0.
     const cancelled = new Set();
+    // Phase 3.5: steps whose agent asked for input. They are NOT failures — the step stays `pending`, its
+    // dependents are neither run nor skipped, and the run stops scheduling so it can be resumed.
+    const waiting = new Set();
     let callsUsed = 0; // model calls = executed skill steps (tool steps are free)
     let stoppedForBudget = false;
+    // Phase 3.5: observations are handed to the sink as a DELTA, so it appends instead of de-duplicating.
+    let emitted = 0;
+    const fire = (at) => {
+        if (!deps.onProgress)
+            return;
+        const delta = observations.slice(emitted);
+        emitted = observations.length;
+        deps.onProgress({ at, plan, observations: delta, callsUsed, waiting: [...waiting] });
+    };
     for (const wave of executionWaves(plan.steps)) {
         // A step runs only if all its dependencies succeeded; otherwise it is skipped.
         const runnable = [];
@@ -89,12 +105,16 @@ export async function executePlan(plan, deps) {
                 runnable.push(step);
             }
         }
+        // Every skipped/cancelled verdict for this wave is now decided and nothing is in flight: the
+        // cheapest honest moment to get the wave's shape on disk, and it precedes the budget stop below.
+        fire('wave-partition');
         // Phase 22 budget gate: if running this wave's skill steps would exceed the call budget, stop BEFORE
         // it (phase granularity). Remaining steps keep status 'pending' and can resume with a raised budget.
         if (deps.callBudget !== undefined) {
             const waveCalls = foldCalls(runnable, deps.callBudget - callsUsed, deps.reserve);
             if (waveCalls > 0 && callsUsed + waveCalls > deps.callBudget) {
                 stoppedForBudget = true;
+                fire('budget-stop');
                 break;
             }
         }
@@ -104,22 +124,43 @@ export async function executePlan(plan, deps) {
             const results = await Promise.all(batch.map((s) => runStep(s, deps, limiters)));
             results.forEach((obs, j) => {
                 const step = batch[j];
-                step.status = obs.ok ? 'succeeded' : 'failed';
+                // A waiting agent is the one non-terminal step outcome: it is neither a success nor a failure, so
+                // it must not mark the step `failed` — that would skip every dependent and make the branch
+                // unrecoverable on resume, which is the opposite of what waiting means.
+                const isWaiting = !obs.ok && obs.code === 'agent-waiting';
+                step.status = isWaiting ? 'pending' : obs.ok ? 'succeeded' : 'failed';
                 if (step.skill)
                     callsUsed += 1;
                 // Charging what an agent actually SPENT is the refund: an aborted or cancelled task reports its
                 // metered total and the unspent reservation is simply never charged. No ledger, no refund path.
                 else if (step.agent)
                     callsUsed += obs.callsUsed ?? stepCalls(step, Number.POSITIVE_INFINITY, deps.reserve);
-                if (!obs.ok && obs.code === 'cancelled')
-                    cancelled.add(step.id);
-                if (!obs.ok)
-                    failedOrSkipped.add(step.id);
+                if (isWaiting)
+                    waiting.add(step.id);
+                else {
+                    if (!obs.ok && obs.code === 'cancelled')
+                        cancelled.add(step.id);
+                    if (!obs.ok)
+                        failedOrSkipped.add(step.id);
+                }
                 observations.push(obs);
             });
+            fire('batch');
         }
+        // Something is waiting for a human. Scheduling further waves would run work whose inputs may change
+        // once the answer arrives, so the run stops here and resumes when it is answered.
+        if (waiting.size > 0)
+            break;
     }
-    // Success only if every step succeeded AND we didn't stop early for budget.
-    const ok = !stoppedForBudget && plan.steps.every((s) => s.status === 'succeeded');
-    return { ok, plan, observations, callsUsed, ...(stoppedForBudget ? { stoppedForBudget: true } : {}) };
+    // Success only if every step succeeded AND we didn't stop early for budget or for an answer.
+    const ok = !stoppedForBudget && waiting.size === 0 && plan.steps.every((s) => s.status === 'succeeded');
+    fire('plan-end');
+    return {
+        ok,
+        plan,
+        observations,
+        callsUsed,
+        ...(stoppedForBudget ? { stoppedForBudget: true } : {}),
+        ...(waiting.size > 0 ? { waiting: [...waiting] } : {}),
+    };
 }

package/dist/orchestration/orchestrator.d.ts

@@ -54,6 +54,12 @@ export interface OrchestrateInput {
     runAgent?: ExecuteDeps['runAgent'];
     /** Phase 3.1: maps unregistered plan references to structured gaps. */
     resolveGaps?: PlannerInput['resolveGaps'];
+    /** Phase 3.5: the plan is settled — approved if approval was required, and inside the call budget.
+     *  Fired BEFORE the first step runs, so a crash during wave 1 still resumes against a real plan
+     *  instead of replanning from the bare goal. */
+    onPlan?: (plan: ExecutionPlan) => void;
+    /** Phase 3.5: forwarded verbatim to `executePlan` — the per-wave/per-batch commit points. */
+    onProgress?: ExecuteDeps['onProgress'];
 }
 export interface OrchestrateOutcome {
     status: OrchestrationStatus;

package/dist/orchestration/orchestrator.js

@@ -119,7 +119,10 @@ export async function orchestrate(input) {
                 summary: `This task looks like ~${estCalls} model call(s), but the budget is ${maxCalls}. Raise the budget (AI_MAX_CALLS or maxCalls) and re-run, or run the phases that fit with --partial (then resume as you raise it).`,
             };
         }
-        const exec = await executePlan(plan, { runSkill: input.runSkill, runTool: input.runTool, ...(input.runAgent ? { runAgent: input.runAgent } : {}), ...(reserve ? { reserve } : {}), ...(input.policy.maxParallelSteps ? { maxParallelSteps: input.policy.maxParallelSteps } : {}), ...(input.policy.limits ? { limits: input.policy.limits } : {}), ...(input.signal ? { signal: input.signal } : {}), ...(maxCalls !== undefined ? { callBudget: maxCalls } : {}) });
+        // Settled: approved (if required) and within budget. Everything a resume needs about the PLAN is
+        // known, and nothing has run yet.
+        input.onPlan?.(plan);
+        const exec = await executePlan(plan, { ...(input.onProgress ? { onProgress: input.onProgress } : {}), runSkill: input.runSkill, runTool: input.runTool, ...(input.runAgent ? { runAgent: input.runAgent } : {}), ...(reserve ? { reserve } : {}), ...(input.policy.maxParallelSteps ? { maxParallelSteps: input.policy.maxParallelSteps } : {}), ...(input.policy.limits ? { limits: input.policy.limits } : {}), ...(input.signal ? { signal: input.signal } : {}), ...(maxCalls !== undefined ? { callBudget: maxCalls } : {}) });
         allObservations.push(...exec.observations);
         if (exec.stoppedForBudget) {
             const done = plan.steps.filter((s) => s.status === 'succeeded').length;
@@ -132,6 +135,20 @@ export async function orchestrate(input) {
                 summary: `Ran ${done} of ${plan.steps.length} step(s) within the ${maxCalls}-call budget. Raise the budget (AI_MAX_CALLS) and resume to continue.`,
             };
         }
+        // An agent is waiting for a human. This MUST precede the failure branch: replanning here would
+        // discard the plan the waiting task belongs to and orphan every sibling agent's completed work.
+        if (exec.waiting?.length) {
+            const asked = exec.observations.find((o) => o.code === 'agent-waiting');
+            const done = plan.steps.filter((st) => st.status === 'succeeded').length;
+            return {
+                status: 'waiting_for_clarification',
+                plan,
+                planHistory,
+                observations: [...allObservations],
+                clarification: asked?.error ?? 'an agent needs more information to continue',
+                summary: `Paused after ${done} of ${plan.steps.length} step(s): an agent needs an answer. Resume with it to continue.`,
+            };
+        }
         if (exec.ok)
             return { status: 'completed', plan, planHistory, observations: [...allObservations], summary: `completed "${plan.goal}" in ${plan.steps.length} step(s)` };
         // Failed: gather evidence and replan (orchestrate only) or stop.

package/dist/runtime/events.d.ts

@@ -6,10 +6,15 @@
  * Token-streaming extension point: `response.delta` is reserved here (content-bearing, redacted like
  * everything else). Provider token streaming is NOT implemented in 1.0 — no delta is ever emitted yet —
  * but declaring the arm keeps the host/emitter architecture ready for it without a breaking change.
+ *
+ * EVOLUTION CONTRACT: this union GROWS. A new arm is additive at runtime — an existing consumer keeps
+ * receiving the events it knows — but it breaks an exhaustive `switch` at COMPILE time. Consumers must
+ * carry a default case. Arms added this way are announced in the CHANGELOG.
  */
 import type { Clock } from '../util/clock.js';
 import type { ErrorCategory } from '../types.js';
 import type { ExecutableMode, ModeSource, RuntimeMode, RuntimeStatus } from './types.js';
+import type { AgentTaskState } from '../agents/task.js';
 export type RuntimeEvent = {
     type: 'runtime.started';
     ts: number;
@@ -54,6 +59,45 @@ export type RuntimeEvent = {
     ts: number;
     runId: string;
     text: string;
+} | {
+    type: 'agent.task.started';
+    ts: number;
+    runId: string;
+    agentTaskId: string;
+    agentId: string;
+    stepId: string;
+    state: AgentTaskState;
+} | {
+    type: 'agent.task.progress';
+    ts: number;
+    runId: string;
+    agentTaskId: string;
+    agentId: string;
+    stepId: string;
+    /** Per inner WAVE, never per inner step: a chatty agent would otherwise flood the ring buffer
+     *  and push every other event out of it. */
+    innerSteps: {
+        total: number;
+        succeeded: number;
+    };
+    callsUsed: number;
+    toolCallsUsed: number;
+} | {
+    type: 'agent.task.completed';
+    ts: number;
+    runId: string;
+    agentTaskId: string;
+    agentId: string;
+    stepId: string;
+    state: AgentTaskState;
+    innerSteps: {
+        total: number;
+        succeeded: number;
+    };
+    callsUsed: number;
+    toolCallsUsed: number;
+    /** How many findings were ADMITTED. Never the findings themselves. */
+    findings: number;
 };
 /** Distributive Omit so an event can be emitted without pre-stamping `ts`. */
 type WithoutTs<T> = T extends unknown ? Omit<T, 'ts'> : never;