@duetso/agent 0.2.2 → 0.2.4

package/dist/src/turn-runner/turn-runner.js

@@ -2,33 +2,44 @@ import { Agent, } from "@earendil-works/pi-agent-core";
 import { isContextOverflow } from "@earendil-works/pi-ai";
 import { resolveProviderApiKey } from "../model-resolution/duet-gateway.js";
 import dedent from "dedent";
+import { stripSystemReminders, systemReminder } from "../lib/system-reminder.js";
 import { assistantText } from "../core/serializer.js";
-import { scheduledStateFallbackWakeAt } from "./duration.js";
+import { classifyRoute } from "../model-routing/classifier.js";
+import { loadRoutingTable } from "../model-routing/loader.js";
+import { ADVISOR_EXECUTOR_GUIDANCE_LAYER } from "../model-routing/prompts.js";
+import { resolveTierDefault } from "../model-routing/resolve.js";
+import { ModelRouter, } from "../model-routing/router.js";
+import { BUILT_IN_ROUTING_TABLE, isVirtualModel, } from "../model-routing/table.js";
 import { toXML } from "../lib/xml.js";
 import { createObservationalContextTransform, DEFAULT_EFFECTIVE_CONTEXT, estimateTokens, resolveObservationalMemorySettings, stripObservationalContextMessages, updateObservationalMemory, } from "../memory/observational.js";
 import { rebuildMemoryContextPack } from "../memory/context-pack.js";
 import { createEmbeddingClient } from "../memory/embedding.js";
-import { loadStoredMemory } from "../memory/storage.js";
+import { loadStoredMemory, readSessionObservations, replaceSessionObservations, } from "../memory/storage.js";
 import { MemoryContextCache } from "../memory/store.js";
-import { DEFAULT_CLI_MEMORY_MODEL, DEFAULT_CLI_MODEL, resolveModelName, } from "../model-resolution/resolver.js";
+import { DEFAULT_CLI_MEMORY_MODEL, DEFAULT_CLI_MODEL, resolveModelName, routingCatalogAdapter, } from "../model-resolution/resolver.js";
+import { DEFAULT_TASK_WAIT_BUDGET_MS } from "../types/config.js";
 import { COMPACT_MESSAGE_TOKENS_RATIO, compactTurnState, } from "./state-compaction.js";
 import { createAgentEventTranslator, agentMessageText } from "./agent-events.js";
-import { createRecallMemorySystemPromptLayer, createSourceOfTruthSystemPromptLayer, createForkContextReminder, createStateAgentSystemPromptLayer, createStateMachineSystemPromptLayer, } from "./prompts.js";
+import { createRecallMemorySystemPromptLayer, createSourceOfTruthSystemPromptLayer, createStateMachineSystemPromptLayer, withheldAskReminder, parkNudge, } from "./prompts.js";
 import { applyEvictionHorizon, calculateWireTokens, createInitialHorizon, findEvictionHorizon, } from "./wire-shaping.js";
-import { createDefaultTurnRunnerTools, createTurnRunnerTools, resolveStateCwd, formatCarriedTodosReminder, formatStateMachineTerminalAcknowledgmentPrompt, isTurnRunnerControlResult, } from "./tools.js";
+import { createDefaultTurnRunnerTools, createTurnRunnerTools, resolveStateCwd, formatCarriedTodosReminder, formatStateMachineTerminalAcknowledgmentPrompt, isTurnRunnerControlResult, MINIMUM_STATE_MACHINE_DELAY_MS, } from "./tools.js";
 import { connectMcpServers } from "./mcp.js";
 import { SkillContext } from "./skill-context.js";
-import { currentScheduledState, isAwaitingUserAnswer, isWaitingOnScheduledState, repeatedSelectionLoopCount, } from "./state-machine-session.js";
-import { StateMachineController, } from "./state-machine-controller.js";
+import { currentParkState } from "./state-machine-session.js";
+import { failActiveSession, markTerminalAcknowledged, planDecision, planWake, recordPlannedTerminal, recordScheduled, recordSettled, repeatedSelectionLoopCount, startSession as startStateMachineSession, supersede, } from "./state-machine-decisions.js";
+import { createSubagentExecutor, classifySpawnModel, } from "./subagent.js";
 import { completeTurn, copyOptionalArray, createInitialTurnState } from "./turn-state.js";
 import { DEFAULT_TRANSIENT_RETRY_POLICY, lastMessageIsTransientFailure, transientRetryDelayMs, } from "./transient-error.js";
-import { addUsage, addUsageByModel, usageFromMessages } from "./usage-accounting.js";
+import { addUsage, addUsageByModel, usageFromAiSdk } from "./usage-accounting.js";
+import { SystemRuntimeClock } from "./runtime-clock.js";
+import { createTaskManager } from "../tasks/task-manager.js";
+import { createShellStateHandle } from "./shell-state-handle.js";
+import { createSpawnAgentTool, createTaskAdminTools, lostTaskRecoveryReminder, settlementNotice, wrapBackgroundable, } from "./task-tools.js";
 /**
  * How many times the parent is re-prompted to emit the
- * select_state_machine_state it owes (after a state completes or after the
- * user answers a state's question) before the runner gives up and records an
- * `error` terminal. Bounds the protocol-violation retry loop so a parent that
- * never transitions can't spin forever.
+ * select_state_machine_state it owes after a state completes before the runner
+ * gives up and records an `error` terminal. Bounds the protocol-violation retry
+ * loop so a parent that never transitions can't spin forever.
  */
 const PARENT_TRANSITION_RETRY_BUDGET = 3;
 /** Order matches `TurnContextWindowUsage` fields; indexes map to `scaled[0..3]`. */
@@ -101,6 +112,16 @@ export function scaleContextWindowUsageToTotalTokens(base, totalTokens) {
         globalMemory: scaled[3],
     };
 }
+function emptyTokenUsage() {
+    return {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    };
+}
 export class TurnRunner {
     config;
     eventHandlers = new Set();
@@ -116,14 +137,55 @@ export class TurnRunner {
      * transcript grows across every pi-agent turn in this duet-agent session.
      */
     parentAgent;
+    /** Virtual-model policy owner for the parent session, retained while a concrete pin suspends it. */
+    modelRouter;
+    /** Validated project routing table used by parent retargets and explicit virtual state models. */
+    routingTable;
+    /** Model selection queued while a parent turn is running; applied at the next turn boundary. */
+    pendingModelSelection;
+    /** Advisor target and transcript budget selected with the current virtual tier. */
+    advisorPolicy;
     /** True only while the parent pi agent is actively producing the public terminal event. */
     parentAgentRunning = false;
-    /** Last turn-runner control tool result observed from the parent agent. */
-    parentControlResult = { type: "none" };
-    /** Runtime owner for state-machine progress and active state work. */
-    stateMachineController;
-    /** Parent prompt started by a steer while state-machine work is driving the turn. */
-    activeStateWorkPrompt;
+    /** Control results captured during the current parent pass. More than one is a protocol error. */
+    parentControlResults = [];
+    /** Durable state-machine policy ledger; execution lives in TaskManager. */
+    stateMachine;
+    /** Runtime owner for every state execution and scheduled wake. */
+    /** Protected for test probes (task descriptors, scope injection); production owner is the loop. */
+    taskManager;
+    /** Execution-only metadata keyed by TaskManager's stable task id. */
+    stateTasks = new Map();
+    /** One-shot context attached to the first real parent pass after lost-task recovery. */
+    recoveredTaskReminder;
+    /** Ask withheld by the quiescence gate; re-surfaced on the parent's next pass. */
+    withheldAskQuestions;
+    /** Legacy persisted user-lane projection retained until the next loop owns it. */
+    hydratedQueuedCommands;
+    /** Inputs waiting for the single parent slot between sequential passes. */
+    parentInputs = [];
+    /** Wakes the loop when a user command arrives while task work is in process. */
+    parentInputWaiters = new Set();
+    /** Settlements already folded into the ledger during replacement/interrupt. */
+    ignoredTaskSettlements = new Set();
+    /** Delivery posture for task-backed foreground bash calls. */
+    taskSettlementDelivery = new Map();
+    /** Coalesces same-tick settlements into one FIFO drain and one B3 notice. */
+    settlementDeliveryQueued = false;
+    /** Monotonic root-scope suffix; each public turn owns one root scope. */
+    nextRootScope = 1;
+    /** Scope currently accepting state tasks. */
+    activeRootScopeId;
+    /** Tools are built once at the public-turn boundary and reused by every parent pass. */
+    turnTools;
+    /** Set by interrupt so the loop's sole exit can short-circuit pending-work computation. */
+    interruptReason;
+    /** Full task/process unwind started by interrupt(), awaited before its terminal. */
+    interruptCleanup;
+    /** Guards the single public terminal emission for the active turn. */
+    terminalEmitted = false;
+    /** Shared construction path for relay agent states and spawned children. */
+    subagentExecutor;
     /**
      * Set true by `interrupt()` while a parent-agent prompt is in flight, so
      * `runAgentWorker` can tell our own abort apart from a real provider error
@@ -173,20 +235,62 @@ export class TurnRunner {
     /** MCP servers connected during start(). Disposed on runner.dispose(). */
     mcpRuntime;
     skillContext;
-    constructor(config) {
+    clock;
+    minimumScheduledDelayMs;
+    /** Foreground expiry yields a still-running result without cancelling the task. */
+    taskWaitBudgetMs;
+    constructor(config, dependencies = {}) {
         this.config = config;
+        this.clock = dependencies.clock ?? new SystemRuntimeClock();
+        this.minimumScheduledDelayMs =
+            dependencies.minimumScheduledDelayMs ?? MINIMUM_STATE_MACHINE_DELAY_MS;
+        this.taskWaitBudgetMs = config.taskWaitBudgetMs ?? DEFAULT_TASK_WAIT_BUDGET_MS;
         this.skillContext = new SkillContext(config);
-        this.stateMachineController = new StateMachineController({
-            cwd: config.cwd ?? process.cwd(),
-            createStateAgent: (input) => this.createStateAgentHandle(input),
-            onSessionChanged: (session) => this.emit({ type: "state_machine", stateMachine: session }),
+        this.taskManager = createTaskManager({
+            clock: this.clock,
+            onEvent: (event) => this.handleTaskEvent(event),
+        });
+        this.subagentExecutor = createSubagentExecutor({
+            createAgent: (input, onControlResult) => this.createAgent(input, onControlResult),
+            skillContext: {
+                resolveSkills: (spec, ctx) => this.skillContext.resolveSubagentSkills(spec.allowedSkills, ctx.machineContext ? `state "${ctx.machineContext.currentState}"` : "sub-agent"),
+                resolveSlashSkillPrompt: (prompt, skills) => this.skillContext.resolveSlashSkillPrompt(prompt, skills),
+                createSystemPromptWithAppendedLayers: (input) => this.createBaseSystemPromptWithAppendedLayers(input),
+            },
+            inheritedOptions: () => this.resolveSubagentInheritedOptions(),
+            resolveModel: (model) => this.resolveStateModel(model),
+            seedMessages: (spec, ctx) => spec.forkContext
+                ? [...(ctx.forkSource?.messages() ?? this.parentAgent?.state.messages ?? [])]
+                : [],
+            parentSystemPrompt: (ctx) => ctx.forkSource?.systemPrompt() ?? this.parentAgent?.state.systemPrompt,
+            createTools: (cwd, ctx) => this.createTools("agent", cwd, false, ctx.childScopeId && ctx.ownerScopeId
+                ? {
+                    ownerScopeId: ctx.childScopeId,
+                    ...(ctx.memoryContext?.sessionId
+                        ? { memorySessionId: ctx.memoryContext.sessionId }
+                        : {}),
+                    forkSource: {
+                        messages: () => [...(ctx.agent?.state.messages ?? [])],
+                        systemPrompt: () => ctx.agent?.state.systemPrompt,
+                    },
+                    modelSetting: () => {
+                        const model = ctx.agent?.state.model;
+                        return model ? `${model.provider}:${model.id}` : DEFAULT_CLI_MODEL;
+                    },
+                }
+                : undefined),
+            retryTransientServerErrors: (agent) => this.retryTransientServerErrors(agent),
+            emitAgentEvent: (event, origin) => this.emitAgentEvent(event, origin),
+            recordUsage: (usage, modelId) => this.recordUsage(usage, modelId),
+            emitTurnUsage: (origin) => this.emitTurnUsage(origin),
         });
     }
     async dispose() {
         this.parentAgent?.clearAllQueues();
-        this.activeStateWorkPrompt = undefined;
-        this.setQueuedCommands([]);
+        this.parentInputs.length = 0;
         this.clearFollowUpQueue();
+        await this.taskManager.interruptAll("Runner disposed.");
+        await this.taskManager.reapAll("Runner disposed.");
         await this.memoryPersistence?.dispose();
         this.memoryPersistence = undefined;
         await this.mcpRuntime?.dispose();
@@ -232,28 +336,25 @@ export class TurnRunner {
      * uses) so the rendered prefix lines up with the new horizon and the
      * next prompt-cache fault is paid once instead of twice.
      *
-     * Rejected with a soft warning when a turn chain is in flight —
-     * mutating the horizon mid-stream would invalidate the request the
-     * parent (or a state agent) is already dispatching. `activeTurnPromise`
-     * is the single source of truth here, so poll/timer sleeps pass the
-     * gate cleanly: the chain has already resolved to the `sleep` terminal
-     * before compact is allowed to run.
+     * Rejected with a soft warning while a parent pass is dispatching or while
+     * the turn loop is active without an in-process task. A running task opens
+     * the parent-idle window: its transcript is isolated from the parent wire
+     * horizon, so compact may safely advance that horizon between passes.
      */
     async compact() {
         this.requireStarted();
-        // `activeTurnPromise` is the single source of truth for "a turn chain
-        // is in flight" — it covers the parent agent dispatching, a state
-        // agent dispatching while the parent is paused, and a poll/script
-        // command currently executing. Sleep terminals (poll/timer waits)
-        // have already resolved the chain and cleared this, so compact is
-        // free to run during those waits.
-        if (this.activeTurnPromise || this.compactInFlight) {
+        // Parent work owns the wire transcript and therefore closes the gate.
+        // In-process state work leaves the parent idle and opens it; scheduled
+        // waits have already settled the public turn and are open as well.
+        if (this.parentAgentRunning ||
+            (this.activeTurnPromise && this.taskManager.pendingWork().kind !== "open") ||
+            this.compactInFlight) {
             this.emit({
                 type: "system",
                 level: "warn",
                 message: this.compactInFlight
                     ? "compact ignored: a compact pass is already in progress."
-                    : "compact ignored: a turn chain is in flight; send compact between turns.",
+                    : "compact ignored: a parent pass is in flight; retry in the parent-idle window.",
             });
             return;
         }
@@ -300,6 +401,7 @@ export class TurnRunner {
                 return;
             }
             this.wireGuardHorizon.evictionHorizon = newHorizon;
+            this.modelRouter?.noteCompaction();
             const retainedAfter = applyEvictionHorizon(observable, newHorizon);
             const afterTokens = calculateWireTokens(retainedAfter);
             const dropped = currentRetained.length - retainedAfter.length;
@@ -347,7 +449,38 @@ export class TurnRunner {
                 options: this.resolveTurnOptions(startOptions, command.state.options),
             }
             : createInitialTurnState(mode, this.resolveTurnOptions(startOptions));
-        this.stateMachineController.hydrate(state.stateMachine);
+        await this.initializeModelRouter(state.options?.model);
+        this.stateMachine = state.stateMachine;
+        const recovery = this.taskManager.recover(state.tasks ?? [], state.nextTaskId, state.taskOutputTails);
+        const pendingLostTaskIds = new Set([
+            ...(state.pendingLostTaskReminderTaskIds ?? []),
+            ...recovery.lost.map((descriptor) => descriptor.id),
+        ]);
+        const lostSnapshots = [...pendingLostTaskIds]
+            .map((id) => this.taskManager.output(id))
+            .filter((snapshot) => snapshot !== undefined);
+        if (lostSnapshots.length > 0) {
+            this.recoveredTaskReminder = lostTaskRecoveryReminder(lostSnapshots);
+            while (this.taskManager.nextSettled()) {
+                // Recovery is delivered through the one-shot reminder, not the live settlement lane.
+            }
+        }
+        this.hydratedQueuedCommands = state.queuedCommands ? [...state.queuedCommands] : undefined;
+        const interruptedOnRecovery = command.state &&
+            (state.status === "running" ||
+                (state.status === "sleeping" && this.taskManager.pendingWork().kind !== "sleep"));
+        const recoveredState = {
+            ...state,
+            ...(interruptedOnRecovery
+                ? { status: "interrupted", agent: { ...state.agent, status: "cancelled" } }
+                : {}),
+            tasks: [...this.taskManager.list()],
+            taskOutputTails: this.snapshotTaskOutputTails(),
+            pendingLostTaskReminderTaskIds: lostSnapshots.length > 0
+                ? lostSnapshots.map((snapshot) => snapshot.descriptor.id)
+                : undefined,
+            nextTaskId: this.taskManager.nextTaskId(),
+        };
         // Hydrate the wire-shaping object in place. `this.wireGuardHorizon` is
         // referenced by the observational context transform; replacing the
         // reference would orphan the transform's view. `Object.assign` over
@@ -356,14 +489,20 @@ export class TurnRunner {
         if (state.wireGuardHorizon) {
             Object.assign(this.wireGuardHorizon, state.wireGuardHorizon);
         }
-        this.setState(state);
+        this.setState(recoveredState);
         this.initializeParentAgent();
         this.started = true;
         const hydratedState = this.requireRunnerState();
         this.emit({ type: "turn_started", state: hydratedState });
         return hydratedState;
     }
-    async turn(command) {
+    /**
+     * Route a turn-driving command and resolve with the shared chain terminal.
+     * `onAccepted` fires only after the command has entered the active driver or
+     * the runner-owned queue; transports can acknowledge delivery at that
+     * boundary without leaking transport metadata into durable turn state.
+     */
+    async turn(command, onAccepted) {
         this.requireStarted();
         await this.ensureMemoryLoaded();
         await this.ensureSkillsLoaded();
@@ -380,10 +519,12 @@ export class TurnRunner {
             // turn() is the concurrency boundary: repeated calls extend or queue
             // behind the active chain instead of creating a separate parent transcript.
             this.handleCommandDuringActiveTurn(command);
+            onAccepted?.();
             return this.activeTurnPromise;
         }
-        const activeTurnPromise = this.runTurnChain(command);
+        const activeTurnPromise = this.runTurnLoop(command);
         this.activeTurnPromise = activeTurnPromise;
+        onAccepted?.();
         try {
             return await activeTurnPromise;
         }
@@ -393,46 +534,174 @@ export class TurnRunner {
             }
         }
     }
-    async runTurnChain(command) {
+    async runTurnLoop(command) {
         this.turnUsage = undefined;
         this.turnUsageByModel = undefined;
+        this.interruptReason = undefined;
+        this.interruptCleanup = undefined;
+        this.terminalEmitted = false;
+        this.activeRootScopeId = `turn-${this.nextRootScope++}`;
+        this.turnTools = this.createTools(this.requireRunnerState().mode).tools;
+        this.enqueueParentInput(command.type === "wake" ? { type: "wake" } : { type: "user_command", command });
+        const carriedUserCommands = this.hydratedQueuedCommands?.filter((queued) => queued.type !== "wake");
+        if (carriedUserCommands && carriedUserCommands.length > 0) {
+            for (const queued of carriedUserCommands) {
+                this.enqueueParentInput({ type: "user_command", command: queued });
+            }
+        }
+        else {
+            for (const entry of this.getFollowUpQueue()) {
+                this.enqueueParentInput({
+                    type: "user_command",
+                    command: {
+                        type: "prompt",
+                        message: entry.message,
+                        behavior: "follow_up",
+                        images: entry.images,
+                    },
+                });
+            }
+        }
+        this.hydratedQueuedCommands = undefined;
+        let questions;
+        let completion = {
+            status: "completed",
+        };
+        let terminal;
         try {
-            let terminal;
-            terminal = await this.executeTurnCommand(command);
-            terminal = await this.drainQueuedTurnCommands(terminal);
-            terminal = { ...terminal, state: this.snapshotState(terminal.state) };
-            if (this.turnUsage) {
+            while (!questions && !this.interruptReason) {
+                this.enqueueAvailableSettlements();
+                const pendingBeforeInput = this.taskManager.pendingWork();
+                const runnableIndex = pendingBeforeInput.kind === "open"
+                    ? this.parentInputs.findIndex((queued) => queued.type === "task_settlements" ||
+                        (queued.type === "user_command" && queued.command.behavior === "steer"))
+                    : 0;
+                const input = runnableIndex >= 0 ? this.parentInputs.splice(runnableIndex, 1)[0] : undefined;
+                if (!input) {
+                    if (pendingBeforeInput.kind !== "open")
+                        break;
+                    if (this.parentInputs.length > 0) {
+                        await this.taskManager.waitForSettlement();
+                    }
+                    else {
+                        await this.waitForLoopActivity();
+                    }
+                    continue;
+                }
+                if (input.type === "wake" &&
+                    input.queued === true &&
+                    this.taskManager.pendingWork().kind !== "sleep" &&
+                    this.requireRunnerState().status !== "sleeping") {
+                    continue;
+                }
+                const result = await this.processParentLoopInput(input);
+                if (result?.type === "ask") {
+                    if (this.taskManager.pendingWork().kind === "open") {
+                        // Terminal ⇒ quiescent forbids delivering the ask now. Keep the
+                        // questions just long enough to remind the parent on its next pass
+                        // (settlements guarantee one); the parent re-asks if still relevant.
+                        this.withheldAskQuestions = result.questions;
+                    }
+                    else {
+                        questions = result.questions;
+                    }
+                }
+                if (result?.type === "interrupted")
+                    this.interruptReason ??= "Interrupted";
+                if (result?.type === "state_completed") {
+                    this.enqueueParentInput({
+                        type: "transition_enforcement",
+                        stateName: result.stateName,
+                        output: result.output,
+                    });
+                }
+                if (result?.type === "terminal") {
+                    completion = {
+                        status: result.status === "error" ? "failed" : "completed",
+                        ...(result.result !== undefined ? { result: result.result } : {}),
+                        ...(result.error !== undefined ? { error: result.error } : {}),
+                    };
+                    if (this.stateMachine?.terminal && !this.stateMachine.terminalAcknowledged) {
+                        this.enqueueParentInput({ type: "terminal_acknowledgment" });
+                    }
+                }
+                // Preserve the old drain rule: follow-ups arriving after a sleep was
+                // selected remain queued for the next user-driven turn. A stale wake,
+                // however, is skipped above so it cannot clobber the meaningful result.
+                if (this.taskManager.pendingWork().kind === "sleep" &&
+                    this.parentInputs.length > 0 &&
+                    this.parentInputs.every((queued) => queued.type === "user_command" && queued.command.behavior === "follow_up")) {
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            completion = {
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            };
+            await this.taskManager.interruptAll(`Turn failed: ${completion.error}`);
+        }
+        finally {
+            await this.interruptCleanup;
+            if (!this.interruptReason && !questions && this.taskManager.pendingWork().kind === "open") {
+                await this.taskManager.interruptAll("Turn exited with in-process work still active.");
+                completion = {
+                    status: "failed",
+                    error: "Turn exited with in-process work still active.",
+                };
+            }
+            this.discardStaleTaskSettlements();
+            const quiescentState = this.snapshotState(this.requireRunnerState());
+            try {
+                await this.updateMemoryAfterAgentRun(quiescentState.agent.messages, quiescentState.options);
+            }
+            catch (error) {
+                if (!this.interruptReason) {
+                    completion = {
+                        status: "failed",
+                        error: error instanceof Error ? error.message : String(error),
+                    };
+                }
+            }
+            const state = this.snapshotState(this.requireRunnerState());
+            if (this.interruptReason) {
                 terminal = {
-                    ...terminal,
-                    turnUsage: this.turnUsage,
-                    usageByModel: this.turnUsageByModel ?? [],
-                    ...(this.lastParentUsageSnapshot
+                    type: "interrupted",
+                    state: {
+                        ...state,
+                        status: "interrupted",
+                        agent: { ...state.agent, status: "cancelled" },
+                    },
+                };
+            }
+            else if (questions) {
+                terminal = {
+                    type: "ask",
+                    questions,
+                    state: { ...state, status: "waiting_for_human" },
+                };
+            }
+            else {
+                const settledPending = this.taskManager.pendingWork();
+                terminal =
+                    settledPending.kind === "sleep"
                         ? {
-                            effectiveContextWindow: this.lastParentUsageSnapshot.effectiveContextWindow,
-                            contextWindowUsage: this.lastParentUsageSnapshot.contextWindowUsage,
-                            lastMessageUsage: this.lastParentUsageSnapshot.lastMessageUsage,
+                            type: "sleep",
+                            wakeAt: settledPending.wakeAt,
+                            state: { ...state, status: "sleeping" },
                         }
-                        : {}),
-                };
+                        : completeTurn(state, completion.status, completion.result, completion.error);
             }
+            terminal = this.attachTurnUsage({ ...terminal, state: this.snapshotState(terminal.state) });
             this.setState(terminal.state);
-            this.emit(terminal);
-            return terminal;
-        }
-        finally {
+            this.emitTerminalOnce(terminal);
+            this.turnTools = undefined;
+            this.activeRootScopeId = undefined;
             this.turnUsage = undefined;
             this.turnUsageByModel = undefined;
         }
-    }
-    async executeTurnCommand(command) {
-        switch (command.type) {
-            case "prompt":
-                return this.prompt(command);
-            case "answer":
-                return this.answer(command);
-            case "wake":
-                return this.wake();
-        }
+        return terminal;
     }
     handleCommandDuringActiveTurn(command) {
         if ((command.type === "prompt" || command.type === "answer") && this.parentAgentRunning) {
@@ -441,20 +710,11 @@ export class TurnRunner {
             this.sendCommandToAgent(this.requireParentAgent(), command);
             return;
         }
-        if (command.type === "prompt" || command.type === "answer") {
-            const message = this.commandToUserMessage(command);
-            if (this.stateMachineController.hasActiveWork()) {
-                if (command.behavior === "follow_up") {
-                    // State-machine work is driving the terminal event. Follow-ups are
-                    // transition context, so replay them before the next state decision.
-                    this.enqueueTurnCommand(command);
-                    return;
-                }
-                this.startParentPromptDuringActiveStateWork(message, command);
-                return;
-            }
+        this.enqueueParentInput(command.type === "wake" ? { type: "wake", queued: true } : { type: "user_command", command });
+        if ((command.type === "prompt" || command.type === "answer") &&
+            command.behavior === "follow_up") {
+            this.appendFollowUpPrompt(this.commandToUserMessage(command), command.images);
         }
-        this.enqueueTurnCommand(command);
     }
     sendCommandToAgent(agent, command) {
         const message = this.commandToUserMessage(command);
@@ -468,69 +728,96 @@ export class TurnRunner {
             agent.followUp(agentMessage);
         }
     }
-    startParentPromptDuringActiveStateWork(message, command) {
-        const prompt = this.runParentPromptDuringActiveStateWork(message, command);
-        this.activeStateWorkPrompt = prompt;
-        void prompt.finally(() => {
-            if (this.activeStateWorkPrompt === prompt)
-                this.activeStateWorkPrompt = undefined;
-        });
+    enqueueParentInput(input) {
+        this.parentInputs.push(input);
+        for (const wake of this.parentInputWaiters)
+            wake();
+        this.parentInputWaiters.clear();
     }
-    async runParentPromptDuringActiveStateWork(message, command) {
-        const prompt = command.behavior === "steer"
-            ? dedent `
-            <system-reminder>
-            The user sent this as a steer message while state-machine work is running.
-            If the state-machine should change course, call select_state_machine_state to restart the current state with updated input or choose a different state.
-            </system-reminder>
-
-            ${message}
-          `
-            : message;
-        const terminal = await this.prompt({
-            type: "prompt",
-            message: prompt,
-            behavior: command.behavior,
-            images: command.type === "prompt" ? command.images : undefined,
+    async waitForLoopActivity() {
+        if (this.parentInputs.length > 0)
+            return;
+        let wake;
+        const parentInput = new Promise((resolve) => {
+            wake = resolve;
+            this.parentInputWaiters.add(wake);
         });
-        this.setState(terminal.state);
-        return terminal;
+        try {
+            await Promise.race([this.taskManager.waitForSettlement().then(() => undefined), parentInput]);
+        }
+        finally {
+            this.parentInputWaiters.delete(wake);
+        }
     }
-    async drainQueuedTurnCommands(terminal) {
-        let latest = terminal;
-        while (this.getQueuedCommands().length > 0) {
-            if (latest.type === "sleep" &&
-                this.getQueuedCommands().every((command) => this.isFollowUpQueueCommand(command))) {
-                return latest;
-            }
-            if (latest.type === "interrupted" ||
-                (latest.type === "complete" && latest.status === "failed")) {
-                this.setQueuedCommands([]);
-                this.clearFollowUpQueue();
-                return latest;
+    enqueueAvailableSettlements() {
+        if ([...this.taskSettlementDelivery.values()].includes("foreground_pending"))
+            return;
+        const settlements = [];
+        for (let settlement = this.taskManager.nextSettled(); settlement; settlement = this.taskManager.nextSettled()) {
+            const delivery = this.taskSettlementDelivery.get(settlement.id);
+            this.taskSettlementDelivery.delete(settlement.id);
+            if (delivery !== "suppress")
+                settlements.push(settlement);
+        }
+        if (settlements.length === 0)
+            return;
+        const canSteer = this.parentAgentRunning &&
+            this.parentControlResults.length === 0 &&
+            settlements.every((settlement) => !this.stateTasks.has(settlement.id));
+        if (canSteer) {
+            const snapshots = settlements
+                .map((settlement) => this.taskManager.output(settlement.id))
+                .filter((snapshot) => snapshot !== undefined);
+            if (snapshots.length > 0) {
+                this.requireParentAgent().steer(buildUserAgentMessage(settlementNotice(snapshots), undefined));
+                return;
             }
-            const queued = this.shiftQueuedCommand();
-            if (!queued)
-                break;
-            this.removeQueuedFollowUpPrompt(queued);
-            this.setState({
-                ...latest.state,
-                followUpQueue: this.getFollowUpQueue(),
-                queuedCommands: this.getQueuedCommands(),
-            });
-            // A wake only has work to do when the runner is currently sleeping on
-            // a scheduled state. If the session moved on (the prior queued
-            // command already drove the state machine, or the session was never
-            // sleeping to begin with), running wake here would emit a
-            // "Nothing to wake." terminal that clobbers the real terminal from
-            // the previous command in this drain chain. Skipping the queued wake
-            // keeps the meaningful terminal as the single emitted event.
-            if (queued.type === "wake" && latest.state.status !== "sleeping") {
+        }
+        this.parentInputs.unshift({ type: "task_settlements", settlements });
+    }
+    handleTaskEvent(event) {
+        if (event.type === "started") {
+            this.emit({ type: "task_started", task: event.descriptor });
+            return;
+        }
+        if (event.type === "output") {
+            this.emit({ type: "task_output", taskId: event.id, chunk: event.chunk });
+            return;
+        }
+        this.emit({ type: "task_settled", settlement: event.settlement });
+        if (this.taskSettlementDelivery.get(event.settlement.id) === "foreground_pending")
+            return;
+        this.scheduleSettlementDelivery();
+    }
+    scheduleSettlementDelivery() {
+        if (this.settlementDeliveryQueued)
+            return;
+        this.settlementDeliveryQueued = true;
+        queueMicrotask(() => {
+            this.settlementDeliveryQueued = false;
+            this.enqueueAvailableSettlements();
+            for (const wake of this.parentInputWaiters)
+                wake();
+            this.parentInputWaiters.clear();
+        });
+    }
+    discardStaleTaskSettlements() {
+        for (let settlement = this.taskManager.nextSettled(); settlement; settlement = this.taskManager.nextSettled()) {
+            this.stateTasks.delete(settlement.id);
+            this.ignoredTaskSettlements.delete(settlement.id);
+            this.taskSettlementDelivery.delete(settlement.id);
+        }
+        for (const input of this.parentInputs) {
+            if (input.type !== "task_settlements")
                 continue;
+            for (const settlement of input.settlements) {
+                this.stateTasks.delete(settlement.id);
+                this.ignoredTaskSettlements.delete(settlement.id);
+                this.taskSettlementDelivery.delete(settlement.id);
             }
-            latest = await this.executeTurnCommand(queued);
         }
-        return latest;
+        const userInputs = this.parentInputs.filter((input) => input.type !== "task_settlements");
+        this.parentInputs.splice(0, this.parentInputs.length, ...userInputs);
     }
     commandToUserMessage(command) {
         if (command.type === "prompt") {
@@ -546,39 +833,30 @@ export class TurnRunner {
             return base;
         return `${base}\n\n${this.skillContext.resolveSlashSkillPrompt(command.message)}`;
     }
-    enqueueTurnCommand(command) {
-        if ((command.type === "prompt" || command.type === "answer") &&
-            command.behavior === "follow_up") {
-            this.appendFollowUpPrompt(this.commandToUserMessage(command), command.images);
-        }
-        this.setQueuedCommands([...this.getQueuedCommands(), command]);
-    }
     replaceFollowUpQueue(entries) {
         this.setFollowUpQueue(entries);
         this.parentAgent?.clearFollowUpQueue();
-        for (const entry of this.getFollowUpQueue()) {
-            this.parentAgent?.followUp(buildUserAgentMessage(entry.message, entry.images));
+        this.parentInputs.splice(0, this.parentInputs.length, ...this.parentInputs.filter((input) => input.type !== "user_command" || input.command.behavior !== "follow_up"));
+        if (this.parentAgentRunning) {
+            for (const entry of entries) {
+                this.parentAgent?.followUp(buildUserAgentMessage(entry.message, entry.images));
+            }
+        }
+        else if (this.activeTurnPromise) {
+            for (const entry of entries) {
+                this.enqueueParentInput({
+                    type: "user_command",
+                    command: {
+                        type: "prompt",
+                        message: entry.message,
+                        behavior: "follow_up",
+                        images: entry.images,
+                    },
+                });
+            }
         }
-        this.replaceQueuedFollowUpCommands(entries);
         this.emitFollowUpQueue();
     }
-    replaceQueuedFollowUpCommands(entries) {
-        this.removeQueuedFollowUpCommands();
-        if (!this.state || this.parentAgentRunning)
-            return;
-        this.setQueuedCommands([
-            ...this.getQueuedCommands(),
-            ...entries.map((entry) => ({
-                type: "prompt",
-                message: entry.message,
-                behavior: "follow_up",
-                images: entry.images,
-            })),
-        ]);
-    }
-    removeQueuedFollowUpCommands() {
-        this.setQueuedCommands(this.getQueuedCommands().filter((command) => !this.isFollowUpQueueCommand(command)));
-    }
     isFollowUpQueueCommand(command) {
         return ((command.type === "prompt" || command.type === "answer") && command.behavior === "follow_up");
     }
@@ -619,264 +897,402 @@ export class TurnRunner {
         this.requireStarted();
         if (!this.state)
             return;
-        const hadActiveControllerWork = this.stateMachineController.hasActiveWork();
-        this.stateMachineController.interrupt("Interrupted");
-        const interruptedState = this.snapshotState(this.state);
-        const terminal = {
-            type: "interrupted",
-            state: {
-                ...interruptedState,
-                status: "interrupted",
-                agent: { ...interruptedState.agent, status: "cancelled" },
-            },
-        };
-        this.setState(terminal.state);
-        if (this.parentAgentRunning || hadActiveControllerWork) {
-            // The active turn emits the terminal event after agent.prompt() unwinds;
-            // interrupt() only aborts out-of-band. The interrupted snapshot is
-            // already on `this.state` above — `runAgentWorker` reads it from there.
-            this.parentAgentInterrupted = true;
-        }
+        this.interruptReason = "Interrupted";
+        this.parentAgentInterrupted = this.parentAgentRunning;
         this.parentAgent?.abort();
         this.parentAgent?.clearAllQueues();
-        this.activeStateWorkPrompt = undefined;
-        this.setQueuedCommands([]);
+        this.parentInputs.length = 0;
         this.clearFollowUpQueue();
         this.parentAgentRunning = false;
+        this.interruptCleanup = this.interruptTasks("Interrupted");
+        if (!this.activeTurnPromise) {
+            this.terminalEmitted = false;
+            void this.interruptCleanup.then(() => {
+                const state = this.snapshotState(this.requireRunnerState());
+                const terminal = {
+                    type: "interrupted",
+                    state: {
+                        ...state,
+                        status: "interrupted",
+                        agent: { ...state.agent, status: "cancelled" },
+                    },
+                };
+                this.setState(terminal.state);
+                this.emitTerminalOnce(terminal);
+            });
+        }
     }
     emit(event) {
         for (const handler of this.eventHandlers) {
             handler(event);
         }
     }
-    async prompt(command) {
-        const originalState = this.requireRunnerState();
-        const state = this.clearFinishedTodosAtTurnStart({ ...originalState, status: "running" });
-        const resolvedPrompt = this.skillContext.resolveSlashSkillPrompt(command.message);
-        const todoReminder = formatCarriedTodosReminder(state.todos);
-        const prompt = todoReminder ? `${todoReminder}\n\n${resolvedPrompt}` : resolvedPrompt;
-        const images = promptImagesToContent(command.images);
-        let terminal;
-        if (state.mode === "agent") {
-            terminal = await this.runAgentMode(state, prompt, images);
-        }
-        else {
-            terminal = await this.runTurnRunnerAgentWithStateMachineTools({
-                state,
-                prompt,
-                images,
-                mode: state.mode,
-            });
+    async processParentLoopInput(input) {
+        switch (input.type) {
+            case "user_command":
+                return this.runUserCommandPass(input.command, input.continuation);
+            case "task_settlements":
+                return this.processTaskSettlements(input.settlements);
+            case "transition_enforcement":
+                return this.selectNextStateAfterCompletion(input.stateName, input.output);
+            case "terminal_acknowledgment":
+                return this.runTerminalAcknowledgmentPass();
+            case "wake":
+                return this.runWakeInput();
         }
-        return this.restoreSleepAfterPromptIfNeeded(originalState, terminal);
-    }
-    async answer(command) {
-        const message = this.commandToUserMessage(command);
-        return this.prompt({
-            type: "prompt",
-            message,
-            behavior: command.behavior,
-            images: command.images,
-        });
     }
-    async wake() {
-        const originalState = this.requireRunnerState();
-        const state = { ...originalState, status: "running" };
-        if (originalState.status === "sleeping") {
-            // Sleeping scheduled states already ended the previous duet-agent turn.
-            // Wake starts a new state-machine-driven turn; normal prompts while
-            // sleeping instead start parent-driven turns.
-            const result = await this.stateMachineController.wake();
-            if (result)
-                return this.driveStateMachineResult(result, state);
-        }
-        return {
-            type: "complete",
-            status: "completed",
-            state: originalState,
-            result: "Nothing to wake.",
+    async runUserCommandPass(command, continuation = false) {
+        const runningState = {
+            ...this.requireRunnerState(),
+            status: "running",
         };
-    }
-    restoreSleepAfterPromptIfNeeded(originalState, terminal) {
-        if (originalState.status !== "sleeping" ||
-            terminal.type !== "complete" ||
-            !isWaitingOnScheduledState(terminal.state.stateMachine)) {
-            return terminal;
-        }
-        if (terminal.status === "failed") {
+        const state = continuation ? runningState : this.clearFinishedTodosAtTurnStart(runningState);
+        let prompt = this.commandToUserMessage(command);
+        if (!continuation &&
+            command.behavior === "steer" &&
+            this.taskManager.pendingWork().kind === "open") {
+            prompt = `${systemReminder(dedent `
+        <system-reminder>
+        The user sent this as a steer message while state-machine work is running.
+        If the state-machine should change course, call select_state_machine_state to restart the current state with updated input or choose a different state.
+        </system-reminder>
+      `)}\n\n${prompt}`;
+        }
+        const todoReminder = continuation ? undefined : formatCarriedTodosReminder(state.todos);
+        if (todoReminder)
+            prompt = `${todoReminder}\n\n${prompt}`;
+        if (!continuation)
+            this.removeQueuedFollowUpPrompt(command);
+        const worker = await this.runParentPass({
+            state,
+            prompt,
+            images: promptImagesToContent(command.images),
+            continuation,
+        });
+        this.setState(worker.outcome.state);
+        if (worker.outcome.type === "complete" &&
+            worker.outcome.status === "failed" &&
+            this.taskManager.pendingWork().kind === "sleep") {
             this.emit({
                 type: "system",
                 level: "error",
-                message: terminal.error ?? terminal.result ?? "Prompt failed while waiting.",
+                message: worker.outcome.error ?? worker.outcome.result ?? "Prompt failed while waiting.",
             });
         }
-        const state = currentScheduledState(terminal.state.stateMachine);
-        const progress = state ? terminal.state.stateMachine?.progress?.states[state.name] : undefined;
-        const wakeAt = progress?.nextWakeAt ?? scheduledStateFallbackWakeAt(state);
-        return {
-            type: "sleep",
-            wakeAt,
-            state: { ...terminal.state, status: "sleeping" },
-        };
+        if (worker.outcome.type === "interrupted")
+            return { type: "interrupted" };
+        if (state.mode === "agent") {
+            if (worker.control.type === "ask_user_question") {
+                return { type: "ask", questions: worker.control.questions };
+            }
+            return worker.outcome.status === "failed"
+                ? { type: "terminal", status: "error", error: worker.outcome.error }
+                : { type: "terminal", status: "completed", result: worker.outcome.result };
+        }
+        const result = await this.stateMachineResultFromWorker(worker, worker.outcome.state);
+        if (result)
+            return result;
+        return worker.outcome.status === "failed"
+            ? { type: "terminal", status: "error", error: worker.outcome.error }
+            : { type: "terminal", status: "completed", result: worker.outcome.result };
     }
-    controllerResultToTerminal(result, baseState = this.requireRunnerState()) {
-        const state = this.snapshotState(baseState);
-        switch (result.type) {
-            case "state_completed":
-                return completeTurn(state, "completed", JSON.stringify(result.output ?? null));
-            case "ask":
-                return {
-                    type: "ask",
-                    questions: result.questions,
-                    state: { ...state, status: "waiting_for_human" },
-                };
-            case "sleep":
-                return { type: "sleep", wakeAt: result.wakeAt, state: { ...state, status: "sleeping" } };
-            case "interrupted":
-                return { type: "interrupted", state: { ...state, status: "interrupted" } };
-            case "terminal":
-                if (result.status === "error") {
-                    // A runtime failure (poll timeout, unknown/invalid selected state,
-                    // agent/script state failure, misconfigured-poll gate, or exhausted
-                    // protocol-violation retries) is the ONLY state-machine outcome that
-                    // fails the turn. The user-facing message rides on event.error; the
-                    // same string is also recorded on state.stateMachine.terminal.reason
-                    // by recordStateFailed, so the parent's acknowledgment turn and the
-                    // board/relay see the identical reason.
-                    return completeTurn(state, "failed", undefined, result.error);
-                }
-                // A deliberately selected terminal (completed/failed/cancelled, incl.
-                // the auto-injected `cancelled` that `wont do` maps to) is a
-                // successful turn outcome — not a user abort. Report turn-completion
-                // status "completed" so the backend never surfaces "Error: cancelled —
-                // try again". The machine's own status survives on
-                // state.stateMachine.terminal.status (set by recordStateMachineCompleted),
-                // which is what the board column resolves from. Only an explicit user
-                // stop — type:"interrupted" via interrupt() — surfaces the cancel
-                // message.
-                return completeTurn(state, "completed", result.result);
-        }
-    }
-    async driveStateMachineResult(result, baseState = this.requireRunnerState()) {
-        let next = result;
-        let state = baseState;
-        // The controller only executes states. TurnRunner owns the continuation
-        // loop so queued follow-ups always update the parent transcript before the
-        // parent chooses the next state.
-        while (next.type === "state_completed") {
-            state = this.requireRunnerState();
-            const queued = await this.drainQueuedTurnCommands({
-                type: "complete",
-                status: "completed",
-                state: this.snapshotState({ ...state, status: "running" }),
+    async runParentPass(input) {
+        const agent = this.requireParentAgent();
+        if (agent.hasQueuedMessages()) {
+            throw new Error("Parent pi steer/follow-up queues must be empty at internal pass start.");
+        }
+        const recoveredTaskReminder = this.recoveredTaskReminder;
+        this.recoveredTaskReminder = undefined;
+        if (recoveredTaskReminder) {
+            this.setState({
+                ...this.requireRunnerState(),
+                pendingLostTaskReminderTaskIds: undefined,
             });
-            if (queued.type !== "complete" || queued.status !== "completed")
-                return queued;
-            this.setState(queued.state);
-            state = queued.state;
-            next = await this.selectNextStateAfterCompletion(next.stateName, next.output);
-        }
-        if (next.type === "interrupted" && this.activeStateWorkPrompt) {
-            return this.activeStateWorkPrompt;
-        }
-        if (next.type === "terminal") {
-            // Run the parent's terminal acknowledgment turn so the
-            // state-machine outcome is propagated back to the parent.
-            // `terminate: true` on the state-machine tools means the parent's
-            // prompt loop ends right after it selects a terminal (or a state
-            // that then errors at runtime) — without this pass the parent has
-            // no transcript entry for the outcome and cannot summarize it to
-            // the user before control returns to them.
-            const acknowledged = await this.runStateMachineTerminalAcknowledgment();
-            if (acknowledged)
-                return acknowledged;
-            state = this.requireRunnerState();
-        }
-        return this.controllerResultToTerminal(next, state);
-    }
-    /**
-     * Re-prompt the parent agent once after a state-machine terminal.
-     *
-     * The flag is per-session, so a fresh state machine created during
-     * the acknowledgment turn — which `createStateMachineSession` builds
-     * as a brand-new session object — will run its own acknowledgment
-     * when it terminates. The flag's only job is to prevent the same
-     * session.terminal from being re-acknowledged, which would otherwise
-     * happen if the parent (incorrectly) routes back into the controller
-     * on the already-terminal session and the controller re-records a
-     * terminal on it.
-     *
-     * Behavior:
-     * - Builds the acknowledgment prompt via
-     *   `formatStateMachineTerminalAcknowledgmentPrompt`. The prompt is
-     *   neutral with respect to "decided vs runtime failure" — the
-     *   parent's own transcript already shows whether it selected the
-     *   terminal, and `status`/`reason` carry the rest of the framing.
-     * - Runs one parent worker pass with full state-machine tool access.
-     *   The parent is steered to reply in plain text and let control
-     *   return to the user; full tool access only means a control action
-     *   on this turn (e.g. an explicitly instructed create) is handled
-     *   rather than silently dropped, per the next bullet.
-     * - On interruption, surfaces an `interrupted` terminal event for
-     *   the whole turn.
-     * - When the parent's reply carries a control action, drives that
-     *   control through the standard `driveStateMachineResult` path so
-     *   any newly-created state machine runs end-to-end and itself
-     *   produces a follow-up terminal (which also gets acknowledged via
-     *   its own session).
-     * - When the parent's reply is plain text, returns `undefined` so
-     *   the caller renders the original terminal (preserving
-     *   status/error/SM history) and the parent's natural-language
-     *   summary lands on the transcript as the final assistant message.
-     */
-    async runStateMachineTerminalAcknowledgment() {
-        const session = this.stateMachineController.getSession();
+        }
+        const recoveryInput = recoveredTaskReminder
+            ? {
+                ...input,
+                state: { ...input.state, pendingLostTaskReminderTaskIds: undefined },
+                prompt: `${recoveredTaskReminder}\n\n${input.prompt}`,
+            }
+            : input;
+        const parked = currentParkState(this.stateMachine);
+        // Append to the pass already being made, so a transition out of park costs
+        // no extra model call. The selection tools put the same reminder in their
+        // terminating result on the entry pass, before currentState has changed.
+        return this.runAgentWorker(parked
+            ? { ...recoveryInput, prompt: `${recoveryInput.prompt}\n\n${parkNudge(parked.name)}` }
+            : recoveryInput);
+    }
+    async runWakeInput() {
+        const planned = planWake(this.stateMachine, this.clock.now());
+        if (!planned) {
+            return { type: "terminal", status: "completed", result: "Nothing to wake." };
+        }
+        await this.cancelScheduledTasks("Scheduled wake fired.");
+        this.setStateMachine(planned.session);
+        return this.executePlannedWork(planned.work);
+    }
+    async runTerminalAcknowledgmentPass() {
+        const session = this.stateMachine;
         if (!session?.terminal || session.terminalAcknowledged)
             return undefined;
-        this.stateMachineController.markTerminalAcknowledged();
-        const sessionForPrompt = this.stateMachineController.getSession();
-        if (!sessionForPrompt?.terminal)
+        this.setStateMachine(markTerminalAcknowledged(session));
+        const acknowledged = this.stateMachine;
+        if (!acknowledged?.terminal)
             return undefined;
-        const acknowledgmentPrompt = formatStateMachineTerminalAcknowledgmentPrompt({
-            session: sessionForPrompt,
-        });
-        // `snapshotState` re-reads parentAgent messages directly, so this turn
-        // state includes the parent's transcript through the terminal-selecting
-        // tool call without a separate refresh step.
-        const turnState = this.snapshotState({ ...this.requireRunnerState(), status: "running" });
-        const workerResult = await this.runAgentWorker({
-            state: turnState,
-            prompt: acknowledgmentPrompt,
-            ...this.createTools(turnState.mode),
+        const worker = await this.runParentPass({
+            state: this.snapshotState({ ...this.requireRunnerState(), status: "running" }),
+            prompt: formatStateMachineTerminalAcknowledgmentPrompt({ session: acknowledged }),
+            continuation: true,
         });
-        this.setState(workerResult.outcome.state);
-        if (workerResult.outcome.type === "interrupted") {
-            return { type: "interrupted", state: workerResult.outcome.state };
-        }
-        const followUp = await this.controllerResultFromWorkerResult(workerResult, workerResult.outcome.state);
-        // On the acknowledgment turn the prior machine is already terminal, so a
-        // create_state_machine_definition here is legal follow-up work, not a
-        // violation — controllerResultFromWorkerResult returns it as a result.
-        // A plain-text reply returns undefined so the caller renders the original
-        // terminal with the parent's summary as the final assistant message.
-        if (followUp) {
-            return this.driveStateMachineResult(followUp, workerResult.outcome.state);
+        this.setState(worker.outcome.state);
+        if (worker.outcome.type === "interrupted")
+            return { type: "interrupted" };
+        return this.stateMachineResultFromWorker(worker, worker.outcome.state);
+    }
+    async executePlannedWork(work) {
+        if ("terminal" in work) {
+            const settled = recordPlannedTerminal(this.requireStateMachine(), work.terminal);
+            this.setStateMachine(settled.session);
+            return settled.outcome;
+        }
+        if ("schedule" in work) {
+            if (work.schedule.wakeAt > this.clock.now()) {
+                this.taskManager.start({
+                    kind: "scheduled",
+                    name: work.schedule.stateName,
+                    label: `Wait for ${work.schedule.stateName}`,
+                    ownerScopeId: this.requireRootScope(),
+                    wakeAt: work.schedule.wakeAt,
+                });
+                const settled = recordScheduled(this.requireStateMachine(), work.schedule.stateName, work.schedule.wakeAt);
+                this.setStateMachine(settled.session);
+                return settled.outcome;
+            }
+            const now = this.clock.now();
+            const startedAt = this.stateMachine?.progress?.states[work.schedule.stateName]?.startedAt;
+            const settled = recordSettled(this.requireStateMachine(), work.schedule.stateName, "timer", {
+                type: "completed",
+                output: {
+                    elapsedMs: startedAt === undefined ? 0 : Math.max(0, now - startedAt),
+                    timestamp: now,
+                },
+            }, undefined, now);
+            this.setStateMachine(settled.session);
+            return settled.outcome;
+        }
+        if ("park" in work)
+            return undefined;
+        if ("subagent" in work.run) {
+            this.startSubagentTask(work.run.subagent, work.run.stateName);
+        }
+        else {
+            this.startShellTask(work.run.shell, work.run.stateName, work.run.pollPolicy);
         }
         return undefined;
     }
+    startSubagentTask(spec, stateName) {
+        const ownerScopeId = this.requireRootScope();
+        const handle = this.taskManager.start({
+            kind: "subagent",
+            name: stateName,
+            label: `Run state ${stateName}`,
+            ownerScopeId,
+            execute: async ({ signal, taskId }) => {
+                const run = this.createStateSubagentRun({
+                    state: { kind: "agent", name: stateName, ...spec },
+                    prompt: spec.prompt,
+                    origin: { taskId },
+                });
+                const metadata = this.stateTasks.get(taskId);
+                if (metadata?.kind === "agent")
+                    metadata.run = run;
+                const interrupt = () => run.interrupt(String(signal.reason ?? "Interrupted"));
+                if (signal.aborted)
+                    interrupt();
+                signal.addEventListener("abort", interrupt, { once: true });
+                try {
+                    return await run.prompt();
+                }
+                finally {
+                    signal.removeEventListener("abort", interrupt);
+                }
+            },
+        });
+        this.stateTasks.set(handle.id, { kind: "agent", stateName });
+    }
+    startShellTask(spec, stateName, pollPolicy) {
+        const shell = createShellStateHandle({
+            command: spec.command,
+            cwd: resolveStateCwd(spec.cwd, this.config.cwd ?? process.cwd()),
+            timeoutMs: spec.timeoutMs,
+            successCodes: spec.successCodes,
+        });
+        let taskId;
+        let finish;
+        const finishedPromise = new Promise((resolve) => {
+            finish = resolve;
+        });
+        // Stop semantics are uniform across executors: process groups die by SIGKILL
+        // immediately (matching pi-bash), so the interrupted terminal is never gated
+        // on a grace window. Graceful TERM cleanup, if ever needed, is a future
+        // explicit opt-in, not a blanket default.
+        const unregisterReaper = this.taskManager.registerReaper(async (reason) => {
+            shell.interrupt(reason);
+            await finishedPromise;
+        });
+        const handle = this.taskManager.start({
+            kind: "tool",
+            name: stateName,
+            label: `Run state ${stateName}`,
+            ownerScopeId: this.requireRootScope(),
+            execute: async ({ signal, onOutput }) => {
+                const interrupt = () => shell.interrupt(String(signal.reason ?? "Interrupted"));
+                signal.addEventListener("abort", interrupt, { once: true });
+                try {
+                    const output = await shell.run();
+                    onOutput(output.stdout);
+                    return { type: "completed", output };
+                }
+                catch (error) {
+                    const reason = shell.interruptedReason();
+                    if (reason !== undefined)
+                        return { type: "interrupted", reason };
+                    return {
+                        type: "failed",
+                        error: error instanceof Error ? error.message : String(error),
+                    };
+                }
+                finally {
+                    signal.removeEventListener("abort", interrupt);
+                    finish();
+                    unregisterReaper();
+                }
+            },
+        });
+        taskId = handle.id;
+        this.stateTasks.set(taskId, {
+            kind: pollPolicy ? "poll" : "script",
+            stateName,
+            shell,
+            ...(pollPolicy ? { pollPolicy } : {}),
+        });
+    }
+    async recordTaskSettlements(settlements) {
+        let latest;
+        for (const settlement of settlements) {
+            if (this.ignoredTaskSettlements.delete(settlement.id)) {
+                this.stateTasks.delete(settlement.id);
+                continue;
+            }
+            const metadata = this.stateTasks.get(settlement.id);
+            if (!metadata)
+                continue;
+            this.stateTasks.delete(settlement.id);
+            const result = this.stateResultFromSettlement(settlement);
+            const recorded = recordSettled(this.requireStateMachine(), metadata.stateName, metadata.kind, result, this.partialStateOutput(metadata), this.clock.now());
+            this.setStateMachine(recorded.session);
+            latest = recorded.outcome;
+            if (latest.type === "sleep") {
+                this.taskManager.start({
+                    kind: "scheduled",
+                    name: metadata.stateName,
+                    label: `Wait for ${metadata.stateName}`,
+                    ownerScopeId: this.requireRootScope(),
+                    wakeAt: latest.wakeAt,
+                });
+            }
+        }
+        return latest;
+    }
+    async processTaskSettlements(settlements) {
+        const stateSettlements = settlements.filter((settlement) => this.stateTasks.has(settlement.id) || this.ignoredTaskSettlements.has(settlement.id));
+        const taskSettlements = settlements.filter((settlement) => !stateSettlements.includes(settlement));
+        const stateOutcome = await this.recordTaskSettlements(stateSettlements);
+        if (taskSettlements.length === 0)
+            return stateOutcome;
+        if (stateOutcome) {
+            this.parentInputs.unshift({ type: "task_settlements", settlements: taskSettlements });
+            return stateOutcome;
+        }
+        const snapshots = taskSettlements
+            .map((settlement) => this.taskManager.output(settlement.id))
+            .filter((snapshot) => snapshot !== undefined);
+        if (snapshots.length === 0)
+            return stateOutcome;
+        const worker = await this.runParentPass({
+            state: this.snapshotState({ ...this.requireRunnerState(), status: "running" }),
+            prompt: settlementNotice(snapshots),
+            continuation: true,
+        });
+        this.setState(worker.outcome.state);
+        if (worker.outcome.type === "interrupted")
+            return { type: "interrupted" };
+        if (worker.control.type === "ask_user_question") {
+            return { type: "ask", questions: worker.control.questions };
+        }
+        if (this.requireRunnerState().mode !== "agent") {
+            const controlled = await this.stateMachineResultFromWorker(worker, worker.outcome.state);
+            if (controlled)
+                return controlled;
+        }
+        return worker.outcome.status === "failed"
+            ? { type: "terminal", status: "error", error: worker.outcome.error }
+            : { type: "terminal", status: "completed", result: worker.outcome.result };
+    }
+    stateResultFromSettlement(settlement) {
+        if (settlement.status === "completed") {
+            return settlement.result;
+        }
+        if (settlement.status === "stopped") {
+            return { type: "interrupted", reason: settlement.reason };
+        }
+        return {
+            type: "failed",
+            error: settlement.status === "failed"
+                ? settlement.error instanceof Error
+                    ? settlement.error.message
+                    : String(settlement.error)
+                : `Task ${settlement.id} was lost.`,
+        };
+    }
+    partialStateOutput(metadata) {
+        if (metadata.kind === "agent") {
+            const assistantText = metadata.run?.partialAssistantText();
+            return assistantText ? { assistantText } : undefined;
+        }
+        return metadata.shell.partialOutput();
+    }
+    async interruptTasks(reason) {
+        for (const [id, metadata] of this.stateTasks) {
+            if (this.taskManager.output(id)?.descriptor.status !== "running")
+                continue;
+            const recorded = recordSettled(this.requireStateMachine(), metadata.stateName, metadata.kind, { type: "interrupted", reason }, this.partialStateOutput(metadata), this.clock.now());
+            this.setStateMachine(recorded.session);
+            this.ignoredTaskSettlements.add(id);
+        }
+        await this.taskManager.interruptAll(reason);
+    }
+    async cancelScheduledTasks(reason) {
+        const scheduled = this.taskManager.list().filter((task) => task.status === "scheduled");
+        for (const task of scheduled)
+            this.ignoredTaskSettlements.add(task.id);
+        await Promise.all(scheduled.map((task) => this.taskManager.stop(task.id, reason)));
+    }
     /**
      * Build a loop-warning system reminder when the orchestrator has selected the
      * same state many times in a row within a short window with no other state
      * running in between. This is the idle-"holding" hot loop: re-selecting a
      * state to "keep waiting" is a no-op because selecting runs the state again
      * immediately rather than suspending. The reminder re-teaches the only
-     * primitives that actually wait — ask_user_question for a human reply, a poll
+     * primitives that actually wait — park for a parent-owned human gate, a poll
      * for a checkable condition, a timer for a fixed time — and tells the parent
      * to stop re-selecting the same state unchanged. Returns undefined when the
      * streak is below threshold or spread over too long a span to be a hot loop.
      */
     repeatedSelectionLoopWarning(stateName) {
-        const session = this.stateMachineController.getSession();
+        const session = this.stateMachine;
         const count = session ? repeatedSelectionLoopCount(session, stateName) : undefined;
         if (count === undefined)
             return undefined;
@@ -885,7 +1301,7 @@ export class TurnRunner {
       LOOP DETECTED: you have selected the "${stateName}" state ${count} times in a row, with no other state running in between, in quick succession. Selecting a state is NOT how you wait — every select_state_machine_state call runs the state again immediately and returns, so re-selecting the same "holding" state over and over is a no-op hot loop that suspends nothing.
 
       If you are waiting on something, back it with the primitive that actually suspends, chosen by WHAT you are waiting for:
-      - a human reply or approval → an agent state that calls ask_user_question, then END YOUR TURN. The user's answer arrives as a fresh turn, and only then do you select the next state. Do not re-select to "keep waiting", and if the user sends an unrelated message while the question is open, answer it in plain text and end the turn rather than re-parking this state.
+      - a human reply or approval → select a park state, ask the user yourself with ask_user_question, then END YOUR TURN. The user's answer arrives as a fresh parent turn; select the next state when the park's purpose is fulfilled.
       - a condition a command can check (CI finished, a file appeared, a deploy went ready) → a poll state whose command exits success only when the condition is actually met.
       - a fixed future time → a timer state (wakeAt or wakeAfterMs).
 
@@ -895,7 +1311,7 @@ export class TurnRunner {
     }
     async selectNextStateAfterCompletion(stateName, output) {
         const loopWarning = this.repeatedSelectionLoopWarning(stateName);
-        return this.enforceParentTransition((retryInstruction) => dedent `
+        return this.enforceParentTransition((retryInstruction) => systemReminder(dedent `
         The state "${stateName}" finished.
 
         ${toXML({
@@ -917,38 +1333,16 @@ export class TurnRunner {
 
         CARRY FORWARD BEFORE YOU SELECT. The next state runs in a fresh sub-agent that cannot see this state_completed output, your reasoning, or your reply text — the ONLY thing it receives is the \`input\` and \`override.prompt\` you pass in the select call. So if the next state's job depends on anything this state just produced (a root cause, file path, diagnosis, ID, count, decision), inline those exact facts into the select's \`input\`/\`override.prompt\` on the FIRST transition into it. Do not select it bare and let it come back confused, then add the context on a retry — a select that advances to a finding-dependent state carrying none of the finding is already wrong, even with the right state name. Summarizing the finding in your message to the user does not carry it forward.
         </system-reminder>
-      `, "State completed, but the runner did not call select_state_machine_state.");
-    }
-    /**
-     * Enforce the transition owed after an agent state asked the user a question
-     * and the user answered without the parent advancing the machine.
-     *
-     * The user's answer already ran as an ordinary parent prompt; reaching here
-     * means that turn emitted no `select_state_machine_state`, so the machine is
-     * still suspended at the asking state. Re-prompt under the same bounded
-     * budget as a completed state, then record an `error` terminal if the parent
-     * still refuses to advance.
-     */
-    async enforceTransitionAfterAnsweredAsk() {
-        const stateName = this.stateMachineController.getSession()?.currentState ?? "";
-        return this.enforceParentTransition((retryInstruction) => dedent `
-        You received the user's answer to the question asked by the "${stateName}" state, but you did not call select_state_machine_state. The machine is still suspended at that state and will not advance on its own.
-
-        <system-reminder>
-        THIS TURN MUST END WITH A select_state_machine_state TOOL CALL. The user's answer is the input you route on: pick the next state (or a terminal, including a cancelled terminal if the answer means the work should stop) and pass the answer forward via input or override.prompt. Narration without the tool call ("the user chose X, so I'll move to Y") does not advance the machine and will be rejected and re-prompted.
-
-        ${retryInstruction ?? ""}
-        </system-reminder>
-      `, "User answered the question, but the runner did not call select_state_machine_state.");
+      `), "State completed, but the runner did not call select_state_machine_state.");
     }
     /**
      * Shared bounded-retry loop for transitions the parent owes the machine.
      * Re-prompts up to `PARENT_TRANSITION_RETRY_BUDGET` times with `buildPrompt`
-     * (the second and later attempts carry a retry reminder); the first attempt
-     * that emits a control action returns its result. When the budget is
-     * exhausted with no control action, records an `error` terminal carrying
-     * `failureReason` — a runtime failure of the machine, not a deliberate
-     * `failed` selection.
+     * (the second and later attempts carry a retry reminder); the first accepted
+     * selection ends enforcement, with an immediate outcome only for synchronous
+     * work. When the budget is exhausted with no control action, records an
+     * `error` terminal carrying `failureReason` — a runtime failure of the
+     * machine, not a deliberate `failed` selection.
      */
     async enforceParentTransition(buildPrompt, failureReason) {
         for (let attempt = 1; attempt <= PARENT_TRANSITION_RETRY_BUDGET; attempt++) {
@@ -956,162 +1350,82 @@ export class TurnRunner {
                 ? undefined
                 : `This is retry ${attempt} of ${PARENT_TRANSITION_RETRY_BUDGET}. You did not call select_state_machine_state last time. You must call select_state_machine_state now.`;
             const turnState = this.snapshotState({ ...this.requireRunnerState(), status: "running" });
-            const workerResult = await this.runAgentWorker({
+            const workerResult = await this.runParentPass({
                 state: turnState,
                 prompt: buildPrompt(retryInstruction),
-                ...this.createTools(turnState.mode),
+                continuation: true,
             });
             this.setState(workerResult.outcome.state);
-            const result = await this.controllerResultFromWorkerResult(workerResult, workerResult.outcome.state);
+            const result = await this.stateMachineResultFromWorker(workerResult, workerResult.outcome.state);
             if (result)
                 return result;
+            // Starting an asynchronous state has no immediate outcome. The select
+            // control itself proves the transition obligation was satisfied.
+            if (workerResult.control.type === "select_state_machine_state")
+                return undefined;
         }
-        return this.stateMachineController.failActiveSession(this.stateMachineController.getSession()?.currentState ?? "", failureReason);
-    }
-    createStateAgentHandle(input) {
-        let control = { type: "none" };
-        const seedMessages = this.resolveStateAgentSeedMessages(input.state);
-        // Capture the seeded prefix length up front. The sub-agent's result,
-        // partial text, and recorded usage are all computed by slicing this prefix
-        // off agent.state.messages so a forked parent transcript isn't folded into
-        // this run. Reading `seedMessages.length` lazily at each call site would be
-        // wrong if the agent ever appended into the seed array in place, so snapshot
-        // the count once.
-        const seedMessageCount = seedMessages.length;
-        const state = {
-            status: "running",
-            mode: "agent",
-            // Layer the agent state's optional per-state model/thinkingLevel over the
-            // inherited parent options; see StateMachineAgentState for why these are
-            // UI-set rather than model-chosen.
-            options: {
-                ...this.requireRunnerState().options,
-                ...(input.state.model ? { model: input.state.model } : {}),
-                ...(input.state.thinkingLevel ? { thinkingLevel: input.state.thinkingLevel } : {}),
-            },
-            agent: {
-                status: "running",
-                messages: seedMessages,
-            },
+        const failed = failActiveSession(this.requireStateMachine(), this.stateMachine?.currentState ?? "", failureReason);
+        this.setStateMachine(failed.session);
+        return failed.outcome;
+    }
+    createStateSubagentRun(input) {
+        const spec = {
+            prompt: input.prompt,
+            ...(input.state.systemPrompt ? { systemPrompt: input.state.systemPrompt } : {}),
+            ...(input.state.allowedSkills ? { allowedSkills: input.state.allowedSkills } : {}),
+            ...(input.state.cwd ? { cwd: input.state.cwd } : {}),
+            ...(input.state.model ? { model: input.state.model } : {}),
+            ...(input.state.thinkingLevel ? { thinkingLevel: input.state.thinkingLevel } : {}),
+            ...(input.state.forkContext ? { forkContext: true } : {}),
         };
-        const stateSkills = this.skillContext.resolveStateAgentSkills(input.state);
-        // Expand `/skill` slash commands the same way the parent prompt path does,
-        // scoped to the skills this state is actually allowed to use. Lets state
-        // prompts say "use the /foo skill to do xyz" and have the skill body
-        // injected, instead of shipping the literal `/foo` text to the model.
-        const expandedPrompt = this.skillContext.resolveSlashSkillPrompt(input.prompt, stateSkills);
-        // Hand the sub-agent the machine's overall goal, the full state list, and
-        // which state it is running so it scopes its work to this state instead of
-        // running the whole process (a common over-reach on smaller models). The
-        // session always exists while an agent state is executing.
-        const session = this.stateMachineController.getSession();
+        const session = this.stateMachine;
         const machineContext = session
             ? { definition: session.definition, currentState: input.state.name }
             : undefined;
-        const forkContext = input.state.forkContext === true;
-        const identityLayer = createStateAgentSystemPromptLayer(machineContext);
-        // When forking, the sub-agent's identity + per-state systemPrompt layers
-        // ride in the tail user turn so the system prompt can stay byte-identical to
-        // the parent's and preserve the provider prompt-cache prefix. There is one
-        // exception: a state that restricts skills via allowedSkills must NOT inherit
-        // the parent's full skill catalog. resolveStateAgentSkills returns undefined
-        // only for an unrestricted state; when it returns a concrete allowlist we
-        // rebuild the system prompt around that allowlist instead of reusing the
-        // parent's verbatim, trading the cache prefix for the allowlist contract.
-        const forkSystemPrompt = forkContext
-            ? stateSkills === undefined
-                ? this.parentAgent?.state.systemPrompt
-                : this.createBaseSystemPromptWithAppendedLayers({ skills: stateSkills })
-            : undefined;
-        const tailPrompt = forkContext
-            ? [createForkContextReminder(), identityLayer, input.state.systemPrompt, expandedPrompt]
-                .filter((part) => Boolean(part))
-                .join("\n\n")
-            : expandedPrompt;
-        const agent = this.createAgent({
-            state,
-            ...(forkSystemPrompt ? { systemPrompt: forkSystemPrompt } : {}),
-            prependSystemPrompt: forkContext ? undefined : identityLayer,
-            appendSystemPrompt: forkContext ? undefined : input.state.systemPrompt,
-            skills: stateSkills,
-            // Per-state cwd lets one agent state operate on a different
-            // repository or subdirectory than the parent runner without
-            // mutating shared config.
-            ...this.createTools("agent", input.state.cwd),
-        }, (result) => {
-            control = result;
+        return this.subagentExecutor(spec, {
+            origin: input.origin,
+            ...(machineContext ? { machineContext } : {}),
         });
-        let unsubscribe;
-        let interruptedReason;
-        const finish = () => {
-            if (control.type === "ask_user_question") {
-                return { type: "ask", questions: control.questions };
-            }
-            if (agent.state.errorMessage) {
-                return { type: "failed", error: agent.state.errorMessage };
-            }
-            return {
-                type: "complete",
-                result: assistantText(agent.state.messages.slice(seedMessageCount)),
-            };
-        };
-        const origin = {
-            kind: "state_machine_agent",
-            state: input.state.name,
-        };
-        // A state agent runs a turn just like the parent — a loop of completion
-        // calls — so it streams a `usage` event per completion from its own
-        // `message_end` events. The finally block falls back to summing the whole
-        // message list only when no `message_end` fired (stubbed-agent test path).
-        let recordedMessageUsage = false;
-        return {
-            prompt: async () => {
-                unsubscribe = agent.subscribe((event) => {
-                    this.emitAgentEvent(event, origin);
-                    if (event.type !== "message_end" || event.message.role !== "assistant")
-                        return;
-                    // Record always; tick only on a completion that consumed tokens (see
-                    // the parent path for why a zero-usage attempt must not emit).
-                    this.recordUsage(event.message.usage, agent.state.model.id);
-                    recordedMessageUsage = true;
-                    if (event.message.usage.totalTokens > 0)
-                        this.emitTurnUsage(origin);
-                });
-                try {
-                    await agent.prompt(tailPrompt);
-                    await this.retryTransientServerErrors(agent);
-                    return interruptedReason ? { type: "interrupted" } : finish();
-                }
-                catch (error) {
-                    if (interruptedReason)
-                        return { type: "interrupted" };
-                    if (error instanceof Error)
-                        return { type: "failed", error: error.message };
-                    return { type: "failed", error: String(error) };
-                }
-                finally {
-                    // Fallback for the stubbed-agent path: when no `message_end` streamed,
-                    // fold the message list's usage in on every exit path — success,
-                    // error, or interrupt — so partial work still reaches the aggregate.
-                    // Slice off the seeded prefix so a forked parent transcript's usage
-                    // isn't double-counted (parent messages may already carry usage from
-                    // the parent turn).
-                    if (!recordedMessageUsage) {
-                        this.recordUsage(usageFromMessages(agent.state.messages.slice(seedMessageCount)), agent.state.model.id);
-                        this.emitTurnUsage(origin);
-                    }
-                    unsubscribe?.();
-                }
-            },
-            interrupt: (reason) => {
-                interruptedReason = reason;
-                agent.abort();
-                agent.clearAllQueues();
-                unsubscribe?.();
+    }
+    /** Build a public spawn only after TaskManager has allocated its identity and child scope. */
+    async createSpawnedSubagentRun(publicSpec, taskId, ownerScopeId, childScopeId, forkSource, callerModelSetting) {
+        const parentSetting = callerModelSetting ??
+            this.requireRunnerState().options?.model ??
+            this.config.model ??
+            DEFAULT_CLI_MODEL;
+        const selection = await this.selectSpawnModel(publicSpec.prompt, parentSetting);
+        const memorySessionId = this.config.sessionId
+            ? `${this.config.sessionId}:sub:${taskId}`
+            : undefined;
+        return this.subagentExecutor({
+            ...publicSpec,
+            model: selection.modelName,
+            ...(selection.thinkingLevel ? { thinkingLevel: selection.thinkingLevel } : {}),
+        }, {
+            origin: { taskId },
+            childScopeId,
+            ownerScopeId,
+            memoryContext: {
+                ...(memorySessionId ? { sessionId: memorySessionId } : {}),
+                horizon: createInitialHorizon(),
             },
-            partialAssistantText: () => assistantText(agent.state.messages.slice(seedMessageCount)) || undefined,
-            interruptedReason: () => interruptedReason,
-        };
+            ...(forkSource ? { forkSource } : {}),
+        });
+    }
+    /** Stateless spawn classifier seam; deliberately never consults the session ModelRouter. */
+    async selectSpawnModel(prompt, parentSetting) {
+        const table = this.routingTable ?? BUILT_IN_ROUTING_TABLE;
+        return classifySpawnModel(prompt, parentSetting, {
+            table,
+            resolveCatalog: routingCatalogAdapter,
+            classifierOptions: this.classifierOptions(table),
+        });
+    }
+    async dropSubagentScratch(taskId) {
+        const session = this.memoryPersistence?.session;
+        if (!session || !this.config.sessionId)
+            return;
+        await replaceSessionObservations(session, `${this.config.sessionId}:sub:${taskId}`, []);
     }
     requireRunnerState() {
         if (!this.state) {
@@ -1119,10 +1433,75 @@ export class TurnRunner {
         }
         return this.state;
     }
-    resolveStateAgentSeedMessages(state) {
-        if (!state.forkContext)
-            return [];
-        return [...(this.parentAgent?.state.messages ?? [])];
+    requireStateMachine() {
+        if (!this.stateMachine)
+            throw new Error("No state machine is active.");
+        return this.stateMachine;
+    }
+    /** Protected so test probes can supply a scope when driving tools outside a turn. */
+    requireRootScope() {
+        if (!this.activeRootScopeId)
+            throw new Error("No turn root scope is active.");
+        return this.activeRootScopeId;
+    }
+    setStateMachine(session, notify = false) {
+        this.stateMachine = session;
+        if (notify)
+            this.emit({ type: "state_machine", stateMachine: session });
+    }
+    getActiveStateOutput() {
+        for (const [id, metadata] of this.stateTasks) {
+            if (this.taskManager.output(id)?.descriptor.status !== "running")
+                continue;
+            if (metadata.kind === "agent") {
+                const assistantText = metadata.run?.partialAssistantText();
+                return assistantText
+                    ? { state: metadata.stateName, kind: "agent", output: { assistantText } }
+                    : { state: metadata.stateName, kind: "agent" };
+            }
+            const output = metadata.shell.partialOutput();
+            return output
+                ? { state: metadata.stateName, kind: metadata.kind, output }
+                : { state: metadata.stateName, kind: metadata.kind };
+        }
+        return undefined;
+    }
+    captureParentControlResult(result) {
+        if (result.type === "none")
+            return;
+        if (this.parentControlResults.length > 0) {
+            throw new Error("A parent pass produced more than one control result.");
+        }
+        this.parentControlResults.push(result);
+    }
+    consumeParentControlResult() {
+        const result = this.parentControlResults.shift() ?? { type: "none" };
+        if (this.parentControlResults.length > 0) {
+            throw new Error("A parent pass produced more than one control result.");
+        }
+        return result;
+    }
+    attachTurnUsage(terminal) {
+        if (!this.turnUsage)
+            return terminal;
+        return {
+            ...terminal,
+            turnUsage: this.turnUsage,
+            usageByModel: this.turnUsageByModel ?? [],
+            ...(this.lastParentUsageSnapshot
+                ? {
+                    effectiveContextWindow: this.lastParentUsageSnapshot.effectiveContextWindow,
+                    contextWindowUsage: this.lastParentUsageSnapshot.contextWindowUsage,
+                    lastMessageUsage: this.lastParentUsageSnapshot.lastMessageUsage,
+                }
+                : {}),
+        };
+    }
+    emitTerminalOnce(terminal) {
+        if (this.terminalEmitted)
+            return;
+        this.terminalEmitted = true;
+        this.emit(terminal);
     }
     getState() {
         if (!this.state)
@@ -1140,10 +1519,18 @@ export class TurnRunner {
         const snapshot = {
             ...state,
             agent: parentAgent,
-            stateMachine: this.stateMachineController.getSession(),
+            stateMachine: this.stateMachine,
             todos: copyOptionalArray(state.todos ?? this.state?.todos),
             followUpQueue: copyOptionalArray(state.followUpQueue ?? this.state?.followUpQueue),
-            queuedCommands: copyOptionalArray(state.queuedCommands ?? this.state?.queuedCommands),
+            queuedCommands: this.activeRootScopeId !== undefined
+                ? this.parentInputs
+                    .filter((input) => input.type === "user_command")
+                    .map((input) => input.command)
+                : (this.hydratedQueuedCommands ??
+                    copyOptionalArray(state.queuedCommands ?? this.state?.queuedCommands)),
+            tasks: [...this.taskManager.list()],
+            taskOutputTails: this.snapshotTaskOutputTails(),
+            nextTaskId: this.taskManager.nextTaskId(),
             // Carry wire-shaping state through every snapshot so persistence
             // layers (state.json, terminal payloads, getState consumers) see
             // the current value. Copy by spread so consumers can't mutate the
@@ -1157,6 +1544,16 @@ export class TurnRunner {
         };
         return this.applyAutoStateCompaction(snapshot);
     }
+    snapshotTaskOutputTails() {
+        const tails = {};
+        for (const descriptor of this.taskManager.list()) {
+            const output = this.taskManager.output(descriptor.id)?.output;
+            if (output && output.length > 0) {
+                tails[descriptor.id] = output.slice(-3).map((chunk) => chunk.slice(-1_500));
+            }
+        }
+        return Object.keys(tails).length > 0 ? tails : undefined;
+    }
     /**
      * Caps the size of every state that leaves the runner via emit/return/
      * getState. Runs only when `TurnRunnerConfig.autoStateCompaction` is
@@ -1200,20 +1597,6 @@ export class TurnRunner {
             return;
         this.setState({ ...this.state, followUpQueue: [...entries] });
     }
-    getQueuedCommands() {
-        return [...(this.state?.queuedCommands ?? [])];
-    }
-    setQueuedCommands(commands) {
-        if (!this.state)
-            return;
-        this.setState({ ...this.state, queuedCommands: [...commands] });
-    }
-    shiftQueuedCommand() {
-        const commands = this.getQueuedCommands();
-        const [command, ...remaining] = commands;
-        this.setQueuedCommands(remaining);
-        return command;
-    }
     getTodos() {
         return [...(this.state?.todos ?? [])];
     }
@@ -1268,53 +1651,28 @@ export class TurnRunner {
                 ? undefined
                 : createStateMachineSystemPromptLayer({ mode: state.mode, session: state }),
             this.config.memoryDbPath !== undefined ? createRecallMemorySystemPromptLayer() : undefined,
+            // Advisor timing guidance ships with the tool: description-only
+            // steering measurably under-triggers consults on hard tasks.
+            this.advisorPolicy?.enabled ? ADVISOR_EXECUTOR_GUIDANCE_LAYER : undefined,
             // Source-of-truth-first guidance always applies: even without
             // configured memory, the agent should still prefer live tools,
             // skills, and files in cwd over guessed answers.
             createSourceOfTruthSystemPromptLayer(),
         ].filter((layer) => Boolean(layer));
         const appendSystemPrompt = layers.length > 0 ? layers.join("\n\n") : undefined;
-        this.parentControlResult = { type: "none" };
+        this.parentControlResults.length = 0;
         this.parentAgent = this.createAgent({
             state,
             appendSystemPrompt,
+            parentModelRouting: true,
+            ...(this.modelRouter ? { router: this.modelRouter } : {}),
             ...this.createTools(state.mode),
         }, (result) => {
-            this.parentControlResult = result;
+            this.captureParentControlResult(result);
         });
-        this.replayFollowUpQueueIntoAgent(this.parentAgent);
         this.snapshotActiveAgentState();
     }
-    async runTurnRunnerAgentWithStateMachineTools(input) {
-        const workerResult = await this.runAgentWorker({
-            state: input.state,
-            prompt: input.prompt,
-            images: input.images,
-        });
-        const result = await this.controllerResultFromWorkerResult(workerResult, input.state);
-        if (result)
-            return this.driveStateMachineResult(result, workerResult.outcome.state);
-        // The parent emitted no control action. If the machine is suspended at a
-        // state that asked the user a question, the parent owed a transition to
-        // advance it (the user's answer arrives as an ordinary parent prompt).
-        // Enforce it the same way a completed state does, so an answered ask can
-        // never silently stall the machine.
-        if (isAwaitingUserAnswer(this.stateMachineController.getSession())) {
-            const enforced = await this.enforceTransitionAfterAnsweredAsk();
-            return this.driveStateMachineResult(enforced, this.requireRunnerState());
-        }
-        return this.outcomeToTerminal(workerResult.outcome);
-    }
-    /**
-     * Turns a parent worker turn's control output into the state-machine
-     * execution result the turn runner should drive next, or `undefined` when
-     * the parent emitted no control tool call. Whether that `undefined` is
-     * benign (a top-level agent turn just answering) or a violation (it owed a
-     * select_state_machine_state) is the caller's decision. A valid control
-     * action — select a state, ask the user, or create a machine (including a
-     * replaceActive reset of an active machine) — returns its result.
-     */
-    async controllerResultFromWorkerResult(workerResult, state) {
+    async stateMachineResultFromWorker(workerResult, state) {
         const control = workerResult.control;
         if (control.type === "none")
             return undefined;
@@ -1327,28 +1685,45 @@ export class TurnRunner {
             // replaceActive. So an active, non-terminal session at this point means
             // the agent deliberately chose to replace it — supersede it (recording a
             // `cancelled` terminal) before installing the new machine in its place.
-            const active = this.stateMachineController.getSession();
+            const active = this.stateMachine;
             if (active && !active.terminal) {
-                this.stateMachineController.supersedeActiveSession(`Superseded by a new state machine ("${control.definition.name}").`);
+                await this.replaceActiveStateTasks("Replaced by a new state machine.");
+                this.setStateMachine(supersede(active, `Superseded by a new state machine ("${control.definition.name}").`), true);
             }
             const firstState = control.firstState;
-            this.stateMachineController.startSession({
+            this.setStateMachine(startStateMachineSession({
                 prompt: workerResult.outcome.type === "complete" ? (workerResult.outcome.result ?? "") : "",
                 definition: control.definition,
                 currentState: firstState,
-            });
-            return this.stateMachineController.runDecision({ state: firstState });
+            }));
+            return this.runStateMachineDecision({ state: firstState });
         }
-        if (!this.stateMachineController.getSession() && typeof state.mode === "object") {
-            this.stateMachineController.startSession({
+        if (!this.stateMachine && typeof state.mode === "object") {
+            this.setStateMachine(startStateMachineSession({
                 prompt: workerResult.outcome.type === "complete" ? (workerResult.outcome.result ?? "") : "",
                 definition: state.mode,
                 currentState: control.decision.state,
-            });
+            }));
+        }
+        return this.runStateMachineDecision(control.decision);
+    }
+    async runStateMachineDecision(decision) {
+        await this.replaceActiveStateTasks("Replaced by a newly selected state.");
+        await this.cancelScheduledTasks("Replaced by a newly selected state.");
+        const planned = planDecision(this.requireStateMachine(), decision, this.clock.now());
+        this.setStateMachine(planned.session, true);
+        return this.executePlannedWork(planned.work);
+    }
+    async replaceActiveStateTasks(reason) {
+        const active = [...this.stateTasks.entries()].filter(([id]) => this.taskManager.output(id)?.descriptor.status === "running");
+        for (const [id, metadata] of active) {
+            const recorded = recordSettled(this.requireStateMachine(), metadata.stateName, metadata.kind, { type: "interrupted", reason }, this.partialStateOutput(metadata), this.clock.now());
+            this.setStateMachine(recorded.session);
+            this.ignoredTaskSettlements.add(id);
         }
-        return this.stateMachineController.runDecision(control.decision);
+        await Promise.all(active.map(([id]) => this.taskManager.stop(id, reason)));
     }
-    createTools(mode, cwdOverride) {
+    createTools(mode, cwdOverride, includeParentTools = true, childContext) {
         const cwd = resolveStateCwd(cwdOverride, this.config.cwd ?? process.cwd());
         const todoStorage = {
             getTodos: () => this.getTodos(),
@@ -1362,58 +1737,146 @@ export class TurnRunner {
         const recallStorage = {
             getSession: () => this.memoryPersistence?.session,
             embed: this.memoryPersistence?.embed,
-            sessionId: this.config.sessionId,
+            sessionId: childContext?.memorySessionId ?? this.config.sessionId,
             // Reuse the resolved memory model so recall_memory's optional
             // expand flag goes to the same cheap model the observer uses.
             expansionModel: this.resolveMemoryActorModel(undefined),
         };
-        if (mode === "agent") {
-            return {
-                tools: [...createDefaultTurnRunnerTools(cwd, todoStorage, recallStorage), ...mcpTools],
-            };
-        }
+        const router = this.modelRouter;
+        const advisorStorage = includeParentTools && router && this.advisorPolicy?.enabled
+            ? this.createAskAdvisorStorage(router, this.advisorPolicy)
+            : undefined;
+        const baseTools = mode === "agent"
+            ? createDefaultTurnRunnerTools(cwd, todoStorage, recallStorage, advisorStorage)
+            : createTurnRunnerTools({
+                cwd,
+                mode,
+                getDefinition: () => this.stateMachine?.definition,
+                getStateMachine: () => this.stateMachine,
+                getActiveStateOutput: () => this.getActiveStateOutput(),
+                todoStorage,
+                skills,
+                recallStorage,
+                advisorStorage,
+                clock: this.clock,
+                minimumScheduledDelayMs: this.minimumScheduledDelayMs,
+            });
+        const childSafeTools = includeParentTools
+            ? baseTools
+            : baseTools.filter((tool) => tool.name !== "ask_user_question");
+        const taskAwareTools = childSafeTools.map((tool) => tool.name === "bash"
+            ? wrapBackgroundable(tool, {
+                taskManager: this.taskManager,
+                defaultWaitBudgetMs: this.taskWaitBudgetMs,
+                clock: this.clock,
+                ownerScopeId: () => childContext?.ownerScopeId ?? this.requireRootScope(),
+                label: (params) => String(params.command ?? "bash command"),
+                onTaskStarted: (id, foregroundPending) => {
+                    this.taskSettlementDelivery.set(id, foregroundPending ? "foreground_pending" : "deliver");
+                },
+                onForegroundResult: (id, converted) => {
+                    this.taskSettlementDelivery.set(id, converted ? "deliver" : "suppress");
+                    this.scheduleSettlementDelivery();
+                },
+            })
+            : tool);
         return {
             tools: [
-                ...createTurnRunnerTools({
-                    cwd,
-                    mode,
-                    getDefinition: () => this.stateMachineController.getSession()?.definition,
-                    getStateMachine: () => this.stateMachineController.getSession(),
-                    getActiveStateOutput: () => this.stateMachineController.getActiveOutput(),
-                    todoStorage,
-                    skills,
-                    recallStorage,
-                }),
+                ...taskAwareTools,
+                ...(includeParentTools || childContext
+                    ? [
+                        this.createSpawnTool(childContext),
+                        ...createTaskAdminTools({ taskManager: this.taskManager, clock: this.clock }),
+                    ]
+                    : []),
                 ...mcpTools,
             ],
         };
     }
-    replayFollowUpQueueIntoAgent(agent) {
-        for (const entry of this.getFollowUpQueue()) {
-            agent.followUp(buildUserAgentMessage(entry.message, entry.images));
-        }
-    }
-    async runAgentMode(state, prompt, images) {
-        const workerResult = await this.runAgentWorker({
-            state,
-            prompt,
-            images,
+    createSpawnTool(childContext) {
+        const ownerScopeId = () => childContext?.ownerScopeId ?? this.requireRootScope();
+        return createSpawnAgentTool({
+            taskManager: this.taskManager,
+            defaultWaitBudgetMs: this.taskWaitBudgetMs,
+            clock: this.clock,
+            ownerScopeId,
+            createRun: async ({ spec, taskId, ownerScopeId: callerScopeId, childScopeId }) => this.createSpawnedSubagentRun(spec, taskId, callerScopeId, childScopeId, childContext?.forkSource, childContext?.modelSetting()),
+            dropScratch: async (taskId) => this.dropSubagentScratch(taskId),
+            onTaskStarted: (id, foregroundPending) => {
+                this.taskSettlementDelivery.set(id, foregroundPending ? "foreground_pending" : "deliver");
+            },
+            onForegroundResult: (id, converted) => {
+                this.taskSettlementDelivery.set(id, converted ? "deliver" : "suppress");
+                this.scheduleSettlementDelivery();
+            },
         });
-        if (workerResult.control.type === "ask_user_question") {
-            return this.askUserQuestion(workerResult.outcome.state, workerResult.control);
-        }
-        return this.outcomeToTerminal(workerResult.outcome);
     }
-    async runAgentWorker(input) {
+    createAskAdvisorStorage(router, policy) {
+        const resolveAdvisorModel = () => resolveModelName(policy.target.modelName);
+        return {
+            getMessages: () => this.parentAgent?.state.messages ?? this.state?.agent.messages ?? [],
+            getSystemPrompt: () => this.parentAgent?.state.systemPrompt ?? "",
+            getObservations: async () => {
+                const session = this.memoryPersistence?.session;
+                const sessionId = this.config.sessionId;
+                if (!session || !sessionId)
+                    return [];
+                const snapshot = await readSessionObservations(session, sessionId);
+                return snapshot.observations.map((observation) => observation.content);
+            },
+            budgetTokens: policy.transcriptTokens,
+            modelName: () => resolveAdvisorModel().id,
+            thinkingLevel: policy.target.thinkingLevel,
+            advisorGate: () => router.beginAdvisorConsult(),
+            noteAdvisorConsult: (success = true) => router.endAdvisorConsult(success),
+            recordUsage: (usage) => {
+                const model = resolveAdvisorModel();
+                this.recordAndEmitUsage(usageFromAiSdk(usage, model), model.id);
+            },
+            onUsageError: (error) => {
+                const reason = error instanceof Error ? error.message : String(error);
+                this.emit({
+                    type: "system",
+                    level: "warn",
+                    message: `Advisor usage accounting failed; advice was retained: ${reason}`,
+                });
+            },
+        };
+    }
+    /**
+     * Pass-prep applied to EVERY parent pass, including harness overrides of
+     * `runAgentWorker` (they must call this first). One-shot reminders that must
+     * reach "whatever parent pass runs next" live here.
+     */
+    prepareParentPassInput(input) {
+        const withheldAsk = this.withheldAskQuestions;
+        this.withheldAskQuestions = undefined;
+        if (!withheldAsk)
+            return input;
+        return { ...input, prompt: `${withheldAskReminder(withheldAsk)}\n\n${input.prompt}` };
+    }
+    async runAgentWorker(rawInput) {
+        const input = this.prepareParentPassInput(rawInput);
         if (this.parentAgentRunning) {
             throw new Error("Cannot start a parent agent while another parent agent is active.");
         }
         const agent = this.requireParentAgent();
-        this.parentControlResult = { type: "none" };
+        this.applyPendingModelSelection(agent);
+        agent.state.tools = this.turnTools ?? this.createTools(input.state.mode).tools;
+        this.parentControlResults.length = 0;
         this.setParentAgentRunning(true);
         const unsubscribe = agent.subscribe((event) => this.emitParentAgentEvent(event));
         this.parentAgentInterrupted = false;
         try {
+            if (!input.continuation) {
+                this.modelRouter?.noteTurnStart({ promptHasImages: (input.images?.length ?? 0) > 0 });
+            }
+            const switched = await this.modelRouter?.prepareTurn({
+                prevTurnHint: input.prompt,
+                signal: agent.signal,
+            });
+            if (switched)
+                await this.applyRouterSwitch(agent, switched);
             await agent.prompt(input.prompt, input.images);
             // Single-shot recovery: if the provider rejected the first attempt
             // with a context-overflow error, advance the sticky wire-shaping
@@ -1439,7 +1902,7 @@ export class TurnRunner {
         }
         if (this.parentAgentInterrupted) {
             return {
-                control: this.parentControlResult,
+                control: this.consumeParentControlResult(),
                 outcome: { type: "interrupted", state: this.requireRunnerState() },
             };
         }
@@ -1456,13 +1919,11 @@ export class TurnRunner {
             },
             todos: live?.todos ?? input.state.todos,
             followUpQueue: live?.followUpQueue ?? input.state.followUpQueue,
-            queuedCommands: live?.queuedCommands ?? input.state.queuedCommands,
+            tasks: live?.tasks ?? input.state.tasks,
+            nextTaskId: live?.nextTaskId ?? input.state.nextTaskId,
         };
-        if (status === "completed") {
-            await this.updateMemoryAfterAgentRun(messages, state.options);
-        }
         return {
-            control: this.parentControlResult,
+            control: this.consumeParentControlResult(),
             outcome: {
                 type: "complete",
                 status,
@@ -1537,6 +1998,7 @@ export class TurnRunner {
             return false;
         messages.pop();
         this.wireGuardHorizon.evictionHorizon = newHorizon;
+        this.modelRouter?.noteCompaction();
         const remaining = applyEvictionHorizon(observable, newHorizon).length;
         const dropped = observable.length - remaining;
         this.emit({
@@ -1608,7 +2070,7 @@ export class TurnRunner {
             attempt = messagesAppended > 1 ? 1 : attempt + 1;
         }
     }
-    async updateMemoryAfterAgentRun(messages, options) {
+    async updateMemoryAfterAgentRun(messages, options, sessionId = this.config.sessionId, refreshReflections = true) {
         if (this.config.memoryDbPath === undefined) {
             return;
         }
@@ -1624,7 +2086,7 @@ export class TurnRunner {
         const result = await updateObservationalMemory({
             session,
             memory: this.memory,
-            sessionId: this.config.sessionId,
+            sessionId,
             effectiveContext: this.resolveEffectiveContext(this.parentAgent?.state.model.contextWindow),
             actorModel: memoryModel,
             settings: this.config.memory,
@@ -1646,7 +2108,7 @@ export class TurnRunner {
         // the new condensed view. Observer-only updates intentionally do
         // NOT refresh the pack — they leave the rendered prefix stable so
         // the provider's prompt cache survives.
-        if (result.reflections.length > 0) {
+        if (refreshReflections && result.reflections.length > 0) {
             await this.refreshMemoryContextPack();
         }
     }
@@ -1707,14 +2169,19 @@ export class TurnRunner {
     }
     createAgent(input, onControlResult) {
         const options = this.resolveTurnOptions(undefined, input.state.options);
-        const model = resolveModelName(options.model ?? DEFAULT_CLI_MODEL);
+        const initialRoute = input.router?.initialTarget({ hasImages: false });
+        const model = resolveModelName(initialRoute?.modelName ?? options.model ?? DEFAULT_CLI_MODEL);
         // Parent agent configuration is derived from start/session options, not
-        // per-prompt command options. Keeping model and prompt shape stable protects
-        // prompt caching across all pi-agent turns inside a duet-agent session.
-        return new Agent({
+        // per-prompt command options. For concrete selections the model stays
+        // stable for the whole session to protect prompt caching; routed sessions
+        // deliberately trade cache prefixes away when the ModelRouter swaps the
+        // model (per turn or via prepareNextTurn), with the classifier prompt
+        // carrying the don't-switch-mid-task cache preference.
+        let agent;
+        agent = new Agent({
             initialState: {
                 model,
-                thinkingLevel: options.thinkingLevel ?? "medium",
+                thinkingLevel: initialRoute?.thinkingLevel ?? options.thinkingLevel ?? "medium",
                 systemPrompt: input.systemPrompt ??
                     this.createBaseSystemPromptWithAppendedLayers({
                         prepend: [input.prependSystemPrompt],
@@ -1724,7 +2191,18 @@ export class TurnRunner {
                 messages: input.state.agent.messages,
                 tools: input.tools,
             },
-            transformContext: this.createMemoryTransform(),
+            transformContext: this.createMemoryTransform(input.memoryContext),
+            ...(input.parentModelRouting
+                ? {
+                    prepareNextTurn: async (signal) => {
+                        const switched = await this.modelRouter?.prepareTurn({
+                            signal,
+                        });
+                        return switched ? await this.applyRouterSwitch(agent, switched) : undefined;
+                    },
+                }
+                : {}),
+            steeringMode: "all",
             toolExecution: "parallel",
             afterToolCall: async (context) => {
                 const details = context.result.details;
@@ -1735,8 +2213,9 @@ export class TurnRunner {
             },
             getApiKey: resolveProviderApiKey,
         });
+        return agent;
     }
-    createMemoryTransform() {
+    createMemoryTransform(memoryContext) {
         // The memory transform owns history retention against both the token
         // budget (context-window cost on smaller models) and the wire-byte
         // budget (gateway request-body caps). It applies the sticky horizon
@@ -1744,10 +2223,26 @@ export class TurnRunner {
         // provider prompt cache stays valid between eviction events.
         return createObservationalContextTransform({
             memory: this.memory,
-            effectiveContext: this.resolveEffectiveContext(this.parentAgent?.state.model.contextWindow),
+            effectiveContext: () => this.resolveEffectiveContext(this.parentAgent?.state.model.contextWindow),
             settings: this.config.memory,
-            horizon: this.wireGuardHorizon,
-            onCompaction: (messages) => this.ensureMemoryCoverageForCompaction(messages),
+            horizon: memoryContext?.horizon ?? this.wireGuardHorizon,
+            onCompaction: async (messages) => {
+                if (memoryContext) {
+                    try {
+                        await this.updateMemoryAfterAgentRun(messages, undefined, memoryContext.sessionId, false);
+                    }
+                    catch (error) {
+                        this.emit({
+                            type: "system",
+                            level: "warn",
+                            message: `compact: child observation drain failed (${truncateForSystemMessage(error instanceof Error ? error.message : String(error))}); evicting anyway.`,
+                        });
+                    }
+                    return;
+                }
+                await this.ensureMemoryCoverageForCompaction(messages);
+                this.modelRouter?.noteCompaction();
+            },
         });
     }
     // Sticky across all turns within this runner instance. Resets on
@@ -1842,31 +2337,6 @@ export class TurnRunner {
     createBaseSystemPromptWithAppendedLayers(input) {
         return this.skillContext.createSystemPromptWithAppendedLayers(input);
     }
-    askUserQuestion(state, control) {
-        return {
-            type: "ask",
-            questions: control.questions,
-            state: { ...state, status: "waiting_for_human" },
-        };
-    }
-    /**
-     * Lifts the internal `AgentWorkerOutcome` shape into the public
-     * `TurnTerminalEvent` shape returned by `runTurnChain`. `runTurnChain`
-     * attaches `usage` / `effectiveContextWindow` / `contextWindowUsage`
-     * at the chain boundary, so this conversion intentionally omits them.
-     */
-    outcomeToTerminal(outcome) {
-        if (outcome.type === "interrupted") {
-            return { type: "interrupted", state: outcome.state };
-        }
-        return {
-            type: "complete",
-            status: outcome.status,
-            state: outcome.state,
-            result: outcome.result,
-            error: outcome.error,
-        };
-    }
     /**
      * Single source of truth for per-turn option precedence:
      * explicit turn options → carried-over state base → runner config → defaults.
@@ -1887,6 +2357,11 @@ export class TurnRunner {
             this.turnUsageByModel = addUsageByModel(this.turnUsageByModel, modelId, usage);
         }
     }
+    /** Attribute a non-parent model call and publish it once a flat context snapshot exists. */
+    recordAndEmitUsage(usage, modelId) {
+        this.recordUsage(usage, modelId);
+        this.emitTurnUsage();
+    }
     emitAgentEvent(event, origin) {
         if (event.type === "message_start" && event.message.role === "user") {
             this.removeFollowUpPrompt(agentMessageText(event.message));
@@ -1897,6 +2372,9 @@ export class TurnRunner {
     }
     emitParentAgentEvent(event) {
         this.emitAgentEvent(event);
+        if (event.type === "turn_end" && event.message.role === "assistant") {
+            this.modelRouter?.noteAssistantStep(routerStepObservation(event.message, event.toolResults));
+        }
         if (event.type !== "message_end" || event.message.role !== "assistant")
             return;
         // Cache the parent's latest bar/breakdown so subsequent state-agent and
@@ -1913,7 +2391,7 @@ export class TurnRunner {
         // consumed tokens, so a rejected attempt (e.g. a provider context-overflow
         // error the turn then recovers from) carries no usage and would otherwise
         // emit a degenerate all-zero bar.
-        this.recordUsage(event.message.usage, this.requireParentAgent().state.model.id);
+        this.recordUsage(event.message.usage, event.message.model);
         if (event.message.usage.totalTokens > 0)
             this.emitTurnUsage();
     }
@@ -1962,14 +2440,7 @@ export class TurnRunner {
         // can still refresh `lastUsage`. Session cost was already credited
         // at the prior terminal, so a zero `turnUsage.cost.total` does not
         // lose any spend.
-        const turnUsage = this.turnUsage ?? {
-            input: 0,
-            output: 0,
-            cacheRead: 0,
-            cacheWrite: 0,
-            totalTokens: 0,
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-        };
+        const turnUsage = this.turnUsage ?? emptyTokenUsage();
         this.emit({
             type: "usage",
             turnUsage,
@@ -1983,11 +2454,9 @@ export class TurnRunner {
      * Emit a `usage` event reflecting the latest `this.turnUsage`. Reuses the
      * most recent parent context-window snapshot for the bar/breakdown so
      * mid-turn ticks (parent worker finish, state-agent finish) surface cost
-     * without jittering the parent context fields. No-ops when no usage has
-     * been recorded yet or before the first parent emission — both are only
-     * possible during construction/teardown or in test harnesses; a real
-     * parent worker always sets the snapshot before its terminal usage is
-     * recorded.
+     * without jittering the parent context fields. Before the first parent
+     * completion, usage is recorded for the terminal and the first later usage
+     * event, but no incomplete wire event is emitted.
      */
     emitTurnUsage(origin) {
         if (!this.turnUsage || !this.lastParentUsageSnapshot)
@@ -2055,6 +2524,134 @@ export class TurnRunner {
         const userValue = this.config.effectiveContext ?? DEFAULT_EFFECTIVE_CONTEXT;
         return modelWindow !== undefined ? Math.min(userValue, modelWindow) : userValue;
     }
+    /** Load the project table and build the parent router when the persisted selection is virtual. */
+    async initializeModelRouter(modelName) {
+        this.modelRouter = undefined;
+        this.routingTable = undefined;
+        this.advisorPolicy = undefined;
+        const loaded = await loadRoutingTable({
+            cwd: this.config.cwd ?? process.cwd(),
+            catalogAdapter: routingCatalogAdapter,
+        });
+        this.routingTable = loaded.table;
+        if (!modelName || !isVirtualModel(modelName, loaded.table))
+            return;
+        this.advisorPolicy = loaded.table.tiers[modelName].advisor;
+        this.modelRouter = this.createBoundModelRouter(modelName, loaded.table, routingCatalogAdapter);
+    }
+    createBoundModelRouter(tier, table, resolveCatalog) {
+        return this.createModelRouter({
+            table,
+            tier,
+            classify: async (input, signal) => {
+                return classifyRoute(input, { ...this.classifierOptions(table), signal });
+            },
+            resolveCatalog,
+        });
+    }
+    /** One metered classifier contract shared by parent routing and spawned children. */
+    classifierOptions(table) {
+        const model = resolveModelName(table.classifier.target.modelName);
+        return {
+            model: `${model.provider}:${model.id}`,
+            thinkingLevel: table.classifier.target.thinkingLevel,
+            onUsage: (usage) => this.recordAndEmitUsage(usage, model.id),
+        };
+    }
+    /** True when a model name is owned by the validated project table. */
+    isVirtualModelSelection(modelName) {
+        return isVirtualModel(modelName, this.routingTable ?? BUILT_IN_ROUTING_TABLE);
+    }
+    /** Read-only routing snapshot for session-owned UI surfaces. */
+    routeStatus() {
+        return this.modelRouter?.status();
+    }
+    /**
+     * Retarget subsequent parent turns while preserving the current in-flight turn.
+     * Concrete selections pin routing; virtual selections rebuild it so the next
+     * turn classifies from a fresh tier-local baseline.
+     */
+    setModel(modelName) {
+        const routed = this.isVirtualModelSelection(modelName);
+        if (!routed)
+            resolveModelName(modelName);
+        const state = this.requireRunnerState();
+        state.options = { ...state.options, model: modelName };
+        this.pendingModelSelection = modelName;
+        if (!this.parentAgentRunning)
+            this.applyPendingModelSelection(this.requireParentAgent());
+        return { routed };
+    }
+    applyPendingModelSelection(agent) {
+        const selection = this.pendingModelSelection;
+        if (!selection)
+            return;
+        this.pendingModelSelection = undefined;
+        if (!this.isVirtualModelSelection(selection)) {
+            this.modelRouter?.pin();
+            this.advisorPolicy = undefined;
+            agent.state.model = resolveModelName(selection);
+            return;
+        }
+        const table = this.routingTable ?? BUILT_IN_ROUTING_TABLE;
+        this.modelRouter?.unpin();
+        this.advisorPolicy = table.tiers[selection].advisor;
+        this.modelRouter = this.createBoundModelRouter(selection, table, routingCatalogAdapter);
+        const initial = this.modelRouter.initialTarget({ hasImages: false });
+        agent.state.model = resolveModelName(initial.modelName);
+        agent.state.thinkingLevel = initial.thinkingLevel;
+    }
+    /** Explicit virtual state models take the tier's default route without classifier latency. */
+    resolveStateModel(modelName) {
+        if (!modelName || !this.isVirtualModelSelection(modelName))
+            return undefined;
+        const table = this.routingTable ?? BUILT_IN_ROUTING_TABLE;
+        return resolveTierDefault(table, modelName, { hasImages: false }, routingCatalogAdapter);
+    }
+    /** Omitted child models inherit the parent's active concrete target, not its virtual setting. */
+    resolveSubagentInheritedOptions() {
+        const options = { ...this.requireRunnerState().options };
+        if (!options.model || !this.isVirtualModelSelection(options.model))
+            return options;
+        const parent = this.requireParentAgent().state;
+        return {
+            ...options,
+            model: `${parent.model.provider}:${parent.model.id}`,
+            ...(parent.thinkingLevel === "off" ? {} : { thinkingLevel: parent.thinkingLevel }),
+        };
+    }
+    /** Composition seam used by production binding and deterministic runner tests. */
+    createModelRouter(options) {
+        return new ModelRouter(options);
+    }
+    /** Resolve and atomically apply one router-owned model/effort change. */
+    async applyRouterSwitch(agent, switched) {
+        const model = resolveModelName(switched.toModel);
+        agent.state.model = model;
+        agent.state.thinkingLevel = switched.thinkingLevel;
+        if (this.lastParentUsageSnapshot) {
+            this.lastParentUsageSnapshot = {
+                ...this.lastParentUsageSnapshot,
+                effectiveContextWindow: this.resolveEffectiveContext(model.contextWindow),
+            };
+        }
+        this.emit({ type: "router_switch", ...switched });
+        return { model, thinkingLevel: switched.thinkingLevel };
+    }
+}
+const ROUTER_STEP_TEXT_LIMIT = 2_000;
+function routerStepObservation(message, toolResults) {
+    const content = [...message.content, ...toolResults.flatMap((result) => result.content)];
+    const text = content
+        .filter((block) => block.type === "text")
+        .map((block) => stripSystemReminders(block.text))
+        .filter(Boolean)
+        .join("\n")
+        .trim();
+    return {
+        blockTypes: content.map((block) => block.type),
+        text: text.slice(-ROUTER_STEP_TEXT_LIMIT),
+    };
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));