ai-runtime-engine 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to `ai-runtime` are documented here. The format follows
 Versioning](https://semver.org/). Development history and rationale live in
 [docs/DECISIONS.md](docs/DECISIONS.md) and [docs/PROGRESS.md](docs/PROGRESS.md).
 
+## [2.9.0] — 2026-09-05
+
+Agent work becomes VISIBLE. Concurrent agent steps render as live lanes in the interactive terminal,
+`/agents` lists and stops them, `/status` surfaces work that is unfinished, and the lifecycle events
+they all read from are finally declared rather than cast. Additive: with `runtime.agents` absent no
+agent event is ever emitted, so the lane region never opens and run output is identical to 2.8.0.
+
+### Added
+
+- **Agent lifecycle event arms** — `agent.task.started`, `agent.task.progress`, `agent.task.completed`
+  on `RuntimeEvent`. Metadata only: ids, states and counts. `findings` is a COUNT, because a finding's
+  claim is agent-authored text and an event is the one surface a host may forward anywhere.
+- **`agent.task.progress` per inner wave**, plus one at plan end — bounded at waves + 1 per task, never
+  per inner step.
+- **A multi-lane display** (`src/cli/interactive/lanes.ts`) — one live row per concurrent agent, pure
+  and offline-testable: terminal width, colour and the animation tick are all parameters. Piped output,
+  `NO_COLOR` and dumb terminals get append-only transition lines instead of cursor movement.
+- **`/agents`** — list agent tasks with progress, spend and finding counts; **`/agents stop <id>`**
+  stops one, and reports every outcome including the ones that change nothing.
+- **`/status`** now names unfinished agent work, and says which task is waiting for an answer.
+- **`AgentTaskView`** + `agentTaskView()` — the public read shape. The record's persistence internals
+  (inner plan, inner observations, raw findings, diagnostics) stay internal.
+
+### Changed
+
+- **The event union's evolution contract is now documented**: a new arm is additive at runtime but
+  breaks an exhaustive `switch` at COMPILE time. Consumers must carry a default case. Arms added this
+  way are announced here.
+- `AgentTaskView` (2.8.0) — the read RESULT of `parseAgentTasks` — is renamed `AgentTasksRead`, freeing
+  the name for the per-task view above. 2.8.0 was never published, so no released consumer names it.
+
+### Fixed
+
+- **The agent events were a type lie.** Removing the `as never` cast made them *look* typed, but a
+  single object literal with a union-typed `type` compiles while carrying properties from every
+  constituent — so `agent.task.started` shipped four fields it does not declare. The emit now narrows to
+  one arm per branch, and a key-set test covers what the type system still cannot.
+- **`runId` was missing, then wrong.** The events carried none at all, and the fix left
+  `orchestrateRunners` with a positional tail whose resume call site stamped the execution id instead.
+  It is now a required field of an options object.
+- **`/agents stop` was cosmetic.** `AGENT_RESUMABLE` excludes `cancelled`, so a resume offered no record
+  for the stopped step and simply re-ran the agent — a second paid planning call after a human asked it
+  to stop. It also wedged an execution permanently when the stopped task held the pending slot, and
+  overwrote a concurrent writer's work.
+- `/quit` was reachable but absent from `/help`, alongside `/agents`. A test now asserts every command
+  is documented.
+
 ## [2.8.0] — 2026-09-05
 
 Agent work now **survives a crash**. Until this release an agent's progress existed only in memory: the
@@ -750,6 +797,7 @@ Initial release: the provider-agnostic AI **router** — capability-based routin
 scoring, evidence validation, fallback, health tracking, learning-based scoring, multi-model verification,
 budgets, MCP tools, OpenAPI-based adapter generation, and the `AI` class + CLI.
 
+[2.9.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.9.0
 [2.8.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.8.0
 [2.7.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.7.0
 [2.6.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.6.0

package/dist/agents/task.d.ts

@@ -92,6 +92,43 @@ export interface AgentTaskRecord {
 export declare const AGENT_TERMINAL: ReadonlySet<AgentTaskState>;
 /** States a persisted task may be resumed from. Exactly the complement of AGENT_TERMINAL. */
 export declare const AGENT_RESUMABLE: ReadonlySet<AgentTaskState>;
+/**
+ * The PUBLIC read shape of an agent task (Phase 3.6) — what a host or a status line needs to render
+ * progress, and nothing else.
+ *
+ * It exists so the record's internals are not frozen into the public API. `innerPlan`,
+ * `innerObservations`, `innerCheckpoint`, raw `findings` and `diagnostics` are all persistence detail:
+ * they change as the phase evolves, they carry agent-authored content, and a host that reached into
+ * them would break on the next schema version. This shape is counts, ids and states — safe to freeze.
+ */
+export interface AgentTaskView {
+    agentTaskId: string;
+    agentId: string;
+    stepId: string;
+    state: AgentTaskState;
+    innerSteps: {
+        total: number;
+        succeeded: number;
+    };
+    /** What the step reserved from the run's call budget, and what it has actually spent. */
+    callsReserved: number;
+    callsUsed: number;
+    toolCallsUsed: number;
+    /** How many findings were ADMITTED — never the findings themselves. */
+    findings: number;
+    /** Why a non-terminal task stopped, when it was stopped by something outside itself. */
+    interruption?: {
+        kind: 'crash' | 'pause' | 'parent-cancel';
+        at: number;
+    };
+    /** The question this task is waiting on, clamped. Present only while it is waiting. */
+    question?: string;
+    startedAt?: number;
+    endedAt?: number;
+    updatedAt: number;
+}
+/** Project a record onto the public view. The ONE place that mapping lives. */
+export declare function agentTaskView(record: AgentTaskRecord): AgentTaskView;
 /** One row per agent-task state. Read this table; never re-derive a projection at a call site. */
 export interface ProjectionRow {
     step: PlanStepStatus;

package/dist/agents/task.js

@@ -9,6 +9,7 @@
  * normal state and records WHY in `interruption`, so the reason is auditable without growing the
  * lifecycle.
  */
+import { flattenClamp } from '../util/flatten.js';
 /** Terminal agent-task states: reached once, never left. A commit may not move a task out of one. */
 export const AGENT_TERMINAL = new Set(['completed', 'failed', 'cancelled']);
 /** States a persisted task may be resumed from. Exactly the complement of AGENT_TERMINAL. */
@@ -20,6 +21,27 @@ export const AGENT_RESUMABLE = new Set([
     'waiting_for_clarification',
     'paused',
 ]);
+/** Project a record onto the public view. The ONE place that mapping lives. */
+export function agentTaskView(record) {
+    return {
+        agentTaskId: record.agentTaskId,
+        agentId: record.agentId,
+        stepId: record.stepId,
+        state: record.state,
+        innerSteps: record.innerSteps,
+        callsReserved: record.callsReserved,
+        callsUsed: record.callsUsed,
+        toolCallsUsed: record.toolCallsUsed,
+        findings: record.findings.length,
+        ...(record.interruption ? { interruption: { kind: record.interruption.kind, at: record.interruption.at } } : {}),
+        // The ONE untrusted string in this shape: model-authored, read back from a file some other
+        // version wrote, and rendered in a terminal. `.slice()` truncates but strips nothing.
+        ...(record.pendingInner ? { question: flattenClamp(record.pendingInner.question, 240) } : {}),
+        ...(record.startedAt !== undefined ? { startedAt: record.startedAt } : {}),
+        ...(record.endedAt !== undefined ? { endedAt: record.endedAt } : {}),
+        updatedAt: record.updatedAt,
+    };
+}
 export const AGENT_TASK_PROJECTION = {
     created: { step: 'pending', exec: 'running', reachableIn34: true },
     queued: { step: 'pending', exec: 'running', reachableIn34: true },

package/dist/agents/worker.d.ts

@@ -55,8 +55,11 @@ export interface AgentWorkerDeps {
         ref?: ArtifactRef;
         unavailable: boolean;
     };
+    /** Lifecycle notifications. `agent.task.progress` fires once per inner WAVE — never per inner step:
+     *  the inner executor runs one step at a time, so per-step would emit one event per step and a chatty
+     *  agent would push every other event out of the emitter's ring buffer. */
     emit?: (event: {
-        type: 'agent.task.started' | 'agent.task.completed';
+        type: 'agent.task.started' | 'agent.task.progress' | 'agent.task.completed';
         record: AgentTaskRecord;
     }) => void;
     parentSignal?: AbortSignal;
@@ -66,6 +69,11 @@ export interface AgentWorkerDeps {
         executionId?: string;
         planVersion: number;
     };
+    /** Phase 3.6: hands the caller a way to stop THIS task specifically, for as long as it is running.
+     *  Without it the only lever is the run's own controller, which stops every agent at once. */
+    registerAbort?: (agentTaskId: string, abort: () => void) => void;
+    /** Phase 3.6: called when the task is no longer running, so the abort handle is not kept forever. */
+    releaseAbort?: (agentTaskId: string) => void;
     /** Phase 3.5: called whenever the record MATERIALLY changes, so inner progress reaches disk while the
      *  agent is still running. Without a seam inside the inner run, everything between `running` and
      *  `finish()` — the inner plan, every completed inner step, every inner model call — is lost to a

package/dist/agents/worker.js

@@ -120,6 +120,7 @@ export async function runAgentTask(step, envelope, definition, deps) {
     const skillResults = [];
     const finish = (state, failure) => {
         deps.parentSignal?.removeEventListener('abort', onParentAbort);
+        deps.releaseAbort?.(record.agentTaskId);
         record.state = state;
         record.endedAt = deps.clock.now();
         record.updatedAt = record.endedAt;
@@ -165,6 +166,7 @@ export async function runAgentTask(step, envelope, definition, deps) {
     record.state = 'running';
     record.startedAt = deps.clock.now();
     record.updatedAt = record.startedAt;
+    deps.registerAbort?.(record.agentTaskId, () => child.abort());
     deps.emit?.({ type: 'agent.task.started', record });
     deps.onRecord?.(record);
     // (6) THE TOOL SEAM - defense in depth behind narrowEnvelope. Always a structured denial, never a
@@ -261,7 +263,15 @@ export async function runAgentTask(step, envelope, definition, deps) {
                 record.callsUsed = priorCalls + calls;
                 record.toolCallsUsed = priorToolCalls + toolCalls;
                 record.updatedAt = deps.clock.now();
+                record.innerSteps = { total: snap.plan.steps.length, succeeded: record.innerCompletedSteps.length };
                 deps.onRecord?.(record);
+                // One event per WAVE, plus one at the end. `wave-partition` fires BEFORE the wave runs, so on
+                // its own it reports the count from before — for a single-wave inner plan (the common case)
+                // that means the only progress event says 0/N, which is exactly what `started` already said,
+                // and a display would read 0/N until the task simply finished. `plan-end` fires once and is the
+                // only snapshot carrying the final count. Still not per-step: waves + 1 events per task.
+                if (snap.at === 'wave-partition' || snap.at === 'plan-end')
+                    deps.emit?.({ type: 'agent.task.progress', record });
             },
             runSkill: async (id, i) => {
                 const out = await deps.runSkill(id, i, { permissions: envelope.permissions, signal: child.signal, ai: metered });

package/dist/cli/cli.js

@@ -21,7 +21,7 @@ import { mcpCommand, mcpAddCommand, mcpRemoveCommand, mcpEnableCommand, mcpTestC
 import { startRepl } from './interactive/repl.js';
 import { printError } from './render.js';
 const program = new Command();
-program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('2.8.0');
+program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('2.9.0');
 const configOpt = ['-c, --config <path>', 'path to an ai-runtime config file'];
 // Bare `ai-runtime` (no subcommand) opens the interactive terminal. `allowExcessArguments(false)` keeps
 // a mistyped subcommand (e.g. `ai-runtime porviders`) failing fast instead of silently opening the REPL.

package/dist/cli/interactive/repl.js

@@ -13,6 +13,7 @@ import { print, printChunk, printError } from '../render.js';
 import { summarizeWorkspace } from '../../runtime/workspace/workspace.js';
 import { ReplSession, SLASH_COMMANDS } from './session.js';
 import { makeCompleter } from './complete.js';
+import { LaneSet, laneLines, frameDiff, frameRows } from './lanes.js';
 import { colorEnabled, bold, cyan, dim, gray, SPINNER_FRAMES, statusLine, clearLine } from './ansi.js';
 function banner(rt, colors) {
     const ws = rt.workspaceInfo();
@@ -96,6 +97,22 @@ export async function startRepl(configPath) {
     };
     let streamedThisRun = false;
     let spinner;
+    // Phase 3.6: concurrent agent steps render as live lanes. The region opens on the first agent event —
+    // long after the spinner has been stopped by the very first event of the run — so the two never own
+    // the cursor at the same time. With agents disabled no agent event is ever emitted, so the region
+    // never opens and output is byte-identical.
+    const lanes = new LaneSet();
+    let laneRows = 0;
+    let laneTick = 0;
+    // A late event — one arriving after the run has already returned — must not open a region on top of
+    // the prompt and leave `laneRows` set for the NEXT run's cursor arithmetic to walk into.
+    let runInFlight = false;
+    const closeLanes = () => {
+        if (laneRows > 0)
+            printChunk(frameDiff(laneRows, [], colors));
+        laneRows = 0;
+        lanes.clear();
+    };
     // Live progress + token streaming. Events are already redacted; a throwing observer can't break a run.
     rt.on((e) => {
         spinner?.stop(); // any event means work has started producing output — drop the spinner first
@@ -104,6 +121,30 @@ export async function startRepl(configPath) {
             streamedThisRun = true;
             return;
         }
+        const lane = lanes.observe(e);
+        if (lane) {
+            if (!runInFlight)
+                return; // see `runInFlight`
+            laneTick += 1;
+            if (colors) {
+                // The region must fit the viewport: `cursorUp` saturates at row 0, so a frame taller than the
+                // pane can never walk back to its own top and would redraw itself downward forever.
+                const budget = Math.max(1, (process.stdout.rows || 24) - 2);
+                const all = lanes.list();
+                const shown = all.length > budget ? all.slice(0, budget - 1) : all;
+                const lines = laneLines(shown, { cols: process.stdout.columns || 80, colors, tick: laneTick });
+                if (all.length > shown.length)
+                    lines.push(dim(`  … ${all.length - shown.length} more agent task(s)`, colors));
+                printChunk(frameDiff(laneRows, lines, colors));
+                laneRows = frameRows(lines);
+            }
+            else if (e.type !== 'agent.task.progress') {
+                // Piped, NO_COLOR or a dumb terminal: cursor games would be garbage in a log file, so report
+                // the transitions append-only instead. Progress ticks are dropped — in a log they are noise.
+                print(`  · agent ${lane.agentId} @ ${lane.stepId}: ${lane.state}`);
+            }
+            return;
+        }
         const line = progressLine(e, colors);
         if (line)
             print(line);
@@ -125,18 +166,29 @@ export async function startRepl(configPath) {
         let result;
         streamedThisRun = false;
         spinner = startSpinner(colors);
+        runInFlight = true;
+        // Readline keeps echoing keypresses while the handler awaits, and the cursor sits inside the lane
+        // region — so a keystroke mid-run writes into the frame and its clear-to-end-of-screen erases the
+        // rows below it. Pausing buffers the input instead; it is resumed on both exits below.
+        rl.pause();
         try {
             result = await session.handle(line);
         }
         catch (err) {
+            runInFlight = false;
+            rl.resume();
             spinner.stop();
+            closeLanes();
             if (streamedThisRun)
                 process.stdout.write('\n');
             printError(`error: ${err instanceof Error ? err.message : String(err)}`);
             rl.prompt();
             continue;
         }
+        runInFlight = false;
+        rl.resume();
         spinner.stop();
+        closeLanes(); // hand the cursor back before any result line is printed
         if (streamedThisRun)
             process.stdout.write('\n'); // close the streamed line before printing result lines
         if (result.clear)

package/dist/cli/interactive/session.d.ts

@@ -11,7 +11,10 @@ export interface HandleResult {
     clear?: boolean;
 }
 /** Top-level slash commands, for REPL tab-completion (Phase 21b). Kept in sync with the `handle` dispatch. */
-export declare const SLASH_COMMANDS: readonly ["help", "status", "info", "doctor", "cleanup", "mode", "compare", "models", "config", "providers", "tools", "capabilities", "mcp", "skills", "memory", "conversations", "executions", "resume", "resume-execution", "pause", "cancel", "approve", "deny", "learning", "feedback", "permissions", "budget", "stream", "dry-run", "clear", "exit", "quit"];
+export declare const SLASH_COMMANDS: readonly ["help", "status", "info", "doctor", "cleanup", "mode", "compare", "models", "config", "providers", "tools", "capabilities", "mcp", "skills", "memory", "conversations", "executions", "agents", "resume", "resume-execution", "pause", "cancel", "approve", "deny", "learning", "feedback", "permissions", "budget", "stream", "dry-run", "clear", "exit", "quit"];
+/** Exported so a test can prove every reachable command is documented — the three touch points below
+ *  are synced by hand, and `/agents` shipped tab-completable but absent from this list. */
+export declare const HELP: string[];
 export declare class ReplSession {
     private readonly runtime;
     private mode;
@@ -36,6 +39,10 @@ export declare class ReplSession {
     private learning;
     private permissions;
     private conversationsList;
+    /** Agent tasks across this project's executions, newest first. */
+    private agentsList;
+    /** Stop one agent task. Every outcome is reported — a stop that looks like nothing happened is a bug. */
+    private agentStop;
     private executionsList;
     private resumeExecution;
     private resume;

package/dist/cli/interactive/session.js

@@ -13,13 +13,17 @@ import { actionCapabilityRows, renderActionCapabilities, renderCapabilityGaps }
 import { renderMcpList, renderMcpDetail } from '../commands/mcp.js';
 import { candidatesFrom, deriveCapabilitiesOffline } from '../../runtime/planning/deriveCapabilities.js';
 import { displaySafe } from '../render.js';
+import { AGENT_TERMINAL } from '../../agents/task.js';
+import { TERMINAL as EXEC_TERMINAL } from '../../executions/execution.js';
 /** Top-level slash commands, for REPL tab-completion (Phase 21b). Kept in sync with the `handle` dispatch. */
 export const SLASH_COMMANDS = [
     'help', 'status', 'info', 'doctor', 'cleanup', 'mode', 'compare', 'models', 'config', 'providers', 'tools', 'capabilities', 'mcp',
-    'skills', 'memory', 'conversations', 'executions', 'resume', 'resume-execution', 'pause', 'cancel', 'approve',
+    'skills', 'memory', 'conversations', 'executions', 'agents', 'resume', 'resume-execution', 'pause', 'cancel', 'approve',
     'deny', 'learning', 'feedback', 'permissions', 'budget', 'stream', 'dry-run', 'clear', 'exit', 'quit',
 ];
-const HELP = [
+/** Exported so a test can prove every reachable command is documented — the three touch points below
+ *  are synced by hand, and `/agents` shipped tab-completable but absent from this list. */
+export const HELP = [
     'Commands:',
     '  /help                       show this help',
     '  /status                     workspace, mode, provider count',
@@ -49,6 +53,8 @@ const HELP = [
     '  /conversations              list recent conversations',
     '  /resume <id>                resume a conversation',
     '  /executions                 list persisted executions',
+    '  /agents                     list agent tasks (state, progress, spend, findings)',
+    '  /agents stop <id>           stop one agent task',
     '  /resume-execution <id>      resume an execution',
     '  /approve <id>               approve an execution waiting for approval, then continue',
     '  /deny <id>                  deny an execution waiting for approval (cancels it)',
@@ -59,7 +65,7 @@ const HELP = [
     '  /stream                     toggle token-by-token streaming of answers',
     '  /budget                     show the call/cost budget (AI_MAX_CALLS / AI_MAX_COST_USD)',
     '  /clear                      clear the screen',
-    '  /exit                       leave the session',
+    '  /exit, /quit                leave the session',
     '',
     'Anything else is sent to the runtime as a request.',
 ];
@@ -209,6 +215,8 @@ export class ReplSession {
                 return this.resume(args[0]);
             case 'executions':
                 return this.executionsList();
+            case 'agents':
+                return args[0] === 'stop' ? this.agentStop(args[1]) : this.agentsList();
             case 'resume-execution':
                 return this.resumeExecution(args[0]);
             case 'approve':
@@ -327,6 +335,32 @@ export class ReplSession {
             return { lines: ['no conversations yet.'] };
         return { lines: ['Recent conversations:', ...list.map((c, i) => `  ${i + 1}. ${c.id}  ${c.title} (${c.turns} turns)`)] };
     }
+    /** Agent tasks across this project's executions, newest first. */
+    agentsList() {
+        if (!this.runtime.executionStore.enabled)
+            return { lines: ['agent tasks are not persisted (stateless mode).'] };
+        const tasks = this.runtime.agentTasks().slice(0, 12);
+        if (!tasks.length)
+            return { lines: ['no agent tasks yet.', '(agents run when `runtime.agents.enabled` is set and a plan delegates to one)'] };
+        // A waiting task's question goes on its own line: it is the one thing the user must read to act.
+        const lines = tasks.flatMap((t) => {
+            const steps = `${t.innerSteps.succeeded}/${t.innerSteps.total}`;
+            const spend = `${t.callsUsed}/${t.callsReserved} call(s), ${t.toolCallsUsed} tool call(s)`;
+            const why = t.interruption ? `  (${t.interruption.kind})` : '';
+            // `stepId` is planner-authored and `question` is model-authored: both go through displaySafe,
+            // like every other untrusted string this file renders.
+            const row = `  ${t.agentTaskId}  [${t.state}]  ${t.agentId} @ ${displaySafe(t.stepId, 40)}  ${steps} inner step(s), ${spend}, ${t.findings} finding(s)${why}`;
+            return t.question ? [row, `      ? ${displaySafe(t.question, 200)}`] : [row];
+        });
+        return { lines: ['Agent tasks:', ...lines, '', 'stop one with /agents stop <agent-task-id>'] };
+    }
+    /** Stop one agent task. Every outcome is reported — a stop that looks like nothing happened is a bug. */
+    agentStop(id) {
+        if (!id)
+            return { lines: ['usage: /agents stop <agent-task-id>'] };
+        const r = this.runtime.stopAgentTask(id);
+        return { lines: [`${r.ok ? 'stopped' : 'not stopped'} ${id}: ${r.reason}${r.state ? ` (state: ${r.state})` : ''}`] };
+    }
     executionsList() {
         if (!this.runtime.executionStore.enabled)
             return { lines: ['executions are disabled (stateless mode).'] };
@@ -362,13 +396,31 @@ export class ReplSession {
     status() {
         const ws = this.runtime.workspaceInfo();
         const providers = this.runtime.ai.providers();
-        return {
-            lines: [
-                `workspace: ${ws?.name ?? '(none)'}${ws?.git.branch ? ` @ ${ws.git.branch}` : ''}`,
-                `mode:      ${this.mode}`,
-                `providers: ${providers.length} configured (${providers.filter((p) => p.enabled).length} enabled)`,
-            ],
-        };
+        const lines = [
+            `workspace: ${ws?.name ?? '(none)'}${ws?.git.branch ? ` @ ${ws.git.branch}` : ''}`,
+            `mode:      ${this.mode}`,
+            `providers: ${providers.length} configured (${providers.filter((p) => p.enabled).length} enabled)`,
+        ];
+        // Phase 3.6: agent work is the one thing that can be UNFINISHED and invisible — a task left waiting
+        // or interrupted holds its execution up, so /status names it rather than leaving the user to think
+        // to run /agents. Absent entirely when nothing has ever delegated, so the flag-off output is
+        // unchanged.
+        // Only executions that are themselves still going: a non-terminal task on a finished execution is
+        // stale bookkeeping, and reporting it as "unfinished work" forever would train the user to ignore
+        // this line — which is the one line that has to be trusted when something IS waiting.
+        const live = this.runtime.executionStore.enabled ? this.runtime.executions().filter((e) => !EXEC_TERMINAL.has(e.status)) : [];
+        const tasks = live.flatMap((e) => this.runtime.agentTasks(e.id));
+        if (tasks.length) {
+            const unfinished = tasks.filter((t) => !AGENT_TERMINAL.has(t.state));
+            const waiting = unfinished.filter((t) => t.state === 'waiting_for_clarification' || t.state === 'waiting_for_input');
+            lines.push(`agents:    ${tasks.length} task(s), ${unfinished.length} unfinished${waiting.length ? `, ${waiting.length} waiting for an answer` : ''}`);
+            for (const t of unfinished.slice(0, 3)) {
+                lines.push(`             ${t.agentTaskId} [${t.state}] ${displaySafe(t.agentId, 24)} @ ${displaySafe(t.stepId, 16)}  ${t.innerSteps.succeeded}/${t.innerSteps.total} step(s)`);
+            }
+            if (unfinished.length > 3)
+                lines.push(`             … ${unfinished.length - 3} more (/agents)`);
+        }
+        return { lines };
     }
     setOrShowMode(next) {
         if (!next)

package/dist/executions/agentTasks.d.ts

@@ -35,11 +35,11 @@ export declare const persistedAgentTask: z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         at: number;
-        kind: "pause" | "crash" | "parent-cancel";
+        kind: "crash" | "pause" | "parent-cancel";
         detail?: string | undefined;
     }, {
         at: number;
-        kind: "pause" | "crash" | "parent-cancel";
+        kind: "crash" | "pause" | "parent-cancel";
         detail?: string | undefined;
     }>>;
     provenance: z.ZodObject<{
@@ -361,42 +361,14 @@ export declare const persistedAgentTask: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     v: 1;
     state: "running" | "failed" | "completed" | "waiting_for_clarification" | "cancelled" | "paused" | "waiting_for_input" | "created" | "queued";
-    createdAt: number;
-    updatedAt: number;
     stepId: string;
     agentTaskId: string;
     callsUsed: number;
-    envelopeHash: string;
     agentId: string;
-    provenance: {
-        planVersion: number;
-        executionId?: string | undefined;
-    };
-    agentDefHash: string;
-    stepInputHash: string;
-    attempt: number;
-    innerCompletedSteps: string[];
-    innerObservations: z.objectOutputType<{
-        stepId: z.ZodString;
-        skill: z.ZodOptional<z.ZodString>;
-        tool: z.ZodOptional<z.ZodString>;
-        agent: z.ZodOptional<z.ZodString>;
-        agentTaskId: z.ZodOptional<z.ZodString>;
-        ok: z.ZodBoolean;
-        output: z.ZodOptional<z.ZodString>;
-        error: z.ZodOptional<z.ZodString>;
-        code: z.ZodOptional<z.ZodString>;
-        data: z.ZodOptional<z.ZodUnknown>;
-        artifacts: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
-        callsUsed: z.ZodOptional<z.ZodNumber>;
-    }, z.ZodTypeAny, "passthrough">[];
-    innerObservationsOmitted: number;
     innerSteps: {
         succeeded: number;
         total: number;
     };
-    callsReserved: number;
-    callsRefunded: number;
     toolCallsUsed: number;
     findings: z.objectOutputType<{
         id: z.ZodString;
@@ -440,7 +412,42 @@ export declare const persistedAgentTask: z.ZodObject<{
         supersededBy: z.ZodOptional<z.ZodString>;
         createdAt: z.ZodNumber;
     }, z.ZodTypeAny, "passthrough">[];
+    createdAt: number;
+    updatedAt: number;
+    envelopeHash: string;
+    provenance: {
+        planVersion: number;
+        executionId?: string | undefined;
+    };
+    agentDefHash: string;
+    stepInputHash: string;
+    attempt: number;
+    innerCompletedSteps: string[];
+    innerObservations: z.objectOutputType<{
+        stepId: z.ZodString;
+        skill: z.ZodOptional<z.ZodString>;
+        tool: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
+        agentTaskId: z.ZodOptional<z.ZodString>;
+        ok: z.ZodBoolean;
+        output: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodUnknown>;
+        artifacts: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+        callsUsed: z.ZodOptional<z.ZodNumber>;
+    }, z.ZodTypeAny, "passthrough">[];
+    innerObservationsOmitted: number;
+    callsReserved: number;
+    callsRefunded: number;
     diagnostics: unknown[];
+    interruption?: {
+        at: number;
+        kind: "crash" | "pause" | "parent-cancel";
+        detail?: string | undefined;
+    } | undefined;
+    startedAt?: number | undefined;
+    endedAt?: number | undefined;
     innerPlan?: {
         id: string;
         version: number;
@@ -458,13 +465,6 @@ export declare const persistedAgentTask: z.ZodObject<{
         goal: string;
         reason?: string | undefined;
     } | undefined;
-    startedAt?: number | undefined;
-    endedAt?: number | undefined;
-    interruption?: {
-        at: number;
-        kind: "pause" | "crash" | "parent-cancel";
-        detail?: string | undefined;
-    } | undefined;
     innerPlanVersion?: number | undefined;
     innerCheckpoint?: z.objectOutputType<{
         at: z.ZodNumber;
@@ -488,42 +488,14 @@ export declare const persistedAgentTask: z.ZodObject<{
 }, {
     v: 1;
     state: "running" | "failed" | "completed" | "waiting_for_clarification" | "cancelled" | "paused" | "waiting_for_input" | "created" | "queued";
-    createdAt: number;
-    updatedAt: number;
     stepId: string;
     agentTaskId: string;
     callsUsed: number;
-    envelopeHash: string;
     agentId: string;
-    provenance: {
-        planVersion: number;
-        executionId?: string | undefined;
-    };
-    agentDefHash: string;
-    stepInputHash: string;
-    attempt: number;
-    innerCompletedSteps: string[];
-    innerObservations: z.objectInputType<{
-        stepId: z.ZodString;
-        skill: z.ZodOptional<z.ZodString>;
-        tool: z.ZodOptional<z.ZodString>;
-        agent: z.ZodOptional<z.ZodString>;
-        agentTaskId: z.ZodOptional<z.ZodString>;
-        ok: z.ZodBoolean;
-        output: z.ZodOptional<z.ZodString>;
-        error: z.ZodOptional<z.ZodString>;
-        code: z.ZodOptional<z.ZodString>;
-        data: z.ZodOptional<z.ZodUnknown>;
-        artifacts: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
-        callsUsed: z.ZodOptional<z.ZodNumber>;
-    }, z.ZodTypeAny, "passthrough">[];
-    innerObservationsOmitted: number;
     innerSteps: {
         succeeded: number;
         total: number;
     };
-    callsReserved: number;
-    callsRefunded: number;
     toolCallsUsed: number;
     findings: z.objectInputType<{
         id: z.ZodString;
@@ -567,7 +539,42 @@ export declare const persistedAgentTask: z.ZodObject<{
         supersededBy: z.ZodOptional<z.ZodString>;
         createdAt: z.ZodNumber;
     }, z.ZodTypeAny, "passthrough">[];
+    createdAt: number;
+    updatedAt: number;
+    envelopeHash: string;
+    provenance: {
+        planVersion: number;
+        executionId?: string | undefined;
+    };
+    agentDefHash: string;
+    stepInputHash: string;
+    attempt: number;
+    innerCompletedSteps: string[];
+    innerObservations: z.objectInputType<{
+        stepId: z.ZodString;
+        skill: z.ZodOptional<z.ZodString>;
+        tool: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
+        agentTaskId: z.ZodOptional<z.ZodString>;
+        ok: z.ZodBoolean;
+        output: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodUnknown>;
+        artifacts: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+        callsUsed: z.ZodOptional<z.ZodNumber>;
+    }, z.ZodTypeAny, "passthrough">[];
+    innerObservationsOmitted: number;
+    callsReserved: number;
+    callsRefunded: number;
     diagnostics: unknown[];
+    interruption?: {
+        at: number;
+        kind: "crash" | "pause" | "parent-cancel";
+        detail?: string | undefined;
+    } | undefined;
+    startedAt?: number | undefined;
+    endedAt?: number | undefined;
     innerPlan?: {
         id: string;
         version: number;
@@ -585,13 +592,6 @@ export declare const persistedAgentTask: z.ZodObject<{
         goal: string;
         reason?: string | undefined;
     } | undefined;
-    startedAt?: number | undefined;
-    endedAt?: number | undefined;
-    interruption?: {
-        at: number;
-        kind: "pause" | "crash" | "parent-cancel";
-        detail?: string | undefined;
-    } | undefined;
     innerPlanVersion?: number | undefined;
     innerCheckpoint?: z.objectInputType<{
         at: z.ZodNumber;
@@ -613,15 +613,16 @@ export declare const persistedAgentTask: z.ZodObject<{
         message: z.ZodString;
     }, z.ZodTypeAny, "passthrough"> | undefined;
 }>;
-export interface AgentTaskView {
+/** The result of reading agent tasks back: what parsed, and how much did not. */
+export interface AgentTasksRead {
     tasks: AgentTaskRecord[];
-    /** Records that failed validation and were left out of the view (still on disk, untouched). */
+    /** Records that failed validation and were left out (still on disk, untouched). */
     dropped: number;
 }
 /**
  * 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 declare function parseAgentTasks(exec: Pick<Execution, 'agentTasks'>): AgentTaskView;
+export declare function parseAgentTasks(exec: Pick<Execution, 'agentTasks'>): AgentTasksRead;
 /** One task by id, validated — the lookup every resume path uses. */
 export declare function findAgentTask(exec: Pick<Execution, 'agentTasks'>, agentTaskId: string): AgentTaskRecord | undefined;

package/dist/index.d.ts

@@ -102,8 +102,9 @@ 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 { AgentTaskView } from './executions/agentTasks.js';
-export { AGENT_TERMINAL, AGENT_RESUMABLE } from './agents/task.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';

package/dist/index.js

@@ -80,7 +80,7 @@ export { PLAN_STEP_STATUSES } from './orchestration/plan.js';
 // 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 } from './agents/task.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.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' };
     }

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;

package/dist/runtime/events.js

@@ -6,6 +6,10 @@
  * 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 { systemClock } from '../util/clock.js';
 import { redact } from '../security/redact.js';

package/dist/runtime/runtime.d.ts

@@ -25,6 +25,7 @@ import type { SkillSource, LoadedSource } from '../skills/discovery.js';
 import type { AgentDefinition } from '../agents/definition.js';
 import { ExecutionStore } from '../executions/store.js';
 import type { Execution } from '../executions/execution.js';
+import type { AgentTaskState, AgentTaskView } from '../agents/task.js';
 import { ArtifactStore } from '../artifacts/artifacts.js';
 import type { CompareInput } from '../comparison/comparator.js';
 import type { ComparisonResult } from '../comparison/comparison.js';
@@ -87,6 +88,8 @@ export declare 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. */
     private readonly liveRuns;
+    /** Phase 3.6: agent tasks running RIGHT NOW in this process, and how to stop each one on its own. */
+    private readonly liveAgentTasks;
     /** The config file's `budget:` ceilings, kept only so the 3.3 pre-pass can decline a model call. */
     private readonly _configBudget?;
     private readonly approval?;
@@ -285,6 +288,12 @@ export declare class Runtime {
     private runPersistence;
     /** Run `fn` while heartbeating the execution lease so a long run never lets the lease expire. */
     private withHeartbeat;
+    /**
+     * 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.
+     */
     private orchestrateInput;
     /** Record an EXECUTED orchestration outcome for learning. plan-only, dry-run, and waiting states are
      * skipped — no skill ran, so there is no success/failure to learn (recording them would teach noise). */
@@ -409,6 +418,27 @@ export declare class Runtime {
      * hand one step's completed inner work to a different step with the same id and a different input.
      */
     private agentResumeLookup;
+    /**
+     * 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?: string): 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: string): {
+        ok: boolean;
+        state?: AgentTaskState;
+        reason: string;
+    };
     /** Abort a run that is in flight, recording WHY so a task can tell a pause from a cancellation. */
     private abortLiveRun;
     /** Mark an execution paused (it can be resumed later). */

package/dist/runtime/runtime.js

@@ -54,7 +54,7 @@ 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 { 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';
@@ -159,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;
@@ -854,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);
             }
@@ -887,7 +896,15 @@ export class Runtime {
                 this.liveRuns.set(exec.id, { controller });
             // 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)));
+            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.map(persistableObservation);
             if (outcome.plan) {
@@ -1035,7 +1052,14 @@ export class Runtime {
             clearInterval(timer);
         }
     }
-    orchestrateInput(mode, goal, policy, routing, partial, requiredCapabilities, signal, provenance, sink, agentResume) {
+    /**
+     * 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,
@@ -1055,7 +1079,13 @@ 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, sink?.onRecord, agentResume),
+            ...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 } : {}),
@@ -1392,7 +1422,7 @@ export class Runtime {
                 // 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 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 } : {}) }));
+                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;
@@ -1427,7 +1457,14 @@ export class Runtime {
                 // 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)));
+                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 = [...observationsBefore, ...outcome.observations.map(persistableObservation)];
@@ -1464,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, onRecord, agentResume) {
+    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 {
@@ -1503,8 +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: () => {
@@ -1631,6 +1690,110 @@ export class Runtime {
             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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-runtime-engine",
-  "version": "2.8.0",
+  "version": "2.9.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",