@canonmsg/codex-plugin 0.18.12 → 0.19.1

package/dist/host.js

@@ -4,10 +4,18 @@ import { randomUUID } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { dirname } from 'node:path';
 import { parseArgs } from 'node:util';
-import { getCodexImagePath, materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, } from '@canonmsg/agent-sdk';
-import { captureTurnArtifactSnapshot, collectTurnArtifacts, } from '@canonmsg/coding-agent-host';
-import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildPlanApprovalRequest, resolveQuestionAllowOther, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, buildCanonInboundFrameV1, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, createConversationMetadataLoader, createRuntimeStatePublisher, createTypingStatusPublisher, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfileLock, initRTDBAuth, buildLocalRuntimeId, heartbeatLocalRuntimeEntry, loadRuntimeSessionState, markLocalRuntimeStopped, normalizeTurnMetadata, parseRuntimeCardV1, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, CanonApiError, sendMessageWithRetry, sendMessageWithRetryChunked, shouldTriggerAgentTurn, saveRuntimeSessionState, buildBoundedTurnTrail, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCodingHostInboundPrompt, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
-import { decideAutoReply, } from './inbound-policy.js';
+import { getCodexImagePath, inferUploadMimeType, materializeMessageMedia, materializeReplyContextMedia, } from '@canonmsg/agent-sdk';
+import { resolvePackagedBridgeBin } from './bridge-bin.js';
+import { connectBridge } from '@canonmsg/framework';
+import { ConnectionClosedError, JsonRpcError } from '@canonmsg/framework/protocol';
+/** Send failed at the Canon/bridge boundary (turn itself completed). */
+function isBridgeDeliveryError(error) {
+    return error instanceof JsonRpcError || error instanceof ConnectionClosedError;
+}
+import { STARTUP_RECOVERY_MAX_MESSAGES, STARTUP_RECOVERY_PAGE_SIZE, captureTurnArtifactSnapshot, collectMissedInboundMessages, collectTurnArtifacts, createBufferedNotificationSource, createConversationDirectory, createFinalDelivery, createHitlWaiters, createPortTypingSignals, createRuntimeSignalHandler, createRuntimeWriters, createSessionLifecycle, createTurnQueue, decideAutoReply, handoffFinalMessage, } from '@canonmsg/agent-host';
+import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildPlanApprovalRequest, resolveQuestionAllowOther, buildCanonTurnContextV2, buildFirstPartyCodingRuntimeDescriptor, buildRuntimePresentationPolicy, buildCanonInboundFrameV1, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, EXECUTION_ENVIRONMENT_MODES, DEFAULT_RUNTIME_CAPABILITIES, normalizeTurnMetadata, parseRuntimeCardV1, shouldTriggerAgentTurn, renderCanonHostInboundContent, renderCodingHostInboundPrompt, } from '@canonmsg/core/contract';
+import { ExecutionEnvironmentError, buildConfiguredWorkspaceOptionsWithRoots, buildLocalRuntimeId, buildPublicWorkspaceOptions, buildPublicWorkspaceRoots, heartbeatLocalRuntimeEntry, loadRuntimeSessionState, markLocalRuntimeStopped, prepareConversationEnvironment, releaseConversationEnvironment, resolveCanonAgent, saveRuntimeSessionState, upsertLocalRuntimeEntry, } from '@canonmsg/core/local';
+import { readHostSessionConfig, resolveHostWorkspaceCwd, } from '@canonmsg/core/host';
 import { CodexConversationAdapter, } from './adapter.js';
 import { CodexAppServerAdapter } from './app-server-adapter.js';
 import { CODEX_APP_DYNAMIC_TOOLS, deniedCodexAppToolResult, handleCodexAppToolCall, isCodexAppToolCall, } from './codex-app-tools.js';
@@ -16,11 +24,9 @@ import { clearStoredThreadId, buildCodexThreadPolicyFingerprint, loadStoredThrea
 import { deriveCodexPermissionEnvelope, mapCanonPermissionToCodex, } from './permission-mode.js';
 import { detectCodexCliVersion } from './codex-cli-version.js';
 import { buildCodexModelGuardMessage, formatCodexTurnFailure, isRecoverableCodexThreadError, } from './error-format.js';
-import { startCodexStreamInBackground } from './host-lifecycle.js';
-import { createCodexControlPoller } from './control-channel.js';
+import { attachCodexControlNotifications } from './control-channel.js';
 import { runCli } from './cli-entry.js';
-import { collectMissedInboundMessages, STARTUP_RECOVERY_MAX_MESSAGES, STARTUP_RECOVERY_PAGE_SIZE, } from './startup-recovery.js';
-import { applyTextSegmentBlock, beginCommandBlock, claimCommandBlock, createCommandBlockTracker, } from './turn-activity.js';
+import { beginCommandBlock, claimCommandBlock, createCommandBlockTracker, hasSpeechSegmentText, textSegmentBlockId, } from './turn-activity.js';
 const HELP = `canon-codex — run a local Codex agent host for Canon
 
 USAGE
@@ -72,10 +78,29 @@ export function buildCodexLiveSessionConfig(input) {
         executionBranch: input.executionBranch ?? null,
     };
 }
+function buildCodexQueuedInput(input) {
+    return {
+        turnKey: randomUUID(),
+        prompt: input.prompt,
+        intent: input.intent ?? 'queue',
+        sourceMessageId: input.sourceMessageId ?? null,
+        markAccepted: Boolean(input.markAccepted),
+        imagePaths: input.imagePaths ?? [],
+        mediaAddDirs: input.mediaAddDirs ?? [],
+        planMode: Boolean(input.planMode),
+        artifactRoutingMode: input.artifactRoutingMode ?? 'disabled',
+        canUseCodexAppTools: Boolean(input.canUseCodexAppTools),
+    };
+}
 const MAX_SESSIONS = 12;
 const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+/** Claude's streaming write throttle, adopted for both hosts (bridge plan Phase 2). */
+const STREAMING_THROTTLE_MS = 250;
 const HEARTBEAT_MS = 30_000;
 const IDLE_CHECK_MS = 60_000;
+/** Claude's bounded final-delivery retry machine, adopted for both hosts (bridge plan Phase 2). */
+const FINAL_DELIVERY_RETRY_MS = 30_000;
+const MAX_FINAL_DELIVERY_RETRIES = 1;
 const CODEX_RUNTIME_CAPABILITIES = {
     ...DEFAULT_RUNTIME_CAPABILITIES,
     supportsInterrupt: true,
@@ -83,6 +108,11 @@ const CODEX_RUNTIME_CAPABILITIES = {
     supportsQueue: true,
     supportsNonFinalPermanentMessages: false,
 };
+// This host process resolves and locks exactly one agent profile. The lock
+// handle returned by resolveCanonAgent is held here so the top-level runCli
+// error handler (outside main's scope) can release it on a failed start —
+// there is no core module-global profile-lock to fall back on.
+let activeLockHandle = null;
 let workingDir = process.cwd();
 let workspaceOptions = [];
 let workspaceRoots = [];
@@ -243,16 +273,16 @@ function buildCodexModelOptions(model) {
         ? [{ value: model.trim(), label: modelOptionLabel(model.trim()) }]
         : [];
 }
-async function publishAgentRuntime(agentId, runtime) {
-    await publishHostAgentRuntime(agentId, 'codex', runtime);
-}
-async function loadSessionConfig(conversationId, agentId) {
-    return loadHostSessionConfig({
-        conversationId,
-        agentId,
-        extraStringFields: CODEX_SESSION_CONFIG_FIELDS,
+async function publishAgentRuntime(port, runtime) {
+    await port.publishHostAgentRuntime({
+        clientType: 'codex',
+        runtime: runtime,
     });
 }
+async function loadSessionConfig(port, conversationId) {
+    const raw = await port.getSessionConfig({ conversationId });
+    return readHostSessionConfig(raw, CODEX_SESSION_CONFIG_FIELDS);
+}
 function resolveSessionExecutionMode(config) {
     if (config?.executionMode)
         return config.executionMode;
@@ -494,35 +524,46 @@ export async function main() {
         console.error(`[canon-codex] Could not detect Codex CLI version for ${codexBin}: ${codexCliStatus.error ?? 'unknown result'}`);
     }
     console.error(`[canon-codex] Codex transport: ${useAppServer ? 'app-server' : 'exec --json'}`);
-    const { apiKey, agentId: profileAgentId, agentName: profileAgentName, profile, baseUrl, lockHandle, } = resolveCanonAgent({ logPrefix: '[canon-codex]', expectedClientType: 'codex' });
+    const { agentName: profileAgentName, profile, lockHandle, } = resolveCanonAgent({ logPrefix: '[canon-codex]', expectedClientType: 'codex' });
+    activeLockHandle = lockHandle ?? null;
     console.error(`[canon-codex] Starting${profile ? ` (profile: ${profile})` : ''} in ${workingDir}`);
-    const client = new CanonClient(apiKey, baseUrl);
-    const rtdb = initRTDBAuth(client);
-    const typingSignals = createTypingStatusPublisher({
-        setTyping: (conversationId, typing, status) => status
-            ? client.setTyping(conversationId, typing, status)
-            : client.setTyping(conversationId, typing),
+    // ── Canon via the Bridge (bridge-execution-plan Phase 6) ──
+    // The daemon owns the SSE stream, RTDB auth, control polling, dedup and
+    // reconnect; notification handlers register through a buffered source
+    // inside `configure` (replay-safe) and attach after the machinery exists.
+    const notifications = createBufferedNotificationSource([
+        'ready',
+        'connectionState',
+        'onMessage',
+        'onMessageDeleted',
+        'onConversationUpdated',
+        'onSessionControl',
+        'onControlSignal',
+        'onControlPrimitive',
+        'onControlReply',
+    ]);
+    const bridge = await connectBridge({
+        ...(profile ? { profile } : {}),
+        mode: 'auto',
+        ...(resolvePackagedBridgeBin() ? { binPath: resolvePackagedBridgeBin() } : {}),
+        hello: {
+            clientType: 'codex',
+            wantFamilies: ['messages', 'runtime_turn'],
+        },
+        configure: (bridgeClient) => notifications.connect(bridgeClient),
     });
-    let agentId;
-    let ownerId = null;
-    let ownerName = null;
-    try {
-        const ctx = await client.getAgentMe();
-        agentId = ctx.agentId;
-        ownerId = ctx.ownerId;
-        ownerName = ctx.ownerName;
-        console.error(`[canon-codex] Connected as ${ctx.displayName || agentId}`);
-    }
-    catch {
-        if (profileAgentId) {
-            agentId = profileAgentId;
-        }
-        else {
-            const auth = await client.getAuthToken();
-            agentId = auth.agentId;
-        }
-        console.error(`[canon-codex] Authenticated as ${agentId}`);
-    }
+    // The BridgeClient's zod-derived result shapes mirror the core wire types
+    // structurally; the port pins the strong types the host machinery uses.
+    const port = bridge.client;
+    bridge.client.onProtocolError((error) => {
+        console.error(`[canon-codex] Bridge protocol error: ${error.message}`);
+    });
+    const typingSignals = createPortTypingSignals(port);
+    const agentId = bridge.hello.agentId;
+    const ownerId = bridge.hello.agentContext.ownerId ?? null;
+    const ownerName = bridge.hello.agentContext.ownerName ?? null;
+    console.error(`[canon-codex] Connected as ${bridge.hello.agentName || agentId} `
+        + `(canon-bridge${bridge.spawnedDaemon ? ' spawned' : ''} at ${bridge.socketPath})`);
     const launchArgs = [...process.argv.slice(2)];
     if (!launchArgs.some((arg) => arg === '--cwd' || arg.startsWith('--cwd='))) {
         launchArgs.push('--cwd', workingDir);
@@ -551,292 +592,81 @@ export async function main() {
         lastStartedAt: new Date().toISOString(),
         lastHeartbeatAt: new Date().toISOString(),
     });
-    const runtimeState = createRuntimeStatePublisher({
+    // ── Conversation directory (shared inbound-ingestion bookkeeping from @canonmsg/agent-host) ──
+    const directory = createConversationDirectory({
         agentId,
-        clientType: 'codex',
-        hostMode: true,
-    });
-    const sessions = new Map();
-    const pendingSessionCreations = new Map();
-    const conversationCache = new Map();
-    const knownConversationIds = new Set();
-    const promptedGroupContextConversationIds = new Set();
-    const pendingMembershipChanges = new Map();
-    let lastKnownConversationRefreshAt = 0;
-    const { getConversationMeta } = createConversationMetadataLoader({
-        client,
-        conversationCache,
-    });
+        ownerId,
+        ownerName,
+        refreshFloorMs: HEARTBEAT_MS,
+    }, { port });
+    const { conversationCache, knownConversationIds, refreshKnownConversationIds, handleConversationUpdated, markGroupContextModeUsed, loadHydratedInboundContext, } = directory;
     function resolveWorkspaceIdForBaseCwd(baseCwd) {
         return workspaceOptions.find((option) => option.cwd === baseCwd)?.id;
     }
-    async function refreshKnownConversationIds(force = false) {
-        if (!force && Date.now() - lastKnownConversationRefreshAt < HEARTBEAT_MS) {
-            return;
-        }
-        const conversations = await client.getConversations();
-        knownConversationIds.clear();
-        for (const conversation of conversations) {
-            knownConversationIds.add(conversation.id);
-            conversationCache.set(conversation.id, conversation);
-        }
-        lastKnownConversationRefreshAt = Date.now();
-    }
-    function handleConversationUpdated(payload) {
-        const rawMemberIds = payload.changes.memberIds;
-        if (!Array.isArray(rawMemberIds))
-            return;
-        const memberIds = rawMemberIds.filter((id) => typeof id === 'string');
-        const cached = conversationCache.get(payload.conversationId);
-        const membershipChange = payload.membershipChange
-            ?? (cached ? diffCanonMemberIds(cached.memberIds, memberIds) : null);
-        if (cached) {
-            conversationCache.set(payload.conversationId, {
-                ...cached,
-                memberIds,
-            });
-        }
-        if (membershipChange) {
-            pendingMembershipChanges.set(payload.conversationId, membershipChange);
-        }
-        if (!memberIds.includes(agentId)) {
-            knownConversationIds.delete(payload.conversationId);
-            conversationCache.delete(payload.conversationId);
-        }
-    }
-    function getGroupContextMode(conversationId, conversation) {
-        if (conversation?.type !== 'group')
-            return undefined;
-        if (pendingMembershipChanges.has(conversationId))
-            return 'membership_change';
-        if (!promptedGroupContextConversationIds.has(conversationId))
-            return 'initial';
-        return undefined;
-    }
-    function markGroupContextModeUsed(conversationId, mode) {
-        if (!mode)
-            return;
-        promptedGroupContextConversationIds.add(conversationId);
-        if (mode === 'membership_change') {
-            pendingMembershipChanges.delete(conversationId);
-        }
-    }
-    async function loadHydratedInboundContext(input) {
-        const [conversation, page] = await Promise.all([
-            getConversationMeta(input.conversationId),
-            input.hydratedPage
-                ? Promise.resolve(input.hydratedPage)
-                : client.getMessagesPage(input.conversationId, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT).catch(() => null),
-        ]);
-        return buildHydratedInboundContext({
-            agentId,
-            conversationId: input.conversationId,
-            conversation,
-            page,
-            activeSelfContextId: input.activeSelfContextId,
-            selfContexts: input.selfContexts,
-            provenance: input.provenance,
-            message: input.message,
-            senderName: input.senderName,
-            isOwner: input.isOwner,
-            ownerId,
-            ownerName,
-            membershipChange: pendingMembershipChanges.get(input.conversationId) ?? null,
-            groupContextMode: getGroupContextMode(input.conversationId, conversation),
-        });
-    }
-    function writeState(session) {
-        const appliedAt = Date.now();
-        const controlState = {};
-        if (session.state.model !== undefined) {
-            controlState.model = { value: session.state.model, source: 'applied', appliedAt };
-        }
-        if (session.state.permissionMode !== undefined) {
-            controlState.permissionMode = { value: session.state.permissionMode, source: 'applied', appliedAt };
-        }
-        if (session.state.effort !== undefined) {
-            controlState.effort = { value: session.state.effort, source: 'applied', appliedAt };
-        }
-        runtimeState.writeSessionState(session.conversationId, {
-            lastError: session.state.lastError,
-            model: session.state.model,
-            permissionMode: session.state.permissionMode,
-            effort: session.state.effort,
-            controlState,
-            cwd: session.cwd,
-            executionMode: session.environment.mode,
-            ...(session.environment.branch ? { executionBranch: session.environment.branch } : {}),
-            ...(session.environment.worktreePath ? { worktreePath: session.environment.worktreePath } : {}),
-            ...(resolveExecutionFallbackReason(session.environment)
-                ? { executionFallbackReason: resolveExecutionFallbackReason(session.environment) ?? undefined }
-                : {}),
-            hostMode: true,
-            clientType: 'codex',
-            isActive: true,
-            ...(session.state.contextUsage ? { contextUsage: session.state.contextUsage } : {}),
-        }).catch(() => { });
-    }
-    function writeTurn(session) {
-        const isOpenTurn = session.turnState === 'thinking'
-            || session.turnState === 'streaming'
-            || session.turnState === 'tool'
-            || session.turnState === 'waiting_input';
-        runtimeState.writeTurnState(session.conversationId, {
-            turnId: session.currentTurnId,
-            state: session.turnState,
-            queueDepth: session.queue.length,
-            currentSpeakerId: agentId,
-            lastAcceptedIntent: session.lastAcceptedIntent,
-            capabilities: CODEX_RUNTIME_CAPABILITIES,
-            ...(session.currentTurnOpenedAt ? { openedAt: session.currentTurnOpenedAt } : {}),
-            ...(isOpenTurn && session.currentTurnUpdatedAt ? { turnUpdatedAt: session.currentTurnUpdatedAt } : {}),
-            ...(session.turnState === 'idle' || session.turnState === 'completed' || session.turnState === 'interrupted'
-                ? { completedAt: { '.sv': 'timestamp' } }
-                : {}),
-        }).catch(() => { });
-    }
-    function markTurnProgress(session) {
-        session.currentTurnUpdatedAt = Date.now();
-    }
     async function markQueuedMessageAccepted(conversationId, sourceMessageId, markAccepted) {
         if (!markAccepted || !sourceMessageId)
             return;
-        await client.updateMessageDisposition(conversationId, sourceMessageId, 'accepted_now').catch(() => { });
-    }
-    async function markQueuedPromptsRejected(conversationId, prompts) {
-        await Promise.all(prompts.map((prompt) => {
-            if (!prompt.markAccepted || !prompt.sourceMessageId)
-                return Promise.resolve();
-            return client.updateMessageDisposition(conversationId, prompt.sourceMessageId, 'rejected').catch(() => { });
-        }));
-    }
-    function removeQueuedPrompt(conversationId, sourceMessageId) {
-        const session = sessions.get(conversationId);
-        if (!session || session.queue.length === 0)
-            return;
-        const before = session.queue.length;
-        session.queue = session.queue.filter((prompt) => prompt.sourceMessageId !== sourceMessageId);
-        if (session.queue.length !== before) {
-            writeTurn(session);
-        }
-    }
-    function clearStreaming(conversationId) {
-        runtimeState.clearStreaming(conversationId).catch(() => { });
-    }
-    function writeCodexStreaming(session, text, status) {
-        if (text !== null) {
-            session.turnLiveText = text;
-        }
-        runtimeState.writeStreaming(session.conversationId, {
-            text: session.turnLiveText,
-            status,
-            messageId: session.currentTurnId ?? undefined,
-            turnId: session.currentTurnId,
-            blocks: session.turnBlocks,
+        await port.setDisposition({
+            conversationId,
+            messageId: sourceMessageId,
+            inboundDisposition: 'accepted_now',
         }).catch(() => { });
     }
-    function upsertCodexTextSegment(session, event) {
-        const next = applyTextSegmentBlock({
-            turnLiveText: session.turnLiveText,
-            turnBlocks: session.turnBlocks,
-        }, {
-            turnId: session.currentTurnId,
-            itemId: event.itemId,
-            text: event.text,
-        });
-        session.turnLiveText = next.turnLiveText;
-        session.turnBlocks = next.turnBlocks;
-    }
-    function upsertTurnBlock(session, block) {
-        const now = Date.now();
-        const index = session.turnBlocks.findIndex((existing) => existing.id === block.id);
-        const existing = index >= 0 ? session.turnBlocks[index] : null;
-        const next = {
-            ...(existing ?? {
-                sequence: session.turnBlocks.length + 1,
-                createdAt: now,
-            }),
-            ...block,
-            turnId: session.currentTurnId ?? block.id,
-            updatedAt: now,
-        };
-        session.turnBlocks = index >= 0
-            ? [
-                ...session.turnBlocks.slice(0, index),
-                next,
-                ...session.turnBlocks.slice(index + 1),
-            ]
-            : [...session.turnBlocks, next];
-    }
-    function completeTurnBlock(session, id, summary) {
-        const existing = session.turnBlocks.find((block) => block.id === id);
-        if (!existing)
-            return;
-        upsertTurnBlock(session, {
-            id,
-            kind: existing.kind,
-            status: 'completed',
-            title: existing.title,
-            text: existing.text,
-            summary: summary ?? existing.summary,
-        });
-    }
-    function buildFinalTurnTrail(session) {
-        return buildBoundedTurnTrail(session.turnBlocks.map((block) => ({
-            ...block,
-            turnId: session.currentTurnId ?? block.turnId,
-        })));
-    }
     function buildCodexMessageId(session, kind) {
         return `codex-${kind}-${session.currentTurnId ?? randomUUID()}`;
     }
     function buildCodexRuntimeCardOutcomeMessageId(cardId, status) {
         return `codex-card-${cardId}-${status}`;
     }
-    async function handoffFinalMessage(conversationId) {
-        await sleep(FINAL_MESSAGE_HANDOFF_MS);
-        clearStreaming(conversationId);
-        typingSignals.clear(conversationId).catch(() => { });
-    }
-    function refreshVisibleWorkSignal(session) {
-        if (!session.running || session.closed)
-            return;
-        if (session.turnState !== 'thinking' && session.turnState !== 'tool')
-            return;
-        typingSignals.start(session.conversationId, 'thinking').catch(() => { });
-    }
-    function startVisibleWorkSignal(session) {
-        refreshVisibleWorkSignal(session);
-    }
-    function stopVisibleWorkSignal(session) {
-        if (session.typingKeepaliveTimer) {
-            clearInterval(session.typingKeepaliveTimer);
-            session.typingKeepaliveTimer = null;
-        }
-        typingSignals.clear(session.conversationId).catch(() => { });
-    }
-    function closeSession(conversationId) {
-        const session = sessions.get(conversationId);
-        if (!session)
-            return;
-        session.closed = true;
-        stopVisibleWorkSignal(session);
-        if ('close' in session.adapter && typeof session.adapter.close === 'function') {
-            session.adapter.close();
-        }
-        releaseConversationEnvironment(session.environment);
-        clearStreaming(conversationId);
-        runtimeState.clearSessionState(conversationId).catch(() => { });
-        runtimeState.clearTurnState(conversationId).catch(() => { });
-        typingSignals.clear(conversationId).catch(() => { });
-        typingSignals.dispose(conversationId);
-        sessions.delete(conversationId);
-    }
+    // ── Session manager (generic lifecycle from @canonmsg/agent-host) ──
+    const lifecycle = createSessionLifecycle({
+        maxSessions: MAX_SESSIONS,
+        idleTimeoutMs: IDLE_TIMEOUT_MS,
+        heartbeatMs: HEARTBEAT_MS,
+        idleCheckMs: IDLE_CHECK_MS,
+        logPrefix: '[canon-codex]',
+    }, {
+        knownConversationIds,
+        createSession: (conversationId) => createSessionForConversation(conversationId),
+        isSessionRunning: (session) => session.running,
+        writeTurnOnHeartbeat: (session) => !session.running,
+        writeSessionState: (session) => session.writeState(),
+        writeSessionTurn: (session) => session.writeTurn(),
+        releaseEnvironment: (session) => releaseConversationEnvironment(session.environment),
+        // Codex resume state (thread ids) is persisted during turns, not on close.
+        persistResumeState: () => { },
+        disposeRuntime: (session) => {
+            if ('close' in session.adapter && typeof session.adapter.close === 'function') {
+                session.adapter.close();
+            }
+        },
+        interruptRuntime: (session) => session.adapter.interrupt(),
+        port,
+        publishRuntimeHeartbeat: () => publishRuntimeHeartbeat(),
+        onShutdown: async () => {
+            detachControlNotifications();
+            notifications.detach();
+            await port.clearAgentRuntime().catch(() => { });
+            for (const session of [...sessions.values()]) {
+                await session.adapter.interrupt().catch(() => { });
+            }
+            bridge.client.close();
+        },
+        onShutdownComplete: () => {
+            markLocalRuntimeStopped(runtimeId);
+            lockHandle?.release();
+        },
+    });
+    const { sessions, getOrCreateSession, markSessionPendingInputsRejected, removeQueuedInput, } = lifecycle;
+    /**
+     * Codex-specific new-session reset: clear the stored Codex thread and keep
+     * the Canon session alive (unlike claude, which closes and re-creates).
+     */
     async function resetRuntimeSession(session) {
         const conversationId = session.conversationId;
         session.resetRequested = true;
-        const droppedPrompts = session.queue.splice(0);
-        await markQueuedPromptsRejected(conversationId, droppedPrompts);
+        const droppedInputs = session.pendingInputs.splice(0);
+        await markSessionPendingInputsRejected(conversationId, droppedInputs);
         clearStoredThreadId(runtimeId, agentId, conversationId, session.environment.baseCwd, session.environment.mode);
         session.adapter.clearThreadId();
         session.activeSelfContextId = null;
@@ -854,40 +684,16 @@ export async function main() {
             session.lastAcceptedIntent = null;
             session.resetRequested = false;
         }
-        stopVisibleWorkSignal(session);
-        clearStreaming(conversationId);
+        session.stopVisibleWork();
+        session.clearStreaming().catch(() => { });
         typingSignals.clear(conversationId).catch(() => { });
-        writeState(session);
-        writeTurn(session);
-    }
-    function evictOldestIdle() {
-        let oldest = null;
-        for (const session of sessions.values()) {
-            if (session.running)
-                continue;
-            if (!oldest || session.lastActivity < oldest.lastActivity)
-                oldest = session;
-        }
-        if (oldest) {
-            console.error(`[canon-codex] [${oldest.conversationId.slice(0, 8)}] Evicting idle session`);
-            closeSession(oldest.conversationId);
-        }
+        session.writeState();
+        session.writeTurn();
     }
-    async function getOrCreateSession(conversationId) {
-        knownConversationIds.add(conversationId);
-        const existing = sessions.get(conversationId);
-        if (existing && !existing.closed) {
-            existing.lastActivity = Date.now();
-            return existing;
-        }
-        const pending = pendingSessionCreations.get(conversationId);
-        if (pending)
-            return pending;
-        if (sessions.size >= MAX_SESSIONS) {
-            evictOldestIdle();
-        }
-        const creation = (async () => {
-            const config = await loadSessionConfig(conversationId, agentId);
+    /** Runtime-specific session construction, invoked via the lifecycle's getOrCreateSession. */
+    function createSessionForConversation(conversationId) {
+        return (async () => {
+            const config = await loadSessionConfig(port, conversationId);
             const sessionExecutionMode = resolveSessionExecutionMode(config);
             const workspaceCwd = resolveWorkspaceCwd(config);
             const environment = prepareConversationEnvironment({
@@ -941,12 +747,110 @@ export async function main() {
                         fullAuto: policy.fullAuto,
                         bypassApprovalsAndSandbox: policy.bypassApprovalsAndSandbox,
                     });
-                const session = {
+                // eslint-disable-next-line prefer-const -- session must be declared before the module closures but assigned after them
+                let session;
+                // ── Per-session RTDB writers (generic skeleton from @canonmsg/agent-host) ──
+                // Snapshot streaming behind claude's 250ms min-interval write gate —
+                // deliberate behavior parity (bridge plan Phase 2): rapid runtime
+                // events coalesce into one trailing RTDB write; terminal states
+                // (waiting_input, clear) still bypass the gate.
+                const writers = createRuntimeWriters({
+                    conversationId,
+                    agentId,
+                    capabilities: CODEX_RUNTIME_CAPABILITIES,
+                    fallbackTurnId: `codex-${conversationId}`,
+                    streamingMode: 'snapshot',
+                    streamingThrottleMs: STREAMING_THROTTLE_MS,
+                    requestedControls: {},
+                }, {
+                    session: () => session,
+                    port,
+                    buildSessionStateExtras: (writerSession) => ({
+                        ...(writerSession.state.lastError !== undefined
+                            ? { lastError: writerSession.state.lastError }
+                            : {}),
+                        cwd: writerSession.cwd,
+                        executionMode: writerSession.environment.mode,
+                        ...(writerSession.environment.branch ? { executionBranch: writerSession.environment.branch } : {}),
+                        ...(writerSession.environment.worktreePath ? { worktreePath: writerSession.environment.worktreePath } : {}),
+                        ...(resolveExecutionFallbackReason(writerSession.environment)
+                            ? { executionFallbackReason: resolveExecutionFallbackReason(writerSession.environment) ?? undefined }
+                            : {}),
+                        clientType: 'codex',
+                    }),
+                    formatControlError: (error) => error instanceof Error && error.message.trim()
+                        ? error.message.trim()
+                        : 'Codex did not apply that control.',
+                });
+                // ── HITL input waiter (generic skeleton from @canonmsg/agent-host) ──
+                const hitlWaiters = createHitlWaiters({
+                    conversationId,
+                    replyTimeoutMs: 30 * 60_000,
+                }, {
+                    session: () => session,
+                    port,
+                });
+                // ── Canon turn queue (generic skeleton from @canonmsg/agent-host) ──
+                const turnQueue = createTurnQueue({ conversationId }, {
+                    session: () => session,
+                    isSessionRunning: (queueSession) => queueSession.running,
+                    markSessionRunning: (queueSession) => { queueSession.running = true; },
+                    prepareInput: async () => { },
+                    sendInput: (input) => { void executeTurn(input); },
+                    interruptRuntime: (queueSession) => queueSession.adapter.interrupt(),
+                    port,
+                    writers: {
+                        writeTurn: () => writers.writeTurn(),
+                        stopVisibleWorkSignal: () => writers.stopVisibleWorkSignal(),
+                        clearStreaming: () => writers.clearStreaming(),
+                    },
+                });
+                // ── Final delivery (claude's bounded retry machine, adopted for codex) ──
+                const finalDelivery = createFinalDelivery({
+                    conversationId,
+                    logPrefix: '[canon-codex]',
+                    delivery: { mode: 'retry', retryMs: FINAL_DELIVERY_RETRY_MS, maxRetries: MAX_FINAL_DELIVERY_RETRIES },
+                }, {
+                    session: () => session,
+                    port,
+                    typingSignals,
+                    writers: {
+                        writeState: () => writers.writeState(),
+                        writeTurn: () => writers.writeTurn(),
+                        stopVisibleWorkSignal: () => writers.stopVisibleWorkSignal(),
+                        clearStreaming: () => writers.clearStreaming(),
+                        getFinalTurnTrail: () => writers.getFinalTurnTrail(),
+                        replaceStreamingSnapshot: (text, status) => writers.streamingOutput.replaceSnapshot(text, status),
+                    },
+                    resetCompletedTurnState: (deliverySession) => {
+                        deliverySession.running = false;
+                        deliverySession.state.state = 'idle';
+                        deliverySession.turnState = 'idle';
+                        deliverySession.currentTurnId = null;
+                        deliverySession.currentTurnOpenedAt = null;
+                        deliverySession.currentTurnUpdatedAt = null;
+                        deliverySession.currentTurnCanUseCodexAppTools = false;
+                        deliverySession.lastAcceptedIntent = null;
+                        deliverySession.resetRequested = false;
+                        deliverySession.activeInput = null;
+                        deliverySession.pendingFinalText = null;
+                        deliverySession.pendingFinalDelivery = null;
+                    },
+                    shouldDeliverFinal: (turn, deliverySession) => Boolean(turn)
+                        && !deliverySession.finalizedTurnKeys.has(turn.turnKey)
+                        && !deliverySession.interruptedTurnKeys.has(turn.turnKey),
+                    buildFinalMessageId: (turnKey) => `codex-final-${turnKey}`,
+                    drainPendingInput: () => turnQueue.drainPendingInput(),
+                    // Oversized finals chunk BRIDGE-side (its sendMessage runs core's
+                    // retry+chunking) — the host-side chunked sender is deleted.
+                });
+                session = {
                     conversationId,
                     cwd: sessionCwd,
                     environment,
                     adapter,
-                    queue: [],
+                    pendingInputs: [],
+                    activeInput: null,
                     running: false,
                     state: buildCodexInitialSessionState({
                         model: policy.model,
@@ -961,19 +865,372 @@ export async function main() {
                     currentTurnCanUseCodexAppTools: false,
                     activeSelfContextId: null,
                     lastAcceptedIntent: null,
+                    interruptedTurnKeys: new Set(),
+                    finalizedTurnKeys: new Set(),
+                    pendingFinalText: null,
+                    pendingFinalDelivery: null,
                     resetRequested: false,
                     lastActivity: Date.now(),
                     typingKeepaliveTimer: null,
+                    idleResetTimer: null,
+                    finalDeliveryTimer: null,
                     closed: false,
-                    turnLiveText: '',
-                    turnBlocks: [],
+                    streamingText: '',
+                    availableModels: [],
+                    runtimeControlErrors: {},
+                    pendingReply: null,
                     turnCommandBlocks: createCommandBlockTracker(),
+                    writeState: () => writers.writeState(),
+                    writeTurn: () => writers.writeTurn(),
+                    clearStreaming: () => writers.clearStreaming(),
+                    startVisibleWork: () => writers.startVisibleWorkSignal(),
+                    stopVisibleWork: () => writers.stopVisibleWorkSignal(),
+                    stageTurnBlock: (block) => { writers.streamingOutput.stageBlock(block); },
+                    setStreamingStatus: (status) => { writers.streamingOutput.setStatus(status).catch(() => { }); },
+                    waitForRuntimeInputResponse: (input) => hitlWaiters.waitForRuntimeInputResponse(input),
+                    enqueueInbound: (input) => turnQueue.enqueueCanonInput(input),
                 };
+                const handoffFinal = () => handoffFinalMessage({
+                    conversationId,
+                    clearStreaming: () => writers.clearStreaming(),
+                    typingSignals,
+                });
+                /** Drive the Codex runtime for one queued Canon turn (the adapter's input transport). */
+                async function executeTurn(turn) {
+                    if (session.closed)
+                        return;
+                    if (session.activeInput) {
+                        // Reentrancy guard: a concurrent start raced the in-flight turn —
+                        // requeue at the front; the post-turn drain picks it up.
+                        session.pendingInputs.unshift(turn);
+                        return;
+                    }
+                    // A turn starting during the final-handoff window owns the session
+                    // again — cancel the pending reset and drop any stale streamed state
+                    // from the previous turn (claude's 'running' transition parity).
+                    finalDelivery.clearIdleResetTimer();
+                    session.pendingFinalText = null;
+                    if (writers.streamingOutput.getBlocks().length > 0 || writers.streamingOutput.getText()) {
+                        writers.clearStreaming().catch(() => { });
+                    }
+                    session.activeInput = turn;
+                    session.running = true;
+                    session.state.lastError = undefined;
+                    session.state.state = 'running';
+                    session.currentTurnId = turn.turnKey;
+                    session.turnCommandBlocks = createCommandBlockTracker();
+                    session.currentTurnOpenedAt = Date.now();
+                    session.currentTurnUpdatedAt = session.currentTurnOpenedAt;
+                    session.currentTurnCanUseCodexAppTools = turn.canUseCodexAppTools;
+                    session.lastAcceptedIntent = turn.intent;
+                    session.turnState = 'thinking';
+                    session.lastActivity = Date.now();
+                    writers.writeState();
+                    writers.writeTurn();
+                    writers.startVisibleWorkSignal();
+                    // Status-only seed: 'thinking' renders as a working filament row on the
+                    // clients; text here would be bubbled as speech (v4 register rule).
+                    writers.streamingOutput.startThinking('').catch(() => { });
+                    let artifactBaseline = null;
+                    let artifactsRouted = false;
+                    const routeArtifactsOnce = async () => {
+                        if (artifactsRouted)
+                            return;
+                        artifactsRouted = true;
+                        if (turn.artifactRoutingMode === 'workspace-generated') {
+                            await routeWorkspaceGeneratedArtifacts(session, artifactBaseline);
+                        }
+                    };
+                    // True once the final-delivery machine owns the turn reset (handoff
+                    // timer or bounded retry) — the finally block must not clobber it.
+                    let turnSettledByFinalDelivery = false;
+                    try {
+                        const turnPrompt = turn.prompt;
+                        if (turn.artifactRoutingMode === 'workspace-generated') {
+                            artifactBaseline = await captureTurnArtifactSnapshot({ cwd: session.cwd }).catch((error) => {
+                                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Artifact snapshot failed:`, error instanceof Error ? error.message : error);
+                                return null;
+                            });
+                        }
+                        const modelGuardForTurn = buildCodexModelGuardMessage(session.state.model, codexCliStatus);
+                        if (modelGuardForTurn) {
+                            throw new ExecutionEnvironmentError(modelGuardForTurn, modelGuardForTurn);
+                        }
+                        const turnImagePaths = turn.imagePaths;
+                        const turnMediaAddDirs = turn.mediaAddDirs;
+                        const handleCodexEvent = (event) => {
+                            session.lastActivity = Date.now();
+                            if (event.type === 'thread.started') {
+                                if (session.resetRequested) {
+                                    return;
+                                }
+                                saveStoredThreadId(runtimeId, agentId, conversationId, session.environment.baseCwd, event.threadId, session.environment.mode, session.policyFingerprint);
+                                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Thread ${event.threadId}`);
+                                return;
+                            }
+                            if (event.type === 'skills.changed') {
+                                void refreshCodexSkillInventory(true).then(() => publishRuntimeHeartbeat());
+                                return;
+                            }
+                            if (event.type === 'message') {
+                                session.turnState = 'streaming';
+                                writers.writeTurn();
+                                writers.stopVisibleWorkSignal();
+                                writers.streamingOutput.replaceTextSegmentSnapshot(textSegmentBlockId(session.currentTurnId, event.itemId), event.text);
+                                return;
+                            }
+                            if (event.type === 'plan.updated') {
+                                session.turnState = 'streaming';
+                                writers.writeTurn();
+                                writers.stopVisibleWorkSignal();
+                                writers.streamingOutput.stageBlock({
+                                    id: `plan:${session.currentTurnId}`,
+                                    kind: 'plan',
+                                    status: 'running',
+                                    title: 'Plan',
+                                    text: event.text,
+                                });
+                                if (hasSpeechSegmentText(writers.streamingOutput.getBlocks())) {
+                                    // Speech is already flowing: publish the staged plan block
+                                    // only. Replacing the whole snapshot with plan text would be
+                                    // undone by the next agentMessage snapshot and make the
+                                    // smoothed bubble snap back and forth.
+                                    writers.streamingOutput.flush().catch(() => { });
+                                }
+                                else {
+                                    writers.streamingOutput.replaceSnapshot(event.text, 'streaming').catch(() => { });
+                                }
+                                return;
+                            }
+                            if (event.type === 'waiting') {
+                                session.turnState = 'waiting_input';
+                                writers.writeTurn();
+                                writers.stopVisibleWorkSignal();
+                                writers.streamingOutput.waitingInput().catch(() => { });
+                                return;
+                            }
+                            if (event.type === 'command.started') {
+                                const blockId = beginCommandBlock(session.turnCommandBlocks, {
+                                    turnId: session.currentTurnId,
+                                    command: event.command,
+                                    itemId: event.itemId,
+                                });
+                                writers.streamingOutput.stageBlock({
+                                    id: blockId,
+                                    kind: 'tool',
+                                    status: 'running',
+                                    title: summarizeCommand(event.command),
+                                    summary: 'Command running',
+                                });
+                                if (hasSpeechSegmentText(writers.streamingOutput.getBlocks())) {
+                                    // Speech is already flowing: the staged tool block narrates
+                                    // the command in the margin. Publish it without flapping the
+                                    // bubble status away from 'streaming'.
+                                    writers.streamingOutput.flush().catch(() => { });
+                                    return;
+                                }
+                                session.turnState = 'tool';
+                                writers.writeTurn();
+                                writers.startVisibleWorkSignal();
+                                writers.streamingOutput.setStatus('tool').catch(() => { });
+                                return;
+                            }
+                            if (event.type === 'command.completed') {
+                                const blockId = claimCommandBlock(session.turnCommandBlocks, {
+                                    turnId: session.currentTurnId,
+                                    command: event.command,
+                                    itemId: event.itemId,
+                                });
+                                const existing = writers.streamingOutput.getBlocks().find((block) => block.id === blockId);
+                                if (existing) {
+                                    writers.streamingOutput.stageBlock({
+                                        id: blockId,
+                                        kind: existing.kind,
+                                        status: 'completed',
+                                        summary: 'Command completed',
+                                    });
+                                }
+                                if (session.turnState === 'tool'
+                                    && !hasSpeechSegmentText(writers.streamingOutput.getBlocks())) {
+                                    session.turnState = 'thinking';
+                                    writers.writeTurn();
+                                    writers.startVisibleWorkSignal();
+                                    writers.streamingOutput.setStatus('thinking').catch(() => { });
+                                }
+                                else {
+                                    // Speech is flowing (or the turn never left streaming):
+                                    // publish the staged completion without a status flap.
+                                    writers.streamingOutput.flush().catch(() => { });
+                                }
+                                return;
+                            }
+                            if (event.type === 'turn.completed') {
+                                // Codex reports per-turn token usage but no context window, so the
+                                // meter publishes tokens only (input + cached covers the full
+                                // prompt context of the completed turn).
+                                const totalTokens = (event.usage?.input_tokens ?? 0)
+                                    + (event.usage?.cached_input_tokens ?? 0)
+                                    + (event.usage?.output_tokens ?? 0);
+                                if (totalTokens > 0) {
+                                    session.state.contextUsage = { totalTokens };
+                                }
+                                writers.writeState();
+                            }
+                        };
+                        const logCodexLine = (line) => {
+                            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${line}`);
+                        };
+                        const clearStoredThread = () => {
+                            clearStoredThreadId(runtimeId, agentId, conversationId, session.environment.baseCwd, session.environment.mode);
+                            session.adapter.clearThreadId();
+                        };
+                        const runTurnOnce = () => session.adapter.runTurn(turnPrompt, handleCodexEvent, logCodexLine, turnImagePaths, turnMediaAddDirs, {
+                            planMode: turn.planMode,
+                            onServerRequest: (request) => handleCodexServerRequest(session, request),
+                        });
+                        let result = await runTurnOnce();
+                        if (!result.interrupted
+                            && !result.finalMessage
+                            && result.exitCode
+                            && result.exitCode !== 0
+                            && isRecoverableCodexThreadError(result.errorText)) {
+                            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Stored thread was not found; clearing and retrying once`);
+                            clearStoredThread();
+                            result = await runTurnOnce();
+                        }
+                        if (result.threadId && !session.resetRequested) {
+                            saveStoredThreadId(runtimeId, agentId, conversationId, session.environment.baseCwd, result.threadId, session.environment.mode, session.policyFingerprint);
+                        }
+                        if (!result.interrupted && result.finalMessage && turn.planMode) {
+                            await routeArtifactsOnce();
+                            const planApproval = buildPlanApprovalRequest(session.currentTurnId ?? randomUUID(), 'Plan ready for review.', {
+                                responseUserId: ownerId ?? undefined,
+                                title: 'Codex Plan',
+                                body: result.finalMessage,
+                            });
+                            await port.sendMessage({
+                                conversationId,
+                                text: planApproval.text,
+                                messageId: buildCodexMessageId(session, 'plan'),
+                                metadata: {
+                                    ...planApproval.metadata,
+                                    turnId: session.currentTurnId,
+                                    turnSemantics: 'control',
+                                    replyBehavior: 'suppress_auto_reply',
+                                },
+                            });
+                            await handoffFinal();
+                            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Sent plan approval card`);
+                        }
+                        else if (!result.interrupted && result.finalMessage) {
+                            if (isRecoverableCodexThreadError(result.errorText)) {
+                                clearStoredThread();
+                            }
+                            await routeArtifactsOnce();
+                            // Claude's final-delivery machine (deliberate behavior parity):
+                            // failed sends are re-marked pending and retried on a bounded
+                            // timer instead of throwing into the generic failure path.
+                            const delivered = await finalDelivery.deliverFinalReply(result.finalMessage, turn);
+                            if (delivered) {
+                                session.activeInput = null;
+                                session.running = false;
+                                finalDelivery.scheduleFinalHandoffReset();
+                            }
+                            else {
+                                finalDelivery.scheduleFinalDeliveryRetry();
+                            }
+                            turnSettledByFinalDelivery = true;
+                        }
+                        else if (!result.interrupted && result.exitCode && result.exitCode !== 0) {
+                            await routeArtifactsOnce();
+                            const userVisibleError = formatCodexTurnFailure(result.errorText);
+                            session.state.lastError = userVisibleError;
+                            writers.writeState();
+                            if (result.errorText) {
+                                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Turn exited ${result.exitCode}: ${result.errorText}`);
+                            }
+                            const turnTrail = writers.getFinalTurnTrail();
+                            await port.sendMessage({
+                                conversationId,
+                                text: userVisibleError,
+                                messageId: buildCodexMessageId(session, 'error'),
+                                ...(session.activeSelfContextId
+                                    ? { selfContextId: session.activeSelfContextId }
+                                    : {}),
+                                metadata: {
+                                    turnId: session.currentTurnId,
+                                    turnSemantics: 'turn_complete',
+                                    deliveryIntent: session.lastAcceptedIntent ?? undefined,
+                                    ...(turnTrail.length > 0 ? { turnTrail } : {}),
+                                },
+                            });
+                            await handoffFinal();
+                        }
+                        else if (!result.interrupted) {
+                            await routeArtifactsOnce();
+                            await handoffFinal();
+                        }
+                        else if (result.interrupted) {
+                            session.turnState = 'interrupted';
+                            writers.writeTurn();
+                            writers.stopVisibleWorkSignal();
+                            writers.clearStreaming().catch(() => { });
+                            typingSignals.clear(conversationId).catch(() => { });
+                            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Turn interrupted`);
+                        }
+                    }
+                    catch (error) {
+                        const message = error instanceof ExecutionEnvironmentError
+                            ? error.userMessage
+                            : isBridgeDeliveryError(error)
+                                ? `The Codex host completed the turn, but Canon could not deliver the reply: ${error.message}`
+                                : `The Codex host failed during the turn: ${error instanceof Error ? error.message : String(error)}`;
+                        session.state.lastError = message;
+                        writers.writeState();
+                        await routeArtifactsOnce();
+                        await port.sendMessage({
+                            conversationId,
+                            text: message,
+                            messageId: buildCodexMessageId(session, 'failure'),
+                            ...(session.activeSelfContextId
+                                ? { selfContextId: session.activeSelfContextId }
+                                : {}),
+                            metadata: {
+                                turnId: session.currentTurnId,
+                                turnSemantics: 'turn_complete',
+                                deliveryIntent: session.lastAcceptedIntent ?? undefined,
+                            },
+                        }).catch(() => { });
+                        await handoffFinal();
+                        if (error instanceof Error && isRecoverableCodexThreadError(error.message)) {
+                            clearStoredThreadId(runtimeId, agentId, conversationId, session.environment.baseCwd, session.environment.mode);
+                        }
+                        console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Turn failed:`, error);
+                    }
+                    finally {
+                        session.lastActivity = Date.now();
+                        if (!turnSettledByFinalDelivery) {
+                            writers.stopVisibleWorkSignal();
+                            session.running = false;
+                            session.state.state = 'idle';
+                            session.turnState = 'idle';
+                            session.currentTurnId = null;
+                            session.currentTurnOpenedAt = null;
+                            session.currentTurnUpdatedAt = null;
+                            session.currentTurnCanUseCodexAppTools = false;
+                            session.lastAcceptedIntent = null;
+                            session.resetRequested = false;
+                            session.activeInput = null;
+                            writers.writeState();
+                            writers.writeTurn();
+                            turnQueue.drainPendingInput();
+                        }
+                    }
+                }
                 sessions.set(conversationId, session);
-                await controlPoller.baseline([conversationId]);
                 console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Environment → ${environment.mode} (${sessionCwd})`);
-                writeState(session);
-                writeTurn(session);
+                session.writeState();
+                session.writeTurn();
                 return session;
             }
             catch (error) {
@@ -981,114 +1238,57 @@ export async function main() {
                 throw error;
             }
         })();
-        pendingSessionCreations.set(conversationId, creation);
-        try {
-            return await creation;
-        }
-        finally {
-            pendingSessionCreations.delete(conversationId);
-        }
-    }
-    function enqueuePrompt(session, prompt, intent = 'queue', toFront = false, sourceMessageId, markAccepted = false, imagePaths = [], mediaAddDirs = [], planMode = false, artifactRoutingMode = 'disabled', canUseCodexAppTools = false) {
-        const nextPrompt = {
-            prompt,
-            intent,
-            sourceMessageId,
-            markAccepted,
-            imagePaths,
-            mediaAddDirs,
-            planMode,
-            artifactRoutingMode,
-            canUseCodexAppTools,
-        };
-        if (toFront) {
-            session.queue.unshift(nextPrompt);
-        }
-        else {
-            session.queue.push(nextPrompt);
-        }
-        session.lastActivity = Date.now();
-        writeTurn(session);
-        void runNextTurn(session);
     }
     function resolveArtifactRoutingMode(participantContext) {
         return participantContext.conversationType === 'direct' && participantContext.isOwner
             ? 'workspace-generated'
             : 'disabled';
     }
-    async function waitForRuntimeInputResponse(input) {
-        while (Date.now() < input.expiresAt) {
-            const response = await client.consumeRuntimeInputResponse({
-                conversationId: input.conversationId,
-                inputId: input.inputId,
-            }).catch(() => null);
-            if (response?.status === 'submitted') {
-                return { status: 'submitted', value: response.value, answers: response.answers };
-            }
-            if (response?.status === 'cancelled' || response?.status === 'timeout') {
-                return { status: response.status };
-            }
-            await sleep(1_000);
-        }
-        const response = await client.consumeRuntimeInputResponse({
-            conversationId: input.conversationId,
-            inputId: input.inputId,
-        }).catch(() => null);
-        if (response?.status === 'submitted') {
-            return { status: 'submitted', value: response.value, answers: response.answers };
-        }
-        return { status: 'timeout' };
-    }
+    /**
+     * Approval answers read the bridge's DURABLE record (the bridge owns the
+     * single destructive consume loop + the approval_reply fast path); same 1s
+     * cadence as the legacy consume poll.
+     */
     async function waitForRuntimeApprovalResponse(input) {
+        const read = async () => port.getHitlState({ requestId: input.approvalId }).catch(() => null);
         while (Date.now() < input.expiresAt) {
-            const response = await client.consumeRuntimeApprovalResponse({
-                conversationId: input.conversationId,
-                approvalId: input.approvalId,
-            }).catch(() => null);
-            if (response?.status === 'allow') {
-                return { decision: 'allow', sessionRule: response.sessionRule };
+            const state = await read();
+            if (state?.status === 'submitted') {
+                const answer = (state.answer ?? {});
+                return answer.decision === 'deny'
+                    ? { decision: 'deny' }
+                    : { decision: 'allow', sessionRule: answer.sessionRule };
             }
-            if (response?.status === 'deny' || response?.status === 'timeout') {
+            if (state?.status === 'cancelled' || state?.status === 'timeout') {
                 return { decision: 'deny' };
             }
             await sleep(1_000);
         }
-        await client.consumeRuntimeApprovalResponse({
-            conversationId: input.conversationId,
-            approvalId: input.approvalId,
-        }).catch(() => null);
         return { decision: 'deny' };
     }
     async function waitForRuntimeCardResponse(input) {
-        while (Date.now() < input.expiresAt) {
-            const response = await client.consumeRuntimeCardResponse({
-                conversationId: input.conversationId,
-                cardId: input.cardId,
-            }).catch(() => null);
-            if (response?.status === 'submitted') {
+        const read = async () => port.getHitlState({ requestId: input.cardId }).catch(() => null);
+        const map = (state) => {
+            if (state?.status === 'submitted') {
+                const answer = (state.answer ?? {});
                 return {
                     status: 'submitted',
-                    ...(response.actionId ? { actionId: response.actionId } : {}),
-                    ...(response.values ? { values: response.values } : {}),
+                    ...(answer.actionId ? { actionId: answer.actionId } : {}),
+                    ...(answer.values ? { values: answer.values } : {}),
                 };
             }
-            if (response?.status === 'cancelled' || response?.status === 'timeout') {
-                return { status: response.status };
+            if (state?.status === 'cancelled' || state?.status === 'timeout') {
+                return { status: state.status };
             }
+            return null;
+        };
+        while (Date.now() < input.expiresAt) {
+            const mapped = map(await read());
+            if (mapped)
+                return mapped;
             await sleep(1_000);
         }
-        const response = await client.consumeRuntimeCardResponse({
-            conversationId: input.conversationId,
-            cardId: input.cardId,
-        }).catch(() => null);
-        if (response?.status === 'submitted') {
-            return {
-                status: 'submitted',
-                ...(response.actionId ? { actionId: response.actionId } : {}),
-                ...(response.values ? { values: response.values } : {}),
-            };
-        }
-        return { status: 'timeout' };
+        return map(await read()) ?? { status: 'timeout' };
     }
     function runtimeCardRequestPayload(method, params) {
         if (method !== 'item/runtimeCard/request'
@@ -1132,14 +1332,15 @@ export async function main() {
             let requestCreated = false;
             let requestResolved = false;
             try {
-                await client.createRuntimeCardRequest({
+                await port.requestCard({
                     conversationId: session.conversationId,
                     cardId,
                     card: { ...card, cardId },
-                    expiresAt,
-                    // Omit responseUserId so the backend targets a reachable member (the
-                    // owner if present, else the sole other member) — the owner is often
-                    // not a member of agent-to-user DMs.
+                    expiresAt: new Date(expiresAt).toISOString(),
+                    // responseUserId: null → the backend targets a reachable member
+                    // (the owner if present, else the sole other member) — the owner is
+                    // often not a member of agent-to-user DMs.
+                    responseUserId: null,
                     native: {
                         runtime: 'codex',
                         method: request.method,
@@ -1150,21 +1351,20 @@ export async function main() {
                             threadId: readString(params, 'threadId') ?? '',
                         },
                     },
-                    turnId: session.currentTurnId ?? undefined,
+                    ...(session.currentTurnId ? { turnId: session.currentTurnId } : {}),
                 });
                 requestCreated = true;
                 session.turnState = 'waiting_input';
-                markTurnProgress(session);
-                upsertTurnBlock(session, {
+                session.stageTurnBlock({
                     id: `card:${cardId}`,
                     kind: 'input',
                     status: 'pending',
                     title: card.title,
                     summary: card.template ?? 'runtime card',
                 });
-                writeTurn(session);
-                stopVisibleWorkSignal(session);
-                writeCodexStreaming(session, null, 'waiting_input');
+                session.writeTurn();
+                session.stopVisibleWork();
+                session.setStreamingStatus('waiting_input');
                 const response = await waitForRuntimeCardResponse({
                     conversationId: session.conversationId,
                     cardId,
@@ -1172,7 +1372,9 @@ export async function main() {
                 });
                 requestResolved = true;
                 const outcome = buildRuntimeCardOutcome(cardId, response.status, { reason: response.status });
-                await sendMessageWithRetry(client, session.conversationId, outcome.text, {
+                await port.sendMessage({
+                    conversationId: session.conversationId,
+                    text: outcome.text,
                     messageId: buildCodexRuntimeCardOutcomeMessageId(cardId, response.status),
                     metadata: {
                         ...outcome.metadata,
@@ -1181,25 +1383,27 @@ export async function main() {
                         replyBehavior: 'suppress_auto_reply',
                     },
                 });
-                completeTurnBlock(session, `card:${cardId}`, `Card ${response.status}`);
+                session.stageTurnBlock({
+                    id: `card:${cardId}`,
+                    kind: 'input',
+                    status: 'completed',
+                    summary: `Card ${response.status}`,
+                });
                 if (session.turnState === 'waiting_input') {
                     session.turnState = 'thinking';
-                    markTurnProgress(session);
-                    writeTurn(session);
-                    startVisibleWorkSignal(session);
-                    writeCodexStreaming(session, null, 'thinking');
+                    session.writeTurn();
+                    session.startVisibleWork();
+                    session.setStreamingStatus('thinking');
                 }
                 return response;
             }
             catch (error) {
                 if (requestCreated && !requestResolved) {
-                    await client.consumeRuntimeCardResponse({
-                        conversationId: session.conversationId,
-                        cardId,
-                        cancel: true,
-                    }).catch(() => null);
+                    await port.cancelHitl({ requestId: cardId }).catch(() => null);
                     const outcome = buildRuntimeCardOutcome(cardId, 'cancelled', { reason: 'interrupted' });
-                    await sendMessageWithRetry(client, session.conversationId, outcome.text, {
+                    await port.sendMessage({
+                        conversationId: session.conversationId,
+                        text: outcome.text,
                         messageId: buildCodexRuntimeCardOutcomeMessageId(cardId, 'cancelled'),
                         metadata: {
                             ...outcome.metadata,
@@ -1217,17 +1421,19 @@ export async function main() {
             const paramsArguments = isRecord(params.arguments) ? params.arguments : null;
             const questions = mapCodexQuestions(params.questions ?? paramsInput?.questions ?? paramsArguments?.questions);
             const inputId = readString(params, 'itemId') ?? requestId;
-            await client.createRuntimeInputRequest({
+            await port.requestInput({
                 conversationId: session.conversationId,
                 inputId,
                 kind: 'clarify',
-                expiresAt,
-                responseUserId: ownerId ?? undefined,
+                expiresAt: new Date(expiresAt).toISOString(),
+                ...(ownerId ? { responseUserId: ownerId } : {}),
                 title: 'Codex needs input',
                 prompt: questions?.length
                     ? 'Codex needs your input to continue.'
                     : 'Codex needs input.',
-                ...(questions ? { questions } : {}),
+                ...(questions
+                    ? { questions: questions }
+                    : { questions: [] }),
                 sensitive: Boolean(questions?.some((question) => question.isSecret)),
                 native: {
                     runtime: 'codex',
@@ -1239,13 +1445,9 @@ export async function main() {
                         threadId: readString(params, 'threadId') ?? '',
                     },
                 },
-                turnId: session.currentTurnId ?? undefined,
-            });
-            const response = await waitForRuntimeInputResponse({
-                conversationId: session.conversationId,
-                inputId,
-                expiresAt,
+                ...(session.currentTurnId ? { turnId: session.currentTurnId } : {}),
             });
+            const response = await session.waitForRuntimeInputResponse({ inputId, expiresAt });
             return { answers: response.status === 'submitted' ? response.answers ?? {} : {} };
         }
         const mappedApproval = mapCodexAppServerApprovalRequest({
@@ -1254,25 +1456,29 @@ export async function main() {
         });
         if (mappedApproval) {
             const approvalId = readString(params, 'approvalId') ?? readString(params, 'itemId') ?? requestId;
-            await client.createRuntimeApprovalRequest({
+            await port.requestApproval({
                 conversationId: session.conversationId,
                 approvalId,
                 toolName: mappedApproval.toolName,
-                toolSummary: mappedApproval.toolSummary,
+                detail: mappedApproval.toolSummary,
                 category: mappedApproval.category,
-                risk: mappedApproval.risk,
-                riskLevel: mappedApproval.riskLevel,
+                risk: mappedApproval.risk ?? 'normal',
+                ...(mappedApproval.riskLevel ? { riskLevel: mappedApproval.riskLevel } : {}),
                 native: {
                     ...mappedApproval.native,
                     requestId,
                     method: request.method,
                 },
-                details: mappedApproval.details,
-                ...(mappedApproval.diff ? { diff: mappedApproval.diff } : {}),
-                responseUserId: ownerId ?? undefined,
+                ...(mappedApproval.details
+                    ? { details: mappedApproval.details }
+                    : {}),
+                ...(mappedApproval.diff
+                    ? { diff: mappedApproval.diff }
+                    : {}),
+                ...(ownerId ? { responseUserId: ownerId } : {}),
                 allowSessionRule: true,
-                expiresAt,
-                turnId: session.currentTurnId ?? undefined,
+                expiresAt: new Date(expiresAt).toISOString(),
+                ...(session.currentTurnId ? { turnId: session.currentTurnId } : {}),
             });
             const response = await waitForRuntimeApprovalResponse({
                 conversationId: session.conversationId,
@@ -1308,7 +1514,12 @@ export async function main() {
                 : decision === 'reject'
                     ? `The plan was declined — keep planning and wait for guidance before implementing.${feedback ? `\n\nNotes:\n${feedback}` : ''}`
                     : `Please revise the plan.${feedback ? `\n\nRevision feedback:\n${feedback}` : ''}`;
-            enqueuePrompt(session, prompt, 'queue', false, input.message.id, false, [], [], decision !== 'approve', 'disabled', input.isOwner);
+            session.enqueueInbound(buildCodexQueuedInput({
+                prompt,
+                sourceMessageId: input.message.id,
+                planMode: decision !== 'approve',
+                canUseCodexAppTools: input.isOwner,
+            }));
             return;
         }
         let materialized = [];
@@ -1381,7 +1592,9 @@ export async function main() {
             const userMessage = error instanceof ExecutionEnvironmentError ? error.userMessage : message;
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Failed to create session: ${message}`);
             await markQueuedMessageAccepted(input.conversationId, input.message.id, shouldMarkAccepted);
-            await sendMessageWithRetryChunked(client, input.conversationId, `I couldn't start a coding session for this workspace: ${userMessage}`, {
+            await port.sendMessage({
+                conversationId: input.conversationId,
+                text: `I couldn't start a coding session for this workspace: ${userMessage}`,
                 messageId: `codex-start-failed-${input.message.id}`,
                 ...(activeSelfContextId ? { selfContextId: activeSelfContextId } : {}),
                 metadata: {
@@ -1404,19 +1617,36 @@ export async function main() {
             message: input.message,
         });
         if (session.running && deliveryIntent === 'interrupt') {
-            const artifactRoutingMode = resolveArtifactRoutingMode(participantContext);
-            enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode, artifactRoutingMode, participantContext.isOwner);
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Interrupting current turn for explicit human send-now`);
-            await session.adapter.interrupt().catch(() => { });
-            clearStreaming(input.conversationId);
-            typingSignals.clear(input.conversationId).catch(() => { });
-            return;
         }
         const artifactRoutingMode = resolveArtifactRoutingMode(participantContext);
-        enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode, artifactRoutingMode, participantContext.isOwner);
+        // The shared turn queue handles queue/interrupt/start semantics.
+        session.enqueueInbound(buildCodexQueuedInput({
+            prompt,
+            intent: deliveryIntent,
+            sourceMessageId: input.message.id,
+            markAccepted: shouldMarkAccepted,
+            imagePaths,
+            mediaAddDirs,
+            planMode: planCommand.planMode,
+            artifactRoutingMode,
+            canUseCodexAppTools: participantContext.isOwner,
+        }));
     }
-    function sendTurnArtifactFile(session, file) {
-        return sendMediaFileMessage(client, session.conversationId, file.path, '', {
+    async function sendTurnArtifactFile(session, file) {
+        // Byte transfer is bridge-owned (§B8): hand the bridge a path, it streams
+        // the upload; then send the permanent message with the attachment ref.
+        const uploaded = await port.uploadMedia({
+            path: file.path,
+            mime: inferUploadMimeType(file.path),
+            fileName: file.fileName,
+            conversationId: session.conversationId,
+        });
+        return port.sendMessage({
+            conversationId: session.conversationId,
+            text: '',
+            contentType: uploaded.attachment.kind,
+            attachments: [uploaded.attachment],
             ...(session.activeSelfContextId ? { selfContextId: session.activeSelfContextId } : {}),
             metadata: {
                 ...(session.currentTurnId ? { turnId: session.currentTurnId } : {}),
@@ -1456,298 +1686,6 @@ export async function main() {
             console.error(`${logPrefix} Artifact routing failed:`, error instanceof Error ? error.message : error);
         }
     }
-    async function runNextTurn(session) {
-        if (session.running || session.closed)
-            return;
-        const nextTurn = session.queue.shift();
-        if (!nextTurn)
-            return;
-        session.running = true;
-        session.state.lastError = undefined;
-        session.state.state = 'running';
-        session.currentTurnId = randomUUID();
-        session.turnLiveText = '';
-        session.turnBlocks = [];
-        session.turnCommandBlocks = createCommandBlockTracker();
-        session.currentTurnOpenedAt = Date.now();
-        session.currentTurnUpdatedAt = session.currentTurnOpenedAt;
-        session.currentTurnCanUseCodexAppTools = nextTurn.canUseCodexAppTools === true;
-        session.lastAcceptedIntent = nextTurn.intent;
-        session.turnState = 'thinking';
-        session.lastActivity = Date.now();
-        await markQueuedMessageAccepted(session.conversationId, nextTurn.sourceMessageId, nextTurn.markAccepted);
-        writeState(session);
-        writeTurn(session);
-        startVisibleWorkSignal(session);
-        // Status-only seed: 'thinking' renders as a working filament row on the
-        // clients; text here would be bubbled as speech (v4 register rule).
-        writeCodexStreaming(session, '', 'thinking');
-        let artifactBaseline = null;
-        let artifactsRouted = false;
-        const routeArtifactsOnce = async () => {
-            if (artifactsRouted)
-                return;
-            artifactsRouted = true;
-            if (nextTurn.artifactRoutingMode === 'workspace-generated') {
-                await routeWorkspaceGeneratedArtifacts(session, artifactBaseline);
-            }
-        };
-        try {
-            const turnId = session.currentTurnId ?? randomUUID();
-            session.currentTurnId = turnId;
-            let turnPrompt = nextTurn.prompt;
-            if (nextTurn.artifactRoutingMode === 'workspace-generated') {
-                artifactBaseline = await captureTurnArtifactSnapshot({ cwd: session.cwd }).catch((error) => {
-                    console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Artifact snapshot failed:`, error instanceof Error ? error.message : error);
-                    return null;
-                });
-            }
-            const modelGuard = buildCodexModelGuardMessage(session.state.model, codexCliStatus);
-            if (modelGuard) {
-                throw new ExecutionEnvironmentError(modelGuard, modelGuard);
-            }
-            const turnImagePaths = nextTurn.imagePaths ?? [];
-            const turnMediaAddDirs = nextTurn.mediaAddDirs ?? [];
-            const handleCodexEvent = (event) => {
-                session.lastActivity = Date.now();
-                if (event.type === 'thread.started') {
-                    if (session.resetRequested) {
-                        return;
-                    }
-                    saveStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, event.threadId, session.environment.mode, session.policyFingerprint);
-                    console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Thread ${event.threadId}`);
-                    return;
-                }
-                if (event.type === 'skills.changed') {
-                    void refreshCodexSkillInventory(true).then(() => publishRuntimeHeartbeat());
-                    return;
-                }
-                if (event.type === 'message') {
-                    session.turnState = 'streaming';
-                    markTurnProgress(session);
-                    writeTurn(session);
-                    stopVisibleWorkSignal(session);
-                    upsertCodexTextSegment(session, event);
-                    writeCodexStreaming(session, null, 'streaming');
-                    return;
-                }
-                if (event.type === 'plan.updated') {
-                    session.turnState = 'streaming';
-                    markTurnProgress(session);
-                    writeTurn(session);
-                    stopVisibleWorkSignal(session);
-                    upsertTurnBlock(session, {
-                        id: `plan:${session.currentTurnId}`,
-                        kind: 'plan',
-                        status: 'running',
-                        title: 'Plan',
-                        text: event.text,
-                    });
-                    writeCodexStreaming(session, event.text, 'streaming');
-                    return;
-                }
-                if (event.type === 'waiting') {
-                    session.turnState = 'waiting_input';
-                    markTurnProgress(session);
-                    writeTurn(session);
-                    stopVisibleWorkSignal(session);
-                    writeCodexStreaming(session, null, 'waiting_input');
-                    return;
-                }
-                if (event.type === 'command.started') {
-                    session.turnState = 'tool';
-                    markTurnProgress(session);
-                    writeTurn(session);
-                    startVisibleWorkSignal(session);
-                    const blockId = beginCommandBlock(session.turnCommandBlocks, {
-                        turnId: session.currentTurnId,
-                        command: event.command,
-                        itemId: event.itemId,
-                    });
-                    upsertTurnBlock(session, {
-                        id: blockId,
-                        kind: 'tool',
-                        status: 'running',
-                        title: summarizeCommand(event.command),
-                        summary: 'Command running',
-                    });
-                    writeCodexStreaming(session, null, 'tool');
-                    return;
-                }
-                if (event.type === 'command.completed') {
-                    const blockId = claimCommandBlock(session.turnCommandBlocks, {
-                        turnId: session.currentTurnId,
-                        command: event.command,
-                        itemId: event.itemId,
-                    });
-                    completeTurnBlock(session, blockId, 'Command completed');
-                    if (session.turnState === 'tool') {
-                        session.turnState = 'thinking';
-                        markTurnProgress(session);
-                        writeTurn(session);
-                        startVisibleWorkSignal(session);
-                        writeCodexStreaming(session, null, 'thinking');
-                    }
-                    return;
-                }
-                if (event.type === 'turn.completed') {
-                    // Codex reports per-turn token usage but no context window, so the
-                    // meter publishes tokens only (input + cached covers the full
-                    // prompt context of the completed turn).
-                    const totalTokens = (event.usage?.input_tokens ?? 0)
-                        + (event.usage?.cached_input_tokens ?? 0)
-                        + (event.usage?.output_tokens ?? 0);
-                    if (totalTokens > 0) {
-                        session.state.contextUsage = { totalTokens };
-                    }
-                    writeState(session);
-                }
-            };
-            const logCodexLine = (line) => {
-                console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] ${line}`);
-            };
-            const clearStoredThread = () => {
-                clearStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, session.environment.mode);
-                session.adapter.clearThreadId();
-            };
-            const runTurnOnce = () => session.adapter.runTurn(turnPrompt, handleCodexEvent, logCodexLine, turnImagePaths, turnMediaAddDirs, {
-                planMode: nextTurn.planMode,
-                onServerRequest: (request) => handleCodexServerRequest(session, request),
-            });
-            let result = await runTurnOnce();
-            if (!result.interrupted
-                && !result.finalMessage
-                && result.exitCode
-                && result.exitCode !== 0
-                && isRecoverableCodexThreadError(result.errorText)) {
-                console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Stored thread was not found; clearing and retrying once`);
-                clearStoredThread();
-                result = await runTurnOnce();
-            }
-            if (result.threadId && !session.resetRequested) {
-                saveStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, result.threadId, session.environment.mode, session.policyFingerprint);
-            }
-            if (!result.interrupted && result.finalMessage && nextTurn.planMode) {
-                await routeArtifactsOnce();
-                const planApproval = buildPlanApprovalRequest(session.currentTurnId ?? randomUUID(), 'Plan ready for review.', {
-                    responseUserId: ownerId ?? undefined,
-                    title: 'Codex Plan',
-                    body: result.finalMessage,
-                });
-                await sendMessageWithRetry(client, session.conversationId, planApproval.text, {
-                    messageId: buildCodexMessageId(session, 'plan'),
-                    metadata: {
-                        ...planApproval.metadata,
-                        turnId: session.currentTurnId,
-                        turnSemantics: 'control',
-                        replyBehavior: 'suppress_auto_reply',
-                    },
-                });
-                await handoffFinalMessage(session.conversationId);
-                console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Sent plan approval card`);
-            }
-            else if (!result.interrupted && result.finalMessage) {
-                if (isRecoverableCodexThreadError(result.errorText)) {
-                    clearStoredThread();
-                }
-                await routeArtifactsOnce();
-                const turnTrail = buildFinalTurnTrail(session);
-                await sendMessageWithRetryChunked(client, session.conversationId, result.finalMessage, {
-                    messageId: buildCodexMessageId(session, 'final'),
-                    ...(session.activeSelfContextId
-                        ? { selfContextId: session.activeSelfContextId }
-                        : {}),
-                    metadata: {
-                        turnId: session.currentTurnId,
-                        turnSemantics: 'turn_complete',
-                        deliveryIntent: session.lastAcceptedIntent ?? undefined,
-                        ...(turnTrail.length > 0 ? { turnTrail } : {}),
-                    },
-                });
-                await handoffFinalMessage(session.conversationId);
-                console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Sent reply (${result.finalMessage.length} chars)`);
-            }
-            else if (!result.interrupted && result.exitCode && result.exitCode !== 0) {
-                await routeArtifactsOnce();
-                const userVisibleError = formatCodexTurnFailure(result.errorText);
-                session.state.lastError = userVisibleError;
-                writeState(session);
-                if (result.errorText) {
-                    console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Turn exited ${result.exitCode}: ${result.errorText}`);
-                }
-                const turnTrail = buildFinalTurnTrail(session);
-                await sendMessageWithRetryChunked(client, session.conversationId, userVisibleError, {
-                    messageId: buildCodexMessageId(session, 'error'),
-                    ...(session.activeSelfContextId
-                        ? { selfContextId: session.activeSelfContextId }
-                        : {}),
-                    metadata: {
-                        turnId: session.currentTurnId,
-                        turnSemantics: 'turn_complete',
-                        deliveryIntent: session.lastAcceptedIntent ?? undefined,
-                        ...(turnTrail.length > 0 ? { turnTrail } : {}),
-                    },
-                });
-                await handoffFinalMessage(session.conversationId);
-            }
-            else if (!result.interrupted) {
-                await routeArtifactsOnce();
-                await handoffFinalMessage(session.conversationId);
-            }
-            else if (result.interrupted) {
-                session.turnState = 'interrupted';
-                writeTurn(session);
-                stopVisibleWorkSignal(session);
-                clearStreaming(session.conversationId);
-                typingSignals.clear(session.conversationId).catch(() => { });
-                console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Turn interrupted`);
-            }
-        }
-        catch (error) {
-            const message = error instanceof ExecutionEnvironmentError
-                ? error.userMessage
-                : error instanceof CanonApiError
-                    ? `The Codex host completed the turn, but Canon could not deliver the reply: ${error.message}`
-                    : `The Codex host failed during the turn: ${error instanceof Error ? error.message : String(error)}`;
-            session.state.lastError = message;
-            writeState(session);
-            await routeArtifactsOnce();
-            await sendMessageWithRetryChunked(client, session.conversationId, message, {
-                messageId: buildCodexMessageId(session, 'failure'),
-                ...(session.activeSelfContextId
-                    ? { selfContextId: session.activeSelfContextId }
-                    : {}),
-                metadata: {
-                    turnId: session.currentTurnId,
-                    turnSemantics: 'turn_complete',
-                    deliveryIntent: session.lastAcceptedIntent ?? undefined,
-                },
-            }).catch(() => { });
-            await handoffFinalMessage(session.conversationId);
-            if (error instanceof Error && isRecoverableCodexThreadError(error.message)) {
-                clearStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, session.environment.mode);
-            }
-            console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Turn failed:`, error);
-        }
-        finally {
-            stopVisibleWorkSignal(session);
-            session.running = false;
-            session.state.state = 'idle';
-            session.turnState = 'idle';
-            session.currentTurnId = null;
-            session.currentTurnOpenedAt = null;
-            session.currentTurnUpdatedAt = null;
-            session.currentTurnCanUseCodexAppTools = false;
-            session.lastAcceptedIntent = null;
-            session.resetRequested = false;
-            session.lastActivity = Date.now();
-            writeState(session);
-            writeTurn(session);
-            if (session.queue.length > 0) {
-                void runNextTurn(session);
-            }
-        }
-    }
     let streamConnected = false;
     const hostAvailableExecutionModes = [
         ...EXECUTION_ENVIRONMENT_MODES,
@@ -1816,7 +1754,7 @@ export async function main() {
             if (modelGuard) {
                 session.state.lastError = modelGuard;
                 console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${modelGuard}`);
-                writeState(session);
+                session.writeState();
                 // The poller consumes the node; skip effort handling for this pass,
                 // matching the legacy loop.
                 return;
@@ -1824,58 +1762,42 @@ export async function main() {
             session.adapter.setModel(control.model);
             session.state.model = control.model;
             console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Model set for next turn -> ${control.model}`);
-            writeState(session);
+            session.writeState();
         }
         if (control.permissionMode) {
             console.error(`[canon-codex] [${conversationId.slice(0, 8)}] approval mode is session-creation-only; ignoring mid-session change request (${control.permissionMode})`);
             // Convergence contract: a consumed session control must always be
             // answered. Re-publish the currently applied state so clients settle on
             // the authoritative value instead of holding the composer until timeout.
-            writeState(session);
+            session.writeState();
         }
         if (control.effort) {
             if (CODEX_EFFORT_VALUES.has(control.effort)) {
                 session.adapter.setReasoningEffort(control.effort);
                 session.state.effort = control.effort;
                 console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Reasoning effort set for next turn -> ${control.effort}`);
-                writeState(session);
+                session.writeState();
             }
             else {
                 console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Ignoring unknown effort level (${control.effort})`);
                 // Same contract: ignored values still get an authoritative re-publish.
-                writeState(session);
+                session.writeState();
             }
         }
     }
-    async function handleControlSignal(event) {
-        const { conversationId, type } = event;
-        const session = sessions.get(conversationId);
-        // No live session: dedupe already advanced, but the node stays in place,
-        // matching the legacy loop.
-        if (!session || session.closed)
-            return { consume: false };
-        if (type === 'new_session') {
-            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] new_session signal`);
-            await resetRuntimeSession(session);
-            return;
-        }
-        if (!session.running && (type !== 'stop_and_drop' || session.queue.length === 0)) {
-            // Nothing to interrupt or drop — just consume the signal.
-            return;
-        }
-        console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${type} signal`);
-        if (type === 'stop_and_drop') {
-            const droppedPrompts = session.queue.splice(0);
-            await markQueuedPromptsRejected(conversationId, droppedPrompts);
-        }
-        if (session.running) {
-            await session.adapter.interrupt();
-        }
-        session.turnState = 'interrupted';
-        writeTurn(session);
-        clearStreaming(conversationId);
-        typingSignals.clear(conversationId).catch(() => { });
-    }
+    // Interrupt/stop-clear signal handling (generic shell from @canonmsg/agent-host).
+    const handleControlSignal = createRuntimeSignalHandler({
+        agentId,
+        logPrefix: '[canon-codex]',
+        capabilities: CODEX_RUNTIME_CAPABILITIES,
+    }, {
+        sessions,
+        port,
+        isSessionRunning: (session) => session.running,
+        interruptRuntime: (session) => session.adapter.interrupt(),
+        resetSession: (session) => resetRuntimeSession(session),
+        markSessionPendingInputsRejected,
+    });
     async function handleControlPrimitive(event) {
         const { conversationId, value } = event;
         const primitiveId = typeof value.id === 'string' ? value.id : '';
@@ -1895,32 +1817,27 @@ export async function main() {
         try {
             await session.adapter.compactThread();
             console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Compact requested`);
-            writeState(session);
+            session.writeState();
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             session.state.lastError = `Could not compact Codex context: ${message}`;
             console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${session.state.lastError}`);
-            writeState(session);
+            session.writeState();
         }
     }
-    const controlPoller = createCodexControlPoller({
-        rtdb,
-        agentId,
-        conversationIds: () => sessions.keys(),
-        hasActiveWork: () => [...sessions.values()].some((session) => !session.closed
-            && (session.running || session.queue.length > 0 || session.turnState === 'waiting_input')),
+    // Control events arrive as bridge notifications — the bridge owns the ONE
+    // authoritative /control consumer for this identity (plan §2); the host's
+    // adaptive poller (cadence, jitter, baselines) is deleted with it.
+    const detachControlNotifications = attachCodexControlNotifications({
+        source: notifications.source,
         onSessionControl: ({ conversationId, control }) => {
             applySessionControl(conversationId, control);
         },
         onSignal: handleControlSignal,
         onPrimitive: handleControlPrimitive,
-        onError: (error) => {
-            // The legacy loop ignored transient RTDB failures; keep read/consume
-            // errors quiet but surface handler failures.
-            if (error.scope !== 'handler')
-                return;
-            console.error(`[canon-codex] [${(error.conversationId ?? 'unknown').slice(0, 8)}] Control ${error.key ?? 'poll'} handler failed:`, error.error instanceof Error ? error.error.message : error.error);
+        onError: (error, kind, conversationId) => {
+            console.error(`[canon-codex] [${(conversationId ?? 'unknown').slice(0, 8)}] Control ${kind} handler failed:`, error instanceof Error ? error.message : error);
         },
     });
     let publishRuntimeDetailsInFlight = false;
@@ -1933,7 +1850,7 @@ export async function main() {
         });
         if (!streamConnected)
             return;
-        await publishAgentRuntime(agentId, runtimeDescriptor).catch((error) => {
+        await publishAgentRuntime(port, runtimeDescriptor).catch((error) => {
             console.error('[canon-codex] Failed to publish agent runtime:', error);
         });
         if (publishRuntimeDetailsInFlight)
@@ -1943,15 +1860,14 @@ export async function main() {
             await refreshKnownConversationIds().catch((error) => {
                 console.error('[canon-codex] Failed to refresh known conversations:', error);
             });
-            await publishHostSessionSnapshots({
+            await port.publishHostSessionSnapshots({
                 conversationIds: Array.from(knownConversationIds),
-                agentId,
                 clientType: 'codex',
                 runtime: runtimeDescriptor,
-                workspaceOptions,
+                workspaceOptions: workspaceOptions.map(({ id, cwd }) => ({ id, cwd })),
                 defaultCwd: workingDir,
-                extraSessionConfigFields: CODEX_SESSION_CONFIG_FIELDS,
-                liveSessionConfigByConversation: new Map(Array.from(sessions.values()).map((session) => {
+                extraSessionConfigFields: [...CODEX_SESSION_CONFIG_FIELDS],
+                liveSessionConfigByConversation: Object.fromEntries(Array.from(sessions.values()).map((session) => {
                     const workspaceId = resolveWorkspaceIdForBaseCwd(session.environment.baseCwd);
                     return [
                         session.conversationId,
@@ -2033,7 +1949,10 @@ export async function main() {
                             : 'This Codex host uses the current exec --json transport, so Canon can show thinking, tool activity, and completed assistant-message previews, but not native plan questions or structured approvals.',
                     ],
                 };
-                await runtimeState.writeRuntimeInfo(conversationId, payload);
+                await port.publishRuntimeStatus({
+                    conversationId,
+                    presentation: payload,
+                });
             })).catch((error) => {
                 console.error('[canon-codex] Failed to publish runtime info:', error);
             });
@@ -2042,66 +1961,91 @@ export async function main() {
             publishRuntimeDetailsInFlight = false;
         }
     };
-    const stream = new CanonStream({
-        apiKey,
-        agentId,
-        handler: {
-            onMessage: (payload) => {
-                const message = payload.message;
-                if (message.senderId === agentId)
-                    return;
-                if (payload.turnDispatch && payload.turnDispatch.kind !== 'run_turn') {
-                    console.error(`[canon-codex] [${payload.conversationId.slice(0, 8)}] Ignoring server-dispatched observe-only message: ${payload.turnDispatch.reason}`);
-                    return;
-                }
-                void enqueueInboundMessage({
-                    conversationId: payload.conversationId,
-                    message,
-                    senderName: message.senderName || message.senderId,
-                    isOwner: message.isOwner ?? (ownerId != null && message.senderId === ownerId),
-                    behavior: payload.behavior,
-                    activeSelfContextId: payload.activeSelfContextId,
-                    selfContexts: payload.selfContexts,
-                    provenance: payload.provenance,
-                    turnDispatch: payload.turnDispatch,
-                });
-                if (message.id) {
-                    saveRuntimeSessionState(runtimeId, {
-                        conversationId: payload.conversationId,
-                        baseCwd: workingDir,
-                        lastInboundMessageId: message.id,
-                    });
-                }
-            },
-            onMessageDeleted: (payload) => {
-                removeQueuedPrompt(payload.conversationId, payload.messageId);
-            },
-            onConversationUpdated: (payload) => {
-                handleConversationUpdated(payload);
-            },
-            onConnected: () => {
+    // ── Inbound Canon events (bridge notifications) ──
+    // The bridge owns SSE reconnect/heartbeat/replay + dedup + self-filtering.
+    // HITL control-reply messages (approval_reply / plan_approval_reply) are
+    // STRIPPED from onMessage bridge-side; plan replies arrive as
+    // onControlReply and re-enter the plan flow below.
+    const handleBridgeMessage = (payload) => {
+        const message = payload.message;
+        if (message.senderId === agentId)
+            return;
+        if (payload.turnDispatch && payload.turnDispatch.kind !== 'run_turn') {
+            console.error(`[canon-codex] [${payload.conversationId.slice(0, 8)}] Ignoring server-dispatched observe-only message: ${payload.turnDispatch.reason}`);
+            return;
+        }
+        void enqueueInboundMessage({
+            conversationId: payload.conversationId,
+            message,
+            senderName: message.senderName || message.senderId,
+            isOwner: message.isOwner ?? (ownerId != null && message.senderId === ownerId),
+            behavior: payload.behavior,
+            activeSelfContextId: payload.activeSelfContextId,
+            selfContexts: payload.selfContexts,
+            provenance: payload.provenance,
+            turnDispatch: payload.turnDispatch,
+        });
+        if (message.id) {
+            saveRuntimeSessionState(runtimeId, {
+                conversationId: payload.conversationId,
+                baseCwd: workingDir,
+                lastInboundMessageId: message.id,
+            });
+        }
+    };
+    const attachInboundNotifications = () => notifications.attach({
+        onMessage: (params) => {
+            handleBridgeMessage(params);
+        },
+        onMessageDeleted: (params) => {
+            const payload = params;
+            removeQueuedInput(payload.conversationId, payload.messageId);
+        },
+        onConversationUpdated: (params) => {
+            handleConversationUpdated(params);
+        },
+        onControlReply: (params) => {
+            const payload = params;
+            const message = payload.message;
+            // Only the plan flow consumes stripped control replies host-side —
+            // approval/card replies resolve against the bridge's HITL records.
+            if (!isRecord(message.metadata) || message.metadata.type !== 'plan_approval_reply') {
+                return;
+            }
+            void enqueueInboundMessage({
+                conversationId: payload.conversationId,
+                message,
+                senderName: message.senderName || message.senderId,
+                isOwner: message.isOwner ?? (ownerId != null && message.senderId === ownerId),
+            });
+        },
+        ready: () => {
+            streamConnected = true;
+            void publishRuntimeHeartbeat();
+            console.error('[canon-codex] Bridge ready');
+        },
+        connectionState: (params) => {
+            const { upstream } = params;
+            if (upstream === 'connected') {
                 streamConnected = true;
                 void publishRuntimeHeartbeat();
-                console.error('[canon-codex] SSE connected');
-            },
-            onDisconnected: () => {
+                console.error('[canon-codex] Canon upstream connected');
+            }
+            else {
                 streamConnected = false;
-                runtimeState.clearAgentRuntime().catch(() => { });
-                console.error('[canon-codex] SSE disconnected');
-            },
-            onError: (error) => console.error(`[canon-codex] SSE error: ${error.message}`),
+                port.clearAgentRuntime().catch(() => { });
+                console.error(`[canon-codex] Canon upstream ${upstream}`);
+            }
         },
     });
     await refreshCodexSkillInventory();
     try {
-        const conversations = await client.getConversations();
-        lastKnownConversationRefreshAt = Date.now();
+        const conversations = await directory.listConversations();
+        directory.primeFromStartup(conversations);
         for (const conversation of conversations) {
-            knownConversationIds.add(conversation.id);
-            conversationCache.set(conversation.id, conversation);
-            clearStreaming(conversation.id);
-            runtimeState.clearSessionState(conversation.id).catch(() => { });
-            runtimeState.clearTurnState(conversation.id).catch(() => { });
+            port.clearStreaming({ conversationId: conversation.id }).catch(() => { });
+            port.clearSessionState({ conversationId: conversation.id }).catch(() => { });
+            port.clearTurnState({ conversationId: conversation.id }).catch(() => { });
         }
         for (const conversation of conversations) {
             const cursor = loadRuntimeSessionState(runtimeId, {
@@ -2109,7 +2053,12 @@ export async function main() {
                 baseCwd: workingDir,
             })?.lastInboundMessageId;
             const recovery = await collectMissedInboundMessages({
-                fetchPage: (before) => client.getMessagesPage(conversation.id, STARTUP_RECOVERY_PAGE_SIZE, before),
+                fetchPage: (before) => port.getMessages({
+                    conversationId: conversation.id,
+                    limit: STARTUP_RECOVERY_PAGE_SIZE,
+                    ...(before ? { before } : {}),
+                    includeBehavior: true,
+                }),
                 cursor,
                 agentId,
             });
@@ -2152,56 +2101,17 @@ export async function main() {
     catch (error) {
         console.error('[canon-codex] Failed to load startup conversations:', error);
     }
-    startCodexStreamInBackground(stream, (error) => {
-        console.error('[canon-codex] SSE start error:', error instanceof Error ? error.message : error);
-    });
-    controlPoller.start();
-    const heartbeat = setInterval(() => {
-        for (const session of sessions.values()) {
-            writeState(session);
-            if (!session.running) {
-                writeTurn(session);
-            }
-        }
-        void publishRuntimeHeartbeat();
-    }, HEARTBEAT_MS);
-    const idleCheck = setInterval(() => {
-        const now = Date.now();
-        for (const conversationId of [...sessions.keys()]) {
-            const session = sessions.get(conversationId);
-            if (!session || session.running)
-                continue;
-            if (now - session.lastActivity > IDLE_TIMEOUT_MS) {
-                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Idle timeout`);
-                closeSession(conversationId);
-            }
-        }
-    }, IDLE_CHECK_MS);
-    const shutdown = async () => {
-        console.error('[canon-codex] Shutting down...');
-        controlPoller.stop();
-        clearInterval(heartbeat);
-        clearInterval(idleCheck);
-        stream.stop();
-        await runtimeState.clearAgentRuntime().catch(() => { });
-        for (const session of [...sessions.values()]) {
-            await session.adapter.interrupt().catch(() => { });
-            closeSession(session.conversationId);
-        }
-        markLocalRuntimeStopped(runtimeId);
-        (lockHandle ?? getActiveProfileLock())?.release();
-        process.exit(0);
-    };
-    process.on('SIGINT', shutdown);
-    process.on('SIGTERM', shutdown);
-    process.on('SIGHUP', shutdown);
+    attachInboundNotifications();
+    // ── Heartbeat + idle cleanup + graceful shutdown (agent-host lifecycle) ──
+    lifecycle.startTimers();
+    lifecycle.installSignalHandlers();
     console.error('[canon-codex] Ready — sessions created on demand');
     await new Promise(() => { });
 }
 runCli(import.meta.url, main, (error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`[canon-codex] ${message}`);
-    getActiveProfileLock()?.release();
+    activeLockHandle?.release();
     process.exit(1);
 }, {
     name: 'canon-codex',