@canonmsg/codex-plugin 0.14.0 → 0.18.0

package/dist/host.js

@@ -4,8 +4,8 @@ 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, } from '@canonmsg/agent-sdk';
-import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildPlanApprovalRequest, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, 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, rtdbRead, rtdbWrite, CanonApiError, sendMessageWithRetry, sendMessageWithRetryChunked, shouldTriggerAgentTurn, saveRuntimeSessionState, buildBoundedTurnTrail, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCanonTurnBriefPrompt, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
+import { getCodexImagePath, materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, } from '@canonmsg/agent-sdk';
+import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildPlanApprovalRequest, resolveQuestionAllowOther, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, 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, renderCanonTurnBriefPrompt, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { decideAutoReply, } from './inbound-policy.js';
 import { CodexConversationAdapter, } from './adapter.js';
 import { CodexAppServerAdapter } from './app-server-adapter.js';
@@ -15,7 +15,10 @@ import { deriveCodexPermissionEnvelope, mapCanonPermissionToCodex, } from './per
 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 { buildOutboxContextLine, ensureOutboxDir, flushOutbox, resolveOutboxDir, } from './outbox.js';
 import { runCli } from './cli-entry.js';
+import { collectMissedInboundMessages, STARTUP_RECOVERY_MAX_MESSAGES, STARTUP_RECOVERY_PAGE_SIZE, } from './startup-recovery.js';
 import { beginCommandBlock, claimCommandBlock, createCommandBlockTracker, } from './turn-activity.js';
 const HELP = `canon-codex — run a local Codex agent host for Canon
 
@@ -54,9 +57,6 @@ const MAX_SESSIONS = 12;
 const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 const HEARTBEAT_MS = 30_000;
 const IDLE_CHECK_MS = 60_000;
-const CONTROL_POLL_MS = 2_000;
-const IDLE_CONTROL_POLL_MS = 10_000;
-const CONTROL_POLL_JITTER_MS = 1_000;
 const CODEX_RUNTIME_CAPABILITIES = {
     ...DEFAULT_RUNTIME_CAPABILITIES,
     supportsInterrupt: true,
@@ -64,29 +64,20 @@ const CODEX_RUNTIME_CAPABILITIES = {
     supportsQueue: true,
     supportsNonFinalPermanentMessages: false,
 };
-function controlPollDelayMs(hasActiveWork) {
-    const base = hasActiveWork ? CONTROL_POLL_MS : IDLE_CONTROL_POLL_MS;
-    return base + Math.floor(Math.random() * CONTROL_POLL_JITTER_MS);
-}
 let workingDir = process.cwd();
 let workspaceOptions = [];
 let workspaceRoots = [];
 let workspaceRootMetadata = [];
+/** GPT reasoning-effort levels, applied next turn via model_reasoning_effort. */
+const CODEX_EFFORT_OPTIONS = [
+    { value: 'minimal', label: 'Minimal' },
+    { value: 'low', label: 'Low' },
+    { value: 'medium', label: 'Medium' },
+    { value: 'high', label: 'High' },
+];
+const CODEX_EFFORT_VALUES = new Set(CODEX_EFFORT_OPTIONS.map((option) => option.value));
 function buildCodexRuntimeDescriptor(input) {
     const commands = [
-        ...(input.supportsPlanMode
-            ? [{
-                    id: 'plan',
-                    label: 'Plan first',
-                    description: 'Ask Codex to plan before implementing. Text after /plan becomes the planning prompt.',
-                    aliases: ['plan'],
-                    category: 'plan',
-                    placements: ['composer_slash', 'command_palette'],
-                    availability: ['always'],
-                    trailingTextBehavior: 'send_as_prompt',
-                    dispatch: { kind: 'text_passthrough', template: '/plan {argument}' },
-                }]
-            : []),
         {
             id: 'runtime-status',
             label: 'Runtime status',
@@ -113,8 +104,36 @@ function buildCodexRuntimeDescriptor(input) {
         executionModes: input.executionModes,
         permissionModes: input.permissionModes,
         defaultPermissionMode: input.defaultPermissionMode,
+        permissionModeLabel: 'Execution policy',
+        modelLiveBehavior: 'next_turn',
+        effortOptions: [...CODEX_EFFORT_OPTIONS],
+        defaultEffort: 'medium',
+        effortLiveBehavior: 'next_turn',
         presentation: input.presentation,
         streamingTextMode: 'snapshot',
+        ...(input.supportsPlanMode
+            ? {
+                turnModes: [
+                    {
+                        id: 'normal',
+                        label: 'Normal',
+                        description: 'Let Codex answer or act normally.',
+                        scope: 'next_turn',
+                        default: true,
+                        activation: { kind: 'message_metadata', value: 'normal' },
+                    },
+                    {
+                        id: 'plan',
+                        label: 'Plan',
+                        description: 'Ask Codex to plan before implementing.',
+                        scope: 'next_turn',
+                        ownerOnly: true,
+                        aliases: ['plan'],
+                        activation: { kind: 'message_metadata', value: 'plan' },
+                    },
+                ],
+            }
+            : {}),
         commands,
         ...(input.supportsRichCards
             ? {
@@ -162,7 +181,7 @@ async function loadSessionConfig(conversationId, agentId) {
     return loadHostSessionConfig({
         conversationId,
         agentId,
-        extraStringFields: ['permissionMode'],
+        extraStringFields: ['permissionMode', 'effort'],
     });
 }
 function resolveSessionExecutionMode(config) {
@@ -237,6 +256,7 @@ function buildCanonPrompt(input) {
         activeSelfContextId: input.activeSelfContextId,
         provenance: input.provenance,
         replyContext: input.replyContext,
+        sessionContextLines: input.sessionContextLines,
         message: input.message,
     }));
 }
@@ -329,15 +349,21 @@ function mapCodexQuestions(value) {
             const description = typeof optionRecord.description === 'string' && optionRecord.description.trim()
                 ? optionRecord.description.trim().slice(0, 300)
                 : undefined;
-            return [{ label, value: label, ...(description ? { description } : {}) }];
+            const preview = typeof optionRecord.preview === 'string' && optionRecord.preview.trim()
+                ? optionRecord.preview.trim().slice(0, 4000)
+                : undefined;
+            return [{ label, value: label, ...(description ? { description } : {}), ...(preview ? { preview } : {}) }];
         });
         return [{
                 id,
                 question,
                 ...(header ? { header } : {}),
                 ...(choices.length > 0 ? { choices } : {}),
-                ...(choices.length > 0 && record.allowOther !== false ? { allowOther: true } : {}),
-                ...(record.allowOther === true || record.isOther === true ? { allowOther: true } : {}),
+                // Shared automatic-"Other" convention (Mac-app parity): on for choice
+                // questions unless the agent explicitly opts out.
+                ...(resolveQuestionAllowOther(choices.length > 0, record.allowOther ?? record.isOther)
+                    ? { allowOther: true }
+                    : {}),
                 ...(record.isSecret === true ? { isSecret: true } : {}),
                 ...(record.multiSelect === true ? { multiSelect: true } : {}),
             }];
@@ -403,7 +429,7 @@ export async function main() {
     const { apiKey, agentId: profileAgentId, agentName: profileAgentName, profile, baseUrl, lockHandle, } = resolveCanonAgent({ logPrefix: '[canon-codex]', expectedClientType: 'codex' });
     console.error(`[canon-codex] Starting${profile ? ` (profile: ${profile})` : ''} in ${workingDir}`);
     const client = new CanonClient(apiKey, baseUrl);
-    initRTDBAuth(client);
+    const rtdb = initRTDBAuth(client);
     const typingSignals = createTypingStatusPublisher({
         setTyping: (conversationId, typing, status) => status
             ? client.setTyping(conversationId, typing, status)
@@ -575,6 +601,7 @@ export async function main() {
             hostMode: true,
             clientType: 'codex',
             isActive: true,
+            ...(session.state.contextUsage ? { contextUsage: session.state.contextUsage } : {}),
         }).catch(() => { });
     }
     function writeTurn(session) {
@@ -800,12 +827,16 @@ export async function main() {
                     throw new ExecutionEnvironmentError(modelGuard, modelGuard);
                 }
                 const storedThreadId = loadStoredThreadId(runtimeId, agentId, conversationId, environment.baseCwd, environment.mode, policy.fingerprint);
+                const initialEffort = config?.effort && CODEX_EFFORT_VALUES.has(config.effort)
+                    ? config.effort
+                    : null;
                 const adapter = useAppServer
                     ? new CodexAppServerAdapter({
                         cwd: sessionCwd,
                         threadId: storedThreadId,
                         codexBin,
                         model: policy.model ?? null,
+                        reasoningEffort: initialEffort,
                         sandbox: policy.sandbox,
                         approvalPolicy: policy.approvalPolicy,
                         addDirs: args['add-dir'] ?? [],
@@ -818,6 +849,7 @@ export async function main() {
                         threadId: storedThreadId,
                         codexBin,
                         model: policy.model ?? null,
+                        reasoningEffort: initialEffort,
                         sandbox: policy.sandbox,
                         approvalPolicy: policy.approvalPolicy,
                         codexProfile: typeof args['codex-profile'] === 'string' ? args['codex-profile'] : null,
@@ -854,10 +886,8 @@ export async function main() {
                     turnCommandBlocks: createCommandBlockTracker(),
                 };
                 sessions.set(conversationId, session);
-                await Promise.all([
-                    baselineControlSignal(conversationId),
-                    baselineSessionControl(conversationId),
-                ]);
+                await controlPoller.baseline([conversationId]);
+                ensureOutboxDir(sessionCwd).catch((error) => console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Failed to create media outbox:`, error));
                 console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Environment → ${environment.mode} (${sessionCwd})`);
                 writeState(session);
                 writeTurn(session);
@@ -1124,6 +1154,7 @@ export async function main() {
                     method: request.method,
                 },
                 details: mappedApproval.details,
+                ...(mappedApproval.diff ? { diff: mappedApproval.diff } : {}),
                 responseUserId: ownerId ?? undefined,
                 allowSessionRule: true,
                 expiresAt,
@@ -1148,6 +1179,10 @@ export async function main() {
     }
     async function enqueueInboundMessage(input) {
         knownConversationIds.add(input.conversationId);
+        if (input.turnDispatch && input.turnDispatch.kind !== 'run_turn') {
+            console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Suppressed server-dispatched turn: ${input.turnDispatch.reason}`);
+            return;
+        }
         if (isRecord(input.message.metadata)
             && input.message.metadata.type === 'plan_approval_reply'
             && typeof input.message.metadata.decision === 'string') {
@@ -1156,7 +1191,9 @@ export async function main() {
             const decision = input.message.metadata.decision;
             const prompt = decision === 'approve'
                 ? 'The plan was approved. Implement the approved plan now.'
-                : `Please revise the plan.${feedback ? `\n\nRevision feedback:\n${feedback}` : ''}`;
+                : 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');
             return;
         }
@@ -1173,8 +1210,12 @@ export async function main() {
             }
         }
         const renderedContent = renderInboundContent(input.message, materialized);
+        const turnMetadata = normalizeTurnMetadata(input.message.metadata);
+        const requestedPlanMode = turnMetadata?.requestedTurnMode === 'plan';
         const planCommand = useAppServer
-            ? parsePlanCommand(renderedContent)
+            ? requestedPlanMode
+                ? { planMode: true, content: renderedContent }
+                : parsePlanCommand(renderedContent)
             : { planMode: false, content: renderedContent };
         const content = planCommand.content;
         const hydrated = await loadHydratedInboundContext({
@@ -1203,14 +1244,18 @@ export async function main() {
             .filter((path) => path !== null);
         const mediaAddDirs = uniqueStrings(promptMaterialized.map((attachment) => dirname(attachment.path)));
         const participantContext = hydrated.participantContext;
-        const autoReply = decideAutoReply(participantContext, behavior);
+        const autoReply = input.turnDispatch?.kind === 'run_turn'
+            ? {
+                allow: true,
+                reason: input.turnDispatch.reason || 'server dispatch allowed this turn',
+            }
+            : decideAutoReply(participantContext, behavior);
         if (!autoReply.allow) {
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Suppressed auto-reply: ${autoReply.reason}`);
             return;
         }
         console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Message from ${input.senderName}: "${content.slice(0, 80)}" (${autoReply.reason})`);
         markGroupContextModeUsed(input.conversationId, participantContext.groupContextMode);
-        const turnMetadata = normalizeTurnMetadata(input.message.metadata);
         const deliveryIntent = turnMetadata?.deliveryIntent ?? 'queue';
         const shouldMarkAccepted = turnMetadata?.inboundDisposition === 'queued';
         let session;
@@ -1242,6 +1287,7 @@ export async function main() {
             activeSelfContextId,
             provenance: hydrated.provenance,
             replyContext,
+            sessionContextLines: [buildOutboxContextLine(session.cwd)],
             message: input.message,
         });
         if (session.running && deliveryIntent === 'interrupt') {
@@ -1254,6 +1300,45 @@ export async function main() {
         }
         enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode);
     }
+    /**
+     * Turn-end media outbox flush (see ./outbox.ts for the convention). Never
+     * throws: upload failures are logged and the files stay in place for a
+     * later turn.
+     */
+    async function flushSessionOutbox(session) {
+        const logPrefix = `[canon-codex] [${session.conversationId.slice(0, 8)}]`;
+        try {
+            const result = await flushOutbox({
+                outboxDir: resolveOutboxDir(session.cwd),
+                send: (file) => sendMediaFileMessage(client, session.conversationId, file.path, '', {
+                    ...(session.activeSelfContextId ? { selfContextId: session.activeSelfContextId } : {}),
+                    metadata: {
+                        ...(session.currentTurnId ? { turnId: session.currentTurnId } : {}),
+                        // Media is permanent conversation content (promoted like a final
+                        // reply) but must never re-trigger other agents — the host's own
+                        // final text message stays the only turn-complete trigger.
+                        turnSemantics: 'turn_complete',
+                        replyBehavior: 'suppress_auto_reply',
+                    },
+                }),
+            });
+            for (const entry of result.sent) {
+                console.error(`${logPrefix} Sent outbox file ${entry.file.fileName} (${entry.messageId})`
+                    + (entry.removeFailed ? ' — removal failed; it may resend next turn' : ''));
+            }
+            for (const failure of result.failed) {
+                console.error(`${logPrefix} Outbox upload failed for ${failure.file.fileName}; left in place: ${failure.error}`);
+            }
+            for (const skipped of result.skipped) {
+                if (skipped.reason === 'too-large' || skipped.reason === 'file-cap') {
+                    console.error(`${logPrefix} Outbox skipped ${skipped.fileName} (${skipped.reason}); left in place`);
+                }
+            }
+        }
+        catch (error) {
+            console.error(`${logPrefix} Outbox flush failed:`, error instanceof Error ? error.message : error);
+        }
+    }
     async function runNextTurn(session) {
         if (session.running || session.closed)
             return;
@@ -1362,6 +1447,15 @@ export async function main() {
                     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);
                 }
             };
@@ -1389,6 +1483,11 @@ export async function main() {
             if (result.threadId && !session.resetRequested) {
                 saveStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, result.threadId, session.environment.mode, session.policyFingerprint);
             }
+            // Turn-end outbox flush — media lands before the final text reply.
+            // Interrupted turns keep their files for the next completed turn.
+            if (!result.interrupted) {
+                await flushSessionOutbox(session);
+            }
             if (!result.interrupted && result.finalMessage && nextTurn.planMode) {
                 const planApproval = buildPlanApprovalRequest(session.currentTurnId ?? randomUUID(), 'Plan ready for review.', {
                     responseUserId: ownerId ?? undefined,
@@ -1504,9 +1603,6 @@ export async function main() {
             }
         }
     }
-    let controlStopped = false;
-    const lastSeenControl = new Map();
-    const lastSeenSignal = new Map();
     let streamConnected = false;
     const hostAvailableExecutionModes = [
         ...EXECUTION_ENVIRONMENT_MODES,
@@ -1540,28 +1636,87 @@ export async function main() {
             supportsRichCards: useAppServer,
         }),
     };
-    async function baselineControlSignal(conversationId) {
-        if (lastSeenSignal.has(conversationId))
-            return;
-        const raw = await rtdbRead(`/control/${conversationId}/${agentId}/signal`).catch(() => null);
-        if (!raw || typeof raw !== 'object')
+    function applySessionControl(conversationId, control) {
+        const session = sessions.get(conversationId);
+        if (!session || session.closed)
             return;
-        const timestamp = Number(raw.updatedAt ?? 0);
-        if (timestamp > 0) {
-            lastSeenSignal.set(conversationId, timestamp);
+        if (control.model && control.model !== session.state.model) {
+            const modelGuard = buildCodexModelGuardMessage(control.model, codexCliStatus);
+            if (modelGuard) {
+                session.state.lastError = modelGuard;
+                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${modelGuard}`);
+                writeState(session);
+                // The poller consumes the node; skip effort handling for this pass,
+                // matching the legacy loop.
+                return;
+            }
+            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);
+        }
+        if (control.permissionMode) {
+            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] approval mode is session-creation-only; ignoring mid-session change request (${control.permissionMode})`);
+        }
+        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);
+            }
+            else {
+                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Ignoring unknown effort level (${control.effort})`);
+            }
         }
     }
-    async function baselineSessionControl(conversationId) {
-        if (lastSeenControl.has(conversationId))
+    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;
-        const raw = await rtdbRead(`/control/${conversationId}/${agentId}/session`).catch(() => null);
-        if (!raw || typeof raw !== 'object')
+        }
+        if (!session.running && (type !== 'stop_and_drop' || session.queue.length === 0)) {
+            // Nothing to interrupt or drop — just consume the signal.
             return;
-        const timestamp = Number(raw.updatedAt ?? 0);
-        if (timestamp > 0) {
-            lastSeenControl.set(conversationId, timestamp);
         }
+        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(() => { });
     }
+    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')),
+        onSessionControl: ({ conversationId, control }) => {
+            applySessionControl(conversationId, control);
+        },
+        onSignal: handleControlSignal,
+        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);
+        },
+    });
     let publishRuntimeDetailsInFlight = false;
     const publishRuntimeHeartbeat = async () => {
         heartbeatLocalRuntimeEntry(runtimeId, {
@@ -1618,6 +1773,12 @@ export async function main() {
                 const payload = {
                     descriptor,
                     surfaceMode: 'host',
+                    // The exec --json transport cannot block on approvals — without a
+                    // strip-level warning a user can believe they have an approval
+                    // gate they do not have.
+                    ...(useAppServer
+                        ? {}
+                        : { warning: "Approvals can't block on this Codex CLI — update Codex to enable the app-server transport and approval gates." }),
                     statusItems: [
                         {
                             id: 'transport',
@@ -1643,6 +1804,11 @@ export async function main() {
                             value: useAppServer ? 'Enabled' : 'Limited until app-server transport',
                             ...(useAppServer ? {} : { tone: 'warning' }),
                         },
+                        {
+                            id: 'mediaOut',
+                            label: 'Media out',
+                            value: 'Turn-end outbox',
+                        },
                     ],
                     execution: {
                         resolvedWorkspaceLabel: workspace?.label ?? workspaceId ?? null,
@@ -1677,6 +1843,10 @@ export async function main() {
                 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,
@@ -1686,6 +1856,7 @@ export async function main() {
                     activeSelfContextId: payload.activeSelfContextId,
                     selfContexts: payload.selfContexts,
                     provenance: payload.provenance,
+                    turnDispatch: payload.turnDispatch,
                 });
                 if (message.id) {
                     saveRuntimeSessionState(runtimeId, {
@@ -1774,17 +1945,19 @@ export async function main() {
                 conversationId: conversation.id,
                 baseCwd: workingDir,
             })?.lastInboundMessageId;
-            const latestPage = await client.getMessagesPage(conversation.id, 25);
-            const inboundMessages = latestPage.messages
-                .filter((message) => message.senderId !== agentId)
-                .sort((a, b) => String(a.createdAt ?? '').localeCompare(String(b.createdAt ?? '')));
-            const cursorIndex = cursor
-                ? inboundMessages.findIndex((message) => message.id === cursor)
-                : -1;
-            const messagesToRecover = cursorIndex >= 0
-                ? inboundMessages.slice(cursorIndex + 1)
-                : inboundMessages.slice(-1);
-            for (const latestMessage of messagesToRecover) {
+            const recovery = await collectMissedInboundMessages({
+                fetchPage: (before) => client.getMessagesPage(conversation.id, STARTUP_RECOVERY_PAGE_SIZE, before),
+                cursor,
+                agentId,
+            });
+            const latestPage = recovery.newestPage;
+            if (recovery.mode === 'truncated-window') {
+                console.error(`[canon-codex] [${conversation.id.slice(0, 8)}] Startup recovery cursor not found within ${STARTUP_RECOVERY_MAX_MESSAGES} messages; recovering truncated window`);
+            }
+            if (recovery.messages.length > 1) {
+                console.error(`[canon-codex] [${conversation.id.slice(0, 8)}] Recovered ${recovery.messages.length} missed messages in ${conversation.id}`);
+            }
+            for (const latestMessage of recovery.messages) {
                 const triggerDecision = shouldTriggerAgentTurn({
                     senderType: latestMessage.senderType ?? 'human',
                     metadata: latestMessage.metadata,
@@ -1819,89 +1992,7 @@ export async function main() {
     startCodexStreamInBackground(stream, (error) => {
         console.error('[canon-codex] SSE start error:', error instanceof Error ? error.message : error);
     });
-    const pollControl = async () => {
-        while (!controlStopped) {
-            const hadActiveWork = [...sessions.values()].some((session) => !session.closed
-                && (session.running || session.queue.length > 0 || session.turnState === 'waiting_input'));
-            for (const conversationId of [...sessions.keys()]) {
-                try {
-                    const controlRaw = await rtdbRead(`/control/${conversationId}/${agentId}/session`);
-                    if (controlRaw && typeof controlRaw === 'object') {
-                        const control = controlRaw;
-                        const timestamp = control.updatedAt ?? 0;
-                        if (timestamp > (lastSeenControl.get(conversationId) ?? 0)) {
-                            lastSeenControl.set(conversationId, timestamp);
-                            const session = sessions.get(conversationId);
-                            if (session && !session.closed) {
-                                if (control.model && control.model !== session.state.model) {
-                                    const modelGuard = buildCodexModelGuardMessage(control.model, codexCliStatus);
-                                    if (modelGuard) {
-                                        session.state.lastError = modelGuard;
-                                        console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${modelGuard}`);
-                                        writeState(session);
-                                        await rtdbWrite(`/control/${conversationId}/${agentId}/session`, null).catch(() => { });
-                                        continue;
-                                    }
-                                    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);
-                                }
-                                if (control.permissionMode) {
-                                    console.error(`[canon-codex] [${conversationId.slice(0, 8)}] approval mode is session-creation-only; ignoring mid-session change request (${control.permissionMode})`);
-                                }
-                                if (control.effort) {
-                                    console.error(`[canon-codex] [${conversationId.slice(0, 8)}] effort control is not mapped yet (${control.effort})`);
-                                }
-                            }
-                            await rtdbWrite(`/control/${conversationId}/${agentId}/session`, null).catch(() => { });
-                        }
-                    }
-                    const raw = await rtdbRead(`/control/${conversationId}/${agentId}/signal`);
-                    if (!raw || typeof raw !== 'object')
-                        continue;
-                    const signal = raw;
-                    const timestamp = signal.updatedAt ?? 0;
-                    if ((signal.type !== 'interrupt' && signal.type !== 'stop_and_drop' && signal.type !== 'new_session')
-                        || timestamp <= (lastSeenSignal.get(conversationId) ?? 0)) {
-                        continue;
-                    }
-                    lastSeenSignal.set(conversationId, timestamp);
-                    const session = sessions.get(conversationId);
-                    if (!session || session.closed)
-                        continue;
-                    if (signal.type === 'new_session') {
-                        console.error(`[canon-codex] [${conversationId.slice(0, 8)}] new_session signal`);
-                        await resetRuntimeSession(session);
-                        await rtdbWrite(`/control/${conversationId}/${agentId}/signal`, null).catch(() => { });
-                        continue;
-                    }
-                    if (!session.running && (signal.type !== 'stop_and_drop' || session.queue.length === 0)) {
-                        await rtdbWrite(`/control/${conversationId}/${agentId}/signal`, null).catch(() => { });
-                        continue;
-                    }
-                    console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${signal.type} signal`);
-                    if (signal.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(() => { });
-                    await rtdbWrite(`/control/${conversationId}/${agentId}/signal`, null).catch(() => { });
-                }
-                catch {
-                    // Ignore transient RTDB failures.
-                }
-            }
-            await new Promise((resolve) => setTimeout(resolve, controlPollDelayMs(hadActiveWork)));
-        }
-    };
-    void pollControl();
+    controlPoller.start();
     const heartbeat = setInterval(() => {
         for (const session of sessions.values()) {
             writeState(session);
@@ -1925,7 +2016,7 @@ export async function main() {
     }, IDLE_CHECK_MS);
     const shutdown = async () => {
         console.error('[canon-codex] Shutting down...');
-        controlStopped = true;
+        controlPoller.stop();
         clearInterval(heartbeat);
         clearInterval(idleCheck);
         stream.stop();

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { main as hostMain } from './host.js';
 export { main as registerMain } from './register.js';
 export { main as setupMain } from './setup.js';
-export { mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';
+export { extractCodexApprovalDiff, mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';
 export type { CanonCodexApprovalRequest, CodexAppServerApprovalMethod, CodexApprovalDecision, CodexNativeApprovalRequest, } from './app-server-approval.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { main as hostMain } from './host.js';
 export { main as registerMain } from './register.js';
 export { main as setupMain } from './setup.js';
-export { mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';
+export { extractCodexApprovalDiff, mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';