@ouro.bot/cli 0.1.0-alpha.2 → 0.1.0-alpha.200

package/dist/senses/pipeline.js

@@ -0,0 +1,693 @@
+"use strict";
+// Shared per-turn pipeline for all senses.
+// Senses are thin transport adapters; this module owns the common lifecycle:
+//   resolve friend -> trust gate -> load session -> drain pending -> runAgent -> postTurn -> token accumulation.
+//
+// Transport-level concerns (BB API calls, Teams cards, readline) stay in sense adapters.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitObligationTransitionEpisodes = emitObligationTransitionEpisodes;
+exports.handleInboundTurn = handleInboundTurn;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../nerves/runtime");
+const commands_1 = require("./commands");
+const continuity_1 = require("./continuity");
+const manager_1 = require("../heart/bridges/manager");
+const identity_1 = require("../heart/identity");
+const tasks_1 = require("../repertoire/tasks");
+const coding_1 = require("../repertoire/coding");
+const session_activity_1 = require("../heart/session-activity");
+const socket_client_1 = require("../heart/daemon/socket-client");
+const active_work_1 = require("../heart/active-work");
+const delegation_1 = require("../heart/delegation");
+const target_resolution_1 = require("../heart/target-resolution");
+const thoughts_1 = require("../heart/daemon/thoughts");
+const pending_1 = require("../mind/pending");
+const obligations_1 = require("../heart/obligations");
+const obligations_2 = require("../mind/obligations");
+const provider_failover_1 = require("../heart/provider-failover");
+const provider_ping_1 = require("../heart/provider-ping");
+const auth_flow_1 = require("../heart/daemon/auth-flow");
+const tempo_1 = require("../heart/tempo");
+const temporal_view_1 = require("../heart/temporal-view");
+const start_of_turn_packet_1 = require("../heart/start-of-turn-packet");
+const sync_1 = require("../heart/sync");
+const config_1 = require("../heart/config");
+const presence_1 = require("../heart/presence");
+const episodes_1 = require("../mind/episodes");
+const cares_1 = require("../heart/cares");
+/**
+ * Emit episodes for obligation state transitions detected during a turn.
+ * Exported for direct testability (avoids v8 coverage merge issues in multi-file test suites).
+ */
+function emitObligationTransitionEpisodes(agentRoot, preTurnObligationIds, postTurnObligations, preTurnObligations) {
+    const postTurnObligationIds = new Set(postTurnObligations.map((ob) => `${ob.id}:${ob.status}`));
+    for (const key of preTurnObligationIds) {
+        if (!postTurnObligationIds.has(key)) {
+            const [obId] = key.split(":");
+            const matchedOb = postTurnObligations.find((ob) => ob.id === obId) ?? preTurnObligations.find((ob) => ob.id === obId);
+            (0, episodes_1.emitEpisode)(agentRoot, {
+                kind: "obligation_shift",
+                summary: `obligation "${matchedOb?.content ?? obId}" status changed`,
+                whyItMattered: "obligation state transition detected during turn",
+                relatedEntities: [`obligation:${obId}`],
+                salience: "medium",
+            });
+        }
+    }
+}
+function emptyTaskBoard() {
+    return {
+        compact: "",
+        full: "",
+        byStatus: {
+            drafting: [],
+            processing: [],
+            validating: [],
+            collaborating: [],
+            paused: [],
+            blocked: [],
+            done: [],
+            cancelled: [],
+        },
+        issues: [],
+        actionRequired: [],
+        unresolvedDependencies: [],
+        activeSessions: [],
+        activeBridges: [],
+    };
+}
+function isLiveCodingSessionStatus(status) {
+    return status === "spawning"
+        || status === "running"
+        || status === "waiting_input"
+        || status === "stalled";
+}
+function prependTurnSections(message, sections) {
+    /* v8 ignore next -- defensive: only user messages with non-empty sections reach here @preserve */
+    if (message.role !== "user" || sections.length === 0)
+        return message;
+    const prefix = sections.join("\n\n");
+    /* v8 ignore start -- defensive: multipart content branch; non-string user messages are rare @preserve */
+    if (typeof message.content === "string") {
+        return {
+            ...message,
+            content: `${prefix}\n\n${message.content}`,
+        };
+    }
+    return {
+        ...message,
+        content: [
+            { type: "text", text: `${prefix}\n\n` },
+            ...message.content,
+        ],
+    };
+    /* v8 ignore stop */
+}
+function readInnerWorkState() {
+    const defaultJob = {
+        status: "idle",
+        content: null,
+        origin: null,
+        mode: "reflect",
+        obligationStatus: null,
+        surfacedResult: null,
+        queuedAt: null,
+        startedAt: null,
+        surfacedAt: null,
+    };
+    try {
+        const agentRoot = (0, identity_1.getAgentRoot)();
+        const pendingDir = (0, pending_1.getInnerDialogPendingDir)((0, identity_1.getAgentName)());
+        const sessionPath = (0, thoughts_1.getInnerDialogSessionPath)(agentRoot);
+        const { pendingMessages, turns, runtimeState } = (0, thoughts_1.readInnerDialogRawData)(sessionPath, pendingDir);
+        const dialogStatus = (0, thoughts_1.deriveInnerDialogStatus)(pendingMessages, turns, runtimeState);
+        const job = (0, thoughts_1.deriveInnerJob)(pendingMessages, turns, runtimeState);
+        // Derive obligationPending from both the pending message field and the obligation store
+        const storeObligationPending = (0, obligations_1.readPendingObligations)(agentRoot).length > 0;
+        return {
+            status: dialogStatus.processing === "started" ? "running" : "idle",
+            hasPending: dialogStatus.queue !== "clear",
+            origin: dialogStatus.origin,
+            contentSnippet: dialogStatus.contentSnippet,
+            obligationPending: dialogStatus.obligationPending || storeObligationPending,
+            job,
+        };
+    }
+    catch {
+        return {
+            status: "idle",
+            hasPending: false,
+            job: defaultJob,
+        };
+    }
+}
+// ── Pipeline ──────────────────────────────────────────────────────
+let _lastSessionKey = null;
+async function handleInboundTurn(input) {
+    return (0, sync_1.runWithSyncContext)(async () => {
+        // Reset session-scoped state when the session changes
+        const sessionKey = `${input.channel}/${input.sessionKey ?? "session"}`;
+        if (sessionKey !== _lastSessionKey) {
+            _lastSessionKey = sessionKey;
+            // Reset file-state cache and scrutiny tracking for the new session
+            const { fileStateCache } = await Promise.resolve().then(() => __importStar(require("../mind/file-state")));
+            const { resetSessionModifiedFiles } = await Promise.resolve().then(() => __importStar(require("../mind/scrutiny")));
+            fileStateCache.clear();
+            resetSessionModifiedFiles();
+        }
+        // Step 0: Check for pending failover reply
+        if (input.failoverState?.pending) {
+            const userText = input.messages
+                .filter((m) => m.role === "user")
+                .map((m) => typeof m.content === "string" ? m.content : /* v8 ignore next -- defensive: multipart content fallback @preserve */ "")
+                .join(" ")
+                .trim();
+            const pendingContext = input.failoverState.pending;
+            const failoverAction = (0, provider_failover_1.handleFailoverReply)(userText, pendingContext);
+            const failoverAgentName = pendingContext.agentName;
+            input.failoverState.pending = null; // always clear before acting
+            if (failoverAction.action === "switch") {
+                let switchSucceeded = false;
+                try {
+                    (0, auth_flow_1.writeAgentProviderSelection)(failoverAgentName, "human", failoverAction.provider);
+                    (0, auth_flow_1.writeAgentProviderSelection)(failoverAgentName, "agent", failoverAction.provider);
+                    switchSucceeded = true;
+                    /* v8 ignore start -- defensive: write failure during provider switch @preserve */
+                }
+                catch (switchError) {
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "error",
+                        component: "senses",
+                        event: "senses.failover_switch_error",
+                        message: `failed to switch provider to ${failoverAction.provider}`,
+                        meta: { agentName: failoverAgentName, provider: failoverAction.provider, error: switchError instanceof Error ? switchError.message : String(switchError) },
+                    });
+                }
+                /* v8 ignore stop */
+                /* v8 ignore next -- false branch: write-failure fallthrough @preserve */
+                if (switchSucceeded) {
+                    (0, runtime_1.emitNervesEvent)({
+                        component: "senses",
+                        event: "senses.failover_switch",
+                        message: `switched provider to ${failoverAction.provider} via failover`,
+                        meta: { agentName: failoverAgentName, provider: failoverAction.provider },
+                    });
+                    // Replace "switch to <provider>" with a context message for the agent.
+                    // The session already has the user's original question from the failed turn.
+                    // The agent needs to know what happened so it can respond appropriately.
+                    const newProviderSecrets = (() => {
+                        try {
+                            const { secrets } = (0, auth_flow_1.loadAgentSecrets)(failoverAgentName);
+                            const cfg = secrets.providers[failoverAction.provider];
+                            return cfg?.model ?? cfg?.modelName ?? "";
+                            /* v8 ignore next 2 -- defensive: secrets read failure @preserve */
+                        }
+                        catch {
+                            return "";
+                        }
+                    })();
+                    const newProviderLabel = newProviderSecrets ? `${failoverAction.provider} (${newProviderSecrets})` : failoverAction.provider;
+                    input.messages = [{
+                            role: "user",
+                            content: `[provider switch: ${pendingContext.errorSummary}. switched to ${newProviderLabel}. your conversation history is intact — respond to the user's last message.]`,
+                        }];
+                    input.switchedProvider = failoverAction.provider;
+                }
+                // Switch failed OR succeeded — either way, fall through to normal processing.
+            }
+        }
+        // Step 0b: Slash command interception (before friend resolution / agent turn)
+        {
+            const firstUserMsg = input.messages.find((m) => m.role === "user");
+            const userText = firstUserMsg
+                ? (typeof firstUserMsg.content === "string"
+                    ? firstUserMsg.content
+                    : Array.isArray(firstUserMsg.content)
+                        ? firstUserMsg.content.find((p) => p.type === "text")?.text ?? ""
+                        : /* v8 ignore next -- defensive: content is always string or array @preserve */ "")
+                : "";
+            const parsed = (0, commands_1.parseSlashCommand)(userText);
+            if (parsed) {
+                const registry = (0, commands_1.getSharedCommandRegistry)();
+                const dispatchResult = registry.dispatch(parsed.command, { channel: input.channel });
+                if (dispatchResult.handled && dispatchResult.result) {
+                    (0, runtime_1.emitNervesEvent)({
+                        component: "senses",
+                        event: "senses.pipeline_command",
+                        message: `slash command intercepted: /${parsed.command}`,
+                        meta: { command: parsed.command, channel: input.channel },
+                    });
+                    if (dispatchResult.result.message) {
+                        input.callbacks.onTextChunk(dispatchResult.result.message);
+                    }
+                    // Return a minimal result — no agent turn, no session write
+                    const resolvedContext = await input.friendResolver.resolve();
+                    return {
+                        resolvedContext,
+                        gateResult: { allowed: true },
+                        turnOutcome: "command",
+                        commandAction: dispatchResult.result.action,
+                    };
+                }
+            }
+        }
+        // Step 1: Resolve friend
+        const resolvedContext = await input.friendResolver.resolve();
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.pipeline_start",
+            message: "inbound turn pipeline started",
+            meta: {
+                channel: input.channel,
+                friendId: resolvedContext.friend.id,
+                senseType: input.capabilities.senseType,
+            },
+        });
+        // Step 2: Trust gate
+        const gateInput = {
+            friend: resolvedContext.friend,
+            provider: input.provider ?? "local",
+            externalId: input.externalId ?? "",
+            tenantId: input.tenantId,
+            channel: input.channel,
+            senseType: input.capabilities.senseType,
+            isGroupChat: input.isGroupChat ?? false,
+            groupHasFamilyMember: input.groupHasFamilyMember ?? false,
+            hasExistingGroupWithFamily: input.hasExistingGroupWithFamily ?? false,
+        };
+        const gateResult = input.enforceTrustGate(gateInput);
+        // Gate rejection: return early, no agent turn
+        if (!gateResult.allowed) {
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.pipeline_gate_reject",
+                message: "trust gate rejected inbound turn",
+                meta: {
+                    channel: input.channel,
+                    friendId: resolvedContext.friend.id,
+                    reason: gateResult.reason,
+                },
+            });
+            return {
+                resolvedContext,
+                gateResult,
+            };
+        }
+        // Step 3: Load/create session
+        const session = await input.sessionLoader.loadOrCreate();
+        const sessionMessages = session.messages;
+        let mustResolveBeforeHandoff = (0, continuity_1.resolveMustResolveBeforeHandoff)(session.state?.mustResolveBeforeHandoff === true, input.continuityIngressTexts);
+        const lastFriendActivityAt = input.channel === "inner"
+            ? session.state?.lastFriendActivityAt
+            : new Date().toISOString();
+        const currentObligation = input.continuityIngressTexts
+            ?.map((text) => text.trim())
+            .filter((text) => text.length > 0)
+            .at(-1);
+        const currentSession = {
+            friendId: resolvedContext.friend.id,
+            channel: input.channel,
+            key: input.sessionKey ?? "session",
+            sessionPath: session.sessionPath,
+        };
+        // Step 3b: Pre-turn sync pull (opt-in) — MUST happen before any continuity state reads
+        // so that obligations, episodes, cares, etc. reflect the latest remote state.
+        let syncFailure;
+        let syncConfig = { enabled: false, remote: "origin" };
+        try {
+            syncConfig = (0, config_1.getSyncConfig)();
+        }
+        catch { /* config not available */ }
+        // Wrap the turn body in try/finally so drainSyncWrites always runs — even on
+        // error or early-return failover paths. This prevents writes from leaking into
+        // the next turn's accumulator.
+        try {
+            /* v8 ignore start -- sync-enabled branches tested in sync.test.ts, pipeline tests mock at module boundary @preserve */
+            if (syncConfig.enabled) {
+                const pullResult = (0, sync_1.preTurnPull)((0, identity_1.getAgentRoot)(), syncConfig);
+                if (!pullResult.ok) {
+                    syncFailure = pullResult.error;
+                }
+                // Check for pending-sync from a prior failed push
+                if (!syncFailure) {
+                    const pendingSyncPath = path.join((0, identity_1.getAgentRoot)(), "state", "pending-sync.json");
+                    try {
+                        if (fs.existsSync(pendingSyncPath)) {
+                            const pendingSync = JSON.parse(fs.readFileSync(pendingSyncPath, "utf-8"));
+                            syncFailure = `prior sync push failed: ${pendingSync.error ?? "unknown"}`;
+                            fs.unlinkSync(pendingSyncPath);
+                        }
+                    }
+                    catch {
+                        // Ignore read errors for pending-sync
+                    }
+                }
+            }
+            /* v8 ignore stop */
+            const activeBridges = (0, manager_1.createBridgeManager)().findBridgesForSession({
+                friendId: currentSession.friendId,
+                channel: currentSession.channel,
+                key: currentSession.key,
+            });
+            const bridgeContext = (0, manager_1.formatBridgeContext)(activeBridges) || undefined;
+            let sessionActivity = [];
+            try {
+                const agentRoot = (0, identity_1.getAgentRoot)();
+                sessionActivity = (0, session_activity_1.listSessionActivity)({
+                    sessionsDir: `${agentRoot}/state/sessions`,
+                    friendsDir: `${agentRoot}/friends`,
+                    agentName: (0, identity_1.getAgentName)(),
+                    currentSession: {
+                        friendId: currentSession.friendId,
+                        channel: currentSession.channel,
+                        key: currentSession.key,
+                    },
+                });
+            }
+            catch {
+                sessionActivity = [];
+            }
+            let targetCandidates = [];
+            try {
+                if (input.channel !== "inner") {
+                    const agentRoot = (0, identity_1.getAgentRoot)();
+                    targetCandidates = await (0, target_resolution_1.listTargetSessionCandidates)({
+                        sessionsDir: `${agentRoot}/state/sessions`,
+                        friendsDir: `${agentRoot}/friends`,
+                        agentName: (0, identity_1.getAgentName)(),
+                        currentSession: {
+                            friendId: currentSession.friendId,
+                            channel: currentSession.channel,
+                            key: currentSession.key,
+                        },
+                        friendStore: input.friendStore,
+                    });
+                }
+            }
+            catch {
+                targetCandidates = [];
+            }
+            let pendingObligations = [];
+            try {
+                pendingObligations = (0, obligations_1.readPendingObligations)((0, identity_1.getAgentRoot)());
+            }
+            catch {
+                pendingObligations = [];
+            }
+            let codingSessions = [];
+            let otherCodingSessions = [];
+            try {
+                const liveCodingSessions = (0, coding_1.getCodingSessionManager)()
+                    .listSessions()
+                    .filter((session) => isLiveCodingSessionStatus(session.status) && Boolean(session.originSession));
+                codingSessions = liveCodingSessions.filter((session) => session.originSession?.friendId === currentSession.friendId
+                    && session.originSession.channel === currentSession.channel
+                    && session.originSession.key === currentSession.key);
+                otherCodingSessions = liveCodingSessions.filter((session) => !(session.originSession?.friendId === currentSession.friendId
+                    && session.originSession.channel === currentSession.channel
+                    && session.originSession.key === currentSession.key));
+            }
+            catch {
+                codingSessions = [];
+                otherCodingSessions = [];
+            }
+            const activeWorkFrame = (0, active_work_1.buildActiveWorkFrame)({
+                currentSession,
+                currentObligation,
+                mustResolveBeforeHandoff,
+                inner: readInnerWorkState(),
+                bridges: activeBridges,
+                codingSessions,
+                otherCodingSessions,
+                pendingObligations,
+                taskBoard: (() => {
+                    try {
+                        return (0, tasks_1.getTaskModule)().getBoard();
+                    }
+                    catch {
+                        return emptyTaskBoard();
+                    }
+                })(),
+                friendActivity: sessionActivity,
+                targetCandidates,
+                innerReturnObligations: (() => {
+                    try {
+                        return (0, obligations_2.listActiveObligations)((0, identity_1.getAgentName)());
+                    }
+                    catch {
+                        return [];
+                    }
+                })(),
+            });
+            const delegationDecision = (0, delegation_1.decideDelegation)({
+                channel: input.channel,
+                ingressTexts: input.continuityIngressTexts ?? [],
+                activeWork: activeWorkFrame,
+                mustResolveBeforeHandoff,
+            });
+            // Step 4: Drain deferred friend returns, then ordinary per-session pending.
+            const deferredReturns = input.channel === "inner"
+                ? []
+                : (input.drainDeferredReturns?.(resolvedContext.friend.id) ?? []);
+            const sessionPending = input.drainPending(input.pendingDir);
+            const pending = [...deferredReturns, ...sessionPending];
+            // Assemble messages: session messages + pending + inbound user messages
+            // NOTE: live world-state checkpoint and pending messages are rendered via buildSystem (system prompt sections)
+            const extraPrefixSections = input.onPendingDrained?.(pending) ?? [];
+            // extraPrefixSections from onPendingDrained still prepend to user message (e.g., inner dialog wakes)
+            if (extraPrefixSections.length > 0 && input.messages.length > 0) {
+                input.messages[0] = prependTurnSections(input.messages[0], extraPrefixSections);
+            }
+            // Append user messages from the inbound turn
+            for (const msg of input.messages) {
+                sessionMessages.push(msg);
+            }
+            // Step 4b: Continuity pipeline — derive tempo, build start-of-turn packet, snapshot obligations
+            let renderedStartOfTurnPacket;
+            const preTurnObligationIds = new Set(pendingObligations.map((ob) => `${ob.id}:${ob.status}`));
+            try {
+                const agentRoot = (0, identity_1.getAgentRoot)();
+                const agentName = (0, identity_1.getAgentName)();
+                const recentEpisodes = (0, episodes_1.readRecentEpisodes)(agentRoot, { limit: 20 });
+                const activeCares = (0, cares_1.readActiveCares)(agentRoot);
+                const tempoState = (0, tempo_1.deriveTempo)({
+                    activeSessions: sessionActivity.length + 1,
+                    openObligations: pendingObligations.length,
+                    recentEpisodeCount: recentEpisodes.length,
+                    lastActivityAgeMs: sessionActivity.length > 0
+                        ? Date.now() - new Date(sessionActivity[0].lastActivityAt).getTime()
+                        : 0,
+                    hasBlockers: false, // obligations use specific statuses, not "blocked"
+                    highSalienceEpisodes: recentEpisodes.filter((ep) => ep.salience === "high" || ep.salience === "critical").length,
+                    activeCareCount: activeCares.length,
+                    atRiskCareCount: activeCares.filter((c) => c.currentRisk != null).length,
+                });
+                const temporalView = (0, temporal_view_1.buildTemporalView)(agentRoot, {
+                    tempo: tempoState.mode,
+                    preloaded: {
+                        recentEpisodes,
+                        activeObligations: pendingObligations,
+                        activeCares,
+                    },
+                });
+                const startOfTurnPacket = (0, start_of_turn_packet_1.buildStartOfTurnPacket)(temporalView, {
+                    canonicalObligations: {
+                        primary: activeWorkFrame.primaryObligation,
+                        all: activeWorkFrame.pendingObligations,
+                    },
+                });
+                /* v8 ignore next 3 -- syncFailure propagation tested in sync.test.ts @preserve */
+                if (syncFailure) {
+                    startOfTurnPacket.syncFailure = syncFailure;
+                }
+                renderedStartOfTurnPacket = (0, start_of_turn_packet_1.renderStartOfTurnPacket)(startOfTurnPacket);
+                if (!renderedStartOfTurnPacket)
+                    renderedStartOfTurnPacket = undefined;
+                // Update self-presence
+                const presence = (0, presence_1.derivePresence)(agentRoot, agentName, {
+                    activeSessions: sessionActivity.length + 1,
+                    openObligations: pendingObligations.length,
+                    activeBridges: activeBridges.length,
+                    codingLanes: codingSessions.length,
+                    currentTempo: tempoState.mode,
+                });
+                (0, presence_1.writePresence)(agentRoot, agentName, presence);
+            }
+            catch (continuityError) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "senses",
+                    event: "senses.continuity_error",
+                    message: "continuity pipeline failed, continuing without start-of-turn packet",
+                    meta: { error: continuityError instanceof Error ? continuityError.message : String(continuityError) },
+                });
+            }
+            // Step 5: runAgent
+            const existingToolContext = input.runAgentOptions?.toolContext;
+            const runAgentOptions = {
+                ...input.runAgentOptions,
+                bridgeContext,
+                activeWorkFrame,
+                delegationDecision,
+                startOfTurnPacket: renderedStartOfTurnPacket,
+                pendingMessages: pending.length > 0 ? pending.map((msg) => ({ from: msg.from, content: msg.content })) : undefined,
+                currentSessionKey: currentSession.key,
+                currentObligation,
+                mustResolveBeforeHandoff,
+                setMustResolveBeforeHandoff: (value) => {
+                    mustResolveBeforeHandoff = value;
+                },
+                toolContext: {
+                    /* v8 ignore next -- default no-op signin satisfies interface; real signin injected by sense adapter @preserve */
+                    signin: async () => undefined,
+                    ...existingToolContext,
+                    context: resolvedContext,
+                    friendStore: input.friendStore,
+                    currentSession,
+                    activeBridges,
+                },
+            };
+            const result = await input.runAgent(sessionMessages, input.callbacks, input.channel, input.signal, runAgentOptions);
+            // Step 5b: Failover on terminal error
+            if (result.outcome === "errored" && input.failoverState) {
+                try {
+                    const agentName = (0, identity_1.getAgentName)();
+                    const agentConfig = (0, identity_1.loadAgentConfig)();
+                    const currentProvider = agentConfig.humanFacing.provider;
+                    /* v8 ignore next -- defensive: errorClassification always set when errored @preserve */
+                    const classification = result.errorClassification ?? "unknown";
+                    const inventory = await (0, provider_ping_1.runHealthInventory)(agentName, currentProvider);
+                    const { secrets } = (0, auth_flow_1.loadAgentSecrets)(agentName);
+                    const providerModels = {};
+                    for (const [p, cfg] of Object.entries(secrets.providers)) {
+                        const model = cfg.model ?? cfg.modelName;
+                        if (typeof model === "string" && model)
+                            providerModels[p] = model;
+                    }
+                    // Use agent.json model (source of truth), not secrets model (may be stale)
+                    const currentModel = agentConfig.humanFacing.model;
+                    const failoverContext = (0, provider_failover_1.buildFailoverContext)(
+                    /* v8 ignore next -- defensive: error always set when errored @preserve */
+                    result.error?.message ?? "unknown error", classification, currentProvider, currentModel, agentName, inventory, providerModels);
+                    input.failoverState.pending = failoverContext;
+                    input.postTurn(sessionMessages, session.sessionPath, result.usage);
+                    return {
+                        resolvedContext,
+                        gateResult,
+                        usage: result.usage,
+                        turnOutcome: result.outcome,
+                        sessionPath: session.sessionPath,
+                        messages: sessionMessages,
+                        drainedPending: pending,
+                        failoverMessage: failoverContext.userMessage,
+                    };
+                    /* v8 ignore start -- failover catch: tested via pipeline failover sequence throws test but v8 under-reports catch coverage @preserve */
+                }
+                catch (failoverError) {
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "senses",
+                        event: "senses.failover_error",
+                        message: "failover sequence failed, falling through",
+                        meta: { error: failoverError instanceof Error ? failoverError.message : String(failoverError) },
+                    });
+                }
+                /* v8 ignore stop */
+            }
+            // Step 5c: Emit episodes for obligation state transitions
+            try {
+                const agentRoot = (0, identity_1.getAgentRoot)();
+                const postTurnObligations = (0, obligations_1.readPendingObligations)(agentRoot);
+                emitObligationTransitionEpisodes(agentRoot, preTurnObligationIds, postTurnObligations, pendingObligations);
+            }
+            catch {
+                // Episode emission is non-fatal
+            }
+            // Step 6: postTurn
+            const continuingState = {
+                ...(mustResolveBeforeHandoff ? { mustResolveBeforeHandoff: true } : {}),
+                ...(typeof lastFriendActivityAt === "string" ? { lastFriendActivityAt } : {}),
+            };
+            const nextState = result.outcome === "settled" || result.outcome === "blocked" || result.outcome === "superseded" || result.outcome === "observed"
+                ? (typeof lastFriendActivityAt === "string"
+                    ? { lastFriendActivityAt }
+                    : undefined)
+                : (Object.keys(continuingState).length > 0 ? continuingState : undefined);
+            input.postTurn(sessionMessages, session.sessionPath, result.usage, undefined, nextState);
+            // Step 7: Token accumulation
+            await input.accumulateFriendTokens(input.friendStore, resolvedContext.friend.id, result.usage);
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.pipeline_end",
+                message: "inbound turn pipeline completed",
+                meta: {
+                    channel: input.channel,
+                    friendId: resolvedContext.friend.id,
+                },
+            });
+            // DRY cross-session awareness: notify inner dialog that activity happened on another channel
+            // Inner dialog's next checkpoint will include this session's state
+            if (input.channel !== "inner") {
+                try {
+                    (0, socket_client_1.requestInnerWake)((0, identity_1.getAgentName)()).catch(/* v8 ignore next */ () => { });
+                }
+                catch { /* getAgentName may fail in test environments */ }
+            }
+            return {
+                resolvedContext,
+                gateResult,
+                usage: result.usage,
+                turnOutcome: result.outcome,
+                completion: result.completion,
+                sessionPath: session.sessionPath,
+                messages: sessionMessages,
+                drainedPending: pending,
+                ...(input.switchedProvider ? { switchedProvider: input.switchedProvider } : {}),
+            };
+        }
+        finally {
+            // Step 6b: Post-turn sync push (opt-in, turn-scoped writes only).
+            // In a finally block so writes are always drained — even on error or early-return
+            // failover paths. This prevents writes from leaking into the next turn.
+            const writtenPaths = (0, sync_1.drainSyncWrites)();
+            /* v8 ignore next 3 -- postTurnPush integration tested in sync.test.ts @preserve */
+            if (syncConfig.enabled && writtenPaths.length > 0) {
+                (0, sync_1.postTurnPush)((0, identity_1.getAgentRoot)(), syncConfig, writtenPaths);
+            }
+        }
+    }); // end runWithSyncContext
+}