ai-runtime-engine 1.3.0 → 2.8.0

package/dist/runtime/runtime.js

@@ -3,12 +3,16 @@
  * a RuntimeContext, executes chat through `AI.run()`, and streams redacted lifecycle events. It never
  * routes or scores; all model selection stays in the one router. Unimplemented modes degrade to chat.
  */
-import { resolve } from 'node:path';
+import { resolve, join } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { stringify as stringifyYaml } from 'yaml';
+import { generateSkillManifest } from '../generation/generateSkill.js';
 import { AI } from '../plugin/ai.js';
 import { setCredentialResolver } from '../security/credentials.js';
 import { loadRuntimeConfig } from './config.js';
 import { detectWorkspace } from './workspace/workspace.js';
 import { HeuristicIntentClassifier } from './intent/classifier.js';
+import { AIIntentClassifier } from './intent/aiClassifier.js';
 import { resolveMode, resolveStrategy } from './modes/modeResolver.js';
 import { resolvePolicy } from './policy.js';
 import { CHAT_TASK, buildChatRequest, toRuntimeResult, inputText } from './modes/chat.js';
@@ -20,10 +24,21 @@ import { MemoryStore } from '../memory/memory.js';
 import { classifyMemory } from '../memory/classifier.js';
 import { summarizeWorkspace } from './workspace/workspace.js';
 import { compileContext } from '../context/compiler.js';
+import { verifyContextLoss } from '../context/lossVerifier.js';
+import { summarizeOverBudget } from '../context/summarize.js';
 import { resolveContextBudget } from '../context/budget.js';
 import { TokenEstimator } from '../context/tokens.js';
 import { ToolRegistry } from '../tools/registry.js';
-import { resolvePermissions } from '../tools/permissions.js';
+import { resolvePermissions, clampMcpPermissions } from '../tools/permissions.js';
+import { flattenClamp } from '../util/flatten.js';
+import { wrapUntrusted } from '../tools/untrusted.js';
+import { redact } from '../security/redact.js';
+import { McpManager } from '../mcp/manager.js';
+import { mcpTool, mcpToolId } from '../mcp/toolAdapter.js';
+import { StaticMcpSource } from '../mcp/mcp.js';
+import { ActionCapabilityRegistry, capabilityReportFrom } from '../capabilities/registry.js';
+import { namespacedId } from '../capabilities/capability.js';
+import { candidatesFrom, deriveCapabilities } from './planning/deriveCapabilities.js';
 import { filesystemTool } from '../tools/builtins/filesystem.js';
 import { shellTool } from '../tools/builtins/shell.js';
 import { gitTool } from '../tools/builtins/git.js';
@@ -32,15 +47,52 @@ import { fileAnalyzerSkill } from '../skills/builtins/fileAnalyzer.js';
 import { repositoryAnalyzerSkill } from '../skills/builtins/repositoryAnalyzer.js';
 import { discoverSkills, scanRepoForSkills, loadSkillSource, loadSkillPackage } from '../skills/discovery.js';
 import { orchestrate } from '../orchestration/orchestrator.js';
+import { foldCalls } from '../orchestration/budget.js';
+import { narrowEnvelope } from '../agents/envelope.js';
+import { runAgentTask } from '../agents/worker.js';
 import { executePlan } from '../orchestration/executor.js';
 import { ExecutionStore } from '../executions/store.js';
 import { RESUMABLE, TERMINAL } from '../executions/execution.js';
 import { captureCheckpoint, reconcile } from '../executions/checkpoint.js';
+import { AGENT_TERMINAL, AGENT_RESUMABLE } from '../agents/task.js';
+import { parseAgentTasks } from '../executions/agentTasks.js';
+import { stepIdentity } from '../agents/worker.js';
+import { hashOf } from '../util/hash.js';
+/** Checkpoints kept per execution. Only the newest is ever read; the rest are audit trail, and the
+ *  record is rewritten on every commit, so this is a file-size bound (Phase 3.5). */
+const CHECKPOINTS_MAX = 5;
+/** Findings carried into a replan prompt. Bounded because they are rendered into a model call. */
+const FINDINGS_BRIEF_MAX = 10;
+/**
+ * What an observation looks like ON DISK (Phase 3.5).
+ *
+ * Two jobs, both at the persistence boundary. REDACTION: an observation carries tool output, which is
+ * arbitrary text from outside the process — a tool that prints a token would otherwise write it into
+ * the execution file verbatim, where it survives every later read. Every other egress (logs, telemetry,
+ * CLI) already redacts; the store did not, and Phase 3.5 writes far more of this content far more often.
+ * SLIMMING: findings already live on the agent task record in the same file, so keeping only their ids
+ * here stops every finding being stored twice and rewritten on every commit.
+ *
+ * The live observation is untouched — callers still receive full findings from the run itself.
+ */
+function persistableObservation(obs) {
+    const data = obs.data;
+    const slimmed = data && Array.isArray(data.findings)
+        ? { ...obs, data: { ...(({ findings: _drop, ...rest }) => rest)(data), findingIds: data.findings.map((f) => f?.id).filter((id) => typeof id === 'string') } }
+        : obs;
+    return redact(slimmed);
+}
 import { ArtifactStore } from '../artifacts/artifacts.js';
 import { compare } from '../comparison/comparator.js';
 import { renderComparison } from '../comparison/render.js';
 import { LearningStore } from '../learning/learningStore.js';
-import { resolveRoutingPrefs, withPreferredProviders } from './routing.js';
+import { resolveRoutingPrefs, withPreferredProviders, mergeRouting } from './routing.js';
+import { loadModelProfile, resolveModelDirective, directiveToOverrides } from './models/modelProfile.js';
+import { HashEmbedder } from '../memory/embedders/hash.js';
+import { HttpEmbedder } from '../memory/embedders/http.js';
+import { Credential } from '../security/credentials.js';
+import { makeCodec, deriveKey } from '../store/crypto.js';
+import { AIError } from '../core/fallback/errors.js';
 import { tokenize } from '../memory/bm25.js';
 let runCounter = 0;
 function nextRunId() {
@@ -54,6 +106,23 @@ function numFromEnv(env, key) {
     const n = Number(raw);
     return Number.isFinite(n) ? n : undefined;
 }
+/**
+ * Clamp a source-controlled string before it is rendered into a MODEL PROMPT (invariant 15/16). Ids,
+ * provider ids, and tool lists come from tools/skills/packs — and from MCP servers in Phase 3.2 — so a
+ * rendered catalog row must never carry newlines, control characters, or unbounded text that could forge
+ * additional rows or smuggle instructions into the planner prompt.
+ */
+function promptSafe(raw, max = 80) {
+    return flattenClamp(raw, max);
+}
+/** Merge gap lists first-wins by capabilityId: pre-pass, then post-plan check, then plan validation. */
+function mergeGapsById(list) {
+    const out = new Map();
+    for (const g of list)
+        if (!out.has(g.capabilityId))
+            out.set(g.capabilityId, g);
+    return [...out.values()];
+}
 export class Runtime {
     _ai;
     settingsValue;
@@ -65,20 +134,46 @@ export class Runtime {
     _memory;
     _conversations;
     estimator = new TokenEstimator();
+    /** ACTION-capability registry (Phase 3.1). Declared BEFORE the tool/skill registries so its
+     *  ingest listeners are attached in time to capture the builtin registrations below. */
+    _capabilities = new ActionCapabilityRegistry();
+    /** MCP server lifecycle (Phase 3.2). Connection is LAZY: nothing is contacted until first use. */
+    _mcp;
+    mcpConnected = false;
+    mcpToolIds = new Set();
+    mcpWarnings = [];
     _tools = new ToolRegistry();
     _skills = new SkillRegistry();
     _executions;
     _artifacts;
     _learning;
     workspaceRoot;
+    _modelProfile;
     configPermissions;
+    /** The INJECTED clock. Agent deadlines are measured against it, never a real timer, so an offline
+     *  test with a fake clock stays deterministic. */
+    clock;
+    /** Multi-agent core (Phase 3.4). False ⇒ every agent path is inert. */
+    agentsEnabled;
+    agentDefs = new Map();
+    /** 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();
+    /** The config file's `budget:` ceilings, kept only so the 3.3 pre-pass can decline a model call. */
+    _configBudget;
     approval;
     _configFile;
     _loadedSkillSources = [];
     constructor(config = { router: { providers: [] } }, options = {}, workspace) {
-        this._ai = new AI(config.router, options.ai);
+        // Phase 19: fold the config's per-provider concurrency caps into the AI (shared limiter across runs).
+        const perProvider = config.runtime?.concurrency?.perProvider;
+        const aiOptions = { ...options.ai, ...(perProvider ? { concurrency: { ...(options.ai?.concurrency ?? {}), perProvider } } : {}) };
+        this._ai = new AI(config.router, aiOptions);
         this.settingsValue = config.runtime ?? {};
-        this.classifier = options.classifier ?? new HeuristicIntentClassifier();
+        // Base classifier: a caller-supplied one wins, else the deterministic heuristic. When
+        // `runtime.intent.aiFallback` is on, wrap it so an *ambiguous* heuristic result consults one model call.
+        const baseClassifier = options.classifier ?? new HeuristicIntentClassifier();
+        this.classifier = this.settingsValue.intent?.aiFallback ? new AIIntentClassifier(this._ai, baseClassifier) : baseClassifier;
         this.env = options.ai?.env ?? process.env;
         if (workspace)
             this.workspace = workspace;
@@ -87,19 +182,64 @@ export class Runtime {
             this.approval = options.host.approval;
         if (options.configFile)
             this._configFile = options.configFile;
+        const cfgBudget = config.router.budget?.maxCalls ?? config.router.budget?.maxCostUsd;
+        if (cfgBudget !== undefined)
+            this._configBudget = cfgBudget;
         // Local store (conversations + memory). Disabled → NullAreas (stateless mode).
         const clock = options.ai?.clock ?? systemClock;
+        this.clock = clock;
+        this.agentsEnabled = config.runtime?.agents?.enabled === true;
+        for (const [id, def] of Object.entries(config.runtime?.agents?.definitions ?? {}))
+            this.agentDefs.set(id, def);
         const root = workspace?.root ?? resolveCwd(options.workspace ?? options.host?.workspace);
         this.workspaceRoot = root;
-        this._store = new RuntimeStore({ workspaceRoot: root, ...(workspace?.name ? { workspaceName: workspace.name } : {}), env: this.env, clock, enabled: options.persistence !== 'disabled' });
-        this._memory = new MemoryStore(this._store, clock);
+        const persistenceEnabled = options.persistence !== 'disabled';
+        const cipher = persistenceEnabled ? this.buildCipher() : undefined; // throws a hard CONFIG error if encrypt:true but no key
+        this._store = new RuntimeStore({ workspaceRoot: root, ...(workspace?.name ? { workspaceName: workspace.name } : {}), env: this.env, clock, enabled: persistenceEnabled, ...(this.settingsValue.organization ? { organization: this.settingsValue.organization } : {}), ...(cipher ? { cipher } : {}) });
+        // MCP (Phase 3.2): construct always (cheap, connects nothing); a discovered tool becomes an ordinary
+        // Runtime Tool so runTool's permission/approval/signal machinery applies with no parallel path.
+        this._mcp = new McpManager({
+            ...(config.mcp?.servers ? { servers: config.mcp.servers } : {}),
+            ...(persistenceEnabled ? { store: this._store.mcp() } : {}),
+            env: this.env,
+            clock,
+            ...(options.ai?.fetchImpl ? { fetchImpl: options.ai.fetchImpl } : {}),
+            onToolsDiscovered: (serverId, tools) => this.registerMcpTools(serverId, tools),
+            onServerRemoved: (serverId) => this.deregisterMcpTools(serverId),
+        });
+        this._modelProfile = loadModelProfile(root); // models.md (per-mode/task routing); undefined if absent
+        this._memory = new MemoryStore(this._store, clock, this.buildEmbedder(options.ai?.fetchImpl));
         this._conversations = new ConversationStore(this._store.conversations(), clock);
         this._executions = new ExecutionStore(this._store.executions(), { clock });
         this._artifacts = new ArtifactStore(this._store.artifacts(), clock);
         this._learning = new LearningStore(this._store.learning());
         // Built-in tools + generic skills (QA-neutral). Users add more via registerTool/registerSkill.
-        this._tools.register(filesystemTool).register(shellTool).register(gitTool);
+        // Action capabilities: wire live accessors + ingest listeners BEFORE any registration, then
+        // register the builtins as TRUSTED (the only code allowed to claim bare curated ids).
+        this._capabilities
+            .attachAccessors({
+            toolIds: () => this._tools.ids(),
+            skills: () => this._skills.list().map((s) => ({ id: s.id, ...(s.tools ? { tools: s.tools } : {}) })),
+            mcpAvailability: (serverId) => this.mcpAvailability(serverId),
+        })
+            .configure(this.settingsValue.capabilities ?? {});
+        // An MCP-backed tool ingests under the `mcp:` namespace (its source kind drives the resolution
+        // tie-break and `removeBySourcePrefix`); `mcpToolIds` is populated BEFORE register for exactly this.
+        this._tools.attach({
+            onRegister: (t, trusted) => (this.mcpToolIds.has(t.id) ? this._capabilities.ingestMcpTool(t) : this._capabilities.ingestTool(t, trusted)),
+            onUnregister: (id) => this._capabilities.removeSource(this.mcpToolIds.has(id) ? 'mcp' : 'tool', id),
+        });
+        this._skills.attach({ onRegister: (sk) => this._capabilities.ingestSkill(sk), onUnregister: (id) => this._capabilities.removeSource('skill', id) });
+        this._tools.register(filesystemTool, true).register(shellTool, true).register(gitTool, true);
         this._skills.register(fileAnalyzerSkill).register(repositoryAnalyzerSkill);
+        // Cache-seeded MCP catalog: a previously discovered tool is plan-referenceable BEFORE (or entirely
+        // without) a connection — at availability `unknown`, denying honestly at call time. No I/O beyond
+        // the store read the manager already did, so lazy connect is preserved.
+        for (const serverId of this._mcp.ids()) {
+            const cached = this._mcp.tools(serverId);
+            if (cached.length)
+                this.registerMcpTools(serverId, cached, { cached: true });
+        }
         // Host integration: attach an event sink and register a credential resolver if supplied.
         const host = options.host;
         this.emitter = new RuntimeEmitter({
@@ -113,6 +253,41 @@ export class Runtime {
         if (!hasChat)
             this._ai.registerTask(CHAT_TASK);
     }
+    /**
+     * Build the memory embedder from `runtime.embedding` (Phase 14). Absent → undefined → BM25 keyword
+     * retrieval (the offline default). `local` = the zero-dep deterministic HashEmbedder; `openai-compatible`
+     * = the HTTP adapter (key by env NAME via `Credential`; a missing `baseUrl` yields no embedder → BM25).
+     */
+    buildEmbedder(fetchImpl) {
+        const cfg = this.settingsValue.embedding;
+        if (!cfg)
+            return undefined;
+        if (cfg.provider === 'local')
+            return new HashEmbedder();
+        if (!cfg.baseUrl)
+            return undefined; // openai-compatible needs an endpoint; no URL → stay on BM25
+        return new HttpEmbedder({
+            baseUrl: cfg.baseUrl,
+            model: cfg.model ?? 'text-embedding-3-small',
+            credential: new Credential(cfg.apiKeyEnv, this.env),
+            ...(fetchImpl ? { fetchImpl } : {}),
+        });
+    }
+    /**
+     * Build the store cipher from `runtime.storage` (Phase 18). Absent / `encrypt:false` → undefined → a
+     * plaintext store (the default). `encrypt:true` resolves the key from the env var NAMED by `keyEnv` via
+     * `Credential` (never a value) and derives an AES-256 key; a missing key is a hard CONFIG error (silent
+     * plaintext would be a lie). The key lives only inside the returned codec — never logged or serialized.
+     */
+    buildCipher() {
+        const cfg = this.settingsValue.storage;
+        if (!cfg?.encrypt)
+            return undefined;
+        const key = new Credential(cfg.keyEnv, this.env).use();
+        if (!key)
+            throw new AIError(`storage encryption is enabled but the key env var ${cfg.keyEnv} is not set`, { category: 'CONFIG' });
+        return makeCodec(deriveKey(key));
+    }
     /** Build a Runtime from a workspace: load config (.ai-runtime/config.yaml > root fallback), detect workspace. */
     static async load(options = {}) {
         const workspaceRoot = resolveCwd(options.workspace ?? options.host?.workspace);
@@ -210,6 +385,36 @@ export class Runtime {
             return base;
         return withPreferredProviders(base, this._learning.preferredProviders());
     }
+    /** The loaded `models.md` routing profile (per-mode/per-task model directives), or undefined if none. */
+    modelProfile() {
+        return this._modelProfile;
+    }
+    /**
+     * Fold the `models.md` directive for this (mode, task) into the run — a soft prefer (universal, merged
+     * into routing), a strategy, or a hard pin (chat path, via the request escape hatch). Precedence is
+     * explicit per-run > models.md: the caller's own strategy/pin win, and prefer is unioned (never
+     * re-admitting an exclusion). No profile / no matching directive ⇒ the request is returned unchanged.
+     */
+    applyModelProfile(req, mode) {
+        if (!this._modelProfile)
+            return req;
+        const directive = resolveModelDirective(this._modelProfile, { mode, ...(mode === 'chat' ? { task: 'chat' } : {}) });
+        if (!directive)
+            return req;
+        const o = directiveToOverrides(directive);
+        const next = { ...req };
+        if (o.strategy && next.strategy === undefined)
+            next.strategy = o.strategy;
+        if ((o.provider || o.model) && next.request?.provider === undefined && next.request?.model === undefined) {
+            next.request = { ...(next.request ?? {}), ...(o.provider ? { provider: o.provider } : {}), ...(o.model ? { model: o.model } : {}) };
+        }
+        if (o.routing) {
+            const merged = mergeRouting(next.routing, o.routing);
+            if (merged)
+                next.routing = merged;
+        }
+        return next;
+    }
     /** Apply free-text feedback (e.g. "that worked" / "wrong root cause") to the most recent outcome. */
     feedback(text, opts) {
         return this._learning.feedback(text, opts ?? {});
@@ -246,18 +451,206 @@ export class Runtime {
         this._skills.register(skill);
         return this;
     }
+    /**
+     * Register an agent definition (Phase 3.4). Chainable, and inert unless `runtime.agents.enabled` is
+     * set — registering a definition grants nothing on its own, exactly like adding an MCP server.
+     */
+    registerAgent(id, def) {
+        if (!/^[a-z0-9][a-z0-9_-]{0,32}$/.test(id))
+            throw new AIError(`invalid agent id '${id}' — use lowercase letters, digits, '_' or '-' (max 33 chars)`, { category: 'CONFIG' });
+        this.agentDefs.set(id, def);
+        return this;
+    }
+    /** The agent definition ids this runtime knows (registered or configured). */
+    agents() {
+        return [...this.agentDefs.keys()].sort();
+    }
+    /**
+     * This run's agent envelopes. THE ONLY call site of `narrowEnvelope` — never re-derive an inner
+     * catalog, a permission clamp, or a reservation anywhere else (see the header of agents/envelope.ts).
+     */
+    agentEnvelopes(policy) {
+        if (!this.agentsEnabled || this.agentDefs.size === 0)
+            return [];
+        const routing = this.effectiveRouting();
+        return [...this.agentDefs].map(([id, definition]) => narrowEnvelope({
+            agentId: id,
+            definition,
+            parentTools: this._tools.ids(),
+            parentSkills: this.skills().map((sk) => ({ id: sk.id, ...(sk.tools ? { tools: sk.tools } : {}) })),
+            parentPermissions: policy.permissions,
+            ...(routing ? { parentRouting: routing } : {}),
+            defaults: {
+                maxToolCalls: this.settingsValue.agents?.maxToolCalls ?? 25,
+                maxDurationMs: this.settingsValue.agents?.maxDurationMs ?? 120_000,
+                maxInnerCalls: this.settingsValue.agents?.maxInnerCalls ?? 3,
+            },
+        }));
+    }
+    // ── MCP (Phase 3.2) ────────────────────────────────────────────────────────
+    /** The MCP server manager: `list()`, `status(id)`, `test(id)`, `addServer`, `removeServer`, `setEnabled`. */
+    mcp() {
+        return this._mcp;
+    }
+    /**
+     * Connect every enabled MCP server, discover their tools, and register them. LAZY BY DESIGN: a one-shot
+     * CLI command that never touches MCP pays nothing, and a failing server records its state instead of
+     * breaking construction. Idempotent — the second call is a no-op.
+     */
+    async connectMcp() {
+        if (this.mcpConnected)
+            return this._mcp.list();
+        this.mcpConnected = true;
+        return this._mcp.connectAll();
+    }
+    /** Whether any MCP server is configured at all (absent ⇒ MCP is entirely inert). */
+    hasMcpServers() {
+        return this._mcp.ids().length > 0;
+    }
+    /**
+     * Register one server's discovered tools as ordinary Runtime Tools (+ their namespaced action
+     * capabilities, via the tool registry's ingest listener). A generated id NEVER shadows an existing
+     * non-MCP tool: the collision is skipped and reported, because silently replacing `filesystem` would be
+     * a privilege swap.
+     */
+    registerMcpTools(serverId, tools, opts = {}) {
+        const fresh = new Set();
+        for (const decl of tools) {
+            const id = mcpToolId(serverId, decl.name);
+            if (this._tools.get(id) && !this.mcpToolIds.has(id)) {
+                this.mcpWarnings.push(`MCP tool '${id}' collides with a registered tool and was skipped`);
+                continue;
+            }
+            // A CACHED annotation must never RELAX a gate: `readOnlyHint` would lower the permission gate, and
+            // `destructiveHint: false` would remove the confirmation. Until a live handshake says otherwise the
+            // tool is write-like AND destructive. (The adapter also re-reads live annotations at call time —
+            // this is the registration-side half of the same rule.)
+            const gated = opts.cached ? { ...decl, readOnly: false, destructive: true } : decl;
+            this.mcpToolIds.add(id); // before register: the capability ingest hook routes on this set
+            this._tools.register(mcpTool({
+                call: (sid, t, a, o) => this._mcp.call(sid, t, a, o),
+                usable: (sid) => this._mcp.usable(sid),
+                liveTool: (sid, t) => this._mcp.liveTool(sid, t),
+            }, serverId, gated));
+            fresh.add(id);
+        }
+        // A live discovery is the AUTHORITY on what this server offers: anything we still have registered
+        // that the server no longer lists (a stale cache entry, a withdrawn tool) must go, or it would keep
+        // reporting itself as available and get planned against.
+        if (!opts.cached) {
+            for (const id of [...this.mcpToolIds]) {
+                if (!id.startsWith(`${serverId}.`) || fresh.has(id))
+                    continue;
+                this._tools.unregister(id);
+                this.mcpToolIds.delete(id);
+                this._capabilities.removeSource('mcp', id);
+            }
+        }
+        this.publishMcpSource(serverId, tools);
+    }
+    /**
+     * The legacy declaration path (`AI.run({ mcp: true })`) — tools DECLARED to a model, never executed
+     * through here. It honors the same read/full split as execution (declaring a tool the executor would
+     * refuse just invites the model to plan around it) and is keyed by server id, so re-publishing with an
+     * empty list REVOKES it.
+     */
+    publishMcpSource(serverId, tools) {
+        const servers = this.permissions().mcp.servers;
+        const grant = Object.prototype.hasOwnProperty.call(servers, serverId) ? servers[serverId] : 'off';
+        const offered = grant === 'full' ? tools : grant === 'read' ? tools.filter((t) => t.readOnly) : [];
+        // Names are emitted ALREADY namespaced: McpRegistry only prefixes a name without a dot, so a server
+        // tool called `other.thing` would otherwise appear to the model inside another source's namespace.
+        const specs = offered.map((t) => ({ name: mcpToolId(serverId, t.name), description: `${t.description} (MCP server: ${serverId})`, ...(t.inputSchema ? { parameters: t.inputSchema } : {}) }));
+        this._ai.registerMcpSource(new StaticMcpSource(serverId, specs));
+    }
+    /** Drop a server's tools (removal / disable). */
+    deregisterMcpTools(serverId) {
+        for (const id of [...this.mcpToolIds]) {
+            if (!id.startsWith(`${serverId}.`))
+                continue;
+            this._tools.unregister(id);
+            this.mcpToolIds.delete(id);
+        }
+        this._capabilities.removeMcpServer(serverId);
+        this.publishMcpSource(serverId, []); // revoke the model-facing declarations too
+    }
+    /** Map a server's lifecycle state onto capability availability (the D7 derivation table). */
+    mcpAvailability(serverId) {
+        const st = this._mcp.status(serverId);
+        if (!st)
+            return 'unavailable';
+        if (!st.enabled || st.state === 'disabled')
+            return 'disabled';
+        if (st.state === 'connected' || st.state === 'degraded')
+            return 'available';
+        if (st.state === 'configured' || st.state === 'connecting')
+            return 'unknown'; // cache-seeded / in flight
+        return 'unavailable'; // auth_failed | unreachable
+    }
+    /** Warnings from MCP wiring (id collisions) plus the manager's own (invalid store files, etc.). */
+    mcpWarningsList() {
+        return [...this.mcpWarnings, ...this._mcp.warningsList()];
+    }
+    /**
+     * Release long-lived resources — today: MCP stdio child processes. A one-shot CLI command and the REPL
+     * both call this on completion/exit; without it a spawned server keeps the event loop alive.
+     */
+    async close() {
+        await this._mcp.close();
+    }
     /** Skills whose required tools are all registered. */
     skills() {
         return this._skills.match({ tools: this._tools.ids() });
     }
+    /**
+     * Scaffold a skill MANIFEST from a natural-language goal (Phase 21a). Drafts a `*.skill.yaml` via the
+     * model, validated by `parseManifest` + tool-membership + a dry compile. **Writes nothing** — pass the
+     * returned manifest to `saveScaffoldedSkill` on explicit confirm.
+     */
+    async scaffoldSkill(goal) {
+        return generateSkillManifest({ goal, tools: this._tools.ids(), ai: this._ai });
+    }
+    /**
+     * Write a scaffolded manifest into the consented `.ai-runtime/skills/` directory (Phase 21a). Only call
+     * this after the user has confirmed the drafted manifest. Returns the written path. The id was validated
+     * as kebab-case at generation; it is re-checked here so a hand-built manifest can't escape the skills dir.
+     */
+    saveScaffoldedSkill(manifest) {
+        if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(manifest.id))
+            throw new AIError(`unsafe skill id: ${JSON.stringify(manifest.id)}`, { category: 'CONFIG' });
+        const dir = join(this.workspaceRoot, '.ai-runtime', 'skills');
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `${manifest.id}.skill.yaml`);
+        writeFileSync(path, stringifyYaml(manifest));
+        return path;
+    }
+    /** The ACTION-capability registry (Phase 3.1): what this runtime can DO, and who provides it. */
+    capabilities() {
+        return this._capabilities;
+    }
     /** The resolved tool permissions for this runtime (config grants over deny-by-default defaults). */
     permissions() {
         return resolvePermissions(this.configPermissions);
     }
+    /**
+     * The ONE resolved-permission view for a run: config grants merged with a per-run override, with `mcp`
+     * merged by per-server MINIMUM so an override can only ever NARROW. Extracted from `toolContext`
+     * (Phase 3.3 / D9) so capability resolution and tool execution can never read different permissions.
+     * Never re-derive this merge at a call site: a plain `resolvePermissions({ ...config, ...override })`
+     * would let an override widen `read` to `full` and drop sibling servers.
+     */
+    resolvedPermissions(overrides) {
+        const permissions = resolvePermissions({ ...this.configPermissions, ...(overrides?.permissions ?? {}) });
+        // `mcp` is the first NESTED permission dimension, so a shallow spread would let an override REPLACE
+        // the configured grants — silently widening `read` to `full` and dropping sibling servers. It merges
+        // by per-server minimum instead: an override can only ever narrow (invariant: permissions never widen).
+        permissions.mcp = { servers: clampMcpPermissions(resolvePermissions(this.configPermissions).mcp.servers, overrides?.permissions?.mcp?.servers) };
+        return permissions;
+    }
     toolContext(overrides) {
         return {
             workspaceRoot: this.workspaceRoot,
-            permissions: resolvePermissions({ ...this.configPermissions, ...(overrides?.permissions ?? {}) }),
+            permissions: this.resolvedPermissions(overrides),
             ...(this.approval ? { approval: this.approval } : {}),
             ...(overrides?.signal ? { signal: overrides.signal } : {}),
         };
@@ -277,7 +670,9 @@ export class Runtime {
         const toolCtx = this.toolContext(overrides);
         const ctx = {
             input,
-            ai: this._ai,
+            // Phase 3.4: an agent worker passes its METERED facade here, so a skill's own model calls are
+            // counted against that agent's reservation. Absent ⇒ the real AI, byte-identical.
+            ai: overrides?.ai ?? this._ai,
             callTool: async (toolId, toolInput) => {
                 const tool = this._tools.get(toolId);
                 if (!tool)
@@ -306,7 +701,7 @@ export class Runtime {
         return this.emitter.recent();
     }
     async run(input) {
-        const req = typeof input === 'string' ? { input } : input;
+        let req = typeof input === 'string' ? { input } : input;
         const runId = nextRunId();
         const text = inputText(req.input);
         this.emitter.emit({ type: 'runtime.started', runId, requested: req.mode ?? 'auto' });
@@ -319,6 +714,9 @@ export class Runtime {
         });
         const resolution = modeResult.resolution;
         this.emitter.emit({ type: 'mode.selected', runId, requested: resolution.requested, selected: resolution.selected, executed: resolution.executed, source: resolution.source, confidence: resolution.confidence });
+        // models.md (Phase 23): fold the per-mode/per-task model directive into this run's routing/strategy/pin
+        // — but never over an explicit per-run choice. Downstream strategy/routing/dispatch read the result.
+        req = this.applyModelProfile(req, resolution.executed);
         const strategy = resolveStrategy({
             ...(req.strategy !== undefined ? { explicit: req.strategy } : {}),
             ...(this.settingsValue.defaultStrategy !== undefined ? { configDefault: this.settingsValue.defaultStrategy } : {}),
@@ -339,7 +737,7 @@ export class Runtime {
         // Orchestration modes (plan/execute/orchestrate) plan + drive skills/tools; they do not use the
         // chat memory/context path. Clarification here comes from the planner, not mode ambiguity.
         if (resolution.executed === 'plan' || resolution.executed === 'execute' || resolution.executed === 'orchestrate' || resolution.executed === 'agent' || resolution.executed === 'debug') {
-            return this.runOrchestration(resolution.executed, text, resolution, runId, policy, req.requestId, routing);
+            return this.runOrchestration(resolution.executed, text, resolution, runId, policy, req.requestId, routing, req.partial);
         }
         // Compare mode: fan out the same task across pins and analyze — read-only, no approval gate.
         if (resolution.executed === 'compare') {
@@ -352,14 +750,23 @@ export class Runtime {
             this.emitter.emit({ type: 'clarification.requested', runId, question: clarification.question });
         // Memory: retrieve relevant facts into context, and (unless this is a dry run) capture an explicit
         // "remember …". A dry run performs zero mutations, so it retrieves but never writes.
-        const memTrace = this.applyMemory(text, !policy.dryRun);
+        const memTrace = await this.applyMemory(text, !policy.dryRun);
         // Compile the model context (workspace summary + memory facts + user system) under a token budget.
         const budget = resolveContextBudget({
             ...(req.context?.maxTokens !== undefined ? { perRun: req.context.maxTokens } : {}),
             ...(this.settingsValue.context?.maxTokens !== undefined ? { config: this.settingsValue.context.maxTokens } : {}),
             ...(this.env.AI_CONTEXT_MAX_TOKENS !== undefined ? { env: this.env.AI_CONTEXT_MAX_TOKENS } : {}),
         });
-        const compiled = compileContext(this.contextBlocks(req, context.workspace, memTrace?.retrieved), { budgetTokens: budget, estimator: this.estimator });
+        // Optional abstractive summarization pre-pass (Phase 16, opt-in) — shrinks over-budget non-critical
+        // blocks before the deterministic compile. Never on a dry run (it makes model calls). Failure → originals.
+        // `originalBlocks` is kept so loss verification can compare against the TRUE originals (pre-summary),
+        // catching loss introduced by summarization as well as by the compiler.
+        const originalBlocks = this.contextBlocks(req, context.workspace, memTrace?.retrieved);
+        let blocks = originalBlocks;
+        if (!policy.dryRun && this.settingsValue.context?.summarize) {
+            blocks = await summarizeOverBudget({ ai: this._ai, blocks, budgetTokens: budget, estimator: this.estimator });
+        }
+        const compiled = compileContext(blocks, { budgetTokens: budget, estimator: this.estimator });
         const contextReport = { metrics: compiled.metrics, validation: compiled.validation };
         // Dry-run: chat's only "action" is the model call itself, so a dry run makes NO call. It reports
         // what it would send (mode, compiled-context size) and performs zero mutations.
@@ -374,6 +781,11 @@ export class Runtime {
                 result.memory = memTrace;
             return result;
         }
+        // Optional model-based context-loss verification (Phase 16, opt-in) — appends one advisory check to
+        // validation.checks; never blocks, never runs on a dry run (returned above). Failure → inconclusive.
+        if (this.settingsValue.context?.verifyLoss) {
+            compiled.validation.checks.push(await verifyContextLoss({ ai: this._ai, blocks: originalBlocks, compiled }));
+        }
         const runRequest = buildChatRequest(req, strategy, compiled.system || undefined, routing);
         // Streaming (Phase 13): text-only, chat-mode only, never on a dry run (handled above). Each chunk is
         // emitted as a `response.delta` lifecycle event (redacted by the emitter). We also accumulate the raw
@@ -426,13 +838,29 @@ export class Runtime {
         return this._executions.list();
     }
     /** plan/execute/orchestrate/agent/debug: run the orchestrator and persist a resumable Execution. */
-    async runOrchestration(mode, goal, resolution, runId, policy, requestId, routing) {
+    async runOrchestration(mode, goal, resolution, runId, policy, requestId, routing, partial) {
         const effectiveGoal = mode === 'debug' ? `Investigate and diagnose the following, gathering evidence before concluding: ${goal}` : goal;
+        // Phase 3.4: ONE controller per run, registered under the run id (and the execution id below) so
+        // pauseExecution/cancelExecution can abort agent work that is actually in flight. With agents
+        // disabled nothing consumes the signal, so this is inert.
+        const controller = new AbortController();
+        if (this.agentsEnabled)
+            this.liveRuns.set(runId, { controller });
         // plan mode and dry-run produce no durable work → run without persisting an execution.
         if (mode === 'plan' || policy.dryRun || !this._executions.enabled) {
-            const outcome = await orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, routing));
-            this.recordOrchestration(mode, goal, outcome);
-            return this.mapOutcome(outcome, resolution, runId, undefined);
+            // Phase 3.3 (opt-in): derive + resolve this goal's capabilities BEFORE planning. Done here rather
+            // than in `orchestrateInput` because this scope has the resolved `policy`, so plan/execute/
+            // orchestrate/agent/debug all behave identically. `undefined` when the flag is off, which is the
+            // 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 }));
+                this.recordOrchestration(mode, goal, outcome);
+                return this.mapOutcome(outcome, resolution, runId, undefined, planning);
+            }
+            finally {
+                this.liveRuns.delete(runId);
+            }
         }
         // Reserve the execution BEFORE running (persist-in-progress + claim the requestId under the store
         // lock so a concurrent retry with the same requestId dedupes to it).
@@ -449,11 +877,19 @@ export class Runtime {
             return this.resultFromExecution(reserved.exec, resolution, runId);
         }
         const exec = reserved.exec;
+        // Derive only AFTER the requestId dedup has admitted this as fresh work: an idempotent retry returns
+        // the existing execution above, and paying for a model call whose result is then discarded would
+        // spend budget to answer a question nobody asked.
+        const planning = await this.capabilityPlanning(effectiveGoal, policy, routing);
         try {
             // Renew the lease while the (possibly long) run is in flight so it can't expire mid-run.
-            const outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, routing)));
+            if (this.agentsEnabled)
+                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)));
             exec.status = this.execStatus(outcome.status);
-            exec.observations = outcome.observations;
+            exec.observations = outcome.observations.map(persistableObservation);
             if (outcome.plan) {
                 exec.plan = outcome.plan;
                 exec.planVersion = outcome.plan.version;
@@ -461,17 +897,132 @@ export class Runtime {
             }
             if (outcome.status === 'waiting_for_approval')
                 exec.pending = { kind: 'approval', action: goal };
-            else if (outcome.status === 'waiting_for_clarification' && outcome.clarification)
-                exec.pending = { kind: 'clarification', question: outcome.clarification };
-            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps }));
-            this._executions.commit(exec); // ownership-checked: never clobber a newer owner
+            else if (outcome.status === 'waiting_for_clarification' && outcome.clarification) {
+                // First-wins: if an AGENT is what is waiting, the pending slot records which one, so the answer
+                // is routed into that task's inner resume instead of being appended to the outer goal.
+                const waiter = this.electWaitingAgent(exec);
+                exec.pending = { kind: 'clarification', question: outcome.clarification, ...(waiter ? { agentTaskId: waiter.agentTaskId } : {}) };
+            }
+            else if (outcome.status === 'waiting_for_budget' && outcome.budget)
+                exec.pending = { kind: 'budget', budget: outcome.budget };
+            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps, mcpTools: this.mcpToolHashes(exec.plan) }));
+            if (sink)
+                sink.finalize();
+            else
+                this._executions.commit(exec); // ownership-checked: never clobber a newer owner
             this.recordOrchestration(mode, goal, outcome);
-            return this.mapOutcome(outcome, resolution, runId, exec.id);
+            return this.mapOutcome(outcome, resolution, runId, exec.id, planning);
         }
         finally {
+            this.liveRuns.delete(runId);
+            this.liveRuns.delete(exec.id);
             this._executions.release(exec.id);
         }
     }
+    /**
+     * THE mid-run persistence sink (Phase 3.5) — the only thing that writes an execution while it runs.
+     *
+     * Invariant 18 says everything needed for resume is on disk before the next wave starts, and the
+     * non-obvious part is WHAT that includes. Committing the plan, the completed steps and the agent
+     * records is not enough: the resume gate is `!recon.drifted && !!exec.plan`, and `recon` defaults to
+     * DRIFTED whenever `checkpoints` is empty. Since checkpoints were captured only after orchestration
+     * returned, a crash mid-run always drifted, always replanned, and re-ran every completed agent task —
+     * the exact thing this phase exists to prevent. So the sink captures a checkpoint too.
+     *
+     * Every refusal from the funnel ABORTS the run. A refused commit means another owner now owns this
+     * execution's fate; carrying on would call the same tools and burn the same model calls twice while
+     * that owner re-runs the identical steps, and every result would be discarded at the end anyway.
+     */
+    runPersistence(exec, controller) {
+        // Fixed for each executePlan call: its `callsUsed` is cumulative for that call, so the pool must be
+        // `priorCalls + thisCall`, and `priorCalls` advances only when the call ends. Adding a per-fire delta
+        // instead would let the total go BACKWARDS across replan iterations and over-grant the resume pool.
+        let priorCalls = exec.callsUsed ?? 0;
+        let lastCheckpointed = '';
+        let stopped = false;
+        const commit = () => {
+            if (stopped)
+                return;
+            const outcome = this._executions.commitProgress(exec);
+            if (outcome === 'ok')
+                return;
+            // Stop trying to write, and stop the run itself.
+            stopped = true;
+            this.abortLiveRun(exec.id, outcome === 'paused' ? 'pause' : 'parent-cancel');
+            controller.abort();
+        };
+        /** Capture only when the completed set moved: `captureCheckpoint` hashes files and shells git. */
+        const checkpointIfMoved = () => {
+            const key = exec.completedSteps.join('\u0000');
+            if (key === lastCheckpointed)
+                return;
+            lastCheckpointed = key;
+            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps, mcpTools: this.mcpToolHashes(exec.plan) }));
+            if (exec.checkpoints.length > CHECKPOINTS_MAX)
+                exec.checkpoints.splice(0, exec.checkpoints.length - CHECKPOINTS_MAX);
+        };
+        return {
+            /** The plan is settled and nothing has run: a crash in wave 1 must still resume against a plan. */
+            onPlan: (plan) => {
+                exec.plan = plan;
+                exec.planVersion = plan.version;
+                exec.completedSteps = plan.steps.filter((st) => st.status === 'succeeded').map((st) => st.id);
+                checkpointIfMoved();
+                commit();
+            },
+            onProgress: (snap) => {
+                exec.plan = snap.plan;
+                exec.completedSteps = snap.plan.steps.filter((st) => st.status === 'succeeded').map((st) => st.id);
+                if (snap.observations.length)
+                    exec.observations = [...exec.observations, ...snap.observations.map(persistableObservation)];
+                exec.callsUsed = priorCalls + snap.callsUsed;
+                checkpointIfMoved();
+                commit();
+                // One executePlan call is over; its spend is now part of the floor for the next one.
+                if (snap.at === 'plan-end')
+                    priorCalls = exec.callsUsed ?? priorCalls;
+            },
+            onRecord: (record) => {
+                const tasks = (exec.agentTasks ??= []);
+                const at = tasks.findIndex((t) => t.agentTaskId === record.agentTaskId);
+                // TERMINAL is sticky for a TASK too. A late write from an aborted worker must not reopen a task
+                // that already completed, failed or was cancelled.
+                if (at >= 0 && AGENT_TERMINAL.has(tasks[at].state) && !AGENT_TERMINAL.has(record.state))
+                    return;
+                // Redacted at the boundary: findings, inner observations and diagnostics all carry text that
+                // came from tools and models, and this record is about to become a durable file.
+                // The inner workspace fingerprint. The OUTER checkpoint cannot stand in for it: `planPaths`
+                // reads the outer plan's step inputs, so files an agent touched through its own inner steps are
+                // invisible to it. Captured here because the worker has no workspace root — it is deliberately
+                // not given one.
+                if (record.innerPlan) {
+                    record.innerCheckpoint = captureCheckpoint({ root: this.workspaceRoot, plan: record.innerPlan, skills: this.skills(), completedSteps: record.innerCompletedSteps });
+                }
+                const snapshot = redact({ ...record });
+                if (at >= 0)
+                    tasks[at] = snapshot;
+                else
+                    tasks.push(snapshot);
+                // A task that FINISHED means its step succeeded. Waiting for the batch commit to record that
+                // leaves a window where a crash finds a `completed` record — which is not resumable, so no
+                // record is offered — and a step not in `completedSteps`, so the agent is simply re-run: a
+                // second paid planning call, the tools fired twice, and two records for one step.
+                if (record.state === 'completed' && !exec.completedSteps.includes(record.stepId)) {
+                    exec.completedSteps = [...exec.completedSteps, record.stepId];
+                    checkpointIfMoved();
+                }
+                commit();
+            },
+            /**
+             * The terminal write. It goes through the SAME funnel as every mid-run commit, so a pause or a
+             * cancel that landed while the run was finishing is not overwritten by its result: the plain
+             * `commit()` only refuses a live FOREIGN lease, and pause/cancel release the lease as this very
+             * owner — so nothing stopped the final write from resurrecting a cancelled run as `completed`.
+             */
+            finalize: () => (stopped ? 'terminal' : this._executions.commitProgress(exec)),
+            stopped: () => stopped,
+        };
+    }
     /** Run `fn` while heartbeating the execution lease so a long run never lets the lease expire. */
     async withHeartbeat(id, fn) {
         const timer = setInterval(() => this._executions.heartbeat(id), this._executions.heartbeatMs);
@@ -484,7 +1035,7 @@ export class Runtime {
             clearInterval(timer);
         }
     }
-    orchestrateInput(mode, goal, policy, routing) {
+    orchestrateInput(mode, goal, policy, routing, partial, requiredCapabilities, signal, provenance, sink, agentResume) {
         return {
             goal,
             mode,
@@ -493,9 +1044,22 @@ export class Runtime {
             tools: this._tools.ids(),
             policy,
             ...(routing ? { routing } : {}),
+            ...(partial ? { partial: true } : {}),
             ...(this.approval ? { approval: this.approval } : {}),
-            runSkill: (id, input) => this.runSkill(id, input).then((o) => ({ result: o.result, validation: o.validation })),
-            runTool: (id, input) => this.runTool(id, input),
+            // Phase 3.1: the capability snapshot is opt-in (`runtime.capabilities.catalog`); the gap resolver is
+            // always on but only fires on a validation failure, adding metadata to an unchanged error.
+            ...(this.settingsValue.capabilities?.catalog ? { capabilityCatalog: this.capabilityCatalogText() } : {}),
+            // Phase 3.3: the derived-requirement block (opt-in, pre-rendered + clamped). Absent ⇒ the
+            // OrchestrateInput/PlannerInput objects are key-identical to 2.5.1.
+            ...(requiredCapabilities ? { requiredCapabilities } : {}),
+            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),
+            // Phase 3.5: the commit points. Present ONLY when there is a store to commit to, so a stateless
+            // Runtime builds an OrchestrateInput key-identical to 2.7.0.
+            ...(sink ? { onPlan: sink.onPlan, onProgress: sink.onProgress } : {}),
+            ...(signal ? { signal } : {}),
         };
     }
     /** Record an EXECUTED orchestration outcome for learning. plan-only, dry-run, and waiting states are
@@ -507,19 +1071,168 @@ export class Runtime {
             return;
         this._learning.record({ goalType: this.goalType(goal), mode, ok: outcome.status === 'completed', skills: this.planSkillRefs(outcome.plan) });
     }
+    /**
+     * A capped, FENCED action-capability snapshot for the planner prompt (Phase 3.1, opt-in). Untrusted
+     * sources (anything not an in-tree builtin) have their descriptions fenced, and the block is bounded so
+     * a large catalog can never dominate the prompt.
+     */
+    capabilityCatalogText(maxEntries = 40) {
+        const caps = this._capabilities.list();
+        if (caps.length === 0)
+            return '';
+        const lines = [];
+        for (const c of caps.slice(0, maxEntries)) {
+            const providers = this._capabilities
+                .providersOf(c.id)
+                .map((p) => `${promptSafe(p.providerId)}${p.availability === 'available' ? '' : ` (${p.availability})`}`)
+                .join(', ');
+            lines.push(`  - capability "${promptSafe(c.id)}" [${c.effects.join('/')}] → ${promptSafe(providers, 200)}`);
+        }
+        const more = caps.length > maxEntries ? `\n  …and ${caps.length - maxEntries} more (see /capabilities)` : '';
+        // Skills hidden by a missing tool — the "why can't you do this" answer the planner needs.
+        const usable = new Set(this.skills().map((sk) => sk.id));
+        const blocked = this._skills
+            .list()
+            .filter((sk) => !usable.has(sk.id))
+            .map((sk) => `  - skill "${promptSafe(sk.id)}" needs tool(s) ${promptSafe((sk.tools ?? []).filter((t) => !this._tools.ids().includes(t)).join(', '), 200)} (not registered)`);
+        const unavailable = blocked.length ? `\nUnavailable (do not use):\n${blocked.join('\n')}` : '';
+        return `Action capabilities:\n${lines.join('\n')}${more}${unavailable}`;
+    }
+    /** Any call/cost ceiling declared in the config file's `budget:` block (router-level, not policy). */
+    configBudget() {
+        return this._configBudget;
+    }
+    /** Deriver candidates: registry ids + one clamped label. Built by the SAME helper the CLI uses. */
+    capabilityCandidates() {
+        return candidatesFrom(this._capabilities.list());
+    }
+    /**
+     * Derive the capabilities this goal needs and resolve them (Phase 3.3, opt-in). Offline BM25 first —
+     * free and deterministic — with ONE model call only when the offline rung finds nothing. ADVISORY: it
+     * never blocks a run and never grants anything; a gap is metadata plus a line in the planner prompt.
+     */
+    async capabilityPlanning(goal, policy, routing) {
+        if (!this.settingsValue.capabilities?.planning)
+            return undefined;
+        const permissions = this.resolvedPermissions({ permissions: policy.permissions });
+        const candidates = this.capabilityCandidates();
+        if (candidates.length === 0)
+            return { derived: [], gaps: [], block: '', permissions };
+        // The model rung is skipped whenever ANY budget is set. `maxCalls` is denominated in plan skill steps
+        // (orchestrator.estimateCalls), so it cannot express a pre-plan call — spending one would exceed a
+        // limit only ExecutionPolicy is meant to author — and a COST ceiling is just as much a budget. The
+        // router-config `budget.maxCalls` is consulted directly because it deliberately does NOT flow into
+        // `policy.maxCalls`: threading it there would newly gate ORCHESTRATION for every existing config,
+        // which is a flag-off behavior change this phase must not make. Skipped on a dry run too. The
+        // offline rung still runs in every one of these cases and costs nothing.
+        const budgeted = policy.maxCalls !== undefined || policy.maxCostUsd !== undefined || this.configBudget() !== undefined;
+        const useModel = !policy.dryRun && !budgeted;
+        const res = await deriveCapabilities({ goal, candidates, ...(useModel ? { ai: this._ai } : {}), ...(routing ? { routing } : {}) });
+        if (res.required.length === 0)
+            return { derived: [], gaps: [], block: '', permissions };
+        const resolution = this._capabilities.resolve(res.required, { permissions });
+        return { derived: res.required, gaps: resolution.gaps, block: this.requiredCapabilitiesText(resolution), permissions };
+    }
+    /** The pre-rendered "Required capabilities" planner block (Phase 3.3) — clamped like the 3.1 catalog. */
+    requiredCapabilitiesText(res) {
+        const rows = [
+            ...res.satisfied.map((sat) => `  - "${promptSafe(sat.capabilityId)}" → use ${promptSafe(sat.chosen.providerId)}`),
+            ...res.gaps.map((g) => `  - "${promptSafe(g.capabilityId)}" → NOT AVAILABLE (${g.reason}) — do not plan a step that needs it`),
+        ];
+        return rows.length ? `Required capabilities for this goal (derived):\n${rows.join('\n')}` : '';
+    }
+    /** A step's capability provider id. An MCP-backed tool ingests under `mcp:` (see the ingest hook). */
+    providerIdForRef(ref) {
+        if (ref.kind === 'skill')
+            return namespacedId('skill', ref.id);
+        return namespacedId(this.mcpToolIds.has(ref.id) ? 'mcp' : 'tool', ref.id);
+    }
+    /**
+     * Resolve the capabilities the plan's OWN steps reference (Phase 3.3). ZERO model calls, purely
+     * additive metadata, and the only path that can surface a real `permission` gap with a concrete
+     * policyKey — the always-on validation path resolves namespaced MISSES, which have no providers and are
+     * therefore always reason 'unknown'. It never blocks: a gap here is advice, and the tool's own
+     * permission check remains the authority.
+     */
+    checkPlanCapabilities(plan, permissions, derived) {
+        try {
+            const ids = new Set();
+            for (const step of plan.steps) {
+                const ref = step.skill ? { kind: 'skill', id: step.skill } : step.tool ? { kind: 'tool', id: step.tool } : undefined;
+                if (!ref)
+                    continue;
+                for (const id of this._capabilities.capabilitiesOf(this.providerIdForRef(ref), ref.id))
+                    ids.add(id);
+            }
+            const all = [...ids].sort();
+            const res = this._capabilities.resolve(all, { permissions });
+            const reasonOf = new Map(res.gaps.map((g) => [g.capabilityId, g.reason]));
+            /**
+             * A provider can do more than the step will. `tool:filesystem` provides read_file AND write_file,
+             * so a read-only step would otherwise be reported as needing write access — and the remedy would
+             * tell the operator to GRANT it. Pushing an over-grant for work that may never happen is worse
+             * than saying nothing, so a `permission` gap survives only when the GOAL derived that capability.
+             * Every other reason (unknown / unavailable / disabled provider) is a fact about the plan whatever
+             * the step does, and is always reported.
+             */
+            const keep = (id) => derived.has(id) || reasonOf.get(id) !== 'permission';
+            return { required: all.filter(keep), gaps: res.gaps.filter((g) => keep(g.capabilityId)) };
+        }
+        catch {
+            return { required: [], gaps: [] }; // a check bug can never fail a run the runtime could complete
+        }
+    }
+    /**
+     * Turn unregistered plan references into structured gaps (Phase 3.1's always-on upgrade), resolved
+     * against the RUN's permissions rather than the raw config (Phase 3.3 / D9) — so what resolution
+     * reports and what the executor will allow can never disagree.
+     */
+    resolveMissingRefs(missing, policy) {
+        const ids = [...new Set(missing.map((m) => namespacedId(m.kind, m.id)))];
+        return this._capabilities.resolve(ids, { permissions: this.resolvedPermissions({ permissions: policy.permissions }) }).gaps;
+    }
+    /**
+     * The user-facing report for a set of required capability ids (Phase 3.1), against the runtime's
+     * CONFIGURED posture. A specific run's gaps use that run's merged permissions instead (see
+     * `resolveMissingRefs` and the capability-planning pre-pass); this entry point has no run in scope.
+     */
+    capabilityReport(required) {
+        return this._capabilities.report(required, { permissions: this.permissions() });
+    }
+    /**
+     * Project an orchestration status onto a persisted execution status. EXHAUSTIVE on purpose (Phase
+     * 3.4): the previous catch-all silently persisted an unrecognized status as
+     * `waiting_for_clarification` — resumable, answerable with a text answer, and wrong. The mapping of
+     * the six existing members is unchanged.
+     */
     execStatus(s) {
-        if (s === 'completed' || s === 'dry-run')
-            return 'completed';
-        if (s === 'failed')
-            return 'failed';
-        if (s === 'waiting_for_approval')
-            return 'waiting_for_input';
-        return 'waiting_for_clarification';
-    }
-    mapOutcome(outcome, resolution, runId, execId) {
+        switch (s) {
+            case 'completed':
+            case 'dry-run':
+                return 'completed';
+            case 'failed':
+                return 'failed';
+            case 'waiting_for_approval':
+            case 'waiting_for_budget':
+                return 'waiting_for_input';
+            case 'waiting_for_clarification':
+                return 'waiting_for_clarification';
+            default: {
+                const never = s;
+                return never;
+            }
+        }
+    }
+    mapOutcome(outcome, resolution, runId, execId, planning) {
         const status = outcome.status === 'dry-run' ? 'completed' : outcome.status;
         const ok = outcome.status === 'completed' || outcome.status === 'dry-run' || outcome.status.startsWith('waiting');
         this.emitter.emit({ type: 'run.completed', runId, ok, status, confidence: ok ? 1 : 0 });
+        // One report, three sources: the pre-pass (the goal), the post-plan check (the plan's own steps),
+        // and the always-on validation upgrade (unregistered refs). The post-plan check is free — no model
+        // call — so it runs wherever the flag is on, resumes included.
+        const check = planning && outcome.plan ? this.checkPlanCapabilities(outcome.plan, planning.permissions, new Set(planning.derived)) : undefined;
+        const gaps = mergeGapsById([...(planning?.gaps ?? []), ...(check?.gaps ?? []), ...(outcome.gaps ?? [])]);
+        const required = [...new Set([...(planning?.derived ?? []), ...(check?.required ?? []), ...(outcome.gaps ?? []).map((g) => g.capabilityId)])];
         return {
             ok,
             runId,
@@ -527,20 +1240,25 @@ export class Runtime {
             status,
             response: { text: outcome.summary },
             ...(outcome.plan ? { plan: outcome.plan } : {}),
+            ...(gaps.length ? { capabilityGaps: capabilityReportFrom(required, gaps, (id) => this._capabilities.providersOf(id)) } : {}),
             execution: { ...(execId ? { id: execId } : {}), observations: outcome.observations, planHistory: outcome.planHistory },
             ...(outcome.clarification ? { clarification: { question: outcome.clarification } } : {}),
-            artifacts: [],
+            // Phase 3.4: an agent step's admitted findings carry evidence artifacts. With agents disabled
+            // there are no agent observations, so this is the same empty array as 2.6.0.
+            artifacts: outcome.observations.flatMap((o) => o.artifacts ?? []),
         };
     }
     resultFromExecution(exec, resolution, runId) {
         const ok = exec.status !== 'failed' && exec.status !== 'cancelled';
-        const status = exec.status === 'completed' ? 'completed' : exec.status === 'failed' || exec.status === 'cancelled' ? 'failed' : exec.status === 'waiting_for_clarification' ? 'waiting_for_clarification' : exec.status === 'waiting_for_input' ? 'waiting_for_approval' : 'completed';
+        // waiting_for_input carries a pending kind — a budget pause maps to waiting_for_budget, else approval.
+        const waitingInput = exec.pending?.kind === 'budget' ? 'waiting_for_budget' : 'waiting_for_approval';
+        const status = exec.status === 'completed' ? 'completed' : exec.status === 'failed' || exec.status === 'cancelled' ? 'failed' : exec.status === 'waiting_for_clarification' ? 'waiting_for_clarification' : exec.status === 'waiting_for_input' ? waitingInput : 'completed';
         return {
             ok,
             runId,
             mode: resolution,
             status,
-            response: { text: `execution ${exec.id} (${exec.status})` },
+            response: { text: exec.pending?.kind === 'budget' && exec.pending.budget ? `execution ${exec.id}: ${exec.pending.budget.completedSteps}/${exec.pending.budget.totalSteps} step(s) done — raise the budget and resume` : `execution ${exec.id} (${exec.status})` },
             ...(exec.plan ? { plan: exec.plan } : {}),
             execution: { id: exec.id, observations: exec.observations, planHistory: exec.plan ? [exec.plan] : [] },
             ...(exec.pending?.kind === 'clarification' && exec.pending.question ? { clarification: { question: exec.pending.question } } : {}),
@@ -608,6 +1326,13 @@ export class Runtime {
             return { ok: false, runId, mode: resolution, status: 'failed', response: { text: `cannot resume ${id}: ${acq.reason ?? 'unavailable'}` }, artifacts: [] };
         }
         const exec = acq.execution;
+        // A resumed run is a live run: pause/cancel must be able to abort it, and a refused commit must be
+        // able to stop it — both of which need a controller registered under this execution's id.
+        const controller = new AbortController();
+        // What was on the record BEFORE this resume. The terminal write rebuilds from here rather than
+        // appending: the sink has already been appending this run's observations as they happened, so
+        // appending the outcome's copy too would store every step of a resumed run twice.
+        const observationsBefore = [...exec.observations];
         try {
             if (TERMINAL.has(exec.status))
                 return this.resultFromExecution(exec, resolution, runId);
@@ -626,54 +1351,306 @@ export class Runtime {
                     return this.resultFromExecution(exec, resolution, runId);
                 }
             }
+            // An INNER wait needs its answer, exactly as an approval needs a decision. Without this gate the
+            // ordinary `resume-execution <id>` (the CLI makes --answer optional) falls through to the replan
+            // branch, which replaces the plan and orphans every sibling agent's completed work — destroying
+            // progress in the one situation the wait exists to protect.
+            if (exec.pending?.kind === 'clarification' && exec.pending.agentTaskId && !opts.clarificationAnswer) {
+                return this.resultFromExecution(exec, resolution, runId);
+            }
+            // Phase 3.5: whoever was mid-flight when this execution stopped is gone. Put those records back in
+            // `queued` with the reason BEFORE anything is scheduled against them.
+            if (this.reconcileAgentTasks(exec, 'crash') > 0)
+                this._executions.commit(exec);
             // Reconcile against the checkpoint — drift forces a replan rather than a blind continue.
             const checkpoint = exec.checkpoints[exec.checkpoints.length - 1];
-            const recon = checkpoint ? reconcile(checkpoint, this.workspaceRoot, this.skills()) : { drifted: true, reasons: ['no checkpoint'] };
-            const goal = exec.pending?.kind === 'clarification' && opts.clarificationAnswer ? `${exec.goal}\n\nClarification: ${opts.clarificationAnswer}` : exec.goal;
-            const policy = resolvePolicy({ mode: 'orchestrate', overrides: { autonomy: 'autonomous', approval: 'none', ...(this.configPermissions ? { permissions: this.configPermissions } : {}) }, settings: this.settingsValue });
-            // We only reach here for an approval-pending execution if it was explicitly approved.
+            const recon = checkpoint ? reconcile(checkpoint, this.workspaceRoot, this.skills(), this.mcpToolHashes(exec.plan)) : { drifted: true, reasons: ['no checkpoint'] };
+            // An INNER answer belongs to one agent task, never to the outer goal: appending it here would
+            // replan the whole plan and discard every sibling agent's completed work.
+            const innerAnswered = exec.pending?.kind === 'clarification' && !!exec.pending.agentTaskId && !!opts.clarificationAnswer;
+            const goal = exec.pending?.kind === 'clarification' && opts.clarificationAnswer && !innerAnswered ? `${exec.goal}\n\nClarification: ${opts.clarificationAnswer}` : exec.goal;
+            // Re-read the budget from env so raising AI_MAX_CALLS before resuming actually takes effect (Phase 22).
+            const policy = resolvePolicy({ mode: 'orchestrate', overrides: { autonomy: 'autonomous', approval: 'none', ...(this.configPermissions ? { permissions: this.configPermissions } : {}) }, settings: this.settingsValue, env: { maxCostUsd: numFromEnv(this.env, 'AI_MAX_COST_USD'), maxCalls: numFromEnv(this.env, 'AI_MAX_CALLS') } });
+            if (this.agentsEnabled)
+                this.liveRuns.set(exec.id, { controller });
+            // A resumed run is never re-DERIVED — no surprise second model call on work already approved and
+            // mid-flight — but it does get the FREE post-plan check: a grant may have changed since it started.
+            const planning = this.settingsValue.capabilities?.planning
+                ? { derived: [], gaps: [], block: '', permissions: this.resolvedPermissions({ permissions: policy.permissions }) }
+                : undefined;
+            // Continue (skip completed steps) for an approved plan, a budget pause, or partial progress.
             const approvedNow = exec.pending?.kind === 'approval';
-            const canContinue = !recon.drifted && !!exec.plan && (approvedNow || (exec.completedSteps.length > 0 && !exec.pending));
+            const budgetPaused = exec.pending?.kind === 'budget';
+            // `innerAnswered` is its own arm: the plan is intact and one agent step needs re-running with its
+            // answer. The partial-progress arm cannot cover it — a run where every agent asked before doing
+            // anything has NO completed steps, which is precisely the two-waiting-agents case.
+            const canContinue = !recon.drifted && !!exec.plan && (approvedNow || budgetPaused || innerAnswered || (exec.completedSteps.length > 0 && !exec.pending));
+            const sink = this._executions.enabled ? this.runPersistence(exec, controller) : undefined;
             let outcome;
             if (canContinue && exec.plan) {
-                // No drift → continue: execute the (approved / partially-done) plan, skipping completed steps.
-                const exe = await this.withHeartbeat(exec.id, () => executePlan(exec.plan, { ...this.orchestrateRunners(), maxParallelSteps: policy.maxParallelSteps ?? 2, skip: new Set(exec.completedSteps), ...(opts.signal ? { signal: opts.signal } : {}) }));
-                outcome = { status: exe.ok ? 'completed' : 'failed', plan: exe.plan, planHistory: [exe.plan], observations: exe.observations, summary: exe.ok ? `resumed and completed "${exec.goal}"` : `resume did not complete "${exec.goal}"` };
+                // Continue the plan, skipping completed steps. The call budget is ALWAYS enforced on the continue
+                // path (whether the pause was approval, budget, or partial-progress) so an approved-but-over-budget
+                // plan pauses for budget rather than silently exceeding it; a raised budget re-applies here.
+                const resumeLookup = this.agentResumeLookup(exec, opts.clarificationAnswer);
+                const exe = await this.withHeartbeat(exec.id, () => executePlan(exec.plan, { ...this.orchestrateRunners(policy, opts.signal ?? controller.signal, { executionId: exec.id, planVersion: exec.planVersion }, sink?.onRecord, resumeLookup), ...(sink ? { onProgress: sink.onProgress } : {}), maxParallelSteps: policy.maxParallelSteps ?? 2, ...(policy.limits ? { limits: policy.limits } : {}), skip: new Set(exec.completedSteps), ...(policy.maxCalls !== undefined ? { callBudget: policy.maxCalls } : {}), ...(opts.signal ? { signal: opts.signal } : {}) }));
+                if (exe.stoppedForBudget) {
+                    const done = exe.plan.steps.filter((s) => s.status === 'succeeded').length;
+                    const total = exe.plan.steps.length;
+                    outcome = { status: 'waiting_for_budget', plan: exe.plan, planHistory: [exe.plan], observations: exe.observations, budget: { estCalls: foldCalls(exe.plan.steps, policy.maxCalls), maxCalls: policy.maxCalls, completedSteps: done, totalSteps: total }, summary: `Ran ${done} of ${total} step(s) within the ${policy.maxCalls}-call budget. Raise the budget (AI_MAX_CALLS) and resume to continue.` };
+                }
+                else if (exe.waiting?.length) {
+                    // Answering one agent can simply reveal the next one. Reporting `failed` here (the pre-3.5
+                    // shape, which read `ok` alone) would mark a perfectly resumable run as dead and lie in the
+                    // summary while doing it.
+                    const asked = exe.observations.find((o) => o.code === 'agent-waiting');
+                    outcome = {
+                        status: 'waiting_for_clarification',
+                        plan: exe.plan,
+                        planHistory: [exe.plan],
+                        observations: exe.observations,
+                        clarification: asked?.error ?? 'an agent needs more information to continue',
+                        summary: `Still waiting: ${exe.waiting.length} agent step(s) need an answer.`,
+                    };
+                }
+                else {
+                    outcome = { status: exe.ok ? 'completed' : 'failed', plan: exe.plan, planHistory: [exe.plan], observations: exe.observations, summary: exe.ok ? `resumed and completed "${exec.goal}"` : `resume did not complete "${exec.goal}"` };
+                }
             }
             else {
-                // Drift, or a pending clarification answer, or no partial progress → replan from the goal.
-                // Re-resolve routing so env/config excludes (and learned prefer) still apply to the replan's
-                // planning-model call — a hard exclude must not be dropped just because we're resuming.
-                outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput('orchestrate', goal, policy, this.effectiveRouting())));
+                // Drift, or a pending clarification answer, or no partial progress → replan from the goal. Re-resolve
+                // routing so env/config excludes (and learned prefer) still apply. A budget-paused replan stays
+                // partial so it keeps running-what-fits instead of reverting to notify-and-wait.
+                // Drift replaces the PLAN, not the facts. What the agents proved before the drift is carried
+                // into the new planning context rather than silently orphaned.
+                const brief = this.findingsBrief(exec);
+                // The full argument list. Passing five positionals to a ten-parameter function silently left
+                // this arm with no signal, no provenance, no sink and no resume lookup — so a replan persisted
+                // no agent record AT ALL (onRecord is the only writer of `agentTasks`), could not be paused or
+                // cancelled, and elected `pending` from stale records.
+                outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput('orchestrate', brief ? `${goal}\n\n${brief}` : goal, policy, this.effectiveRouting(), budgetPaused, undefined, this.agentsEnabled ? controller.signal : undefined, { executionId: exec.id, planVersion: exec.planVersion }, sink)));
             }
             exec.status = this.execStatus(outcome.status);
-            exec.observations = [...exec.observations, ...outcome.observations];
+            exec.observations = [...observationsBefore, ...outcome.observations.map(persistableObservation)];
             if (outcome.plan) {
                 exec.plan = outcome.plan;
                 exec.planVersion = outcome.plan.version;
                 exec.completedSteps = outcome.plan.steps.filter((s) => s.status === 'succeeded').map((s) => s.id);
             }
-            delete exec.pending;
-            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps }));
-            this._executions.commit(exec);
-            return this.mapOutcome(outcome, resolution, runId, exec.id);
+            // Preserve a fresh budget pause; otherwise the pending state is resolved — except that answering
+            // one agent's question may simply have revealed the NEXT one (rediscovery: the records are the
+            // source of truth, so a second waiting task is re-elected rather than queued somewhere).
+            if (outcome.status === 'waiting_for_budget' && outcome.budget)
+                exec.pending = { kind: 'budget', budget: outcome.budget };
+            else if (outcome.status === 'waiting_for_clarification' && outcome.clarification) {
+                const waiter = this.electWaitingAgent(exec);
+                exec.pending = { kind: 'clarification', question: outcome.clarification, ...(waiter ? { agentTaskId: waiter.agentTaskId } : {}) };
+            }
+            else
+                delete exec.pending;
+            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps, mcpTools: this.mcpToolHashes(exec.plan) }));
+            if (sink)
+                sink.finalize();
+            else
+                this._executions.commit(exec);
+            return this.mapOutcome(outcome, resolution, runId, exec.id, planning);
         }
         finally {
+            this.liveRuns.delete(exec.id);
             this._executions.release(id);
         }
     }
-    orchestrateRunners() {
+    /**
+     * THE single source of step runners, used by both the fresh-run path and the resume-continue path.
+     * 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) {
+        const envelopes = policy ? this.agentEnvelopes(policy) : [];
+        const byId = new Map(envelopes.map((e) => [e.agentId, e]));
         return {
             runSkill: (skillId, input) => this.runSkill(skillId, input).then((o) => ({ result: o.result, validation: o.validation })),
             runTool: (toolId, input) => this.runTool(toolId, input),
+            ...(envelopes.length
+                ? {
+                    agents: envelopes,
+                    reserve: (step) => (step.agent ? byId.get(step.agent)?.reservation ?? 1 : 0),
+                    runAgent: async (step, ctx) => {
+                        const envelope = byId.get(step.agent ?? '');
+                        const definition = this.agentDefs.get(step.agent ?? '');
+                        if (!envelope || !definition)
+                            return { stepId: step.id, ok: false, code: 'agent-not-enabled', error: `no agent definition '${step.agent ?? ''}'` };
+                        const innerSkills = this._skills.list().filter((sk) => envelope.skills.includes(sk.id));
+                        // Phase 3.5: continue a persisted task for THIS step, if one exists.
+                        const prior = agentResume?.(step);
+                        const out = await runAgentTask(step, envelope, definition, {
+                            ...(prior?.record ? { resume: prior.record } : {}),
+                            ...(prior?.answer ? { resumeAnswer: prior.answer } : {}),
+                            ai: this._ai,
+                            clock: this.clock,
+                            skills: innerSkills,
+                            runSkill: (id, i, o) => this.runSkill(id, i, o).then((r) => ({ result: r.result, validation: r.validation })),
+                            runTool: (id, i, o) => this.runTool(id, i, o),
+                            putArtifact: (content, source) => {
+                                // The `enabled` check must precede `put`: in stateless mode `put` still returns a
+                                // well-formed ref with a real checksum whose `resolve()` is permanently undefined —
+                                // a dangling evidence ref threaded as if it were real.
+                                if (!this._artifacts.enabled)
+                                    return { unavailable: true };
+                                try {
+                                    return { ref: this._artifacts.put({ type: 'agent-evidence', source, content }), unavailable: false };
+                                }
+                                catch {
+                                    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 }),
+                            ...(onRecord ? { onRecord } : {}),
+                            ...(ctx.signal ?? signal ? { parentSignal: ctx.signal ?? signal } : {}),
+                            ...(provenance ? { provenance } : { provenance: { planVersion: 1 } }),
+                            abortReason: () => {
+                                for (const live of this.liveRuns.values())
+                                    if (live.controller.signal.aborted && live.reason)
+                                        return live.reason;
+                                return undefined;
+                            },
+                        });
+                        return out.observation;
+                    },
+                }
+                : {}),
         };
     }
+    /**
+     * A bounded, fenced brief of what the agents have already established (Phase 3.5).
+     *
+     * On drift the plan is thrown away and the goal is replanned — but validated findings are facts about
+     * the WORKSPACE, not about the plan's structure, so discarding them silently would make the run redo
+     * work it had already proved. They are agent-authored text, so they cross a prompt boundary fenced,
+     * exactly like every other untrusted string.
+     */
+    findingsBrief(exec) {
+        const active = parseAgentTasks(exec)
+            .tasks.flatMap((t) => t.findings)
+            .filter((f) => f.status === 'active')
+            .slice(0, FINDINGS_BRIEF_MAX);
+        if (!active.length)
+            return undefined;
+        const lines = active.map((f) => `- [${flattenClamp(f.type, 40)}] ${flattenClamp(f.subject ?? '', 60)}: ${flattenClamp(f.claim, 160)}`);
+        return wrapUntrusted('prior-findings', `Already established by earlier agent work:\n${lines.join('\n')}`);
+    }
+    /**
+     * Fingerprint the MCP tools a plan actually references (Phase 3.5). An MCP server is remote and
+     * mutable: while a plan sits paused it can change a tool's input schema, change what it does, or drop
+     * it entirely — and the plan would then be resumed against a tool that is no longer the tool it was
+     * planned for. Hashing the live declaration makes that visible as ordinary drift.
+     *
+     * Non-MCP tools are deliberately absent: they are in-tree code covered by the config/skill hashes.
+     */
+    mcpToolHashes(plan) {
+        const out = {};
+        if (!plan)
+            return out;
+        for (const step of plan.steps) {
+            if (!step.tool || !step.tool.startsWith('mcp:') || out[step.tool])
+                continue;
+            const tool = this._tools.get(step.tool);
+            // A missing tool hashes to a sentinel rather than being skipped — "gone" must be comparable, or a
+            // removed server would silently look like no drift at all.
+            out[step.tool] = tool ? hashOf({ description: tool.description, parameters: tool.parameters ?? null }) : 'absent';
+        }
+        return out;
+    }
+    /**
+     * Crash / pause / cancel reconciliation (Phase 3.5). A record left `running` or `created` describes a
+     * worker that no longer exists — the process died, or the parent stopped it — so it goes back to
+     * `queued` with an auditable reason. An interruption is deliberately NOT a state: the lifecycle does
+     * not grow, only the explanation does.
+     *
+     * This runs on the RESUME path and inside pause/cancel. Resume alone is not enough: `cancelExecution`
+     * writes a terminal status and resume early-returns on terminal, so a cancelled execution's `running`
+     * records would stay `running` on disk forever, unstamped and unexplained.
+     *
+     * Records that fail validation are preserved in place, never dropped — reconciling is not a licence to
+     * delete what this version could not parse.
+     */
+    reconcileAgentTasks(exec, kind) {
+        const raw = exec.agentTasks;
+        if (!Array.isArray(raw) || raw.length === 0)
+            return 0;
+        const { tasks, dropped } = parseAgentTasks(exec);
+        const now = this.clock.now();
+        const fixed = new Map();
+        for (const t of tasks) {
+            if (t.state !== 'running' && t.state !== 'created')
+                continue;
+            fixed.set(t.agentTaskId, { ...t, state: 'queued', interruption: { kind, at: now }, updatedAt: now });
+        }
+        if (dropped)
+            exec.agentTasksDropped = dropped;
+        if (fixed.size === 0)
+            return 0;
+        exec.agentTasks = raw.map((entry) => fixed.get(entry.agentTaskId ?? '') ?? entry);
+        return fixed.size;
+    }
+    /**
+     * FIRST-WINS PENDING. `Execution.pending` is a single slot but two agents can be waiting at once, so
+     * the earliest-created waiting task claims it. The others are not lost: once this one is answered and
+     * the run continues, the next resume re-elects whichever task is still waiting — rediscovery, rather
+     * than a queue that has to be kept in sync with the records that are already the source of truth.
+     */
+    electWaitingAgent(exec) {
+        return parseAgentTasks(exec).tasks.find((t) => t.state === 'waiting_for_clarification' && t.pendingInner);
+    }
+    /**
+     * Which persisted task, if any, a plan step should CONTINUE. Bound by step-input hash, never by step
+     * id: plan step ids (`s1`, `auto1`) are model-authored and recur across replans, so an id match would
+     * hand one step's completed inner work to a different step with the same id and a different input.
+     */
+    agentResumeLookup(exec, answer) {
+        const tasks = parseAgentTasks(exec).tasks.filter((t) => AGENT_RESUMABLE.has(t.state));
+        const answeringId = exec.pending?.agentTaskId;
+        // A plan may legitimately contain two steps with identical identity (same agent, same input) — a
+        // retry, or genuinely duplicated work. Without claiming, both would resolve to the SAME record and
+        // the second would resume, and then overwrite, the first's inner work.
+        const claimed = new Set();
+        return (step) => {
+            if (!step.agent)
+                return undefined;
+            const hash = stepIdentity(step);
+            const record = tasks.find((t) => t.agentId === step.agent && t.stepInputHash === hash && !claimed.has(t.agentTaskId));
+            if (!record)
+                return undefined;
+            claimed.add(record.agentTaskId);
+            // If the files this agent worked on changed while the run was stopped, its completed inner steps
+            // are no longer safe to skip — the same rule the outer plan already lives by.
+            if (record.innerCheckpoint && reconcile(record.innerCheckpoint, this.workspaceRoot, this.skills()).drifted) {
+                const { innerPlan: _drop, ...rest } = record;
+                return { record: { ...rest, innerCompletedSteps: [], innerObservations: [], innerObservationsOmitted: 0 } };
+            }
+            // The answer belongs to exactly ONE task — the one that asked.
+            return answer && record.agentTaskId === answeringId ? { record, answer } : { record };
+        };
+    }
+    /** Abort a run that is in flight, recording WHY so a task can tell a pause from a cancellation. */
+    abortLiveRun(id, reason) {
+        const live = this.liveRuns.get(id);
+        if (!live)
+            return;
+        live.reason = reason;
+        live.controller.abort();
+    }
     /** Mark an execution paused (it can be resumed later). */
     pauseExecution(id) {
         const exec = this._executions.get(id);
         if (!exec || TERMINAL.has(exec.status))
             return false;
         exec.status = 'paused';
+        // Phase 3.4: abort whatever is actually in flight, so a pause stops live agent work instead of only
+        // flipping a stored status. A no-op with agents disabled — `liveRuns` is empty then.
+        this.abortLiveRun(id, 'pause');
+        // Phase 3.5: stamp whatever was mid-flight. Doing it here rather than only on resume is what stops a
+        // record sitting at `running` with no worker behind it.
+        this.reconcileAgentTasks(exec, 'pause');
         this._executions.save(exec);
         this._executions.release(id);
         return true;
@@ -684,6 +1661,10 @@ export class Runtime {
         if (!exec || TERMINAL.has(exec.status))
             return false;
         exec.status = 'cancelled';
+        this.abortLiveRun(id, 'parent-cancel'); // parent cancelled ⇒ every live agent controller aborted
+        // Cancel is TERMINAL and resume early-returns on terminal, so if this did not reconcile here those
+        // `running` records would stay `running` on disk forever, unstamped and unexplained.
+        this.reconcileAgentTasks(exec, 'parent-cancel');
         this._executions.save(exec);
         this._executions.release(id);
         return true;
@@ -710,7 +1691,7 @@ export class Runtime {
      * `capture` is false on a dry run — retrieval is read-only, but writing a fact is a mutation the dry
      * run must not perform.
      */
-    applyMemory(text, capture = true) {
+    async applyMemory(text, capture = true) {
         if (!this.memoryEnabled())
             return undefined;
         try {
@@ -722,7 +1703,8 @@ export class Runtime {
                     trace.captured = { id: rec.id, scope: rec.scope };
                 }
             }
-            trace.retrieved = this._memory.search(text, { limit: 3 }).map((h) => h.text);
+            // Semantic retrieval when an embedder is configured, else BM25 (searchSemantic degrades internally).
+            trace.retrieved = (await this._memory.searchSemantic(text, { limit: 3 })).map((h) => h.text);
             if (trace.retrieved.length === 0 && !trace.captured)
                 return undefined;
             return trace;