pilotswarm-sdk 0.4.0 → 0.5.0

package/dist/session-proxy.js

@@ -13,7 +13,10 @@ import { computeCronAtNextFire } from "./cron-at.js";
 import { SpanStatusCode, trace as otelTrace } from "@opentelemetry/api";
 import os from "node:os";
 import fs from "node:fs";
+import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { attemptStoreRecovery, runTurnCommit, runTurnPreamble } from "./session-lifecycle.js";
+import { supportsVersionedSnapshots, writeTurnSentinel } from "./snapshot-protocol.js";
 const SYSTEM_AGENT_IDS = new Set(["pilotswarm", "sweeper", "resourcemgr", "facts-manager", "agent-tuner"]);
 const SESSION_RECOVERY_NOTICE = "[SYSTEM: The runtime recovered this session after the live Copilot session was lost on a worker. " +
     "Some very recent in-memory state may have been lost. Re-read the visible conversation and continue carefully from the latest durable state.]";
@@ -23,6 +26,8 @@ const LOSSY_SESSION_REPLAY_NOTICE = "[SYSTEM: The runtime is replaying this turn
 const CORRUPTED_TRANSCRIPT_REPLAY_NOTICE = "[SYSTEM: The runtime recreated this session after the live Copilot transcript became inconsistent. " +
     "Some recent in-memory work may be missing, and the previous turn may have partially executed. " +
     "Re-read the visible conversation and continue carefully from the latest durable state.]";
+const REHYDRATED_SESSION_NOTICE = "[SYSTEM: This session was rehydrated on a different worker from its durable snapshot. " +
+    "The conversation history is fully preserved. Continue seamlessly.]";
 function normalizeJsonObject(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return null;
@@ -429,6 +434,7 @@ export function createSessionProxy(ctx, sessionId, affinityKey, config) {
                 ...(turnMeta?.clientMessageIds && turnMeta.clientMessageIds.length > 0
                     ? { clientMessageIds: turnMeta.clientMessageIds }
                     : {}),
+                ...(turnMeta?.snapshot ? { snapshot: turnMeta.snapshot } : {}),
             }, affinityKey);
         },
         dehydrate(reason, eventData) {
@@ -618,7 +624,7 @@ export function createSessionManagerProxy(ctx) {
 // ─── Activity Registration ───────────────────────────────────────
 // Thin dispatchers — each is a one-liner that calls the corresponding
 // SessionManager or ManagedSession method.
-export function registerActivities(runtime, sessionManager, _sessionStore, githubToken, catalog, provider, storeUrl, cmsSchema, clientConfig, 
+export function registerActivities(runtime, sessionManager, sessionStore, githubToken, catalog, provider, storeUrl, cmsSchema, clientConfig, 
 /** Loaded system agents — used by resolveAgentConfig activity. */
 systemAgents, 
 /** Worker-level session policy — used by getWorkerSessionPolicy activity. */
@@ -715,1020 +721,1159 @@ workerNodeId) {
         let finalTurnResult = null;
         try {
             finalTurnResult = await sessionManager.withRunTurnLock(input.sessionId, "runTurn", async () => {
-                let session = null;
-                let effectivePrompt = input.prompt;
-                try {
-                    session = await sessionManager.getOrCreate(input.sessionId, runConfig, {
-                        turnIndex: input.turnIndex,
+                // ── Session lifecycle protocol preamble (proposal §3.3) ─────────
+                // Only active when the orchestration (1.0.57+) supplied snapshot
+                // coordinates AND the store implements the versioned CAS contract.
+                // Absent either, this activity behaves exactly as before.
+                const lifecycle = input.snapshot && sessionStore && supportsVersionedSnapshots(sessionStore)
+                    ? {
+                        store: sessionStore,
+                        sessionStateDir: sessionManager.getSessionStateDir(),
+                        sessionId: input.sessionId,
+                        expectedVersion: input.snapshot.expectedVersion,
+                        turnKey: input.snapshot.turnKey,
+                        dropWarmSession: () => sessionManager.dropWarmSession(input.sessionId),
                         trace,
-                        lockHeld: true,
-                    });
-                }
-                catch (err) {
-                    const message = err?.message || String(err);
-                    if (isMissingSessionStateErrorMessage(message) || isLiveSessionLostErrorMessage(message)) {
-                        const detail = isMissingSessionStateErrorMessage(message)
-                            ? stripMissingSessionStatePrefix(message)
-                            : message;
-                        trace(`session=${input.sessionId} missing resumable state before turn ${input.turnIndex ?? "unknown"}; ` +
-                            "starting lossy fresh-session replay");
-                        await recordLossyHandoffEvent(catalog, input.sessionId, workerNodeId, {
-                            cause: "missing_resumable_state_before_run_turn",
-                            message: buildLossyReplayMessage(input.sessionId, detail),
-                            detail,
-                            error: message,
-                            recoveryMode: "fresh_session_replay",
-                            nextStep: "replay_pending_turn_with_recreated_copilot_session",
-                            ...(input.turnIndex != null ? { iteration: input.turnIndex } : {}),
-                        }, (failureMessage) => activityCtx.traceInfo(`[runTurn] ${failureMessage}`));
-                        if (catalog) {
-                            await cmsRetryBestEffort(`runTurn.recordEvent system.message-lossy-replay session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
-                                    eventType: "system.message",
-                                    data: {
-                                        content: "The runtime is replaying this turn after a worker restart lost the live Copilot session state before durable dehydrate completed. " +
-                                            "Some recent work may be missing or partially executed.",
-                                    },
-                                }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
-                        }
-                        try {
-                            session = await sessionManager.getOrCreate(input.sessionId, runConfig, {
-                                turnIndex: 0,
-                                trace,
-                                lockHeld: true,
-                            });
-                        }
-                        catch (recoveryErr) {
-                            const recoveryMessage = recoveryErr?.message || String(recoveryErr);
-                            const fatalMessage = isMissingSessionStateErrorMessage(recoveryMessage)
-                                ? buildUnrecoverableSessionLossMessage(input.sessionId, stripMissingSessionStatePrefix(recoveryMessage))
-                                : buildUnrecoverableSessionLossMessage(input.sessionId, recoveryMessage);
-                            trace(`session=${input.sessionId} lossy replay session recreation failed error=${fatalMessage}`);
-                            return await failForMissingState(fatalMessage);
-                        }
-                        effectivePrompt = mergePromptSections([LOSSY_SESSION_REPLAY_NOTICE, input.prompt]) || input.prompt;
                     }
-                    else {
-                        throw err;
+                    : null;
+                let lifecycleBaseVersion = 0;
+                let lifecycleRehydrated = false;
+                // Protocol-native persistence stats: the legacy dehydrate/hydrate
+                // activities no longer run, so the preamble/commit paths feed the
+                // same CMS summary + events the Stats pane reads. Best-effort only.
+                const recordLifecycleHydration = async (version) => {
+                    if (!catalog)
+                        return;
+                    await cmsRetryBestEffort(`runTurn.lifecycleHydrated session=${input.sessionId}`, async () => {
+                        await catalog.upsertSessionMetricSummary(input.sessionId, {
+                            hydrationCountIncrement: 1,
+                            lastHydratedAt: true,
+                        });
+                        await catalog.recordEvents(input.sessionId, [{
+                                eventType: "session.hydrated",
+                                data: { version, protocol: "lifecycle" },
+                            }], workerNodeId);
+                    }, (msg) => activityCtx.traceInfo(msg));
+                };
+                if (lifecycle) {
+                    const pre = await runTurnPreamble(lifecycle);
+                    if (pre.kind === "already-committed") {
+                        activityCtx.traceInfo(`[runTurn] session=${input.sessionId} already-committed recovery at v${pre.version}; ` +
+                            `returning stored result without re-running the turn`);
+                        await recordLifecycleHydration(pre.version);
+                        return { ...pre.result, snapshotVersion: pre.version };
+                    }
+                    lifecycleBaseVersion = pre.baseVersion;
+                    lifecycleRehydrated = pre.kind === "hydrated";
+                    if (lifecycleRehydrated) {
+                        await recordLifecycleHydration(pre.baseVersion);
+                    }
+                    if (pre.kind === "fresh" && pre.lossy && catalog) {
+                        await cmsRetryBestEffort(`runTurn.recordEvent snapshot-store-empty session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
+                                eventType: "session.snapshot_store_empty",
+                                data: {
+                                    expectedVersion: input.snapshot.expectedVersion,
+                                    message: "Snapshot store held no data for a session with committed turns; falling back to fresh-session recovery.",
+                                },
+                            }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
                     }
                 }
-                const getInlineClient = async () => {
-                    if (inlineSdkClient)
-                        return inlineSdkClient;
-                    if (inlineSdkClientPromise)
-                        return await inlineSdkClientPromise;
-                    if (!storeUrl)
-                        throw new Error("No storeUrl — cannot create PilotSwarmClient");
-                    inlineSdkClientPromise = (async () => {
-                        const startedClient = new PilotSwarmClient(internalClientConfig());
-                        await startedClient.start();
-                        inlineSdkClient = startedClient;
-                        return startedClient;
-                    })();
+                const executeTurnBody = async () => {
+                    let session = null;
+                    let effectivePrompt = input.prompt;
                     try {
-                        return await inlineSdkClientPromise;
-                    }
-                    finally {
-                        inlineSdkClientPromise = null;
-                    }
-                };
-                const isAutonomousSystemTurn = () => {
-                    if (!SYSTEM_AGENT_IDS.has(runConfig.agentIdentity || ""))
-                        return false;
-                    if (input.bootstrap === true)
-                        return true;
-                    return /^\s*\[SYSTEM:/i.test(String(input.prompt ?? ""));
-                };
-                const sanitizeAutonomousSystemSessionFilters = (args) => {
-                    if (!args || !isAutonomousSystemTurn())
-                        return args;
-                    if (!args.owner_query && !args.owner_kind)
-                        return args;
-                    const sanitized = { ...args };
-                    delete sanitized.owner_query;
-                    delete sanitized.owner_kind;
-                    return sanitized;
-                };
-                const isReadOnlyTuner = () => runConfig.agentIdentity === "agent-tuner";
-                const normalizeAgentLookup = (value) => (value || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
-                const resolveAgentConfigInline = (agentName) => {
-                    const agents = [
-                        ...(userAgents ?? []).map(a => ({ ...a, system: false, creatable: true })),
-                        ...(systemAgents ?? []).map(a => ({ ...a, creatable: false })),
-                    ];
-                    let lookupNamespace;
-                    let rawName = agentName;
-                    if (agentName.includes(":")) {
-                        const parts = agentName.split(":");
-                        lookupNamespace = parts[0];
-                        rawName = parts.slice(1).join(":");
+                        session = await sessionManager.getOrCreate(input.sessionId, runConfig, {
+                            turnIndex: input.turnIndex,
+                            trace,
+                            lockHeld: true,
+                        });
                     }
-                    const lookup = normalizeAgentLookup(rawName);
-                    const lookupBase = lookup.replace(/agent$/, "");
-                    return agents.find(a => {
-                        if (lookupNamespace && normalizeAgentLookup(a.namespace) !== normalizeAgentLookup(lookupNamespace))
-                            return false;
-                        const candidates = [a.name, a.id, a.title].map(normalizeAgentLookup).filter(Boolean);
-                        return candidates.includes(lookup) || (lookupBase && candidates.includes(lookupBase));
-                    }) ?? null;
-                };
-                const loadDirectChildSessions = async () => {
-                    const sdkClient = await getInlineClient();
-                    const sessions = await sdkClient.listSessions();
-                    const directChildren = sessions.filter(s => s.parentSessionId === input.sessionId);
-                    return await Promise.all(directChildren.map(async (child) => {
-                        const info = await sdkClient._getSessionInfo(child.sessionId);
-                        const outcome = catalog ? await catalog.getChildOutcome(child.sessionId).catch(() => null) : null;
-                        const outcomeResult = normalizeJsonObject(outcome?.resultJson?.current);
-                        const contractCurrent = normalizeJsonObject(outcome?.contractJson?.current);
-                        return {
-                            orchId: `session-${child.sessionId}`,
-                            sessionId: child.sessionId,
-                            title: info.title ?? child.title,
-                            status: info.status,
-                            iterations: info.iterations ?? child.iterations ?? 0,
-                            parentSessionId: child.parentSessionId,
-                            isSystem: child.isSystem ?? info.isSystem ?? false,
-                            agentId: child.agentId ?? info.agentId,
-                            result: outcome?.summary ?? (typeof outcomeResult?.summary === "string" ? outcomeResult.summary : info.result),
-                            contract: contractCurrent ?? undefined,
-                            contractStatus: outcome?.contractJson ? "contracted" : undefined,
-                            verdict: outcome?.verdict ?? undefined,
-                            contractViolations: Array.isArray(outcomeResult?.contractViolations) ? outcomeResult.contractViolations : undefined,
-                            error: info.error,
-                        };
-                    }));
-                };
-                const resolveManagedChild = async (agentId) => {
-                    const targetOrchId = agentId.startsWith("session-") ? agentId : `session-${agentId}`;
-                    const children = await loadDirectChildSessions();
-                    const child = children.find(entry => entry.orchId === targetOrchId);
-                    if (!child) {
-                        throw new Error(`agent "${targetOrchId}" not found. Known agents: ${children.filter(entry => !entry.isSystem).map(entry => entry.orchId).join(", ") || "none"}`);
+                    catch (err) {
+                        const message = err?.message || String(err);
+                        if (isMissingSessionStateErrorMessage(message) || isLiveSessionLostErrorMessage(message)) {
+                            const detail = isMissingSessionStateErrorMessage(message)
+                                ? stripMissingSessionStatePrefix(message)
+                                : message;
+                            // ── Lifecycle store recovery BEFORE lossy replay ─────────
+                            // The store may hold a perfect committed snapshot (e.g. the
+                            // SDK refused to resume from locally damaged files). Restore
+                            // it and retry — lossy replay (whose turn-0 reset DELETES
+                            // the store snapshot) is only reachable when the store is
+                            // empty, making that delete a no-op.
+                            if (lifecycle) {
+                                try {
+                                    const recoveredVersion = await attemptStoreRecovery(lifecycle);
+                                    if (recoveredVersion != null) {
+                                        trace(`session=${input.sessionId} restored committed snapshot v${recoveredVersion} ` +
+                                            `after getOrCreate failure (${detail.slice(0, 120)}); retrying resume`);
+                                        session = await sessionManager.getOrCreate(input.sessionId, runConfig, {
+                                            turnIndex: input.turnIndex,
+                                            trace,
+                                            lockHeld: true,
+                                        });
+                                        lifecycleBaseVersion = recoveredVersion;
+                                        lifecycleRehydrated = true;
+                                    }
+                                }
+                                catch (storeRecoveryErr) {
+                                    trace(`session=${input.sessionId} snapshot-store recovery failed: ` +
+                                        `${storeRecoveryErr?.message ?? storeRecoveryErr}; falling back to lossy replay`);
+                                    session = null;
+                                }
+                            }
+                            if (session) {
+                                // Recovered losslessly — skip the lossy replay machinery.
+                            }
+                            else {
+                                trace(`session=${input.sessionId} missing resumable state before turn ${input.turnIndex ?? "unknown"}; ` +
+                                    "starting lossy fresh-session replay");
+                                await recordLossyHandoffEvent(catalog, input.sessionId, workerNodeId, {
+                                    cause: "missing_resumable_state_before_run_turn",
+                                    message: buildLossyReplayMessage(input.sessionId, detail),
+                                    detail,
+                                    error: message,
+                                    recoveryMode: "fresh_session_replay",
+                                    nextStep: "replay_pending_turn_with_recreated_copilot_session",
+                                    ...(input.turnIndex != null ? { iteration: input.turnIndex } : {}),
+                                }, (failureMessage) => activityCtx.traceInfo(`[runTurn] ${failureMessage}`));
+                                if (catalog) {
+                                    await cmsRetryBestEffort(`runTurn.recordEvent system.message-lossy-replay session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
+                                            eventType: "system.message",
+                                            data: {
+                                                content: "The runtime is replaying this turn after a worker restart lost the live Copilot session state before durable dehydrate completed. " +
+                                                    "Some recent work may be missing or partially executed.",
+                                            },
+                                        }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
+                                }
+                                try {
+                                    session = await sessionManager.getOrCreate(input.sessionId, runConfig, {
+                                        turnIndex: 0,
+                                        trace,
+                                        lockHeld: true,
+                                    });
+                                }
+                                catch (recoveryErr) {
+                                    const recoveryMessage = recoveryErr?.message || String(recoveryErr);
+                                    const fatalMessage = isMissingSessionStateErrorMessage(recoveryMessage)
+                                        ? buildUnrecoverableSessionLossMessage(input.sessionId, stripMissingSessionStatePrefix(recoveryMessage))
+                                        : buildUnrecoverableSessionLossMessage(input.sessionId, recoveryMessage);
+                                    trace(`session=${input.sessionId} lossy replay session recreation failed error=${fatalMessage}`);
+                                    return await failForMissingState(fatalMessage);
+                                }
+                                effectivePrompt = mergePromptSections([LOSSY_SESSION_REPLAY_NOTICE, input.prompt]) || input.prompt;
+                            }
+                        }
+                        else {
+                            throw err;
+                        }
                     }
-                    if (child.isSystem) {
-                        throw new Error(`agent "${targetOrchId}" is a worker-managed system agent and is not a controllable spawned sub-agent`);
+                    // ── Lifecycle p3: sentinel marks the dir as mid-mutation from here
+                    // until the post-turn commit clears it. Written after getOrCreate so
+                    // the turn-0 reset path cannot wipe it, before any body mutation.
+                    if (lifecycle) {
+                        writeTurnSentinel(path.join(sessionManager.getSessionStateDir(), input.sessionId), input.snapshot.turnKey);
+                        if (lifecycleRehydrated) {
+                            effectivePrompt = mergePromptSections([REHYDRATED_SESSION_NOTICE, effectivePrompt]) || effectivePrompt;
+                        }
                     }
-                    return child;
-                };
-                const controlToolBridge = {
-                    spawnAgent: async (args) => {
+                    const getInlineClient = async () => {
+                        if (inlineSdkClient)
+                            return inlineSdkClient;
+                        if (inlineSdkClientPromise)
+                            return await inlineSdkClientPromise;
+                        if (!storeUrl)
+                            throw new Error("No storeUrl — cannot create PilotSwarmClient");
+                        inlineSdkClientPromise = (async () => {
+                            const startedClient = new PilotSwarmClient(internalClientConfig());
+                            await startedClient.start();
+                            inlineSdkClient = startedClient;
+                            return startedClient;
+                        })();
                         try {
-                            const childNestingLevel = (input.nestingLevel ?? 0) + 1;
-                            if (childNestingLevel > MAX_NESTING_LEVEL) {
-                                return `[SYSTEM: spawn_agent failed — you are already at nesting level ${input.nestingLevel ?? 0} (max ${MAX_NESTING_LEVEL}). ` +
-                                    `Sub-agents at this depth cannot spawn further sub-agents. Handle the task directly instead.]`;
-                            }
-                            const existingChildren = (await loadDirectChildSessions()).filter(child => !child.isSystem);
-                            const activeCount = existingChildren.filter(child => child.status === "running").length;
-                            if (activeCount >= MAX_SUB_AGENTS) {
-                                return `[SYSTEM: spawn_agent failed — you already have ${activeCount} running sub-agents (max ${MAX_SUB_AGENTS}). ` +
-                                    `Wait for some to complete before spawning more.]`;
-                            }
-                            let agentTask = args.task || "";
-                            let agentSystemMessage = args.system_message;
-                            let agentToolNames = args.tool_names;
-                            let agentModel = args.model;
-                            let agentReasoningEffort = args.reasoning_effort;
-                            let agentIsSystem = false;
-                            const explicitAgentTitle = typeof args.title === "string" && args.title.trim() ? args.title.trim() : undefined;
-                            let agentTitle = explicitAgentTitle;
-                            let agentTitleIsExplicit = Boolean(explicitAgentTitle);
-                            let agentId;
-                            let agentSplash;
-                            let boundAgentName;
-                            let promptLayeringKind;
-                            let resolvedAgentName = args.agent_name;
-                            const applyAgentDef = (agentDef, useDefinitionDefaults = false) => {
-                                agentTask = useDefinitionDefaults
-                                    ? (agentDef.initialPrompt || `You are the ${agentDef.name} agent. Begin your work.`)
-                                    : (args.task || agentDef.initialPrompt || `You are the ${agentDef.name} agent. Begin your work.`);
-                                agentSystemMessage = useDefinitionDefaults ? undefined : args.system_message;
-                                agentToolNames = useDefinitionDefaults
-                                    ? (agentDef.tools ?? undefined)
-                                    : (args.tool_names ?? agentDef.tools ?? undefined);
-                                agentIsSystem = agentDef.system ?? false;
-                                if (!agentTitleIsExplicit)
-                                    agentTitle = agentDef.title;
-                                agentId = agentDef.id ?? resolvedAgentName;
-                                agentSplash = agentDef.splash;
-                                boundAgentName = agentDef.name;
-                                promptLayeringKind = agentDef.promptLayerKind
-                                    ?? (agentDef.system
-                                        ? ((agentDef.namespace || "pilotswarm") === "pilotswarm"
-                                            ? "pilotswarm-system-agent"
-                                            : "app-system-agent")
-                                        : "app-agent");
+                            return await inlineSdkClientPromise;
+                        }
+                        finally {
+                            inlineSdkClientPromise = null;
+                        }
+                    };
+                    const isAutonomousSystemTurn = () => {
+                        if (!SYSTEM_AGENT_IDS.has(runConfig.agentIdentity || ""))
+                            return false;
+                        if (input.bootstrap === true)
+                            return true;
+                        return /^\s*\[SYSTEM:/i.test(String(input.prompt ?? ""));
+                    };
+                    const sanitizeAutonomousSystemSessionFilters = (args) => {
+                        if (!args || !isAutonomousSystemTurn())
+                            return args;
+                        if (!args.owner_query && !args.owner_kind)
+                            return args;
+                        const sanitized = { ...args };
+                        delete sanitized.owner_query;
+                        delete sanitized.owner_kind;
+                        return sanitized;
+                    };
+                    const isReadOnlyTuner = () => runConfig.agentIdentity === "agent-tuner";
+                    const normalizeAgentLookup = (value) => (value || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
+                    const resolveAgentConfigInline = (agentName) => {
+                        const agents = [
+                            ...(userAgents ?? []).map(a => ({ ...a, system: false, creatable: true })),
+                            ...(systemAgents ?? []).map(a => ({ ...a, creatable: false })),
+                        ];
+                        let lookupNamespace;
+                        let rawName = agentName;
+                        if (agentName.includes(":")) {
+                            const parts = agentName.split(":");
+                            lookupNamespace = parts[0];
+                            rawName = parts.slice(1).join(":");
+                        }
+                        const lookup = normalizeAgentLookup(rawName);
+                        const lookupBase = lookup.replace(/agent$/, "");
+                        return agents.find(a => {
+                            if (lookupNamespace && normalizeAgentLookup(a.namespace) !== normalizeAgentLookup(lookupNamespace))
+                                return false;
+                            const candidates = [a.name, a.id, a.title].map(normalizeAgentLookup).filter(Boolean);
+                            return candidates.includes(lookup) || (lookupBase && candidates.includes(lookupBase));
+                        }) ?? null;
+                    };
+                    const loadDirectChildSessions = async () => {
+                        const sdkClient = await getInlineClient();
+                        const sessions = await sdkClient.listSessions();
+                        const directChildren = sessions.filter(s => s.parentSessionId === input.sessionId);
+                        return await Promise.all(directChildren.map(async (child) => {
+                            const info = await sdkClient._getSessionInfo(child.sessionId);
+                            const outcome = catalog ? await catalog.getChildOutcome(child.sessionId).catch(() => null) : null;
+                            const outcomeResult = normalizeJsonObject(outcome?.resultJson?.current);
+                            const contractCurrent = normalizeJsonObject(outcome?.contractJson?.current);
+                            return {
+                                orchId: `session-${child.sessionId}`,
+                                sessionId: child.sessionId,
+                                title: info.title ?? child.title,
+                                status: info.status,
+                                iterations: info.iterations ?? child.iterations ?? 0,
+                                parentSessionId: child.parentSessionId,
+                                isSystem: child.isSystem ?? info.isSystem ?? false,
+                                agentId: child.agentId ?? info.agentId,
+                                result: outcome?.summary ?? (typeof outcomeResult?.summary === "string" ? outcomeResult.summary : info.result),
+                                contract: contractCurrent ?? undefined,
+                                contractStatus: outcome?.contractJson ? "contracted" : undefined,
+                                verdict: outcome?.verdict ?? undefined,
+                                contractViolations: Array.isArray(outcomeResult?.contractViolations) ? outcomeResult.contractViolations : undefined,
+                                error: info.error,
                             };
-                            if (resolvedAgentName) {
-                                const agentDef = resolveAgentConfigInline(resolvedAgentName);
-                                if (!agentDef) {
-                                    return `[SYSTEM: spawn_agent failed — agent "${resolvedAgentName}" not found. Use ps_list_agents to see available agents.]`;
+                        }));
+                    };
+                    const resolveManagedChild = async (agentId) => {
+                        const targetOrchId = agentId.startsWith("session-") ? agentId : `session-${agentId}`;
+                        const children = await loadDirectChildSessions();
+                        const child = children.find(entry => entry.orchId === targetOrchId);
+                        if (!child) {
+                            throw new Error(`agent "${targetOrchId}" not found. Known agents: ${children.filter(entry => !entry.isSystem).map(entry => entry.orchId).join(", ") || "none"}`);
+                        }
+                        if (child.isSystem) {
+                            throw new Error(`agent "${targetOrchId}" is a worker-managed system agent and is not a controllable spawned sub-agent`);
+                        }
+                        return child;
+                    };
+                    const controlToolBridge = {
+                        spawnAgent: async (args) => {
+                            try {
+                                const childNestingLevel = (input.nestingLevel ?? 0) + 1;
+                                if (childNestingLevel > MAX_NESTING_LEVEL) {
+                                    return `[SYSTEM: spawn_agent failed — you are already at nesting level ${input.nestingLevel ?? 0} (max ${MAX_NESTING_LEVEL}). ` +
+                                        `Sub-agents at this depth cannot spawn further sub-agents. Handle the task directly instead.]`;
+                                }
+                                const existingChildren = (await loadDirectChildSessions()).filter(child => !child.isSystem);
+                                const activeCount = existingChildren.filter(child => child.status === "running").length;
+                                if (activeCount >= MAX_SUB_AGENTS) {
+                                    return `[SYSTEM: spawn_agent failed — you already have ${activeCount} running sub-agents (max ${MAX_SUB_AGENTS}). ` +
+                                        `Wait for some to complete before spawning more.]`;
+                                }
+                                let agentTask = args.task || "";
+                                let agentSystemMessage = args.system_message;
+                                let agentToolNames = args.tool_names;
+                                let agentModel = args.model;
+                                let agentReasoningEffort = args.reasoning_effort;
+                                let agentIsSystem = false;
+                                const explicitAgentTitle = typeof args.title === "string" && args.title.trim() ? args.title.trim() : undefined;
+                                let agentTitle = explicitAgentTitle;
+                                let agentTitleIsExplicit = Boolean(explicitAgentTitle);
+                                let agentId;
+                                let agentSplash;
+                                let agentSplashMobile;
+                                let boundAgentName;
+                                let promptLayeringKind;
+                                let resolvedAgentName = args.agent_name;
+                                const applyAgentDef = (agentDef, useDefinitionDefaults = false) => {
+                                    agentTask = useDefinitionDefaults
+                                        ? (agentDef.initialPrompt || `You are the ${agentDef.name} agent. Begin your work.`)
+                                        : (args.task || agentDef.initialPrompt || `You are the ${agentDef.name} agent. Begin your work.`);
+                                    agentSystemMessage = useDefinitionDefaults ? undefined : args.system_message;
+                                    agentToolNames = useDefinitionDefaults
+                                        ? (agentDef.tools ?? undefined)
+                                        : (args.tool_names ?? agentDef.tools ?? undefined);
+                                    agentIsSystem = agentDef.system ?? false;
+                                    if (!agentTitleIsExplicit)
+                                        agentTitle = agentDef.title;
+                                    agentId = agentDef.id ?? resolvedAgentName;
+                                    agentSplash = agentDef.splash;
+                                    agentSplashMobile = agentDef.splashMobile;
+                                    boundAgentName = agentDef.name;
+                                    promptLayeringKind = agentDef.promptLayerKind
+                                        ?? (agentDef.system
+                                            ? ((agentDef.namespace || "pilotswarm") === "pilotswarm"
+                                                ? "pilotswarm-system-agent"
+                                                : "app-system-agent")
+                                            : "app-agent");
+                                };
+                                if (resolvedAgentName) {
+                                    const agentDef = resolveAgentConfigInline(resolvedAgentName);
+                                    if (!agentDef) {
+                                        return `[SYSTEM: spawn_agent failed — agent "${resolvedAgentName}" not found. Use ps_list_agents to see available agents.]`;
+                                    }
+                                    if (agentDef.system && agentDef.creatable === false) {
+                                        return `[SYSTEM: spawn_agent failed — agent "${resolvedAgentName}" is a worker-managed system agent and cannot be spawned from a session. ` +
+                                            `If it is missing, the workers likely need to be restarted.]`;
+                                    }
+                                    applyAgentDef(agentDef, resolvedAgentName !== args.agent_name);
                                 }
-                                if (agentDef.system && agentDef.creatable === false) {
-                                    return `[SYSTEM: spawn_agent failed — agent "${resolvedAgentName}" is a worker-managed system agent and cannot be spawned from a session. ` +
-                                        `If it is missing, the workers likely need to be restarted.]`;
+                                if (agentModel && !agentModel.includes(":")) {
+                                    return `[SYSTEM: spawn_agent failed — model "${agentModel}" is not allowed. ` +
+                                        `When overriding a sub-agent model, first call list_available_models and then use the exact provider:model value from that list. ` +
+                                        `If you are unsure, omit model so the sub-agent inherits your current model.]`;
                                 }
-                                applyAgentDef(agentDef, resolvedAgentName !== args.agent_name);
+                                // v1.0.49: same-name duplicate spawns are allowed. The
+                                // global MAX_SUB_AGENTS cap and per-spawn nesting limit
+                                // still apply. The parent is responsible for closing
+                                // each instance with complete_agent / cancel_agent /
+                                // delete_agent when it no longer needs the child.
+                                const { boundAgentName: _parentBoundAgentName, promptLayering: _parentPromptLayering, isCrawler: _parentIsCrawler, isHarvester: _parentIsHarvester, ...parentConfig } = input.config;
+                                const childConfig = {
+                                    ...parentConfig,
+                                    ...(agentModel ? { model: agentModel } : {}),
+                                    ...(agentReasoningEffort ? { reasoningEffort: agentReasoningEffort } : {}),
+                                    ...(agentSystemMessage ? { systemMessage: agentSystemMessage } : {}),
+                                    ...(boundAgentName ? { boundAgentName } : {}),
+                                    ...(promptLayeringKind ? { promptLayering: { kind: promptLayeringKind } } : {}),
+                                    ...(agentToolNames ? { toolNames: agentToolNames } : {}),
+                                    ...(args.contract ? { childContract: args.contract } : {}),
+                                };
+                                const parentSystemMsg = typeof childConfig.systemMessage === "string"
+                                    ? childConfig.systemMessage
+                                    : childConfig.systemMessage?.content ?? "";
+                                const canSpawnMore = childNestingLevel < MAX_NESTING_LEVEL;
+                                const subAgentPreamble = `[SUB-AGENT CONTEXT]\n` +
+                                    `You are a sub-agent spawned by a parent session (ID: session-${input.sessionId}).\n` +
+                                    `Your nesting level: ${childNestingLevel} (max: ${MAX_NESTING_LEVEL}).\n` +
+                                    `Your task: "${agentTask.slice(0, 500)}"\n\n` +
+                                    `Instructions:\n` +
+                                    `- Focus exclusively on your assigned task.\n` +
+                                    `- Your final response will be automatically forwarded to the parent agent.\n` +
+                                    `- Be thorough but concise — the parent will synthesize results from multiple agents.\n` +
+                                    `- Do NOT ask the user for input — you are autonomous.\n` +
+                                    `- You are autonomous and goal-driven. If the task implies ongoing monitoring or follow-through until done, keep yourself alive with durable timers until the goal is complete or you can no longer make progress.\n` +
+                                    `- If it is ambiguous whether the task should become a long-running recurring workflow, report that ambiguity back to the parent instead of guessing or asking the user directly.\n` +
+                                    `- When your task is complete, provide a clear summary of your findings/results.\n` +
+                                    `- Prefer using \`store_fact\` for larger structured context handoffs across your session lineage. Put the durable details in facts, then pass fact keys or \`read_facts\` pointers in messages/prompts instead of pasting large context blobs.\n` +
+                                    `- If you write any files with write_artifact, you MUST also call export_artifact and include the artifact:// link in your response.\n` +
+                                    `- If you override a sub-agent model, you MUST first call list_available_models in this session and use only an exact provider:model value returned there. ` +
+                                    `NEVER invent, guess, shorten, or reuse a stale model name.\n` +
+                                    `- Worker-managed system agents are not valid spawn targets. If you expect one and it is missing, report that the workers likely need to be restarted.\n` +
+                                    `- For ANY waiting, sleeping, delaying, or scheduling, you MUST use the \`wait\`, \`wait_on_worker\`, \`cron\`, or \`cron_at\` tools. ` +
+                                    `Use \`wait\` or \`wait_on_worker\` for one-shot delays. Use \`cron\` for fixed recurring intervals and \`cron_at\` for wall-clock schedules. ` +
+                                    `Do NOT implement wall-clock schedules by waking every N minutes to check the clock; use \`cron_at\` with an explicit IANA timezone instead. ` +
+                                    `Do NOT burn tokens polling inside one LLM turn; after a brief immediate re-check at most, yield with a durable timer. ` +
+                                    `NEVER use setTimeout, sleep, setInterval, or any other timing mechanism.\n` +
+                                    (canSpawnMore
+                                        ? `- If your parent task explicitly asks you to spawn sub-agents, delegate, fan out, or parallelize work, you SHOULD do so within runtime limits instead of collapsing the task into a direct answer. ` +
+                                            `If delegation was not explicitly requested, use your judgment and avoid unnecessary fan-out. ` +
+                                            `You have ${MAX_NESTING_LEVEL - childNestingLevel} level(s) of nesting remaining. After spawning, call wait_for_agents to block until they finish.\n`
+                                        : `- You CANNOT spawn sub-agents — you are at the maximum nesting depth. Handle everything directly.\n`);
+                                childConfig.systemMessage = subAgentPreamble + (parentSystemMsg ? "\n\n" + parentSystemMsg : "");
+                                const sdkClient = await getInlineClient();
+                                const normalizedModel = sessionManager.normalizeModelRef(childConfig.model);
+                                if (normalizedModel)
+                                    childConfig.model = normalizedModel;
+                                const childSession = await sdkClient.createSession({
+                                    parentSessionId: input.sessionId,
+                                    nestingLevel: childNestingLevel,
+                                    model: childConfig.model,
+                                    reasoningEffort: childConfig.reasoningEffort,
+                                    systemMessage: childConfig.systemMessage,
+                                    boundAgentName: childConfig.boundAgentName,
+                                    promptLayering: childConfig.promptLayering,
+                                    toolNames: childConfig.toolNames,
+                                    waitThreshold: childConfig.waitThreshold,
+                                    agentId,
+                                });
+                                if (catalog) {
+                                    const meta = {};
+                                    if (agentTitle) {
+                                        meta.title = (agentTitleIsExplicit || agentIsSystem)
+                                            ? agentTitle
+                                            : `${agentTitle}: ${childSession.sessionId.slice(0, 8)}`;
+                                    }
+                                    if (agentId)
+                                        meta.agentId = agentId;
+                                    if (agentSplash)
+                                        meta.splash = agentSplash;
+                                    if (agentSplashMobile)
+                                        meta.splashMobile = agentSplashMobile;
+                                    if (Object.keys(meta).length > 0) {
+                                        // Best-effort: child has been created and is about to be
+                                        // sent its bootstrap. A failed meta update means the row
+                                        // is missing title/agentId/splash, not that the spawn
+                                        // failed. Don't escalate to a thrown spawn_agent.
+                                        const capturedMeta = meta;
+                                        await cmsRetryBestEffort(`runTurn.spawn.updateSession meta session=${childSession.sessionId}`, () => catalog.updateSession(childSession.sessionId, capturedMeta), (msg) => activityCtx.traceInfo(msg));
+                                    }
+                                    const contractJson = buildContractJson(args.contract, input.sessionId, childSession.sessionId);
+                                    if (contractJson) {
+                                        await cmsRetryCritical(`runTurn.spawn.upsertChildOutcome contract child=${childSession.sessionId}`, () => catalog.upsertChildOutcome({
+                                            childSessionId: childSession.sessionId,
+                                            parentSessionId: input.sessionId,
+                                            contractJson,
+                                        }), (msg) => activityCtx.traceInfo(msg));
+                                    }
+                                }
+                                await childSession.send(agentTask, { bootstrap: true });
+                                if (catalog) {
+                                    await cmsRetryBestEffort(`runTurn.spawn.recordEvent agent_spawned session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
+                                            eventType: "session.agent_spawned",
+                                            data: { childSessionId: childSession.sessionId, agentId: agentId || undefined, task: agentTask.slice(0, 500) },
+                                        }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
+                                }
+                                const childOrchId = `session-${childSession.sessionId}`;
+                                return `[SYSTEM: Sub-agent spawned successfully.\n` +
+                                    `  Agent ID: ${childOrchId}\n` +
+                                    `  ${resolvedAgentName ? `Agent: ${resolvedAgentName}\n  ` : ``}Task: "${agentTask.slice(0, 200)}"\n` +
+                                    `  The agent is now running autonomously. Continue your work in this SAME turn and keep following the user's remaining steps. ` +
+                                    `Do NOT stop just because the child started. If your plan says to pause, call wait or wait_for_agents explicitly. ` +
+                                    `You can also use check_agents to poll status, ` +
+                                    `or message_agent to send instructions.]`;
                             }
-                            if (agentModel && !agentModel.includes(":")) {
-                                return `[SYSTEM: spawn_agent failed — model "${agentModel}" is not allowed. ` +
-                                    `When overriding a sub-agent model, first call list_available_models and then use the exact provider:model value from that list. ` +
-                                    `If you are unsure, omit model so the sub-agent inherits your current model.]`;
+                            catch (err) {
+                                return `[SYSTEM: spawn_agent failed: ${err?.message || String(err)}]`;
                             }
-                            // v1.0.49: same-name duplicate spawns are allowed. The
-                            // global MAX_SUB_AGENTS cap and per-spawn nesting limit
-                            // still apply. The parent is responsible for closing
-                            // each instance with complete_agent / cancel_agent /
-                            // delete_agent when it no longer needs the child.
-                            const { boundAgentName: _parentBoundAgentName, promptLayering: _parentPromptLayering, isCrawler: _parentIsCrawler, isHarvester: _parentIsHarvester, ...parentConfig } = input.config;
-                            const childConfig = {
-                                ...parentConfig,
-                                ...(agentModel ? { model: agentModel } : {}),
-                                ...(agentReasoningEffort ? { reasoningEffort: agentReasoningEffort } : {}),
-                                ...(agentSystemMessage ? { systemMessage: agentSystemMessage } : {}),
-                                ...(boundAgentName ? { boundAgentName } : {}),
-                                ...(promptLayeringKind ? { promptLayering: { kind: promptLayeringKind } } : {}),
-                                ...(agentToolNames ? { toolNames: agentToolNames } : {}),
-                                ...(args.contract ? { childContract: args.contract } : {}),
-                            };
-                            const parentSystemMsg = typeof childConfig.systemMessage === "string"
-                                ? childConfig.systemMessage
-                                : childConfig.systemMessage?.content ?? "";
-                            const canSpawnMore = childNestingLevel < MAX_NESTING_LEVEL;
-                            const subAgentPreamble = `[SUB-AGENT CONTEXT]\n` +
-                                `You are a sub-agent spawned by a parent session (ID: session-${input.sessionId}).\n` +
-                                `Your nesting level: ${childNestingLevel} (max: ${MAX_NESTING_LEVEL}).\n` +
-                                `Your task: "${agentTask.slice(0, 500)}"\n\n` +
-                                `Instructions:\n` +
-                                `- Focus exclusively on your assigned task.\n` +
-                                `- Your final response will be automatically forwarded to the parent agent.\n` +
-                                `- Be thorough but concise — the parent will synthesize results from multiple agents.\n` +
-                                `- Do NOT ask the user for input — you are autonomous.\n` +
-                                `- You are autonomous and goal-driven. If the task implies ongoing monitoring or follow-through until done, keep yourself alive with durable timers until the goal is complete or you can no longer make progress.\n` +
-                                `- If it is ambiguous whether the task should become a long-running recurring workflow, report that ambiguity back to the parent instead of guessing or asking the user directly.\n` +
-                                `- When your task is complete, provide a clear summary of your findings/results.\n` +
-                                `- Prefer using \`store_fact\` for larger structured context handoffs across your session lineage. Put the durable details in facts, then pass fact keys or \`read_facts\` pointers in messages/prompts instead of pasting large context blobs.\n` +
-                                `- If you write any files with write_artifact, you MUST also call export_artifact and include the artifact:// link in your response.\n` +
-                                `- If you override a sub-agent model, you MUST first call list_available_models in this session and use only an exact provider:model value returned there. ` +
-                                `NEVER invent, guess, shorten, or reuse a stale model name.\n` +
-                                `- Worker-managed system agents are not valid spawn targets. If you expect one and it is missing, report that the workers likely need to be restarted.\n` +
-                                `- For ANY waiting, sleeping, delaying, or scheduling, you MUST use the \`wait\`, \`wait_on_worker\`, \`cron\`, or \`cron_at\` tools. ` +
-                                `Use \`wait\` or \`wait_on_worker\` for one-shot delays. Use \`cron\` for fixed recurring intervals and \`cron_at\` for wall-clock schedules. ` +
-                                `Do NOT implement wall-clock schedules by waking every N minutes to check the clock; use \`cron_at\` with an explicit IANA timezone instead. ` +
-                                `Do NOT burn tokens polling inside one LLM turn; after a brief immediate re-check at most, yield with a durable timer. ` +
-                                `NEVER use setTimeout, sleep, setInterval, or any other timing mechanism.\n` +
-                                (canSpawnMore
-                                    ? `- If your parent task explicitly asks you to spawn sub-agents, delegate, fan out, or parallelize work, you SHOULD do so within runtime limits instead of collapsing the task into a direct answer. ` +
-                                        `If delegation was not explicitly requested, use your judgment and avoid unnecessary fan-out. ` +
-                                        `You have ${MAX_NESTING_LEVEL - childNestingLevel} level(s) of nesting remaining. After spawning, call wait_for_agents to block until they finish.\n`
-                                    : `- You CANNOT spawn sub-agents — you are at the maximum nesting depth. Handle everything directly.\n`);
-                            childConfig.systemMessage = subAgentPreamble + (parentSystemMsg ? "\n\n" + parentSystemMsg : "");
-                            const sdkClient = await getInlineClient();
-                            const normalizedModel = sessionManager.normalizeModelRef(childConfig.model);
-                            if (normalizedModel)
-                                childConfig.model = normalizedModel;
-                            const childSession = await sdkClient.createSession({
-                                parentSessionId: input.sessionId,
-                                nestingLevel: childNestingLevel,
-                                model: childConfig.model,
-                                reasoningEffort: childConfig.reasoningEffort,
-                                systemMessage: childConfig.systemMessage,
-                                boundAgentName: childConfig.boundAgentName,
-                                promptLayering: childConfig.promptLayering,
-                                toolNames: childConfig.toolNames,
-                                waitThreshold: childConfig.waitThreshold,
-                                agentId,
-                            });
-                            if (catalog) {
-                                const meta = {};
-                                if (agentTitle) {
-                                    meta.title = (agentTitleIsExplicit || agentIsSystem)
-                                        ? agentTitle
-                                        : `${agentTitle}: ${childSession.sessionId.slice(0, 8)}`;
-                                }
-                                if (agentId)
-                                    meta.agentId = agentId;
-                                if (agentSplash)
-                                    meta.splash = agentSplash;
-                                if (Object.keys(meta).length > 0) {
-                                    // Best-effort: child has been created and is about to be
-                                    // sent its bootstrap. A failed meta update means the row
-                                    // is missing title/agentId/splash, not that the spawn
-                                    // failed. Don't escalate to a thrown spawn_agent.
-                                    const capturedMeta = meta;
-                                    await cmsRetryBestEffort(`runTurn.spawn.updateSession meta session=${childSession.sessionId}`, () => catalog.updateSession(childSession.sessionId, capturedMeta), (msg) => activityCtx.traceInfo(msg));
+                        },
+                        setSessionModel: async (args) => {
+                            try {
+                                const requestedModel = String(args.model || "").trim();
+                                if (!requestedModel)
+                                    return "[SYSTEM: set_session_model failed: model is required.]";
+                                if (!storeUrl)
+                                    return "[SYSTEM: set_session_model failed: no storeUrl is configured.]";
+                                const resolved = sessionManager.resolveModelSwitchConfig(requestedModel, "reasoning_effort" in args ? args.reasoning_effort ?? null : undefined);
+                                const sdkClient = new PilotSwarmClient(internalClientConfig());
+                                try {
+                                    await sdkClient.start();
+                                    await sdkClient.duroxideClient.enqueueEvent(`session-${input.sessionId}`, "messages", JSON.stringify({
+                                        type: "cmd",
+                                        cmd: "set_model",
+                                        id: `set-model-tool-${randomUUID()}`,
+                                        args: {
+                                            model: resolved.model,
+                                            reasoningEffort: resolved.reasoningEffort,
+                                            source: "tool",
+                                        },
+                                    }));
                                 }
-                                const contractJson = buildContractJson(args.contract, input.sessionId, childSession.sessionId);
-                                if (contractJson) {
-                                    await cmsRetryCritical(`runTurn.spawn.upsertChildOutcome contract child=${childSession.sessionId}`, () => catalog.upsertChildOutcome({
-                                        childSessionId: childSession.sessionId,
-                                        parentSessionId: input.sessionId,
-                                        contractJson,
-                                    }), (msg) => activityCtx.traceInfo(msg));
+                                finally {
+                                    await sdkClient.stop().catch(() => { });
                                 }
+                                const effortText = resolved.reasoningEffort ? `:${resolved.reasoningEffort}` : "";
+                                return `[SYSTEM: Model switch accepted. Stop this turn now; the runtime will automatically continue on ${resolved.model}${effortText}.]`;
                             }
-                            await childSession.send(agentTask, { bootstrap: true });
-                            if (catalog) {
-                                await cmsRetryBestEffort(`runTurn.spawn.recordEvent agent_spawned session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
-                                        eventType: "session.agent_spawned",
-                                        data: { childSessionId: childSession.sessionId, agentId: agentId || undefined, task: agentTask.slice(0, 500) },
-                                    }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
+                            catch (err) {
+                                return `[SYSTEM: set_session_model failed: ${err?.message || String(err)}]`;
                             }
-                            const childOrchId = `session-${childSession.sessionId}`;
-                            return `[SYSTEM: Sub-agent spawned successfully.\n` +
-                                `  Agent ID: ${childOrchId}\n` +
-                                `  ${resolvedAgentName ? `Agent: ${resolvedAgentName}\n  ` : ``}Task: "${agentTask.slice(0, 200)}"\n` +
-                                `  The agent is now running autonomously. Continue your work in this SAME turn and keep following the user's remaining steps. ` +
-                                `Do NOT stop just because the child started. If your plan says to pause, call wait or wait_for_agents explicitly. ` +
-                                `You can also use check_agents to poll status, ` +
-                                `or message_agent to send instructions.]`;
-                        }
-                        catch (err) {
-                            return `[SYSTEM: spawn_agent failed: ${err?.message || String(err)}]`;
-                        }
-                    },
-                    setSessionModel: async (args) => {
-                        try {
-                            const requestedModel = String(args.model || "").trim();
-                            if (!requestedModel)
-                                return "[SYSTEM: set_session_model failed: model is required.]";
-                            if (!storeUrl)
-                                return "[SYSTEM: set_session_model failed: no storeUrl is configured.]";
-                            const resolved = sessionManager.resolveModelSwitchConfig(requestedModel, "reasoning_effort" in args ? args.reasoning_effort ?? null : undefined);
-                            const sdkClient = new PilotSwarmClient(internalClientConfig());
+                        },
+                        messageAgent: async (args) => {
                             try {
-                                await sdkClient.start();
-                                await sdkClient.duroxideClient.enqueueEvent(`session-${input.sessionId}`, "messages", JSON.stringify({
-                                    type: "cmd",
-                                    cmd: "set_model",
-                                    id: `set-model-tool-${randomUUID()}`,
-                                    args: {
-                                        model: resolved.model,
-                                        reasoningEffort: resolved.reasoningEffort,
-                                        source: "tool",
-                                    },
-                                }));
+                                const child = await resolveManagedChild(args.agent_id);
+                                if (catalog && args.contract_patch) {
+                                    const existing = await catalog.getChildOutcome(child.sessionId);
+                                    const contractJson = appendContractPatchJson(existing?.contractJson ?? null, args.contract_patch, input.sessionId, child.sessionId);
+                                    if (contractJson) {
+                                        await cmsRetryCritical(`runTurn.message.upsertChildOutcome contract child=${child.sessionId}`, () => catalog.upsertChildOutcome({
+                                            childSessionId: child.sessionId,
+                                            parentSessionId: input.sessionId,
+                                            contractJson,
+                                        }), (msg) => activityCtx.traceInfo(msg));
+                                    }
+                                }
+                                const sdkClient = await getInlineClient();
+                                await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ prompt: args.message }));
+                                return `[SYSTEM: Message sent to sub-agent ${child.orchId}: "${args.message.slice(0, 200)}". ` +
+                                    `Continue your work in this SAME turn. If you are waiting on the child, call wait_for_agents explicitly rather than stopping here.]`;
                             }
-                            finally {
-                                await sdkClient.stop().catch(() => { });
+                            catch (err) {
+                                return `[SYSTEM: message_agent failed: ${err?.message || String(err)}]`;
                             }
-                            const effortText = resolved.reasoningEffort ? `:${resolved.reasoningEffort}` : "";
-                            return `[SYSTEM: Model switch accepted. Stop this turn now; the runtime will automatically continue on ${resolved.model}${effortText}.]`;
-                        }
-                        catch (err) {
-                            return `[SYSTEM: set_session_model failed: ${err?.message || String(err)}]`;
-                        }
-                    },
-                    messageAgent: async (args) => {
-                        try {
-                            const child = await resolveManagedChild(args.agent_id);
-                            if (catalog && args.contract_patch) {
-                                const existing = await catalog.getChildOutcome(child.sessionId);
-                                const contractJson = appendContractPatchJson(existing?.contractJson ?? null, args.contract_patch, input.sessionId, child.sessionId);
-                                if (contractJson) {
-                                    await cmsRetryCritical(`runTurn.message.upsertChildOutcome contract child=${child.sessionId}`, () => catalog.upsertChildOutcome({
-                                        childSessionId: child.sessionId,
-                                        parentSessionId: input.sessionId,
-                                        contractJson,
-                                    }), (msg) => activityCtx.traceInfo(msg));
+                        },
+                        checkAgents: async () => {
+                            try {
+                                const children = (await loadDirectChildSessions()).filter(child => !child.isSystem);
+                                if (children.length === 0) {
+                                    return `[SYSTEM: No sub-agents have been spawned yet.]`;
                                 }
+                                const statusLines = children.map((agent) => `  - Agent ${agent.orchId}\n` +
+                                    `    Title: ${agent.title ?? "(untitled)"}\n` +
+                                    `    Status: ${agent.status}\n` +
+                                    `    Contract: ${agent.contractStatus ?? "none"}\n` +
+                                    `    Verdict: ${agent.verdict ?? "none"}\n` +
+                                    `    Iterations: ${agent.iterations ?? 0}\n` +
+                                    (Array.isArray(agent.contractViolations) && agent.contractViolations.length > 0
+                                        ? `    Violations: ${agent.contractViolations.map((v) => v?.code || v?.message || "violation").join(", ")}\n`
+                                        : "") +
+                                    `    Output: ${agent.result ?? agent.error ?? "(no output yet)"}`);
+                                return `[SYSTEM: Sub-agent status report (${children.length} agents):\n${statusLines.join("\n")}]`;
                             }
-                            const sdkClient = await getInlineClient();
-                            await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ prompt: args.message }));
-                            return `[SYSTEM: Message sent to sub-agent ${child.orchId}: "${args.message.slice(0, 200)}". ` +
-                                `Continue your work in this SAME turn. If you are waiting on the child, call wait_for_agents explicitly rather than stopping here.]`;
-                        }
-                        catch (err) {
-                            return `[SYSTEM: message_agent failed: ${err?.message || String(err)}]`;
-                        }
-                    },
-                    checkAgents: async () => {
-                        try {
+                            catch (err) {
+                                return `[SYSTEM: check_agents failed: ${err?.message || String(err)}]`;
+                            }
+                        },
+                        resolveWaitForAgents: async (agentIds) => {
                             const children = (await loadDirectChildSessions()).filter(child => !child.isSystem);
-                            if (children.length === 0) {
-                                return `[SYSTEM: No sub-agents have been spawned yet.]`;
+                            if (agentIds && agentIds.length > 0) {
+                                return await Promise.all(agentIds.map(async (agentId) => (await resolveManagedChild(agentId)).orchId));
                             }
-                            const statusLines = children.map((agent) => `  - Agent ${agent.orchId}\n` +
-                                `    Title: ${agent.title ?? "(untitled)"}\n` +
-                                `    Status: ${agent.status}\n` +
-                                `    Contract: ${agent.contractStatus ?? "none"}\n` +
-                                `    Verdict: ${agent.verdict ?? "none"}\n` +
-                                `    Iterations: ${agent.iterations ?? 0}\n` +
-                                (Array.isArray(agent.contractViolations) && agent.contractViolations.length > 0
-                                    ? `    Violations: ${agent.contractViolations.map((v) => v?.code || v?.message || "violation").join(", ")}\n`
-                                    : "") +
-                                `    Output: ${agent.result ?? agent.error ?? "(no output yet)"}`);
-                            return `[SYSTEM: Sub-agent status report (${children.length} agents):\n${statusLines.join("\n")}]`;
-                        }
-                        catch (err) {
-                            return `[SYSTEM: check_agents failed: ${err?.message || String(err)}]`;
-                        }
-                    },
-                    resolveWaitForAgents: async (agentIds) => {
-                        const children = (await loadDirectChildSessions()).filter(child => !child.isSystem);
-                        if (agentIds && agentIds.length > 0) {
-                            return await Promise.all(agentIds.map(async (agentId) => (await resolveManagedChild(agentId)).orchId));
-                        }
-                        const running = children.filter(child => child.status === "running").map(child => child.orchId);
-                        return running.length > 0 ? running : children.map(child => child.orchId);
-                    },
-                    listSessions: async (args) => {
-                        try {
-                            const sdkClient = await getInlineClient();
-                            const effectiveArgs = sanitizeAutonomousSystemSessionFilters(args);
-                            const limit = Math.max(1, Math.min(100, Number(effectiveArgs?.limit) || 50));
-                            const query = String(effectiveArgs?.query || "").trim().toLowerCase();
-                            const exactSessionId = String(effectiveArgs?.session_id || "").replace(/^session-/, "");
-                            const agentId = String(effectiveArgs?.agent_id || "").trim();
-                            const state = String(effectiveArgs?.state || "").trim().toLowerCase();
-                            const parentSessionId = String(effectiveArgs?.parent_session_id || "").replace(/^session-/, "");
-                            const groupFilterRaw = effectiveArgs?.group_id;
-                            const groupFilter = typeof groupFilterRaw === "string" ? groupFilterRaw.trim() : undefined;
-                            const includeChildren = effectiveArgs?.include_children === true;
-                            const updatedSince = Date.parse(String(effectiveArgs?.updated_since || ""));
-                            const summaryUpdatedSince = Date.parse(String(effectiveArgs?.summary_updated_since || ""));
-                            const sessions = (await sdkClient.listSessions()).filter((session) => matchesSessionOwnerFilters(session, {
-                                includeSystem: effectiveArgs?.include_system === true,
-                                ownerQuery: effectiveArgs?.owner_query,
-                                ownerKind: effectiveArgs?.owner_kind,
-                            })).filter((session) => {
-                                if (!includeChildren && session.parentSessionId)
-                                    return false;
-                                if (exactSessionId && session.sessionId !== exactSessionId)
-                                    return false;
-                                if (agentId && session.agentId !== agentId)
-                                    return false;
-                                if (state && String(session.status || "").toLowerCase() !== state)
-                                    return false;
-                                if (parentSessionId && session.parentSessionId !== parentSessionId)
-                                    return false;
-                                if (groupFilter === "null" && session.groupId)
-                                    return false;
-                                if (groupFilter && groupFilter !== "null" && session.groupId !== groupFilter)
-                                    return false;
-                                if (Number.isFinite(updatedSince)) {
-                                    const updatedAt = Date.parse(session.updatedAt || session.lastActiveAt || session.createdAt || "");
-                                    if (!Number.isFinite(updatedAt) || updatedAt < updatedSince)
+                            const running = children.filter(child => child.status === "running").map(child => child.orchId);
+                            return running.length > 0 ? running : children.map(child => child.orchId);
+                        },
+                        listSessions: async (args) => {
+                            try {
+                                const sdkClient = await getInlineClient();
+                                const effectiveArgs = sanitizeAutonomousSystemSessionFilters(args);
+                                const limit = Math.max(1, Math.min(100, Number(effectiveArgs?.limit) || 50));
+                                const query = String(effectiveArgs?.query || "").trim().toLowerCase();
+                                const exactSessionId = String(effectiveArgs?.session_id || "").replace(/^session-/, "");
+                                const agentId = String(effectiveArgs?.agent_id || "").trim();
+                                const state = String(effectiveArgs?.state || "").trim().toLowerCase();
+                                const parentSessionId = String(effectiveArgs?.parent_session_id || "").replace(/^session-/, "");
+                                const groupFilterRaw = effectiveArgs?.group_id;
+                                const groupFilter = typeof groupFilterRaw === "string" ? groupFilterRaw.trim() : undefined;
+                                const includeChildren = effectiveArgs?.include_children === true;
+                                const updatedSince = Date.parse(String(effectiveArgs?.updated_since || ""));
+                                const summaryUpdatedSince = Date.parse(String(effectiveArgs?.summary_updated_since || ""));
+                                const sessions = (await sdkClient.listSessions()).filter((session) => matchesSessionOwnerFilters(session, {
+                                    includeSystem: effectiveArgs?.include_system === true,
+                                    ownerQuery: effectiveArgs?.owner_query,
+                                    ownerKind: effectiveArgs?.owner_kind,
+                                })).filter((session) => {
+                                    if (!includeChildren && session.parentSessionId)
                                         return false;
-                                }
-                                if (Number.isFinite(summaryUpdatedSince)) {
-                                    const summaryUpdatedAt = Date.parse(session.summaryUpdatedAt || "");
-                                    if (!Number.isFinite(summaryUpdatedAt) || summaryUpdatedAt < summaryUpdatedSince)
+                                    if (exactSessionId && session.sessionId !== exactSessionId)
                                         return false;
-                                }
-                                if (query) {
-                                    const haystack = [
-                                        session.sessionId,
-                                        session.title,
-                                        session.agentId,
-                                        session.shortSummary,
-                                        session.summaryState?.intent,
-                                        session.summaryState?.summary,
-                                        formatSessionOwnerLabel(session),
-                                    ].map((part) => String(part || "").toLowerCase()).join(" ");
-                                    if (!haystack.includes(query))
+                                    if (agentId && session.agentId !== agentId)
+                                        return false;
+                                    if (state && String(session.status || "").toLowerCase() !== state)
+                                        return false;
+                                    if (parentSessionId && session.parentSessionId !== parentSessionId)
+                                        return false;
+                                    if (groupFilter === "null" && session.groupId)
                                         return false;
+                                    if (groupFilter && groupFilter !== "null" && session.groupId !== groupFilter)
+                                        return false;
+                                    if (Number.isFinite(updatedSince)) {
+                                        const updatedAt = Date.parse(session.updatedAt || session.lastActiveAt || session.createdAt || "");
+                                        if (!Number.isFinite(updatedAt) || updatedAt < updatedSince)
+                                            return false;
+                                    }
+                                    if (Number.isFinite(summaryUpdatedSince)) {
+                                        const summaryUpdatedAt = Date.parse(session.summaryUpdatedAt || "");
+                                        if (!Number.isFinite(summaryUpdatedAt) || summaryUpdatedAt < summaryUpdatedSince)
+                                            return false;
+                                    }
+                                    if (query) {
+                                        const haystack = [
+                                            session.sessionId,
+                                            session.title,
+                                            session.agentId,
+                                            session.shortSummary,
+                                            session.summaryState?.intent,
+                                            session.summaryState?.summary,
+                                            formatSessionOwnerLabel(session),
+                                        ].map((part) => String(part || "").toLowerCase()).join(" ");
+                                        if (!haystack.includes(query))
+                                            return false;
+                                    }
+                                    return true;
+                                }).slice(0, limit);
+                                if (sessions.length === 0) {
+                                    return "[SYSTEM: Active sessions (0). No sessions matched the requested filters.]";
                                 }
-                                return true;
-                            }).slice(0, limit);
-                            if (sessions.length === 0) {
-                                return "[SYSTEM: Active sessions (0). No sessions matched the requested filters.]";
+                                const lines = sessions.map((s) => `  - ${s.sessionId}${s.sessionId === input.sessionId ? " (this session)" : ""}\n` +
+                                    `    Title: ${s.title ?? "(untitled)"}\n` +
+                                    `    Owner: ${formatSessionOwnerLabel(s)}\n` +
+                                    `    Agent: ${s.agentId ?? "generic"}\n` +
+                                    `    Group: ${s.groupId ?? "none"}\n` +
+                                    `    Summary: ${s.shortSummary ?? s.summaryState?.summary ?? "(no summary)"}\n` +
+                                    `    Summary Updated: ${s.summaryUpdatedAt ? new Date(s.summaryUpdatedAt).toISOString() : "never"}\n` +
+                                    `    Status: ${s.status}, Iterations: ${s.iterations ?? 0}\n` +
+                                    `    Parent: ${s.parentSessionId ?? "none"}`);
+                                return `[SYSTEM: Active sessions (${sessions.length}):\n${lines.join("\n")}]`;
                             }
-                            const lines = sessions.map((s) => `  - ${s.sessionId}${s.sessionId === input.sessionId ? " (this session)" : ""}\n` +
-                                `    Title: ${s.title ?? "(untitled)"}\n` +
-                                `    Owner: ${formatSessionOwnerLabel(s)}\n` +
-                                `    Agent: ${s.agentId ?? "generic"}\n` +
-                                `    Group: ${s.groupId ?? "none"}\n` +
-                                `    Summary: ${s.shortSummary ?? s.summaryState?.summary ?? "(no summary)"}\n` +
-                                `    Summary Updated: ${s.summaryUpdatedAt ? new Date(s.summaryUpdatedAt).toISOString() : "never"}\n` +
-                                `    Status: ${s.status}, Iterations: ${s.iterations ?? 0}\n` +
-                                `    Parent: ${s.parentSessionId ?? "none"}`);
-                            return `[SYSTEM: Active sessions (${sessions.length}):\n${lines.join("\n")}]`;
-                        }
-                        catch (err) {
-                            return `[SYSTEM: list_sessions failed: ${err?.message || String(err)}]`;
-                        }
-                    },
-                    updateSessionSummary: async (args) => {
-                        try {
-                            if (isReadOnlyTuner())
-                                return `[SYSTEM: update_session_summary is disabled for read-only agent-tuner sessions.]`;
-                            if (!catalog)
-                                return `[SYSTEM: update_session_summary failed: CMS catalog is unavailable.]`;
-                            const hasSummaryState = Object.prototype.hasOwnProperty.call(args ?? {}, "summary_state") && args.summary_state !== undefined && args.summary_state !== null;
-                            const hasTitle = Object.prototype.hasOwnProperty.call(args ?? {}, "title");
-                            if (!hasSummaryState && !hasTitle) {
-                                return `[SYSTEM: update_session_summary failed: summary_state or title is required.]`;
+                            catch (err) {
+                                return `[SYSTEM: list_sessions failed: ${err?.message || String(err)}]`;
                             }
-                            let normalizedSummary;
-                            if (hasSummaryState) {
-                                const summaryResult = normalizeSummaryState(args.summary_state);
-                                if (!summaryResult.ok)
-                                    return `[SYSTEM: update_session_summary failed: ${summaryResult.message}]`;
-                                normalizedSummary = summaryResult;
+                        },
+                        updateSessionSummary: async (args) => {
+                            try {
+                                if (isReadOnlyTuner())
+                                    return `[SYSTEM: update_session_summary is disabled for read-only agent-tuner sessions.]`;
+                                if (!catalog)
+                                    return `[SYSTEM: update_session_summary failed: CMS catalog is unavailable.]`;
+                                const hasSummaryState = Object.prototype.hasOwnProperty.call(args ?? {}, "summary_state") && args.summary_state !== undefined && args.summary_state !== null;
+                                const hasTitle = Object.prototype.hasOwnProperty.call(args ?? {}, "title");
+                                if (!hasSummaryState && !hasTitle) {
+                                    return `[SYSTEM: update_session_summary failed: summary_state or title is required.]`;
+                                }
+                                let normalizedSummary;
+                                if (hasSummaryState) {
+                                    const summaryResult = normalizeSummaryState(args.summary_state);
+                                    if (!summaryResult.ok)
+                                        return `[SYSTEM: update_session_summary failed: ${summaryResult.message}]`;
+                                    normalizedSummary = summaryResult;
+                                }
+                                const titleUpdate = hasTitle
+                                    ? await prepareStickySessionTitleUpdate(catalog, input.sessionId, args.title)
+                                    : undefined;
+                                if (titleUpdate && !titleUpdate.ok)
+                                    return `[SYSTEM: update_session_summary failed: ${titleUpdate.message}]`;
+                                const updated = [];
+                                if (normalizedSummary) {
+                                    await catalog.updateSessionSummary(input.sessionId, normalizedSummary.summaryState, args.short_summary);
+                                    updated.push("summary");
+                                }
+                                if (titleUpdate?.ok) {
+                                    await catalog.updateSession(input.sessionId, titleUpdate.updates);
+                                    updated.push("title");
+                                }
+                                return `[SYSTEM: Session ${updated.join(" and ")} updated.]`;
                             }
-                            const titleUpdate = hasTitle
-                                ? await prepareStickySessionTitleUpdate(catalog, input.sessionId, args.title)
-                                : undefined;
-                            if (titleUpdate && !titleUpdate.ok)
-                                return `[SYSTEM: update_session_summary failed: ${titleUpdate.message}]`;
-                            const updated = [];
-                            if (normalizedSummary) {
-                                await catalog.updateSessionSummary(input.sessionId, normalizedSummary.summaryState, args.short_summary);
-                                updated.push("summary");
+                            catch (err) {
+                                return `[SYSTEM: update_session_summary failed: ${err?.message || String(err)}]`;
                             }
-                            if (titleUpdate?.ok) {
-                                await catalog.updateSession(input.sessionId, titleUpdate.updates);
-                                updated.push("title");
+                        },
+                        sendSessionMessage: async (args) => {
+                            try {
+                                if (isReadOnlyTuner())
+                                    return `[SYSTEM: send_session_message is disabled for read-only agent-tuner sessions.]`;
+                                const targetSessionId = String(args.session_id || "").replace(/^session-/, "");
+                                if (!targetSessionId)
+                                    return `[SYSTEM: send_session_message failed: session_id is required.]`;
+                                if (targetSessionId === input.sessionId)
+                                    return `[SYSTEM: send_session_message failed: target session is this session.]`;
+                                if (!args.subject?.trim() || !args.body?.trim())
+                                    return `[SYSTEM: send_session_message failed: subject and body are required.]`;
+                                if (args.body.length > 8192)
+                                    return `[SYSTEM: send_session_message failed: body exceeds 8 KB.]`;
+                                if (!catalog)
+                                    return `[SYSTEM: send_session_message failed: CMS catalog is unavailable.]`;
+                                const sdkClient = await getInlineClient();
+                                const allowedReasons = new Set(["help", "guidance", "fact-request", "status-request", "handoff"]);
+                                const reason = allowedReasons.has(String(args.reason || "")) ? args.reason : undefined;
+                                const { requestId } = await sendInternalSessionMessage({
+                                    catalog,
+                                    duroxideClient: sdkClient._getDuroxideClient(),
+                                }, {
+                                    fromSessionId: input.sessionId,
+                                    toSessionId: targetSessionId,
+                                    subject: args.subject,
+                                    body: args.body,
+                                    reason,
+                                    expectsResponse: args.expects_response === true,
+                                    expiresAt: args.expires_at,
+                                });
+                                return `[SYSTEM: Cross-session message queued. Request ID: ${requestId}. Target: session-${targetSessionId}.]`;
                             }
-                            return `[SYSTEM: Session ${updated.join(" and ")} updated.]`;
-                        }
-                        catch (err) {
-                            return `[SYSTEM: update_session_summary failed: ${err?.message || String(err)}]`;
-                        }
-                    },
-                    sendSessionMessage: async (args) => {
-                        try {
-                            if (isReadOnlyTuner())
-                                return `[SYSTEM: send_session_message is disabled for read-only agent-tuner sessions.]`;
-                            const targetSessionId = String(args.session_id || "").replace(/^session-/, "");
-                            if (!targetSessionId)
-                                return `[SYSTEM: send_session_message failed: session_id is required.]`;
-                            if (targetSessionId === input.sessionId)
-                                return `[SYSTEM: send_session_message failed: target session is this session.]`;
-                            if (!args.subject?.trim() || !args.body?.trim())
-                                return `[SYSTEM: send_session_message failed: subject and body are required.]`;
-                            if (args.body.length > 8192)
-                                return `[SYSTEM: send_session_message failed: body exceeds 8 KB.]`;
-                            if (!catalog)
-                                return `[SYSTEM: send_session_message failed: CMS catalog is unavailable.]`;
-                            const sdkClient = await getInlineClient();
-                            const allowedReasons = new Set(["help", "guidance", "fact-request", "status-request", "handoff"]);
-                            const reason = allowedReasons.has(String(args.reason || "")) ? args.reason : undefined;
-                            const { requestId } = await sendInternalSessionMessage({
-                                catalog,
-                                duroxideClient: sdkClient._getDuroxideClient(),
-                            }, {
-                                fromSessionId: input.sessionId,
-                                toSessionId: targetSessionId,
-                                subject: args.subject,
-                                body: args.body,
-                                reason,
-                                expectsResponse: args.expects_response === true,
-                                expiresAt: args.expires_at,
-                            });
-                            return `[SYSTEM: Cross-session message queued. Request ID: ${requestId}. Target: session-${targetSessionId}.]`;
-                        }
-                        catch (err) {
-                            return `[SYSTEM: send_session_message failed: ${err?.message || String(err)}]`;
-                        }
-                    },
-                    replySessionMessage: async (args) => {
-                        try {
-                            if (isReadOnlyTuner())
-                                return `[SYSTEM: reply_session_message is disabled for read-only agent-tuner sessions.]`;
-                            const targetSessionId = String(args.session_id || "").replace(/^session-/, "");
-                            if (!targetSessionId || !args.request_id || !args.body?.trim())
-                                return `[SYSTEM: reply_session_message failed: request_id, session_id, and body are required.]`;
-                            if (!catalog)
-                                return `[SYSTEM: reply_session_message failed: CMS catalog is unavailable.]`;
-                            const sdkClient = await getInlineClient();
-                            const allowedVerdicts = new Set(["answered", "declined", "blocked", "stale"]);
-                            const verdict = allowedVerdicts.has(String(args.verdict || "")) ? args.verdict : "answered";
-                            await replyInternalSessionMessage({
-                                catalog,
-                                duroxideClient: sdkClient._getDuroxideClient(),
-                            }, {
-                                requestId: args.request_id,
-                                fromSessionId: input.sessionId,
-                                toSessionId: targetSessionId,
-                                verdict,
-                                body: args.body,
-                            });
-                            return `[SYSTEM: Cross-session reply queued for request ${args.request_id}. Target: session-${targetSessionId}.]`;
-                        }
-                        catch (err) {
-                            return `[SYSTEM: reply_session_message failed: ${err?.message || String(err)}]`;
-                        }
-                    },
-                    completeAgent: async (args) => {
-                        try {
-                            const child = await resolveManagedChild(args.agent_id);
-                            let builtOutcome = null;
-                            if (catalog) {
-                                const existing = await catalog.getChildOutcome(child.sessionId).catch(() => null);
-                                const hasExistingResult = Boolean(normalizeJsonObject(existing?.resultJson?.current));
-                                if (args.result || (existing?.contractJson && !hasExistingResult)) {
-                                    builtOutcome = buildResultJson(args.result, child, existing?.contractJson ?? null, existing?.resultJson ?? null, "success", "completed_without_result");
+                            catch (err) {
+                                return `[SYSTEM: send_session_message failed: ${err?.message || String(err)}]`;
+                            }
+                        },
+                        replySessionMessage: async (args) => {
+                            try {
+                                if (isReadOnlyTuner())
+                                    return `[SYSTEM: reply_session_message is disabled for read-only agent-tuner sessions.]`;
+                                const targetSessionId = String(args.session_id || "").replace(/^session-/, "");
+                                if (!targetSessionId || !args.request_id || !args.body?.trim())
+                                    return `[SYSTEM: reply_session_message failed: request_id, session_id, and body are required.]`;
+                                if (!catalog)
+                                    return `[SYSTEM: reply_session_message failed: CMS catalog is unavailable.]`;
+                                const sdkClient = await getInlineClient();
+                                const allowedVerdicts = new Set(["answered", "declined", "blocked", "stale"]);
+                                const verdict = allowedVerdicts.has(String(args.verdict || "")) ? args.verdict : "answered";
+                                await replyInternalSessionMessage({
+                                    catalog,
+                                    duroxideClient: sdkClient._getDuroxideClient(),
+                                }, {
+                                    requestId: args.request_id,
+                                    fromSessionId: input.sessionId,
+                                    toSessionId: targetSessionId,
+                                    verdict,
+                                    body: args.body,
+                                });
+                                return `[SYSTEM: Cross-session reply queued for request ${args.request_id}. Target: session-${targetSessionId}.]`;
+                            }
+                            catch (err) {
+                                return `[SYSTEM: reply_session_message failed: ${err?.message || String(err)}]`;
+                            }
+                        },
+                        completeAgent: async (args) => {
+                            try {
+                                const child = await resolveManagedChild(args.agent_id);
+                                let builtOutcome = null;
+                                if (catalog) {
+                                    const existing = await catalog.getChildOutcome(child.sessionId).catch(() => null);
+                                    const hasExistingResult = Boolean(normalizeJsonObject(existing?.resultJson?.current));
+                                    if (args.result || (existing?.contractJson && !hasExistingResult)) {
+                                        builtOutcome = buildResultJson(args.result, child, existing?.contractJson ?? null, existing?.resultJson ?? null, "success", "completed_without_result");
+                                    }
+                                    if (builtOutcome?.strictBlocked) {
+                                        return `[SYSTEM: complete_agent blocked by strict contract validation for ${child.orchId}: ${builtOutcome.violations.map(v => v.message || v.code).join("; ")}]`;
+                                    }
                                 }
-                                if (builtOutcome?.strictBlocked) {
-                                    return `[SYSTEM: complete_agent blocked by strict contract validation for ${child.orchId}: ${builtOutcome.violations.map(v => v.message || v.code).join("; ")}]`;
+                                if (catalog && builtOutcome) {
+                                    await cmsRetryCritical(`runTurn.complete.upsertChildOutcome result child=${child.sessionId}`, () => catalog.upsertChildOutcome({
+                                        childSessionId: child.sessionId,
+                                        parentSessionId: input.sessionId,
+                                        resultJson: builtOutcome.resultJson,
+                                        verdict: builtOutcome.verdict,
+                                        summary: builtOutcome.summary,
+                                        completedAt: new Date(),
+                                    }), (msg) => activityCtx.traceInfo(msg));
                                 }
+                                const sdkClient = await getInlineClient();
+                                const cmdId = `done-inline-${Date.now()}`;
+                                await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "done", id: cmdId, args: { reason: "Completed by parent" } }));
+                                return `[SYSTEM: Graceful completion requested for sub-agent ${child.orchId}. ` +
+                                    `Use check_agents or wait_for_agents to observe final completion.]`;
                             }
-                            if (catalog && builtOutcome) {
-                                await cmsRetryCritical(`runTurn.complete.upsertChildOutcome result child=${child.sessionId}`, () => catalog.upsertChildOutcome({
-                                    childSessionId: child.sessionId,
-                                    parentSessionId: input.sessionId,
-                                    resultJson: builtOutcome.resultJson,
-                                    verdict: builtOutcome.verdict,
-                                    summary: builtOutcome.summary,
-                                    completedAt: new Date(),
-                                }), (msg) => activityCtx.traceInfo(msg));
+                            catch (err) {
+                                return `[SYSTEM: complete_agent failed: ${err?.message || String(err)}]`;
                             }
-                            const sdkClient = await getInlineClient();
-                            const cmdId = `done-inline-${Date.now()}`;
-                            await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "done", id: cmdId, args: { reason: "Completed by parent" } }));
-                            return `[SYSTEM: Graceful completion requested for sub-agent ${child.orchId}. ` +
-                                `Use check_agents or wait_for_agents to observe final completion.]`;
-                        }
-                        catch (err) {
-                            return `[SYSTEM: complete_agent failed: ${err?.message || String(err)}]`;
-                        }
-                    },
-                    cancelAgent: async (args) => {
-                        try {
-                            const child = await resolveManagedChild(args.agent_id);
-                            let builtOutcome = null;
-                            if (catalog) {
-                                const existing = await catalog.getChildOutcome(child.sessionId).catch(() => null);
-                                const hasExistingResult = Boolean(normalizeJsonObject(existing?.resultJson?.current));
-                                if (args.partial_result || (existing?.contractJson && !hasExistingResult)) {
-                                    builtOutcome = buildResultJson(args.partial_result, child, existing?.contractJson ?? null, existing?.resultJson ?? null, "cancelled", "completed_without_result");
+                        },
+                        cancelAgent: async (args) => {
+                            try {
+                                const child = await resolveManagedChild(args.agent_id);
+                                let builtOutcome = null;
+                                if (catalog) {
+                                    const existing = await catalog.getChildOutcome(child.sessionId).catch(() => null);
+                                    const hasExistingResult = Boolean(normalizeJsonObject(existing?.resultJson?.current));
+                                    if (args.partial_result || (existing?.contractJson && !hasExistingResult)) {
+                                        builtOutcome = buildResultJson(args.partial_result, child, existing?.contractJson ?? null, existing?.resultJson ?? null, "cancelled", "completed_without_result");
+                                    }
+                                }
+                                if (catalog && builtOutcome) {
+                                    await cmsRetryCritical(`runTurn.cancel.upsertChildOutcome partial child=${child.sessionId}`, () => catalog.upsertChildOutcome({
+                                        childSessionId: child.sessionId,
+                                        parentSessionId: input.sessionId,
+                                        resultJson: builtOutcome.resultJson,
+                                        verdict: builtOutcome.verdict,
+                                        summary: builtOutcome.summary,
+                                        completedAt: new Date(),
+                                    }), (msg) => activityCtx.traceInfo(msg));
                                 }
+                                const sdkClient = await getInlineClient();
+                                const cmdId = `cancel-inline-${Date.now()}`;
+                                await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "cancel", id: cmdId, args: { reason: args.reason ?? "Cancelled by parent" } }));
+                                return `[SYSTEM: Graceful cancellation requested for sub-agent ${child.orchId}. ` +
+                                    `Use check_agents or wait_for_agents to observe final termination.${args.reason ? ` Reason: ${args.reason}` : ""}]`;
                             }
-                            if (catalog && builtOutcome) {
-                                await cmsRetryCritical(`runTurn.cancel.upsertChildOutcome partial child=${child.sessionId}`, () => catalog.upsertChildOutcome({
-                                    childSessionId: child.sessionId,
-                                    parentSessionId: input.sessionId,
-                                    resultJson: builtOutcome.resultJson,
-                                    verdict: builtOutcome.verdict,
-                                    summary: builtOutcome.summary,
-                                    completedAt: new Date(),
-                                }), (msg) => activityCtx.traceInfo(msg));
+                            catch (err) {
+                                return `[SYSTEM: cancel_agent failed: ${err?.message || String(err)}]`;
                             }
-                            const sdkClient = await getInlineClient();
-                            const cmdId = `cancel-inline-${Date.now()}`;
-                            await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "cancel", id: cmdId, args: { reason: args.reason ?? "Cancelled by parent" } }));
-                            return `[SYSTEM: Graceful cancellation requested for sub-agent ${child.orchId}. ` +
-                                `Use check_agents or wait_for_agents to observe final termination.${args.reason ? ` Reason: ${args.reason}` : ""}]`;
-                        }
-                        catch (err) {
-                            return `[SYSTEM: cancel_agent failed: ${err?.message || String(err)}]`;
-                        }
-                    },
-                    deleteAgent: async (args) => {
-                        try {
-                            const child = await resolveManagedChild(args.agent_id);
-                            const sdkClient = await getInlineClient();
-                            if (child.status === "completed" || child.status === "failed" || child.status === "cancelled") {
-                                await sdkClient.deleteSession(child.sessionId);
-                                return `[SYSTEM: Sub-agent ${child.orchId} has been deleted.${args.reason ? ` Reason: ${args.reason}` : ""}]`;
+                        },
+                        deleteAgent: async (args) => {
+                            try {
+                                const child = await resolveManagedChild(args.agent_id);
+                                const sdkClient = await getInlineClient();
+                                if (child.status === "completed" || child.status === "failed" || child.status === "cancelled") {
+                                    await sdkClient.deleteSession(child.sessionId);
+                                    return `[SYSTEM: Sub-agent ${child.orchId} has been deleted.${args.reason ? ` Reason: ${args.reason}` : ""}]`;
+                                }
+                                const cmdId = `delete-inline-${Date.now()}`;
+                                await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "delete", id: cmdId, args: { reason: args.reason ?? "Deleted by parent" } }));
+                                return `[SYSTEM: Graceful deletion requested for sub-agent ${child.orchId}. ` +
+                                    `It will cancel its descendants first and then delete itself.${args.reason ? ` Reason: ${args.reason}` : ""}]`;
                             }
-                            const cmdId = `delete-inline-${Date.now()}`;
-                            await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "delete", id: cmdId, args: { reason: args.reason ?? "Deleted by parent" } }));
-                            return `[SYSTEM: Graceful deletion requested for sub-agent ${child.orchId}. ` +
-                                `It will cancel its descendants first and then delete itself.${args.reason ? ` Reason: ${args.reason}` : ""}]`;
-                        }
-                        catch (err) {
-                            return `[SYSTEM: delete_agent failed: ${err?.message || String(err)}]`;
+                            catch (err) {
+                                return `[SYSTEM: delete_agent failed: ${err?.message || String(err)}]`;
+                            }
+                        },
+                    };
+                    // Cooperative cancellation: poll for lock steal
+                    let cancelled = false;
+                    cancelPoll = setInterval(() => {
+                        if (activityCtx.isCancelled()) {
+                            cancelled = true;
+                            session?.abort?.();
+                            if (cancelPoll)
+                                clearInterval(cancelPoll);
                         }
-                    },
-                };
-                // Cooperative cancellation: poll for lock steal
-                let cancelled = false;
-                cancelPoll = setInterval(() => {
-                    if (activityCtx.isCancelled()) {
-                        cancelled = true;
-                        session?.abort?.();
-                        if (cancelPoll)
-                            clearInterval(cancelPoll);
-                    }
-                }, 2_000);
-                // Build onEvent callback: write each non-ephemeral event to CMS as it fires.
-                // We track every in-flight CMS recordEvents promise so we can flush them
-                // before posting `session.turn_completed`. Without this barrier the
-                // turn_completed insert can race ahead of the SDK's `assistant.message`
-                // insert and CMS will assign the smaller `seq` to turn_completed,
-                // breaking event-ordering invariants downstream (see cms-seq-nodemap).
-                const pendingEventWrites = [];
-                const trackEventWrite = (promise) => {
-                    if (!promise || typeof promise.then !== "function")
-                        return;
-                    pendingEventWrites.push(promise.catch(() => { }));
-                };
-                const EPHEMERAL_TYPES = new Set([
-                    "assistant.message_delta",
-                    "assistant.streaming_delta",
-                    "assistant.reasoning_delta",
-                    "user.message", // Already recorded explicitly above — skip the SDK's duplicate
-                ]);
-                const onEvent = catalog
-                    ? (event) => {
-                        if (EPHEMERAL_TYPES.has(event.eventType))
+                    }, 2_000);
+                    // Build onEvent callback: write each non-ephemeral event to CMS as it fires.
+                    // We track every in-flight CMS recordEvents promise so we can flush them
+                    // before posting `session.turn_completed`. Without this barrier the
+                    // turn_completed insert can race ahead of the SDK's `assistant.message`
+                    // insert and CMS will assign the smaller `seq` to turn_completed,
+                    // breaking event-ordering invariants downstream (see cms-seq-nodemap).
+                    const pendingEventWrites = [];
+                    const trackEventWrite = (promise) => {
+                        if (!promise || typeof promise.then !== "function")
                             return;
-                        const persistedEvent = summarizeSdkSystemPromptEchoEvent(event);
-                        if (!persistedEvent)
-                            return;
-                        if (event.eventType === "session.wait_started") {
-                            const data = (event.data ?? {});
-                            void cmsRetryBestEffort(`runTurn.onEvent updateSession state=waiting session=${input.sessionId}`, () => catalog.updateSession(input.sessionId, {
-                                state: "waiting",
-                                waitReason: data.reason ?? null,
-                                lastActiveAt: new Date(),
-                            }), (msg) => activityCtx.traceInfo(msg));
-                        }
-                        else if (event.eventType === "session.input_required_started") {
-                            const data = (event.data ?? {});
-                            void cmsRetryBestEffort(`runTurn.onEvent updateSession state=input_required session=${input.sessionId}`, () => catalog.updateSession(input.sessionId, {
-                                state: "input_required",
-                                waitReason: data.question ?? null,
-                                lastActiveAt: new Date(),
-                            }), (msg) => activityCtx.traceInfo(msg));
-                        }
-                        if (event.eventType === "assistant.usage") {
-                            const usageUpsert = buildUsageSummaryUpsert(event.data);
-                            if (usageUpsert) {
-                                turnTelemetry.tokensInput += usageUpsert.tokensInputIncrement ?? 0;
-                                turnTelemetry.tokensOutput += usageUpsert.tokensOutputIncrement ?? 0;
-                                turnTelemetry.tokensCacheRead += usageUpsert.tokensCacheReadIncrement ?? 0;
-                                turnTelemetry.tokensCacheWrite += usageUpsert.tokensCacheWriteIncrement ?? 0;
+                        pendingEventWrites.push(promise.catch(() => { }));
+                    };
+                    const EPHEMERAL_TYPES = new Set([
+                        "assistant.message_delta",
+                        "assistant.streaming_delta",
+                        "assistant.reasoning_delta",
+                        "user.message", // Already recorded explicitly above — skip the SDK's duplicate
+                    ]);
+                    const onEvent = catalog
+                        ? (event) => {
+                            if (EPHEMERAL_TYPES.has(event.eventType))
+                                return;
+                            const persistedEvent = summarizeSdkSystemPromptEchoEvent(event);
+                            if (!persistedEvent)
+                                return;
+                            if (event.eventType === "session.wait_started") {
+                                const data = (event.data ?? {});
+                                void cmsRetryBestEffort(`runTurn.onEvent updateSession state=waiting session=${input.sessionId}`, () => catalog.updateSession(input.sessionId, {
+                                    state: "waiting",
+                                    waitReason: data.reason ?? null,
+                                    lastActiveAt: new Date(),
+                                }), (msg) => activityCtx.traceInfo(msg));
                             }
+                            else if (event.eventType === "session.input_required_started") {
+                                const data = (event.data ?? {});
+                                void cmsRetryBestEffort(`runTurn.onEvent updateSession state=input_required session=${input.sessionId}`, () => catalog.updateSession(input.sessionId, {
+                                    state: "input_required",
+                                    waitReason: data.question ?? null,
+                                    lastActiveAt: new Date(),
+                                }), (msg) => activityCtx.traceInfo(msg));
+                            }
+                            if (event.eventType === "assistant.usage") {
+                                const usageUpsert = buildUsageSummaryUpsert(event.data);
+                                if (usageUpsert) {
+                                    turnTelemetry.tokensInput += usageUpsert.tokensInputIncrement ?? 0;
+                                    turnTelemetry.tokensOutput += usageUpsert.tokensOutputIncrement ?? 0;
+                                    turnTelemetry.tokensCacheRead += usageUpsert.tokensCacheReadIncrement ?? 0;
+                                    turnTelemetry.tokensCacheWrite += usageUpsert.tokensCacheWriteIncrement ?? 0;
+                                }
+                            }
+                            else if (event.eventType === "tool.execution_start") {
+                                turnTelemetry.toolCalls += 1;
+                                const eventData = normalizeEventData(event.data);
+                                const toolName = typeof eventData?.toolName === "string"
+                                    ? eventData.toolName
+                                    : typeof eventData?.name === "string"
+                                        ? eventData.name
+                                        : undefined;
+                                if (toolName)
+                                    turnTelemetry.toolNames.add(toolName);
+                            }
+                            else if (event.eventType === "tool.execution_complete" && isFailureToolCompletion(event.data)) {
+                                turnTelemetry.toolErrors += 1;
+                            }
+                            // Best-effort with one transient retry. trackEventWrite tracks
+                            // the wrapped promise so the post-turn barrier waits for the
+                            // retry to settle before emitting turn_completed.
+                            const writePromise = cmsRetryBestEffort(`runTurn.onEvent recordEvent ${persistedEvent.eventType} session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [persistedEvent], workerNodeId), (msg) => activityCtx.traceInfo(msg));
+                            trackEventWrite(writePromise);
                         }
-                        else if (event.eventType === "tool.execution_start") {
-                            turnTelemetry.toolCalls += 1;
-                            const eventData = normalizeEventData(event.data);
-                            const toolName = typeof eventData?.toolName === "string"
-                                ? eventData.toolName
-                                : typeof eventData?.name === "string"
-                                    ? eventData.name
-                                    : undefined;
-                            if (toolName)
-                                turnTelemetry.toolNames.add(toolName);
-                        }
-                        else if (event.eventType === "tool.execution_complete" && isFailureToolCompletion(event.data)) {
-                            turnTelemetry.toolErrors += 1;
+                        : undefined;
+                    // Record the user prompt as a CMS event before running the turn.
+                    // Skip internal timer continuation prompts — they're system-generated, not user input.
+                    const isTimerPrompt = /^The \d+ second wait is now complete\./i.test(input.prompt);
+                    const isRetryAttempt = (input.retryCount ?? 0) > 0;
+                    if (catalog && input.config.turnSystemPrompt && !isRetryAttempt) {
+                        const persistedSystemPrompt = decorateRehydrationSystemPrompt(input.config.turnSystemPrompt, workerNodeId);
+                        void cmsRetryBestEffort(`runTurn.recordEvent system-prompt session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
+                                eventType: "system.message",
+                                data: { content: persistedSystemPrompt },
+                            }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
+                    }
+                    if (catalog && !isTimerPrompt && !input.bootstrap && !isRetryAttempt) {
+                        const promptEventType = isInternalSystemPrompt(input.prompt) ? "system.message" : "user.message";
+                        // v1.0.47: when the orchestration tagged the turn with one or
+                        // more clientMessageIds (the UI-generated identities of the
+                        // contributing local outbox items), persist them on the
+                        // durable user.message event so the client can ack/cancel by
+                        // exact id rather than text match.
+                        const incomingClientMessageIds = Array.isArray(input.clientMessageIds)
+                            ? input.clientMessageIds.filter((id) => typeof id === "string" && id)
+                            : [];
+                        const eventData = { content: input.prompt };
+                        if (incomingClientMessageIds.length > 0) {
+                            eventData.clientMessageIds = incomingClientMessageIds;
                         }
-                        // Best-effort with one transient retry. trackEventWrite tracks
-                        // the wrapped promise so the post-turn barrier waits for the
-                        // retry to settle before emitting turn_completed.
-                        const writePromise = cmsRetryBestEffort(`runTurn.onEvent recordEvent ${persistedEvent.eventType} session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [persistedEvent], workerNodeId), (msg) => activityCtx.traceInfo(msg));
-                        trackEventWrite(writePromise);
+                        const capturedPromptEventType = promptEventType;
+                        void cmsRetryBestEffort(`runTurn.recordEvent ${capturedPromptEventType} session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
+                                eventType: capturedPromptEventType,
+                                data: eventData,
+                            }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
                     }
-                    : undefined;
-                // Record the user prompt as a CMS event before running the turn.
-                // Skip internal timer continuation prompts — they're system-generated, not user input.
-                const isTimerPrompt = /^The \d+ second wait is now complete\./i.test(input.prompt);
-                const isRetryAttempt = (input.retryCount ?? 0) > 0;
-                if (catalog && input.config.turnSystemPrompt && !isRetryAttempt) {
-                    const persistedSystemPrompt = decorateRehydrationSystemPrompt(input.config.turnSystemPrompt, workerNodeId);
-                    void cmsRetryBestEffort(`runTurn.recordEvent system-prompt session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
-                            eventType: "system.message",
-                            data: { content: persistedSystemPrompt },
-                        }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
-                }
-                if (catalog && !isTimerPrompt && !input.bootstrap && !isRetryAttempt) {
-                    const promptEventType = isInternalSystemPrompt(input.prompt) ? "system.message" : "user.message";
-                    // v1.0.47: when the orchestration tagged the turn with one or
-                    // more clientMessageIds (the UI-generated identities of the
-                    // contributing local outbox items), persist them on the
-                    // durable user.message event so the client can ack/cancel by
-                    // exact id rather than text match.
-                    const incomingClientMessageIds = Array.isArray(input.clientMessageIds)
-                        ? input.clientMessageIds.filter((id) => typeof id === "string" && id)
-                        : [];
-                    const eventData = { content: input.prompt };
-                    if (incomingClientMessageIds.length > 0) {
-                        eventData.clientMessageIds = incomingClientMessageIds;
+                    // Mark session as "running" in CMS before the turn, and publish the
+                    // in-flight turn index so stopSessionTurn() can address the
+                    // turn-scoped stop queue (stopTurn.<turnIndex>).
+                    if (catalog) {
+                        await cmsRetryBestEffort(`runTurn.preTurn updateSession state=running session=${input.sessionId}`, () => catalog.updateSession(input.sessionId, {
+                            state: "running",
+                            lastActiveAt: new Date(),
+                        }), (msg) => activityCtx.traceInfo(msg));
+                        await cmsRetryBestEffort(`runTurn.preTurn setActiveTurnIndex session=${input.sessionId} turn=${input.turnIndex ?? 0}`, () => catalog.setActiveTurnIndex(input.sessionId, input.turnIndex ?? 0), (msg) => activityCtx.traceInfo(msg));
                     }
-                    const capturedPromptEventType = promptEventType;
-                    void cmsRetryBestEffort(`runTurn.recordEvent ${capturedPromptEventType} session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
-                            eventType: capturedPromptEventType,
-                            data: eventData,
-                        }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
-                }
-                // Mark session as "running" in CMS before the turn, and publish the
-                // in-flight turn index so stopSessionTurn() can address the
-                // turn-scoped stop queue (stopTurn.<turnIndex>).
-                if (catalog) {
-                    await cmsRetryBestEffort(`runTurn.preTurn updateSession state=running session=${input.sessionId}`, () => catalog.updateSession(input.sessionId, {
-                        state: "running",
-                        lastActiveAt: new Date(),
-                    }), (msg) => activityCtx.traceInfo(msg));
-                    await cmsRetryBestEffort(`runTurn.preTurn setActiveTurnIndex session=${input.sessionId} turn=${input.turnIndex ?? 0}`, () => catalog.setActiveTurnIndex(input.sessionId, input.turnIndex ?? 0), (msg) => activityCtx.traceInfo(msg));
-                }
-                activityCtx.traceInfo(`[runTurn] invoking ManagedSession.runTurn for ${input.sessionId}`);
-                // Record turn_started CMS event
-                if (catalog) {
-                    void cmsRetryBestEffort(`runTurn.recordEvent turn_started session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
-                            eventType: "session.turn_started",
-                            data: { iteration: input.turnIndex ?? 0 },
-                        }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
-                }
-                const runTurnWithPrompt = async (targetSession, prompt) => {
-                    return await targetSession.runTurn(prompt, {
-                        onEvent,
-                        modelSummary: sessionManager.getModelSummary(),
-                        bootstrap: input.bootstrap,
-                        requiredTool: input.requiredTool,
-                        cycleOrigin: input.cycleOrigin,
-                        turnIndex: input.turnIndex,
-                        controlToolBridge,
-                    });
-                };
-                let result = await runTurnWithPrompt(session, effectivePrompt);
-                if (result.type === "error" && isLiveSessionLostErrorMessage(result.message)) {
-                    activityCtx.traceInfo(`[runTurn] live Copilot session lost for ${input.sessionId}; invalidating warm session and attempting recovery`);
-                    await sessionManager.invalidateWarmSession(input.sessionId, { lockHeld: true }).catch((err) => {
-                        activityCtx.traceInfo(`[runTurn] warm-session invalidation failed (non-fatal): ${err?.message ?? err}`);
-                    });
+                    activityCtx.traceInfo(`[runTurn] invoking ManagedSession.runTurn for ${input.sessionId}`);
+                    // Record turn_started CMS event
                     if (catalog) {
-                        await cmsRetryBestEffort(`runTurn.recordEvent system.message-recovery session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
-                                eventType: "system.message",
-                                data: {
-                                    content: "The runtime recovered this session after the worker lost the live Copilot session. " +
-                                        "Some very recent in-memory state may have been lost.",
-                                },
+                        void cmsRetryBestEffort(`runTurn.recordEvent turn_started session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
+                                eventType: "session.turn_started",
+                                data: { iteration: input.turnIndex ?? 0 },
                             }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
                     }
-                    try {
-                        session = await sessionManager.getOrCreate(input.sessionId, runConfig, {
+                    const runTurnWithPrompt = async (targetSession, prompt) => {
+                        return await targetSession.runTurn(prompt, {
+                            onEvent,
+                            modelSummary: sessionManager.getModelSummary(),
+                            bootstrap: input.bootstrap,
+                            requiredTool: input.requiredTool,
+                            cycleOrigin: input.cycleOrigin,
                             turnIndex: input.turnIndex,
-                            trace,
-                            lockHeld: true,
+                            controlToolBridge,
                         });
-                    }
-                    catch (err) {
-                        const recoveryMessage = err?.message || String(err);
-                        const fatalMessage = isMissingSessionStateErrorMessage(recoveryMessage)
-                            ? buildUnrecoverableSessionLossMessage(input.sessionId, stripMissingSessionStatePrefix(recoveryMessage))
-                            : buildUnrecoverableSessionLossMessage(input.sessionId, recoveryMessage);
-                        activityCtx.traceInfo(`[runTurn] unrecoverable session loss for ${input.sessionId}: ${fatalMessage}`);
-                        return await failForMissingState(fatalMessage);
-                    }
-                    const recoveredPrompt = mergePromptSections([SESSION_RECOVERY_NOTICE, input.prompt]) || input.prompt;
-                    result = await runTurnWithPrompt(session, recoveredPrompt);
+                    };
+                    let result = await runTurnWithPrompt(session, effectivePrompt);
                     if (result.type === "error" && isLiveSessionLostErrorMessage(result.message)) {
-                        const fatalMessage = buildUnrecoverableSessionLossMessage(input.sessionId, result.message);
-                        activityCtx.traceInfo(`[runTurn] recovery re-run still reported lost session for ${input.sessionId}: ${fatalMessage}`);
-                        return await failForMissingState(fatalMessage);
-                    }
-                }
-                if (result.type === "error" && isToolCallTranscriptCorruptionErrorMessage(result.message)) {
-                    const transcriptError = result.message;
-                    activityCtx.traceInfo(`[runTurn] corrupted live Copilot transcript for ${input.sessionId}; resetting stored session state and attempting fresh-session replay`);
-                    await sessionManager.resetSessionState(input.sessionId, { lockHeld: true }).catch((err) => {
-                        activityCtx.traceInfo(`[runTurn] stored-session reset failed (non-fatal): ${err?.message ?? err}`);
-                    });
-                    await recordLossyHandoffEvent(catalog, input.sessionId, workerNodeId, {
-                        cause: "corrupted_tool_call_transcript_during_run_turn",
-                        message: "The runtime detected an inconsistent live Copilot transcript and recreated a fresh session to replay the pending turn.",
-                        detail: transcriptError,
-                        error: transcriptError,
-                        recoveryMode: "fresh_session_replay",
-                        nextStep: "replay_pending_turn_with_recreated_copilot_session",
-                        ...(input.turnIndex != null ? { iteration: input.turnIndex } : {}),
-                    }, (failureMessage) => activityCtx.traceInfo(`[runTurn] ${failureMessage}`));
-                    if (catalog) {
-                        await cmsRetryBestEffort(`runTurn.recordEvent system.message-corrupted-transcript session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
-                                eventType: "system.message",
-                                data: {
-                                    content: "The runtime recreated this session after the live Copilot transcript became inconsistent. " +
-                                        "Some recent in-memory work may be missing or partially executed.",
-                                },
-                            }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
-                    }
-                    try {
-                        session = await sessionManager.getOrCreate(input.sessionId, runConfig, {
-                            turnIndex: 0,
-                            trace,
-                            lockHeld: true,
+                        activityCtx.traceInfo(`[runTurn] live Copilot session lost for ${input.sessionId}; invalidating warm session and attempting recovery`);
+                        await sessionManager.invalidateWarmSession(input.sessionId, { lockHeld: true }).catch((err) => {
+                            activityCtx.traceInfo(`[runTurn] warm-session invalidation failed (non-fatal): ${err?.message ?? err}`);
                         });
+                        if (catalog) {
+                            await cmsRetryBestEffort(`runTurn.recordEvent system.message-recovery session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
+                                    eventType: "system.message",
+                                    data: {
+                                        content: "The runtime recovered this session after the worker lost the live Copilot session. " +
+                                            "Some very recent in-memory state may have been lost.",
+                                    },
+                                }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
+                        }
+                        try {
+                            session = await sessionManager.getOrCreate(input.sessionId, runConfig, {
+                                turnIndex: input.turnIndex,
+                                trace,
+                                lockHeld: true,
+                            });
+                        }
+                        catch (err) {
+                            const recoveryMessage = err?.message || String(err);
+                            const fatalMessage = isMissingSessionStateErrorMessage(recoveryMessage)
+                                ? buildUnrecoverableSessionLossMessage(input.sessionId, stripMissingSessionStatePrefix(recoveryMessage))
+                                : buildUnrecoverableSessionLossMessage(input.sessionId, recoveryMessage);
+                            activityCtx.traceInfo(`[runTurn] unrecoverable session loss for ${input.sessionId}: ${fatalMessage}`);
+                            return await failForMissingState(fatalMessage);
+                        }
+                        const recoveredPrompt = mergePromptSections([SESSION_RECOVERY_NOTICE, input.prompt]) || input.prompt;
+                        result = await runTurnWithPrompt(session, recoveredPrompt);
+                        if (result.type === "error" && isLiveSessionLostErrorMessage(result.message)) {
+                            const fatalMessage = buildUnrecoverableSessionLossMessage(input.sessionId, result.message);
+                            activityCtx.traceInfo(`[runTurn] recovery re-run still reported lost session for ${input.sessionId}: ${fatalMessage}`);
+                            return await failForMissingState(fatalMessage);
+                        }
                     }
-                    catch (err) {
-                        const recoveryMessage = err?.message || String(err);
-                        const fatalMessage = `Live Copilot transcript became inconsistent for ${input.sessionId}, and fresh-session recovery failed. ${recoveryMessage}`;
-                        activityCtx.traceInfo(`[runTurn] unrecoverable corrupted transcript for ${input.sessionId}: ${fatalMessage}`);
-                        return { type: "error", message: fatalMessage };
+                    if (result.type === "error" && isToolCallTranscriptCorruptionErrorMessage(result.message)) {
+                        const transcriptError = result.message;
+                        activityCtx.traceInfo(`[runTurn] corrupted live Copilot transcript for ${input.sessionId}; resetting stored session state and attempting fresh-session replay`);
+                        await sessionManager.resetSessionState(input.sessionId, { lockHeld: true }).catch((err) => {
+                            activityCtx.traceInfo(`[runTurn] stored-session reset failed (non-fatal): ${err?.message ?? err}`);
+                        });
+                        await recordLossyHandoffEvent(catalog, input.sessionId, workerNodeId, {
+                            cause: "corrupted_tool_call_transcript_during_run_turn",
+                            message: "The runtime detected an inconsistent live Copilot transcript and recreated a fresh session to replay the pending turn.",
+                            detail: transcriptError,
+                            error: transcriptError,
+                            recoveryMode: "fresh_session_replay",
+                            nextStep: "replay_pending_turn_with_recreated_copilot_session",
+                            ...(input.turnIndex != null ? { iteration: input.turnIndex } : {}),
+                        }, (failureMessage) => activityCtx.traceInfo(`[runTurn] ${failureMessage}`));
+                        if (catalog) {
+                            await cmsRetryBestEffort(`runTurn.recordEvent system.message-corrupted-transcript session=${input.sessionId}`, () => catalog.recordEvents(input.sessionId, [{
+                                    eventType: "system.message",
+                                    data: {
+                                        content: "The runtime recreated this session after the live Copilot transcript became inconsistent. " +
+                                            "Some recent in-memory work may be missing or partially executed.",
+                                    },
+                                }], workerNodeId), (msg) => activityCtx.traceInfo(msg));
+                        }
+                        try {
+                            session = await sessionManager.getOrCreate(input.sessionId, runConfig, {
+                                turnIndex: 0,
+                                trace,
+                                lockHeld: true,
+                            });
+                        }
+                        catch (err) {
+                            const recoveryMessage = err?.message || String(err);
+                            const fatalMessage = `Live Copilot transcript became inconsistent for ${input.sessionId}, and fresh-session recovery failed. ${recoveryMessage}`;
+                            activityCtx.traceInfo(`[runTurn] unrecoverable corrupted transcript for ${input.sessionId}: ${fatalMessage}`);
+                            return { type: "error", message: fatalMessage };
+                        }
+                        const recoveredPrompt = mergePromptSections([CORRUPTED_TRANSCRIPT_REPLAY_NOTICE, input.prompt]) || input.prompt;
+                        result = await runTurnWithPrompt(session, recoveredPrompt);
                     }
-                    const recoveredPrompt = mergePromptSections([CORRUPTED_TRANSCRIPT_REPLAY_NOTICE, input.prompt]) || input.prompt;
-                    result = await runTurnWithPrompt(session, recoveredPrompt);
-                }
-                if (input.parentSessionId
-                    && result.type === "completed"
-                    && typeof result.content === "string"
-                    && /^QUESTION FOR PARENT:/i.test(result.content.trim())) {
-                    result = {
-                        ...result,
-                        type: "wait",
-                        seconds: 60,
-                        reason: "waiting for parent answer",
-                        content: result.content.trim(),
-                    };
-                }
-                activityCtx.traceInfo(`[runTurn] ManagedSession.runTurn completed for ${input.sessionId} type=${result.type}`);
-                // Drain event writes before the atomic post-turn writeback records
-                // session.turn_completed.
-                //
-                // Ordering matters here: every per-event CMS write fired by the
-                // SDK's onEvent callback (assistant.message, tool calls, usage,
-                // etc.) must land in `session_events` with a smaller `seq` than
-                // `session.turn_completed`, otherwise downstream consumers that
-                // walk events in seq order (e.g. cms-seq-nodemap) see the turn
-                // close before its own assistant.message.
-                //
-                // `runTurn` resolves once the SDK has emitted its final events,
-                // but the corresponding `recordEvents` calls were dispatched
-                // fire-and-forget. We therefore:
-                //   1. Sleep 100ms to let any straggler onEvent callbacks fire
-                //      and enqueue their CMS write (quiesce window).
-                //   2. Drain `pendingEventWrites` and await all of them with
-                //      allSettled — failed writes were already logged inline,
-                //      we only need the ordering guarantee.
-                //   3. Await the turn_completed insert so subsequent activity
-                //      logic and any immediate CMS readers see a consistent tail.
-                //
-                // The 100ms is a deliberate, bounded pause. If it ever needs to
-                // grow, prefer a real "SDK turn fully flushed" signal over a
-                // larger sleep.
-                if (catalog) {
-                    await new Promise((resolve) => setTimeout(resolve, 100));
-                    const pendingWritesAtBarrier = pendingEventWrites.splice(0);
-                    if (pendingWritesAtBarrier.length > 0) {
-                        await Promise.allSettled(pendingWritesAtBarrier);
+                    if (input.parentSessionId
+                        && result.type === "completed"
+                        && typeof result.content === "string"
+                        && /^QUESTION FOR PARENT:/i.test(result.content.trim())) {
+                        result = {
+                            ...result,
+                            type: "wait",
+                            seconds: 60,
+                            reason: "waiting for parent answer",
+                            content: result.content.trim(),
+                        };
                     }
-                }
-                if (cancelled)
-                    return { type: "cancelled" };
-                // ── Activity-level writeback: sync turn result → CMS ──
-                // This lets listSessions() read entirely from CMS without
-                // hitting duroxide for every session's customStatus.
-                if (catalog) {
-                    const statusMap = {
-                        completed: "idle", // orchestration decides idle vs completed; default to idle
-                        wait: "waiting",
-                        cron: "running",
-                        input_required: "input_required",
-                        error: "error",
-                        cancelled: "idle",
-                        stopped: "idle",
-                        spawn_agent: "running",
-                        message_agent: "running",
-                        check_agents: "running",
-                        wait_for_agents: "waiting",
-                        list_sessions: "running",
-                        complete_agent: "running",
-                        cancel_agent: "running",
-                        delete_agent: "running",
-                    };
-                    const liveStatus = statusMap[result.type] ?? "idle";
-                    const updates = {
-                        state: liveStatus,
-                        lastActiveAt: new Date(),
-                    };
-                    if (result.type === "error") {
-                        updates.lastError = result.message ?? null;
-                        updates.waitReason = null;
+                    activityCtx.traceInfo(`[runTurn] ManagedSession.runTurn completed for ${input.sessionId} type=${result.type}`);
+                    // Drain event writes before the atomic post-turn writeback records
+                    // session.turn_completed.
+                    //
+                    // Ordering matters here: every per-event CMS write fired by the
+                    // SDK's onEvent callback (assistant.message, tool calls, usage,
+                    // etc.) must land in `session_events` with a smaller `seq` than
+                    // `session.turn_completed`, otherwise downstream consumers that
+                    // walk events in seq order (e.g. cms-seq-nodemap) see the turn
+                    // close before its own assistant.message.
+                    //
+                    // `runTurn` resolves once the SDK has emitted its final events,
+                    // but the corresponding `recordEvents` calls were dispatched
+                    // fire-and-forget. We therefore:
+                    //   1. Sleep 100ms to let any straggler onEvent callbacks fire
+                    //      and enqueue their CMS write (quiesce window).
+                    //   2. Drain `pendingEventWrites` and await all of them with
+                    //      allSettled — failed writes were already logged inline,
+                    //      we only need the ordering guarantee.
+                    //   3. Await the turn_completed insert so subsequent activity
+                    //      logic and any immediate CMS readers see a consistent tail.
+                    //
+                    // The 100ms is a deliberate, bounded pause. If it ever needs to
+                    // grow, prefer a real "SDK turn fully flushed" signal over a
+                    // larger sleep.
+                    if (catalog) {
+                        await new Promise((resolve) => setTimeout(resolve, 100));
+                        const pendingWritesAtBarrier = pendingEventWrites.splice(0);
+                        if (pendingWritesAtBarrier.length > 0) {
+                            await Promise.allSettled(pendingWritesAtBarrier);
+                        }
                     }
-                    else if (result.type === "wait") {
-                        updates.waitReason = result.reason ?? null;
-                        updates.lastError = null;
+                    if (cancelled)
+                        return { type: "cancelled" };
+                    // ── Activity-level writeback: sync turn result → CMS ──
+                    // This lets listSessions() read entirely from CMS without
+                    // hitting duroxide for every session's customStatus.
+                    if (catalog) {
+                        const statusMap = {
+                            completed: "idle", // orchestration decides idle vs completed; default to idle
+                            wait: "waiting",
+                            cron: "running",
+                            input_required: "input_required",
+                            error: "error",
+                            cancelled: "idle",
+                            stopped: "idle",
+                            spawn_agent: "running",
+                            message_agent: "running",
+                            check_agents: "running",
+                            wait_for_agents: "waiting",
+                            list_sessions: "running",
+                            complete_agent: "running",
+                            cancel_agent: "running",
+                            delete_agent: "running",
+                        };
+                        const liveStatus = statusMap[result.type] ?? "idle";
+                        const updates = {
+                            state: liveStatus,
+                            lastActiveAt: new Date(),
+                        };
+                        if (result.type === "error") {
+                            updates.lastError = result.message ?? null;
+                            updates.waitReason = null;
+                        }
+                        else if (result.type === "wait") {
+                            updates.waitReason = result.reason ?? null;
+                            updates.lastError = null;
+                        }
+                        else if (result.type === "input_required") {
+                            updates.waitReason = result.question ?? null;
+                            updates.lastError = null;
+                        }
+                        else {
+                            updates.waitReason = null;
+                            updates.lastError = null;
+                        }
+                        const turnEndedAt = new Date();
+                        await cmsRetryBestEffort(`runTurn.postTurn completeTurnWriteback state=${updates.state} session=${input.sessionId}`, () => catalog.completeTurnWriteback({
+                            sessionId: input.sessionId,
+                            agentId: null,
+                            model: input.config.model ?? null,
+                            reasoningEffort: input.config.reasoningEffort ?? null,
+                            turnIndex: input.turnIndex ?? 0,
+                            startedAt: turnStartedAt,
+                            endedAt: turnEndedAt,
+                            durationMs: Math.max(0, turnEndedAt.getTime() - turnStartedAt.getTime()),
+                            tokensInput: turnTelemetry.tokensInput,
+                            tokensOutput: turnTelemetry.tokensOutput,
+                            tokensCacheRead: turnTelemetry.tokensCacheRead,
+                            tokensCacheWrite: turnTelemetry.tokensCacheWrite,
+                            toolCalls: turnTelemetry.toolCalls,
+                            toolErrors: turnTelemetry.toolErrors,
+                            toolNames: Array.from(turnTelemetry.toolNames).sort(),
+                            resultType: result.type,
+                            errorMessage: result.type === "error" ? (result.message ?? null) : null,
+                            workerNodeId: workerNodeId ?? null,
+                            state: updates.state ?? "idle",
+                            lastActiveAt: updates.lastActiveAt ?? turnEndedAt,
+                            lastError: updates.lastError ?? null,
+                            waitReason: updates.waitReason ?? null,
+                            currentIteration: input.turnIndex ?? 0,
+                        }), (msg) => activityCtx.traceInfo(msg));
                     }
-                    else if (result.type === "input_required") {
-                        updates.waitReason = result.question ?? null;
-                        updates.lastError = null;
+                    return result;
+                };
+                const bodyResult = await executeTurnBody();
+                // ── Session lifecycle protocol commit (proposal §3.2) ───────────
+                // The turn and its snapshot durability are one activity completion:
+                // no observable state exists where the turn "happened" but its
+                // snapshot doesn't. Commit on every result the body produced —
+                // matching today's semantics where the warm session keeps whatever
+                // state the turn (even a cancelled/errored one) left behind. The
+                // layout guard skips paths where no snapshottable session exists:
+                // the SDK writes workspace.yaml on session create, so a dir without
+                // it (fake test clients, failed creates — possibly containing only
+                // our own sentinel) has nothing the store could meaningfully hold,
+                // and committing it would fail the whole turn.
+                const lifecycleSessionDir = lifecycle
+                    ? path.join(sessionManager.getSessionStateDir(), input.sessionId)
+                    : null;
+                if (lifecycle && lifecycleSessionDir && fs.existsSync(path.join(lifecycleSessionDir, "workspace.yaml"))) {
+                    const committed = await runTurnCommit(lifecycle, lifecycleBaseVersion, bodyResult);
+                    if (catalog && committed.sizeBytes != null) {
+                        await cmsRetryBestEffort(`runTurn.commitSummary session=${input.sessionId}`, () => catalog.upsertSessionMetricSummary(input.sessionId, {
+                            snapshotSizeBytes: committed.sizeBytes,
+                            ...(committed.rawSizeBytes != null ? { rawSizeBytes: committed.rawSizeBytes } : {}),
+                        }), (msg) => activityCtx.traceInfo(msg));
                     }
-                    else {
-                        updates.waitReason = null;
-                        updates.lastError = null;
+                    if (committed.alreadyCommitted && committed.storedResult !== undefined) {
+                        // A racing attempt of this same turn won the CAS. Its
+                        // snapshot was restored (restore-not-replay, §3.2 r1–r3) —
+                        // return ITS result so the recorded outcome matches the
+                        // durable lineage instead of this attempt's divergent body.
+                        activityCtx.traceInfo(`[runTurn] session=${input.sessionId} racing attempt committed v${committed.version} first; ` +
+                            `adopting its stored result`);
+                        return { ...committed.storedResult, snapshotVersion: committed.version };
                     }
-                    const turnEndedAt = new Date();
-                    await cmsRetryBestEffort(`runTurn.postTurn completeTurnWriteback state=${updates.state} session=${input.sessionId}`, () => catalog.completeTurnWriteback({
-                        sessionId: input.sessionId,
-                        agentId: null,
-                        model: input.config.model ?? null,
-                        reasoningEffort: input.config.reasoningEffort ?? null,
-                        turnIndex: input.turnIndex ?? 0,
-                        startedAt: turnStartedAt,
-                        endedAt: turnEndedAt,
-                        durationMs: Math.max(0, turnEndedAt.getTime() - turnStartedAt.getTime()),
-                        tokensInput: turnTelemetry.tokensInput,
-                        tokensOutput: turnTelemetry.tokensOutput,
-                        tokensCacheRead: turnTelemetry.tokensCacheRead,
-                        tokensCacheWrite: turnTelemetry.tokensCacheWrite,
-                        toolCalls: turnTelemetry.toolCalls,
-                        toolErrors: turnTelemetry.toolErrors,
-                        toolNames: Array.from(turnTelemetry.toolNames).sort(),
-                        resultType: result.type,
-                        errorMessage: result.type === "error" ? (result.message ?? null) : null,
-                        workerNodeId: workerNodeId ?? null,
-                        state: updates.state ?? "idle",
-                        lastActiveAt: updates.lastActiveAt ?? turnEndedAt,
-                        lastError: updates.lastError ?? null,
-                        waitReason: updates.waitReason ?? null,
-                        currentIteration: input.turnIndex ?? 0,
-                    }), (msg) => activityCtx.traceInfo(msg));
+                    return { ...bodyResult, snapshotVersion: committed.version };
                 }
-                return result;
+                return bodyResult;
             }, { trace });
             if (!finalTurnResult) {
                 throw new Error("runTurn completed without a turn result");
@@ -1808,6 +1953,21 @@ workerNodeId) {
         activityCtx.traceInfo(`[abortTurn] session=${input.sessionId} outcome=${result.outcome}${result.detail ? ` (${result.detail})` : ""}`);
         return result;
     });
+    // ── LEGACY LIFECYCLE ACTIVITIES (compat surface, not dead code) ──
+    //
+    // dehydrateSession / hydrateSession / needsHydrationSession /
+    // checkpointSession are scheduled ONLY by frozen orchestration versions
+    // (≤ 1.0.56: their processPrompt probes needsHydrationSession before
+    // every turn, their wait policy dehydrates, their warm continue-as-new
+    // checkpoints) and by 1.0.57's one-shot normalization of a legacy CAN
+    // input (hydrateSession when input.needsHydration=true). The lifecycle
+    // protocol itself never schedules any of them — hydrate/commit live
+    // inside the runTurn activity (P5).
+    //
+    // Retirement condition: when the ≤1.0.56 handlers are dropped from
+    // DURABLE_SESSION_ORCHESTRATION_REGISTRY, delete these registrations
+    // (and the session-proxy methods that schedule them) in the same
+    // change. Until then they must stay byte-compatible.
     // ── dehydrateSession ────────────────────────────────────
     runtime.registerActivity("dehydrateSession", async (activityCtx, input) => {
         const reason = input.reason ?? "unknown";
@@ -1880,7 +2040,7 @@ workerNodeId) {
             trace(`session=${input.sessionId} complete reason=${reason}`);
             dehydrationSpan.setAttribute("pilotswarm.dehydration_result", "completed");
             if (catalog) {
-                const snapshotSizeBytes = await tryReadSnapshotSizeBytes(_sessionStore, input.sessionId);
+                const snapshotSizeBytes = await tryReadSnapshotSizeBytes(sessionStore, input.sessionId);
                 if (snapshotSizeBytes != null) {
                     dehydrationSpan.setAttribute("pilotswarm.snapshot_size_bytes", snapshotSizeBytes);
                 }
@@ -1967,7 +2127,7 @@ workerNodeId) {
     runtime.registerActivity("checkpointSession", async (activityCtx, input) => {
         await sessionManager.checkpoint(input.sessionId);
         if (catalog) {
-            const snapshotSizeBytes = await tryReadSnapshotSizeBytes(_sessionStore, input.sessionId);
+            const snapshotSizeBytes = await tryReadSnapshotSizeBytes(sessionStore, input.sessionId);
             // Best-effort: metric summary is observability only. The blob has
             // already been written by sessionManager.checkpoint above.
             await cmsRetryBestEffort(`checkpointSession.upsertSummary session=${input.sessionId}`, () => catalog.upsertSessionMetricSummary(input.sessionId, {
@@ -2171,6 +2331,7 @@ workerNodeId) {
             id: agent.id ?? undefined,
             parent: agent.parent ?? undefined,
             splash: agent.splash ?? undefined,
+            splashMobile: agent.splashMobile ?? undefined,
             namespace: agent.namespace ?? undefined,
             promptLayerKind: agent.promptLayerKind ?? undefined,
             creatable: agent.creatable ?? !agent.system,
@@ -2286,6 +2447,15 @@ workerNodeId) {
                 meta.agentId = input.agentId;
             if (input.splash)
                 meta.splash = input.splash;
+            // Frozen orchestration versions don't thread splashMobile through
+            // the spawn input, so resolve it from the loaded agent definition.
+            if (input.agentId) {
+                const normalizeId = (value) => (value || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
+                const lookup = normalizeId(input.agentId);
+                const agentDef = [...(userAgents ?? []), ...(systemAgents ?? [])].find((a) => [a.id, a.name].map(normalizeId).filter(Boolean).includes(lookup));
+                if (agentDef?.splashMobile)
+                    meta.splashMobile = agentDef.splashMobile;
+            }
             if (Object.keys(meta).length > 0 && catalog) {
                 const metaAt = Date.now();
                 // Critical: title/agentId/splash drive UI rendering of the