@canonmsg/codex-plugin 0.9.4 → 0.9.5

package/dist/adapter.d.ts

@@ -60,6 +60,7 @@ export declare class CodexConversationAdapter {
         bypassApprovalsAndSandbox?: boolean;
     });
     getThreadId(): string | null;
+    clearThreadId(): void;
     setModel(model: string | null): void;
     isRunning(): boolean;
     interrupt(): Promise<void>;

package/dist/adapter.js

@@ -31,6 +31,9 @@ export class CodexConversationAdapter {
     getThreadId() {
         return this.threadId;
     }
+    clearThreadId() {
+        this.threadId = null;
+    }
     setModel(model) {
         this.model = model;
     }

package/dist/cli-entry.d.ts

@@ -1,2 +1,2 @@
-export declare function isDirectExecution(moduleUrl: string): boolean;
-export declare function runCli(moduleUrl: string, main: () => void | Promise<void>, onError: (error: unknown) => void): void;
+export { handleCliMetadataRequest, isDirectExecution, readCliPackageVersion, runCli, } from '@canonmsg/core';
+export type { CliMetadata, RunCliMetadataOptions, } from '@canonmsg/core';

package/dist/cli-entry.js

@@ -1,26 +1 @@
-import { realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-export function isDirectExecution(moduleUrl) {
-    const entry = process.argv[1];
-    if (!entry)
-        return false;
-    const abs = resolve(entry);
-    let real = abs;
-    try {
-        real = realpathSync(abs);
-    }
-    catch {
-        // argv[1] may not exist on disk in rare harnesses; fall back to abs
-    }
-    return (pathToFileURL(real).href === moduleUrl ||
-        pathToFileURL(abs).href === moduleUrl);
-}
-export function runCli(moduleUrl, main, onError) {
-    if (!isDirectExecution(moduleUrl)) {
-        return;
-    }
-    Promise.resolve()
-        .then(() => main())
-        .catch(onError);
-}
+export { handleCliMetadataRequest, isDirectExecution, readCliPackageVersion, runCli, } from '@canonmsg/core';

package/dist/codex-cli-version.d.ts

@@ -0,0 +1,2 @@
+import { type CodexCliVersionStatus } from './error-format.js';
+export declare function detectCodexCliVersion(codexBin: string, timeoutMs?: number): CodexCliVersionStatus;

package/dist/codex-cli-version.js

@@ -0,0 +1,22 @@
+import { spawnSync } from 'node:child_process';
+import { parseCodexCliVersion, } from './error-format.js';
+export function detectCodexCliVersion(codexBin, timeoutMs = 2_000) {
+    const result = spawnSync(codexBin, ['--version'], {
+        encoding: 'utf-8',
+        timeout: timeoutMs,
+    });
+    const raw = [result.stdout, result.stderr]
+        .filter((value) => typeof value === 'string' && value.trim().length > 0)
+        .join('\n')
+        .trim();
+    return {
+        codexBin,
+        raw: raw || null,
+        version: parseCodexCliVersion(raw),
+        error: result.error
+            ? result.error.message
+            : result.status === 0
+                ? null
+                : `codex --version exited with status ${result.status ?? 'unknown'}`,
+    };
+}

package/dist/error-format.d.ts

@@ -0,0 +1,16 @@
+export declare const MIN_CODEX_VERSION_FOR_GPT_5_5 = "0.125.0";
+export interface CodexCliVersionStatus {
+    codexBin: string;
+    raw: string | null;
+    version: string | null;
+    error: string | null;
+}
+export declare function normalizeCodexDiagnosticText(value: string | null | undefined): string | null;
+export declare function isRecoverableCodexThreadError(value: string | null | undefined): boolean;
+export declare function isCodexUpgradeRequiredError(value: string | null | undefined): boolean;
+export declare function compareSemverLike(a: string, b: string): number;
+export declare function parseCodexCliVersion(raw: string | null | undefined): string | null;
+export declare function isGpt55Model(model: string | null | undefined): boolean;
+export declare function codexCliUpgradeMessage(model: string): string;
+export declare function buildCodexModelGuardMessage(model: string | null | undefined, status: Pick<CodexCliVersionStatus, 'version'>): string | null;
+export declare function formatCodexTurnFailure(errorText: string | null | undefined): string;

package/dist/error-format.js

@@ -0,0 +1,106 @@
+export const MIN_CODEX_VERSION_FOR_GPT_5_5 = '0.125.0';
+function extractErrorMessage(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const data = value;
+    const direct = typeof data.message === 'string' ? data.message.trim() : '';
+    if (direct)
+        return direct;
+    const error = data.error;
+    if (typeof error === 'string' && error.trim())
+        return error.trim();
+    if (error && typeof error === 'object') {
+        const nested = error;
+        const message = typeof nested.message === 'string' ? nested.message.trim() : '';
+        if (message)
+            return message;
+        const type = typeof nested.type === 'string' ? nested.type.trim() : '';
+        if (type)
+            return type;
+    }
+    return null;
+}
+function parseJsonMessage(text) {
+    try {
+        return extractErrorMessage(JSON.parse(text));
+    }
+    catch {
+        return null;
+    }
+}
+export function normalizeCodexDiagnosticText(value) {
+    if (!value)
+        return null;
+    const normalized = value.replace(/^error:\s*/i, '').trim();
+    if (!normalized)
+        return null;
+    const directJson = parseJsonMessage(normalized);
+    if (directJson)
+        return directJson;
+    for (const line of normalized.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{'))
+            continue;
+        const lineJson = parseJsonMessage(trimmed);
+        if (lineJson)
+            return lineJson;
+    }
+    return normalized;
+}
+export function isRecoverableCodexThreadError(value) {
+    const normalized = normalizeCodexDiagnosticText(value)?.toLowerCase() ?? '';
+    return /thread .*not found/.test(normalized)
+        || normalized.includes('unknown thread')
+        || normalized.includes('find_thread_path')
+        || normalized.includes('state db discrepancy');
+}
+export function isCodexUpgradeRequiredError(value) {
+    const normalized = normalizeCodexDiagnosticText(value)?.toLowerCase() ?? '';
+    return normalized.includes('requires a newer version of codex')
+        || (normalized.includes('upgrade') && normalized.includes('codex'));
+}
+export function compareSemverLike(a, b) {
+    const parse = (value) => value.split('.').map((part) => Number.parseInt(part, 10) || 0);
+    const left = parse(a);
+    const right = parse(b);
+    const length = Math.max(left.length, right.length, 3);
+    for (let index = 0; index < length; index += 1) {
+        const diff = (left[index] ?? 0) - (right[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+export function parseCodexCliVersion(raw) {
+    if (!raw)
+        return null;
+    const match = raw.match(/\b(\d+\.\d+\.\d+)\b/);
+    return match?.[1] ?? null;
+}
+export function isGpt55Model(model) {
+    return typeof model === 'string' && /^gpt-5\.5(?:$|[-_:])/i.test(model.trim());
+}
+export function codexCliUpgradeMessage(model) {
+    return `The selected Codex model (${model}) requires a newer local Codex CLI. Update @openai/codex to ${MIN_CODEX_VERSION_FOR_GPT_5_5} or newer, then restart this Canon host.`;
+}
+export function buildCodexModelGuardMessage(model, status) {
+    const modelId = typeof model === 'string' ? model.trim() : '';
+    if (!isGpt55Model(modelId))
+        return null;
+    if (!status.version)
+        return null;
+    return compareSemverLike(status.version, MIN_CODEX_VERSION_FOR_GPT_5_5) < 0
+        ? codexCliUpgradeMessage(modelId)
+        : null;
+}
+export function formatCodexTurnFailure(errorText) {
+    const normalized = normalizeCodexDiagnosticText(errorText);
+    if (!normalized) {
+        return 'The Codex session stopped unexpectedly before sending a final reply.';
+    }
+    if (isCodexUpgradeRequiredError(normalized)) {
+        return codexCliUpgradeMessage('gpt-5.5');
+    }
+    const shortened = normalized.length > 280 ? `${normalized.slice(0, 277)}...` : normalized;
+    return `Codex failed before sending a final reply: ${shortened}`;
+}

package/dist/host-lifecycle.d.ts

@@ -0,0 +1,4 @@
+export interface LongLivedStream {
+    start(): Promise<void>;
+}
+export declare function startCodexStreamInBackground(stream: LongLivedStream, onError: (error: unknown) => void): void;

package/dist/host-lifecycle.js

@@ -0,0 +1,3 @@
+export function startCodexStreamInBackground(stream, onError) {
+    stream.start().catch(onError);
+}

package/dist/host.js

@@ -6,9 +6,38 @@ import { getCodexImagePath, materializeMessageMedia, } from '@canonmsg/agent-sdk
 import { buildCanonHostPrompt, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, createConversationMetadataLoader, createRuntimeStatePublisher, 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, normalizeTurnState, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, shouldTriggerAgentTurn, saveRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 import { CodexConversationAdapter, } from './adapter.js';
-import { clearStoredThreadId, loadStoredThreadId, saveStoredThreadId, } from './session-store.js';
+import { clearStoredThreadId, buildCodexThreadPolicyFingerprint, loadStoredThreadId, saveStoredThreadId, } from './session-store.js';
 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 { runCli } from './cli-entry.js';
+const HELP = `canon-codex — run a local Codex agent host for Canon
+
+USAGE
+  canon-codex [flags]
+
+COMMON FLAGS
+  --cwd <path>                         Project directory to run Codex from
+  --workspace <path>                   Additional project to expose in Canon
+  --workspace-root <path>              Discover projects under an approved root
+  --model <model>                      Default Codex model for new turns
+  --sandbox <mode>                     Codex sandbox mode
+  --full-auto                          Allow non-interactive write access
+  --codex-bin <path>                   Codex CLI binary to run
+  --config <key=value>                 Forward config to Codex CLI
+  --help, -h                           Show this help
+  --version, -V                        Show package version
+
+AUTH
+  CANON_AGENT=<profile> canon-codex --cwd /path/to/project
+  CANON_API_KEY=agk_live_... canon-codex --cwd /path/to/project
+
+EXAMPLES
+  canon-codex --cwd ~/dev/canon
+  canon-codex --cwd ~/dev/canon --workspace-root ~/dev --full-auto
+
+Keep this terminal open while you want Canon to reach the agent.`;
 const MAX_SESSIONS = 12;
 const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 const HEARTBEAT_MS = 30_000;
@@ -25,7 +54,7 @@ let workspaceOptions = [];
 let workspaceRoots = [];
 let workspaceRootMetadata = [];
 function buildCodexRuntimeDescriptor(input) {
-    return buildFirstPartyCodingRuntimeDescriptor({
+    const descriptor = buildFirstPartyCodingRuntimeDescriptor({
         clientType: 'codex',
         models: input.models,
         workspaces: input.workspaces,
@@ -57,6 +86,27 @@ function buildCodexRuntimeDescriptor(input) {
             },
         ],
     });
+    if (input.models.length > 0) {
+        return descriptor;
+    }
+    return {
+        ...descriptor,
+        coreControls: descriptor.coreControls.filter((control) => control.id !== 'model'),
+    };
+}
+function modelOptionLabel(model) {
+    if (/^gpt-5\.5(?:$|[-_:])/i.test(model))
+        return 'GPT-5.5';
+    if (/^gpt-5\.4-mini(?:$|[-_:])/i.test(model))
+        return 'GPT-5.4 Mini';
+    if (/^gpt-5\.4(?:$|[-_:])/i.test(model))
+        return 'GPT-5.4';
+    return model;
+}
+function buildCodexModelOptions(model) {
+    return typeof model === 'string' && model.trim()
+        ? [{ value: model.trim(), label: modelOptionLabel(model.trim()) }]
+        : [];
 }
 function normalizeRuntimeTurnState(value) {
     const normalizedTurn = normalizeTurnState(value);
@@ -112,14 +162,6 @@ function summarizeCommand(command) {
     const shortened = trimmed.length > 140 ? `${trimmed.slice(0, 137)}...` : trimmed;
     return `Running: ${shortened}`;
 }
-function formatTurnFailure(errorText) {
-    if (!errorText) {
-        return 'The Codex session stopped unexpectedly before sending a final reply.';
-    }
-    const normalized = errorText.replace(/^error:\s*/i, '').trim();
-    const shortened = normalized.length > 280 ? `${normalized.slice(0, 277)}...` : normalized;
-    return `Codex failed before sending a final reply: ${shortened}`;
-}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -157,6 +199,14 @@ export async function main() {
     if (typeof args['ask-for-approval'] === 'string') {
         console.error('[canon-codex] Note: newer Codex CLI releases do not accept --ask-for-approval for `codex exec`; Canon will translate compatible legacy usage when possible.');
     }
+    const codexBin = typeof args['codex-bin'] === 'string' ? args['codex-bin'] : 'codex';
+    const codexCliStatus = detectCodexCliVersion(codexBin);
+    if (codexCliStatus.version) {
+        console.error(`[canon-codex] Detected Codex CLI ${codexCliStatus.version} (${codexBin})`);
+    }
+    else {
+        console.error(`[canon-codex] Could not detect Codex CLI version for ${codexBin}: ${codexCliStatus.error ?? 'unknown result'}`);
+    }
     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);
@@ -264,6 +314,7 @@ export async function main() {
         runtimeState.writeSessionState(session.conversationId, {
             lastError: session.state.lastError,
             model: session.state.model,
+            permissionMode: session.state.permissionMode,
             cwd: session.cwd,
             executionMode: session.environment.mode,
             ...(session.environment.branch ? { executionBranch: session.environment.branch } : {}),
@@ -383,15 +434,37 @@ export async function main() {
             try {
                 const sessionCwd = environment.cwd;
                 const sessionModel = config?.model ?? (typeof args.model === 'string' ? args.model : undefined);
-                const storedThreadId = loadStoredThreadId(runtimeId, agentId, conversationId, environment.baseCwd, environment.mode);
-                if (config?.permissionMode
-                    && !codexPermissionEnvelope.availablePermissionModes.some((option) => option.value === config.permissionMode)) {
-                    throw new ExecutionEnvironmentError(`Permission mode "${config.permissionMode}" is not supported by this Codex host.`, 'This Canon host was started with stricter approval settings. Choose one of the advertised permission modes or restart the host with more permissive flags.');
+                const modelGuard = buildCodexModelGuardMessage(sessionModel, codexCliStatus);
+                if (modelGuard) {
+                    throw new ExecutionEnvironmentError(modelGuard, modelGuard);
+                }
+                const effectivePermissionMode = config?.permissionMode ?? codexPermissionEnvelope.defaultPermissionMode;
+                if (effectivePermissionMode
+                    && !codexPermissionEnvelope.availablePermissionModes.some((option) => option.value === effectivePermissionMode)) {
+                    throw new ExecutionEnvironmentError(`Permission mode "${effectivePermissionMode}" is not supported by this Codex host.`, 'This Canon host was started with stricter approval settings. Choose one of the advertised permission modes or restart the host with more permissive flags.');
                 }
-                const approvalOverride = mapCanonPermissionToCodex(config?.permissionMode);
+                const approvalOverride = mapCanonPermissionToCodex(effectivePermissionMode);
                 const defaultSandbox = (typeof args.sandbox === 'string' ? args.sandbox : null);
                 const defaultFullAuto = Boolean(args['full-auto']);
                 const defaultBypass = Boolean(args['dangerously-bypass-approvals-and-sandbox']);
+                const legacyApprovalPolicy = (typeof args['ask-for-approval'] === 'string'
+                    ? args['ask-for-approval']
+                    : null);
+                const effectiveSandbox = approvalOverride ? approvalOverride.sandbox : defaultSandbox;
+                const effectiveFullAuto = approvalOverride ? approvalOverride.fullAuto : defaultFullAuto;
+                const effectiveBypass = approvalOverride
+                    ? approvalOverride.bypassApprovalsAndSandbox
+                    : defaultBypass;
+                const policyFingerprint = buildCodexThreadPolicyFingerprint({
+                    baseCwd: environment.baseCwd,
+                    executionMode: environment.mode,
+                    permissionMode: effectivePermissionMode ?? null,
+                    sandbox: effectiveSandbox,
+                    approvalPolicy: approvalOverride ? null : legacyApprovalPolicy,
+                    fullAuto: effectiveFullAuto,
+                    bypassApprovalsAndSandbox: effectiveBypass,
+                });
+                const storedThreadId = loadStoredThreadId(runtimeId, agentId, conversationId, environment.baseCwd, environment.mode, policyFingerprint);
                 const session = {
                     conversationId,
                     cwd: sessionCwd,
@@ -399,26 +472,24 @@ export async function main() {
                     adapter: new CodexConversationAdapter({
                         cwd: sessionCwd,
                         threadId: storedThreadId,
-                        codexBin: typeof args['codex-bin'] === 'string' ? args['codex-bin'] : 'codex',
+                        codexBin,
                         model: sessionModel ?? null,
-                        sandbox: approvalOverride ? approvalOverride.sandbox : defaultSandbox,
-                        approvalPolicy: (typeof args['ask-for-approval'] === 'string'
-                            ? args['ask-for-approval']
-                            : null),
+                        sandbox: effectiveSandbox,
+                        approvalPolicy: approvalOverride ? null : legacyApprovalPolicy,
                         codexProfile: typeof args['codex-profile'] === 'string' ? args['codex-profile'] : null,
                         addDirs: args['add-dir'] ?? [],
                         configOverrides: args.config ?? [],
-                        fullAuto: approvalOverride ? approvalOverride.fullAuto : defaultFullAuto,
-                        bypassApprovalsAndSandbox: approvalOverride
-                            ? approvalOverride.bypassApprovalsAndSandbox
-                            : defaultBypass,
+                        fullAuto: effectiveFullAuto,
+                        bypassApprovalsAndSandbox: effectiveBypass,
                     }),
                     queue: [],
                     running: false,
                     state: {
                         model: sessionModel,
+                        permissionMode: effectivePermissionMode,
                         state: 'idle',
                     },
+                    policyFingerprint,
                     turnState: 'idle',
                     currentTurnId: null,
                     currentTurnOpenedAt: null,
@@ -428,7 +499,10 @@ export async function main() {
                     closed: false,
                 };
                 sessions.set(conversationId, session);
-                await baselineControlSignal(conversationId);
+                await Promise.all([
+                    baselineControlSignal(conversationId),
+                    baselineSessionControl(conversationId),
+                ]);
                 console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Environment → ${environment.mode} (${sessionCwd})`);
                 writeState(session);
                 writeTurn(session);
@@ -557,11 +631,15 @@ export async function main() {
             status: 'thinking',
         }).catch(() => { });
         try {
+            const modelGuard = buildCodexModelGuardMessage(session.state.model, codexCliStatus);
+            if (modelGuard) {
+                throw new ExecutionEnvironmentError(modelGuard, modelGuard);
+            }
             const turnImagePaths = nextTurn.imagePaths ?? [];
-            const result = await session.adapter.runTurn(nextTurn.prompt, (event) => {
+            const handleCodexEvent = (event) => {
                 session.lastActivity = Date.now();
                 if (event.type === 'thread.started') {
-                    saveStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, event.threadId, session.environment.mode);
+                    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;
                 }
@@ -589,13 +667,32 @@ export async function main() {
                 if (event.type === 'turn.completed') {
                     writeState(session);
                 }
-            }, (line) => {
+            };
+            const logCodexLine = (line) => {
                 console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] ${line}`);
-            }, turnImagePaths);
+            };
+            const clearStoredThread = () => {
+                clearStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, session.environment.mode);
+                session.adapter.clearThreadId();
+            };
+            const runTurnOnce = () => session.adapter.runTurn(nextTurn.prompt, handleCodexEvent, logCodexLine, turnImagePaths);
+            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) {
-                saveStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, result.threadId, session.environment.mode);
+                saveStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, result.threadId, session.environment.mode, session.policyFingerprint);
             }
             if (!result.interrupted && result.finalMessage) {
+                if (isRecoverableCodexThreadError(result.errorText)) {
+                    clearStoredThread();
+                }
                 await client.sendMessage(session.conversationId, result.finalMessage, {
                     metadata: {
                         turnId: session.currentTurnId,
@@ -608,7 +705,7 @@ export async function main() {
                 console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Sent reply (${result.finalMessage.length} chars)`);
             }
             else if (!result.interrupted && result.exitCode && result.exitCode !== 0) {
-                const userVisibleError = formatTurnFailure(result.errorText);
+                const userVisibleError = formatCodexTurnFailure(result.errorText);
                 session.state.lastError = userVisibleError;
                 writeState(session);
                 if (result.errorText) {
@@ -637,7 +734,9 @@ export async function main() {
             }
         }
         catch (error) {
-            const message = `The Codex host failed to start a turn: ${error instanceof Error ? error.message : String(error)}`;
+            const message = error instanceof ExecutionEnvironmentError
+                ? error.userMessage
+                : `The Codex host failed to start a turn: ${error instanceof Error ? error.message : String(error)}`;
             session.state.lastError = message;
             writeState(session);
             await client.sendMessage(session.conversationId, message, {
@@ -649,7 +748,7 @@ export async function main() {
                 },
             }).catch(() => { });
             await handoffFinalMessage(session.conversationId);
-            if (error instanceof Error && /invalid|not found|unknown thread/i.test(error.message)) {
+            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);
@@ -678,6 +777,7 @@ export async function main() {
         ...EXECUTION_ENVIRONMENT_MODES,
     ];
     const codexPermissionEnvelope = deriveCodexPermissionEnvelope(args);
+    const codexModelOptions = buildCodexModelOptions(args.model);
     let runtimeDescriptor = {
         defaultWorkspaceId: workspaceOptions[0]?.id,
         ...(typeof args.model === 'string' ? { defaultModel: args.model } : {}),
@@ -688,7 +788,7 @@ export async function main() {
             ? { defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode }
             : {}),
         runtimeDescriptor: buildCodexRuntimeDescriptor({
-            models: [],
+            models: codexModelOptions,
             workspaces: buildPublicWorkspaceOptions(workspaceOptions),
             workspaceRoots: workspaceRootMetadata,
             executionModes: hostAvailableExecutionModes,
@@ -707,6 +807,18 @@ export async function main() {
             lastSeenSignal.set(conversationId, timestamp);
         }
     }
+    async function baselineSessionControl(conversationId) {
+        if (lastSeenControl.has(conversationId))
+            return;
+        const raw = await rtdbRead(`/control/${conversationId}/${agentId}/session`).catch(() => null);
+        if (!raw || typeof raw !== 'object')
+            return;
+        const timestamp = Number(raw.updatedAt ?? 0);
+        if (timestamp > 0) {
+            lastSeenControl.set(conversationId, timestamp);
+        }
+    }
+    let publishRuntimeDetailsInFlight = false;
     const publishRuntimeHeartbeat = async () => {
         heartbeatLocalRuntimeEntry(runtimeId, {
             agentId,
@@ -716,84 +828,99 @@ export async function main() {
         });
         if (!streamConnected)
             return;
-        await refreshKnownConversationIds().catch((error) => {
-            console.error('[canon-codex] Failed to refresh known conversations:', error);
-        });
         await publishAgentRuntime(agentId, runtimeDescriptor).catch((error) => {
             console.error('[canon-codex] Failed to publish agent runtime:', error);
         });
-        await publishHostSessionSnapshots({
-            conversationIds: Array.from(knownConversationIds),
-            agentId,
-            clientType: 'codex',
-            runtime: runtimeDescriptor,
-            workspaceOptions,
-            defaultCwd: workingDir,
-            extraSessionConfigFields: ['permissionMode'],
-            liveSessionConfigByConversation: new Map(Array.from(sessions.values()).map((session) => {
-                const workspaceId = resolveWorkspaceIdForBaseCwd(session.environment.baseCwd);
-                return [
-                    session.conversationId,
-                    {
-                        ...(session.state.model ? { model: session.state.model } : {}),
-                        ...(workspaceId ? { workspaceId } : {}),
-                        executionMode: session.environment.mode,
-                        executionBranch: session.environment.branch ?? null,
-                    },
-                ];
-            })),
-        }).catch((error) => {
-            console.error('[canon-codex] Failed to publish session snapshots:', error);
-        });
-        await Promise.all(Array.from(knownConversationIds).map(async (conversationId) => {
-            const session = sessions.get(conversationId);
-            const workspaceId = session
-                ? resolveWorkspaceIdForBaseCwd(session.environment.baseCwd)
-                : runtimeDescriptor.defaultWorkspaceId;
-            const workspace = workspaceOptions.find((option) => option.id === workspaceId) ?? null;
-            const descriptor = runtimeDescriptor.runtimeDescriptor;
-            if (!descriptor)
-                return;
-            const payload = {
-                descriptor,
-                surfaceMode: 'host',
-                statusItems: [
-                    {
-                        id: 'transport',
-                        label: 'Transport',
-                        value: 'exec --json',
-                    },
-                    {
-                        id: 'streaming',
-                        label: 'Live output',
-                        value: 'Thinking, tools, and completed-message previews',
-                    },
-                    {
-                        id: 'nativeActions',
-                        label: 'Native actions',
-                        value: 'Limited until app-server transport',
-                        tone: 'warning',
+        if (publishRuntimeDetailsInFlight)
+            return;
+        publishRuntimeDetailsInFlight = true;
+        try {
+            await refreshKnownConversationIds().catch((error) => {
+                console.error('[canon-codex] Failed to refresh known conversations:', error);
+            });
+            await publishHostSessionSnapshots({
+                conversationIds: Array.from(knownConversationIds),
+                agentId,
+                clientType: 'codex',
+                runtime: runtimeDescriptor,
+                workspaceOptions,
+                defaultCwd: workingDir,
+                extraSessionConfigFields: ['permissionMode'],
+                liveSessionConfigByConversation: new Map(Array.from(sessions.values()).map((session) => {
+                    const workspaceId = resolveWorkspaceIdForBaseCwd(session.environment.baseCwd);
+                    return [
+                        session.conversationId,
+                        {
+                            ...(session.state.model ? { model: session.state.model } : {}),
+                            ...(session.state.permissionMode ? { permissionMode: session.state.permissionMode } : {}),
+                            ...(workspaceId ? { workspaceId } : {}),
+                            executionMode: session.environment.mode,
+                            executionBranch: session.environment.branch ?? null,
+                        },
+                    ];
+                })),
+            }).catch((error) => {
+                console.error('[canon-codex] Failed to publish session snapshots:', error);
+            });
+            await Promise.all(Array.from(knownConversationIds).map(async (conversationId) => {
+                const session = sessions.get(conversationId);
+                const workspaceId = session
+                    ? resolveWorkspaceIdForBaseCwd(session.environment.baseCwd)
+                    : runtimeDescriptor.defaultWorkspaceId;
+                const workspace = workspaceOptions.find((option) => option.id === workspaceId) ?? null;
+                const descriptor = runtimeDescriptor.runtimeDescriptor;
+                if (!descriptor)
+                    return;
+                const payload = {
+                    descriptor,
+                    surfaceMode: 'host',
+                    statusItems: [
+                        {
+                            id: 'transport',
+                            label: 'Transport',
+                            value: 'exec --json',
+                        },
+                        {
+                            id: 'streaming',
+                            label: 'Live output',
+                            value: 'Thinking, tools, and completed-message previews',
+                        },
+                        {
+                            id: 'codex-cli',
+                            label: 'Codex CLI',
+                            value: codexCliStatus.version ?? (codexCliStatus.raw ?? 'Version unknown'),
+                            tone: codexCliStatus.version ? 'default' : 'warning',
+                        },
+                        {
+                            id: 'nativeActions',
+                            label: 'Native actions',
+                            value: 'Limited until app-server transport',
+                            tone: 'warning',
+                        },
+                    ],
+                    execution: {
+                        resolvedWorkspaceLabel: workspace?.label ?? workspaceId ?? null,
+                        resolvedCwd: session?.cwd ?? workspace?.cwd ?? workingDir,
+                        workspaceRootId: workspace?.workspaceRootId ?? null,
+                        workspaceRelativePath: workspace?.workspaceRelativePath ?? null,
+                        executionMode: session?.environment.mode ?? null,
+                        executionBranch: session?.environment.branch ?? null,
+                        worktreePath: session?.environment.worktreePath ?? null,
+                        fallbackReason: resolveExecutionFallbackReason(session?.environment),
                     },
-                ],
-                execution: {
-                    resolvedWorkspaceLabel: workspace?.label ?? workspaceId ?? null,
-                    resolvedCwd: session?.cwd ?? workspace?.cwd ?? workingDir,
-                    workspaceRootId: workspace?.workspaceRootId ?? null,
-                    workspaceRelativePath: workspace?.workspaceRelativePath ?? null,
-                    executionMode: session?.environment.mode ?? null,
-                    executionBranch: session?.environment.branch ?? null,
-                    worktreePath: session?.environment.worktreePath ?? null,
-                    fallbackReason: resolveExecutionFallbackReason(session?.environment),
-                },
-                notes: [
-                    'This Codex host uses the current exec --json transport, so Canon can show thinking, tool activity, and completed assistant-message previews, but not token-by-token text deltas.',
-                    'Codex review, compact/rollback, live plan/diff/reasoning updates, PTY command execution, plugin/app/MCP inventory, and structured approvals require the future app-server transport.',
-                ],
-            };
-            await runtimeState.writeRuntimeInfo(conversationId, payload);
-        })).catch((error) => {
-            console.error('[canon-codex] Failed to publish runtime info:', error);
-        });
+                    notes: [
+                        'This Codex host uses the current exec --json transport, so Canon can show thinking, tool activity, and completed assistant-message previews, but not token-by-token text deltas.',
+                        'Codex review, compact/rollback, live plan/diff/reasoning updates, PTY command execution, plugin/app/MCP inventory, and structured approvals require the future app-server transport.',
+                    ],
+                };
+                await runtimeState.writeRuntimeInfo(conversationId, payload);
+            })).catch((error) => {
+                console.error('[canon-codex] Failed to publish runtime info:', error);
+            });
+        }
+        finally {
+            publishRuntimeDetailsInFlight = false;
+        }
     };
     const stream = new CanonStream({
         apiKey,
@@ -843,7 +970,7 @@ export async function main() {
                 ? { defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode }
                 : {}),
             runtimeDescriptor: buildCodexRuntimeDescriptor({
-                models: [],
+                models: codexModelOptions,
                 workspaces: buildPublicWorkspaceOptions(workspaceOptions),
                 workspaceRoots: workspaceRootMetadata,
                 executionModes: hostAvailableExecutionModes,
@@ -862,7 +989,7 @@ export async function main() {
                 ? { defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode }
                 : {}),
             runtimeDescriptor: buildCodexRuntimeDescriptor({
-                models: [],
+                models: codexModelOptions,
                 workspaces: buildPublicWorkspaceOptions(workspaceOptions),
                 workspaceRoots: workspaceRootMetadata,
                 executionModes: hostAvailableExecutionModes,
@@ -932,7 +1059,7 @@ export async function main() {
     catch (error) {
         console.error('[canon-codex] Failed to load startup conversations:', error);
     }
-    await stream.start().catch((error) => {
+    startCodexStreamInBackground(stream, (error) => {
         console.error('[canon-codex] SSE start error:', error instanceof Error ? error.message : error);
     });
     const pollControl = async () => {
@@ -948,6 +1075,14 @@ export async function main() {
                             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}`);
@@ -960,6 +1095,7 @@ export async function main() {
                                     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`);
@@ -980,14 +1116,14 @@ export async function main() {
                         continue;
                     }
                     console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${signal.type} signal`);
-                    if (session.running) {
-                        await session.adapter.interrupt();
-                    }
-                    session.turnState = 'interrupted';
                     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);
                     client.setTyping(conversationId, false).catch(() => { });
@@ -1042,7 +1178,11 @@ export async function main() {
     await new Promise(() => { });
 }
 runCli(import.meta.url, main, (error) => {
-    console.error('[canon-codex] Fatal error:', error);
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[canon-codex] ${message}`);
     getActiveProfileLock()?.release();
     process.exit(1);
+}, {
+    name: 'canon-codex',
+    help: HELP,
 });

package/dist/register.js

@@ -4,6 +4,27 @@ import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { ackRegistrationApproval, clearPendingRegistration, getOrCreatePendingRegistration, registerAndWaitForApproval, updatePendingRegistration, upsertAgentProfile, AGENTS_PATH, } from '@canonmsg/core';
 import { runCli } from './cli-entry.js';
+const HELP = `canon-codex-register — register or reconnect a Codex agent in Canon
+
+USAGE
+  canon-codex-register --name <name> --description <text> --phone <e164> [flags]
+
+REQUIRED
+  --name <name>              Agent display name shown in Canon
+  --description <text>       Short profile description
+  --phone <e164>             Owner phone number, for example +15551234567
+
+FLAGS
+  --profile <name>           Local profile name in ~/.canon/agents.json
+  --base-url <url>           Canon API base URL override
+  --help, -h                 Show this help
+  --version, -V              Show package version
+
+EXAMPLES
+  canon-codex-register --name "My Codex" --description "Local coding agent" --phone "+15551234567"
+  canon-codex-register --name "Frontend" --description "React work" --phone "+15551234567" --profile frontend
+
+After approval, start it with CANON_AGENT=<profile> canon-codex --cwd /path/to/project.`;
 export async function main() {
     setDefaultResultOrder('ipv4first');
     const { values } = parseArgs({
@@ -92,4 +113,7 @@ export async function main() {
 runCli(import.meta.url, main, (error) => {
     console.error('[canon-codex-register] Fatal error:', error);
     process.exit(1);
+}, {
+    name: 'canon-codex-register',
+    help: HELP,
 });

package/dist/session-store.d.ts

@@ -1,4 +1,13 @@
 import { type ExecutionEnvironmentMode } from '@canonmsg/core';
-export declare function loadStoredThreadId(runtimeId: string | null, agentId: string, conversationId: string, baseCwd: string, executionMode?: ExecutionEnvironmentMode): string | null;
-export declare function saveStoredThreadId(runtimeId: string | null, agentId: string, conversationId: string, baseCwd: string, threadId: string, executionMode?: ExecutionEnvironmentMode): void;
+export declare function buildCodexThreadPolicyFingerprint(input: {
+    baseCwd: string;
+    executionMode?: ExecutionEnvironmentMode;
+    permissionMode?: string | null;
+    sandbox?: string | null;
+    approvalPolicy?: string | null;
+    fullAuto?: boolean;
+    bypassApprovalsAndSandbox?: boolean;
+}): string;
+export declare function loadStoredThreadId(runtimeId: string | null, agentId: string, conversationId: string, baseCwd: string, executionMode?: ExecutionEnvironmentMode, policyFingerprint?: string): string | null;
+export declare function saveStoredThreadId(runtimeId: string | null, agentId: string, conversationId: string, baseCwd: string, threadId: string, executionMode?: ExecutionEnvironmentMode, policyFingerprint?: string): void;
 export declare function clearStoredThreadId(runtimeId: string | null, agentId: string, conversationId: string, baseCwd?: string, executionMode?: ExecutionEnvironmentMode): void;

package/dist/session-store.js

@@ -1,4 +1,5 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { CANON_DIR, clearRuntimeSessionState, loadRuntimeSessionState, saveRuntimeSessionState, } from '@canonmsg/core';
 const STORE_PATH = join(CANON_DIR, 'codex-sessions.json');
@@ -14,29 +15,60 @@ function saveStore(store) {
     mkdirSync(CANON_DIR, { recursive: true });
     writeFileSync(STORE_PATH, JSON.stringify(store, null, 2));
 }
-export function loadStoredThreadId(runtimeId, agentId, conversationId, baseCwd, executionMode) {
+export function buildCodexThreadPolicyFingerprint(input) {
+    return createHash('sha256').update(JSON.stringify({
+        version: 1,
+        baseCwd: input.baseCwd,
+        executionMode: input.executionMode ?? null,
+        permissionMode: input.permissionMode ?? null,
+        sandbox: input.sandbox ?? null,
+        approvalPolicy: input.approvalPolicy ?? null,
+        fullAuto: input.fullAuto === true,
+        bypassApprovalsAndSandbox: input.bypassApprovalsAndSandbox === true,
+    })).digest('hex').slice(0, 24);
+}
+export function loadStoredThreadId(runtimeId, agentId, conversationId, baseCwd, executionMode, policyFingerprint) {
     if (runtimeId) {
         const state = loadRuntimeSessionState(runtimeId, {
             conversationId,
             baseCwd,
             executionMode,
         });
-        if (state?.threadId)
+        if (state?.threadId) {
+            if (policyFingerprint && state.codexPolicyFingerprint !== policyFingerprint) {
+                clearRuntimeSessionState(runtimeId, {
+                    conversationId,
+                    baseCwd,
+                    executionMode,
+                });
+                return null;
+            }
             return state.threadId;
+        }
+        return null;
     }
     const store = loadStore();
     const record = store.agents[agentId]?.[conversationId];
     if (!record || record.cwd !== baseCwd)
         return null;
+    if (policyFingerprint && record.policyFingerprint !== policyFingerprint) {
+        delete store.agents[agentId][conversationId];
+        if (Object.keys(store.agents[agentId]).length === 0) {
+            delete store.agents[agentId];
+        }
+        saveStore(store);
+        return null;
+    }
     return record.threadId;
 }
-export function saveStoredThreadId(runtimeId, agentId, conversationId, baseCwd, threadId, executionMode) {
+export function saveStoredThreadId(runtimeId, agentId, conversationId, baseCwd, threadId, executionMode, policyFingerprint) {
     if (runtimeId) {
         saveRuntimeSessionState(runtimeId, {
             conversationId,
             baseCwd,
             executionMode,
             threadId,
+            ...(policyFingerprint ? { codexPolicyFingerprint: policyFingerprint } : {}),
         });
         return;
     }
@@ -45,6 +77,7 @@ export function saveStoredThreadId(runtimeId, agentId, conversationId, baseCwd,
     store.agents[agentId][conversationId] = {
         threadId,
         cwd: baseCwd,
+        ...(policyFingerprint ? { policyFingerprint } : {}),
         updatedAt: new Date().toISOString(),
     };
     saveStore(store);

package/dist/setup.js

@@ -1,6 +1,17 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 import { runCli } from './cli-entry.js';
+const HELP = `canon-codex-setup — print Canon Codex setup guidance
+
+USAGE
+  canon-codex-setup
+
+FLAGS
+  --help, -h       Show this help
+  --version, -V    Show package version
+
+This command does not register an agent. It checks for the Codex CLI and prints
+the registration and host commands to run next.`;
 export function main() {
     console.log('Canon Codex Plugin Setup');
     console.log('========================\n');
@@ -38,4 +49,7 @@ export function main() {
 runCli(import.meta.url, main, (error) => {
     console.error('[canon-codex-setup] Fatal error:', error);
     process.exit(1);
+}, {
+    name: 'canon-codex-setup',
+    help: HELP,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@canonmsg/agent-sdk": "^1.1.0",
-    "@canonmsg/core": "^0.15.0"
+    "@canonmsg/core": "^0.15.1"
   },
   "engines": {
     "node": ">=18.0.0"