@canonmsg/codex-plugin 0.7.0 → 0.9.1

package/README.md

@@ -22,7 +22,15 @@ canon-codex --cwd /path/to/project
 
 Registration saves a Canon profile in `~/.canon/agents.json`, the same shared profile store used by the Claude Code integration and supported by the OpenClaw plugin.
 
-If the terminal closes or the machine restarts, the agent goes offline until you start the host again. To bring back the same registered agent, rerun `canon-codex --cwd /path/to/project`. Do not run registration again unless Canon tells you the saved API key is invalid. If you registered multiple profiles, relaunch the same one with `CANON_AGENT=<profile> canon-codex --cwd /path/to/project`.
+If the terminal closes or the machine restarts, the agent goes offline until you start the host again. Install `@canonmsg/local-agents` and run `canon-necromance` to list every recorded local agent from newest to oldest, then revive one in the foreground:
+
+```bash
+npm install -g @canonmsg/local-agents
+canon-necromance
+canon-necromance revive my-codex
+```
+
+Do not run registration again unless Canon tells you the saved API key is invalid. If you registered multiple profiles, relaunch the same one with `CANON_AGENT=<profile> canon-codex --cwd /path/to/project`. Keep the revived terminal open; closing it takes this local agent offline.
 
 You do not need a git repo for host mode. The plugin passes `--skip-git-repo-check` to Codex, so any readable working directory is valid.
 
@@ -37,7 +45,15 @@ You do not need a git repo for host mode. The plugin passes `--skip-git-repo-che
 
 ## Current limitation
 
-The stable `codex exec --json` surface exposes thinking state, tool activity, and completed assistant-message previews, but not token-by-token text deltas. v1 therefore publishes live progress and message snapshots without claiming true token streaming.
+The stable `codex exec --json` surface exposes thinking state, tool activity, and completed assistant-message previews, but not token-by-token text deltas. v1 therefore publishes live progress and assistant-message snapshots without claiming true token streaming.
+
+Current Canon control truth for Codex host mode:
+
+- model is live-visible, but current changes apply on the next turn rather than mid-turn
+- workspace selection is setup-only
+- execution mode selection is setup-only
+- the current `Execution policy`/permission choice is setup-only
+- advanced Codex-only controls such as effort, sandbox policy, approval reviewer, or apps/plugins inventory are not exposed on the current transport unless the runtime can actually report them
 
 ## Working directory
 
@@ -48,10 +64,12 @@ canon-codex --cwd /path/to/project
 Advertise multiple project choices to the Canon app:
 
 ```bash
-canon-codex --cwd ~/dev --workspace ~/dev/canon --workspace ~/dev/yumyumv2
+canon-codex --cwd ~/dev --workspace-root ~/dev
 ```
 
-`--cwd` is the default workspace. Each `--workspace` value appears as a selectable workspace during session creation. Worktree mode creates a per-conversation git worktree under `~/.canon/conversation-worktrees`; shared-workspace mode runs directly in the selected directory.
+`--cwd` is the default workspace. Each `--workspace-root` value is an approved local root; the host discovers immediate child projects with common markers such as `.git`, `package.json`, `pyproject.toml`, `Cargo.toml`, or `go.mod` and publishes them as selectable projects during session creation. Use repeated `--workspace /path/to/project` entries to advertise specific projects outside those roots. Worktree mode creates a per-conversation git worktree under `~/.canon/conversation-worktrees`; shared-project mode runs directly in the selected directory.
+
+If worktree isolation is requested for a project that cannot support it, Canon may fall back to shared-project execution and surface the fallback reason in session details instead of failing the session outright.
 
 Useful flags:
 
@@ -89,7 +107,7 @@ If `canon-codex` starts but cannot find the `codex` binary, either fix your `PAT
 canon-codex --cwd /path/to/project --codex-bin /absolute/path/to/codex
 ```
 
-If Canon rejects authenticated requests with `401 Invalid API key`, the stored Canon profile needs a fresh key. Rerun registration for the same profile to overwrite `~/.canon/agents.json`, then restart the host:
+If Canon rejects authenticated requests with `401 Invalid API key`, the stored Canon profile needs a fresh key. Reconnect the same profile to overwrite `~/.canon/agents.json`, then restart or revive the host:
 
 ```bash
 canon-codex-register --name "My Codex" --description "My local coding agent" --phone "+15551234567" --profile my-codex

package/dist/host-runtime.js

@@ -68,8 +68,6 @@ export function renderCanonHostInboundContent(message, materialized) {
 }
 function describeContactCard(card) {
     const parts = [`${card.userType} · userId: ${card.userId}`];
-    if (card.accessLevel)
-        parts.push(`access: ${card.accessLevel}`);
     if (card.ownerName)
         parts.push(`owner: ${card.ownerName}`);
     if (card.about)

package/dist/host.js

@@ -3,7 +3,7 @@ import { setDefaultResultOrder } from 'node:dns';
 import { randomUUID } from 'node:crypto';
 import { parseArgs } from 'node:util';
 import { getCodexImagePath, materializeMessageMedia, } from '@canonmsg/agent-sdk';
-import { buildConfiguredWorkspaceOptions, buildPublicWorkspaceOptions, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, clearSessionState, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfile, initRTDBAuth, normalizeTurnMetadata, normalizeTurnState, prepareConversationEnvironment, releaseLock, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, writeRuntimeInfo, shouldTriggerAgentTurn, writeSessionState, writeTurnState, } from '@canonmsg/core';
+import { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, clearSessionState, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfileLock, initRTDBAuth, buildLocalRuntimeId, heartbeatLocalRuntimeEntry, loadRuntimeSessionState, markLocalRuntimeStopped, normalizeTurnMetadata, normalizeTurnState, prepareConversationEnvironment, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, writeRuntimeInfo, shouldTriggerAgentTurn, saveRuntimeSessionState, writeSessionState, writeTurnState, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 import { CodexConversationAdapter, } from './adapter.js';
@@ -23,6 +23,8 @@ const CODEX_RUNTIME_CAPABILITIES = {
 };
 let workingDir = process.cwd();
 let workspaceOptions = [];
+let workspaceRoots = [];
+let workspaceRootMetadata = [];
 function buildCodexRuntimeDescriptor(input) {
     return {
         coreControls: [
@@ -37,25 +39,32 @@ function buildCodexRuntimeDescriptor(input) {
             },
             {
                 id: 'workspace',
-                label: 'Workspace',
+                label: 'Project',
                 options: input.workspaces.map((workspace) => ({
                     value: workspace.id,
                     label: workspace.label,
+                    ...(workspace.description ? { description: workspace.description } : {}),
+                    ...(workspace.workspaceRootId ? { workspaceRootId: workspace.workspaceRootId } : {}),
+                    ...(workspace.workspaceRelativePath ? { workspaceRelativePath: workspace.workspaceRelativePath } : {}),
+                    ...(workspace.source ? { source: workspace.source } : {}),
                 })),
                 defaultValue: input.workspaces[0]?.id ?? null,
                 availability: 'setup',
                 liveBehavior: 'none',
                 selectionPolicy: 'inherit',
+                description: input.workspaceRoots?.length
+                    ? 'Choose one of the projects discovered inside the approved local roots for this host.'
+                    : 'Choose one of the local projects advertised by this host.',
             },
             {
                 id: 'executionMode',
                 label: 'Execution mode',
                 options: input.executionModes.map((mode) => ({
                     value: mode,
-                    label: mode === 'worktree' ? 'Isolated worktree' : 'Use shared workspace',
+                    label: mode === 'worktree' ? 'Isolated worktree' : 'Use shared project',
                     description: mode === 'worktree'
-                        ? 'Creates or reuses a per-conversation git worktree under ~/.canon/conversation-worktrees when the selected workspace is a git repo.'
-                        : 'Runs directly in the selected workspace. Canon records usage, but does not create a separate checkout.',
+                        ? 'Creates or reuses a per-conversation git worktree under ~/.canon/conversation-worktrees when the selected project is a git repo.'
+                        : 'Runs directly in the selected project folder. Changes happen there.',
                 })),
                 defaultValue: null,
                 availability: 'setup',
@@ -74,6 +83,29 @@ function buildCodexRuntimeDescriptor(input) {
                 selectionPolicy: 'inherit',
             },
         ],
+        actions: [
+            {
+                id: 'stop',
+                label: 'Stop',
+                description: 'Interrupt the current Codex exec turn.',
+                aliases: ['stop'],
+                category: 'turn',
+                placements: ['composer_slash', 'command_palette'],
+                availability: ['busy'],
+                dispatch: { kind: 'signal', signal: 'interrupt' },
+            },
+            {
+                id: 'stop-and-clear-queue',
+                label: 'Stop & clear queue',
+                description: 'Interrupt the current Codex exec turn and drop queued Canon messages.',
+                aliases: ['stop-clear', 'clear-queue'],
+                category: 'turn',
+                placements: ['composer_slash', 'command_palette', 'session_strip'],
+                availability: ['busy_with_queue'],
+                dispatch: { kind: 'signal', signal: 'stop_and_drop' },
+            },
+        ],
+        workspaceRoots: input.workspaceRoots,
         supportsInterrupt: true,
         streamingTextMode: 'snapshot',
     };
@@ -104,11 +136,10 @@ async function loadSessionConfig(conversationId, agentId) {
         extraStringFields: ['permissionMode'],
     });
 }
-// Default to 'locked' (shared workspace) when no mode has been picked. The
-// UI still lets owners flip to 'worktree'; this just stops sessions from
-// failing closed when the mode has never been written.
 function resolveSessionExecutionMode(config) {
-    return config?.executionMode ?? 'locked';
+    if (config?.executionMode)
+        return config.executionMode;
+    throw new ExecutionEnvironmentError('Session config is missing an execution mode.', 'Choose Isolated worktree or Use shared project before starting this coding session.');
 }
 function resolveWorkspaceCwd(config) {
     return resolveHostWorkspaceCwd({
@@ -164,6 +195,7 @@ export async function main() {
             'codex-profile': { type: 'string' },
             'add-dir': { type: 'string', multiple: true },
             workspace: { type: 'string', multiple: true },
+            'workspace-root': { type: 'string', multiple: true },
             config: { type: 'string', multiple: true },
             'codex-bin': { type: 'string' },
             'full-auto': { type: 'boolean' },
@@ -172,13 +204,23 @@ export async function main() {
         strict: true,
     });
     workingDir = (typeof args.cwd === 'string' ? args.cwd : null) || process.cwd();
-    workspaceOptions = buildConfiguredWorkspaceOptions(workingDir, args.workspace ?? []);
+    const workspaceDiscovery = buildConfiguredWorkspaceOptionsWithRoots({
+        primaryCwd: workingDir,
+        configuredWorkspaces: args.workspace ?? [],
+        workspaceRoots: args['workspace-root'] ?? [],
+    });
+    workspaceOptions = workspaceDiscovery.workspaceOptions;
+    workspaceRoots = workspaceDiscovery.workspaceRoots;
+    workspaceRootMetadata = buildPublicWorkspaceRoots(workspaceRoots);
+    for (const warning of workspaceDiscovery.warnings) {
+        console.error(`[canon-codex] ${warning}`);
+    }
     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 { apiKey, agentId: profileAgentId, profile } = resolveCanonAgent({ logPrefix: '[canon-codex]' });
+    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);
+    const client = new CanonClient(apiKey, baseUrl);
     initRTDBAuth(client);
     let agentId;
     let ownerId = null;
@@ -198,6 +240,34 @@ export async function main() {
         }
         console.error(`[canon-codex] Authenticated as ${agentId}`);
     }
+    const launchArgs = [...process.argv.slice(2)];
+    if (!launchArgs.some((arg) => arg === '--cwd' || arg.startsWith('--cwd='))) {
+        launchArgs.push('--cwd', workingDir);
+    }
+    const runtimeId = buildLocalRuntimeId({
+        runtime: 'codex',
+        profile,
+        cwd: workingDir,
+        launchCommand: ['canon-codex', ...launchArgs],
+    });
+    upsertLocalRuntimeEntry({
+        id: runtimeId,
+        runtime: 'codex',
+        profile,
+        agentId,
+        agentName: profileAgentName,
+        cwd: workingDir,
+        baseCwd: workingDir,
+        workspaceRoots: workspaceRoots.map((root) => root.cwd),
+        workspaces: workspaceOptions.map((workspace) => workspace.cwd),
+        launchCommand: ['canon-codex', ...launchArgs],
+        pid: process.pid,
+        status: profile ? 'running' : 'manual',
+        reviveCapability: profile ? 'revivable' : 'manual',
+        surfaceMode: 'host',
+        lastStartedAt: new Date().toISOString(),
+        lastHeartbeatAt: new Date().toISOString(),
+    });
     const sessions = new Map();
     const pendingSessionCreations = new Map();
     const conversationCache = new Map();
@@ -258,6 +328,9 @@ export async function main() {
             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',
             state: session.state.state,
@@ -291,11 +364,33 @@ export async function main() {
         clearStreaming(conversationId);
         client.setTyping(conversationId, false).catch(() => { });
     }
+    function refreshVisibleWorkSignal(session) {
+        if (!session.running || session.closed)
+            return;
+        if (session.turnState !== 'thinking' && session.turnState !== 'tool')
+            return;
+        client.setTyping(session.conversationId, true, 'thinking').catch(() => { });
+    }
+    function startVisibleWorkSignal(session) {
+        refreshVisibleWorkSignal(session);
+        if (session.typingKeepaliveTimer)
+            return;
+        session.typingKeepaliveTimer = setInterval(() => {
+            refreshVisibleWorkSignal(session);
+        }, 3500);
+    }
+    function stopVisibleWorkSignal(session) {
+        if (session.typingKeepaliveTimer) {
+            clearInterval(session.typingKeepaliveTimer);
+            session.typingKeepaliveTimer = null;
+        }
+    }
     function closeSession(conversationId) {
         const session = sessions.get(conversationId);
         if (!session)
             return;
         session.closed = true;
+        stopVisibleWorkSignal(session);
         releaseConversationEnvironment(session.environment);
         clearStreaming(conversationId);
         clearSessionState(conversationId, agentId).catch(() => { });
@@ -342,7 +437,7 @@ export async function main() {
             try {
                 const sessionCwd = environment.cwd;
                 const sessionModel = config?.model ?? (typeof args.model === 'string' ? args.model : undefined);
-                const storedThreadId = loadStoredThreadId(agentId, conversationId, sessionCwd);
+                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.');
@@ -383,6 +478,7 @@ export async function main() {
                     currentTurnOpenedAt: null,
                     lastAcceptedIntent: null,
                     lastActivity: Date.now(),
+                    typingKeepaliveTimer: null,
                     closed: false,
                 };
                 sessions.set(conversationId, session);
@@ -462,7 +558,12 @@ export async function main() {
             const message = error instanceof Error ? error.message : String(error);
             const userMessage = error instanceof ExecutionEnvironmentError ? error.userMessage : message;
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Failed to create session: ${message}`);
-            await client.sendMessage(input.conversationId, `I couldn't start a coding session for this workspace: ${userMessage}`).catch(() => { });
+            await client.sendMessage(input.conversationId, `I couldn't start a coding session for this workspace: ${userMessage}`, {
+                metadata: {
+                    turnSemantics: 'turn_complete',
+                    turnComplete: true,
+                },
+            }).catch(() => { });
             return;
         }
         const turnMetadata = normalizeTurnMetadata(input.message.metadata);
@@ -503,7 +604,7 @@ export async function main() {
         await markQueuedMessageAccepted(session.conversationId, nextTurn.sourceMessageId, nextTurn.markAccepted);
         writeState(session);
         writeTurn(session);
-        client.setTyping(session.conversationId, true, 'thinking').catch(() => { });
+        startVisibleWorkSignal(session);
         rtdbWrite(`/streaming/${session.conversationId}/${agentId}`, {
             text: 'Thinking…',
             status: 'thinking',
@@ -514,13 +615,15 @@ export async function main() {
             const result = await session.adapter.runTurn(nextTurn.prompt, (event) => {
                 session.lastActivity = Date.now();
                 if (event.type === 'thread.started') {
-                    saveStoredThreadId(agentId, session.conversationId, session.cwd, event.threadId);
+                    saveStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, event.threadId, session.environment.mode);
                     console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Thread ${event.threadId}`);
                     return;
                 }
                 if (event.type === 'message') {
                     session.turnState = 'streaming';
                     writeTurn(session);
+                    stopVisibleWorkSignal(session);
+                    client.setTyping(session.conversationId, false).catch(() => { });
                     rtdbWrite(`/streaming/${session.conversationId}/${agentId}`, {
                         text: event.text,
                         status: 'streaming',
@@ -531,7 +634,7 @@ export async function main() {
                 if (event.type === 'command.started') {
                     session.turnState = 'tool';
                     writeTurn(session);
-                    client.setTyping(session.conversationId, false).catch(() => { });
+                    startVisibleWorkSignal(session);
                     rtdbWrite(`/streaming/${session.conversationId}/${agentId}`, {
                         text: summarizeCommand(event.command),
                         status: 'tool',
@@ -546,7 +649,7 @@ export async function main() {
                 console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] ${line}`);
             }, turnImagePaths);
             if (result.threadId) {
-                saveStoredThreadId(agentId, session.conversationId, session.cwd, result.threadId);
+                saveStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, result.threadId, session.environment.mode);
             }
             if (!result.interrupted && result.finalMessage) {
                 await client.sendMessage(session.conversationId, result.finalMessage, {
@@ -583,6 +686,7 @@ export async function main() {
             else if (result.interrupted) {
                 session.turnState = 'interrupted';
                 writeTurn(session);
+                stopVisibleWorkSignal(session);
                 clearStreaming(session.conversationId);
                 client.setTyping(session.conversationId, false).catch(() => { });
                 console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Turn interrupted`);
@@ -601,10 +705,13 @@ export async function main() {
                 },
             }).catch(() => { });
             await handoffFinalMessage(session.conversationId);
-            clearStoredThreadId(agentId, session.conversationId);
+            if (error instanceof Error && /invalid|not found|unknown thread/i.test(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';
@@ -637,12 +744,19 @@ export async function main() {
         runtimeDescriptor: buildCodexRuntimeDescriptor({
             models: [],
             workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            workspaceRoots: workspaceRootMetadata,
             executionModes: hostAvailableExecutionModes,
             permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
             defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
         }),
     };
     const publishRuntimeHeartbeat = async () => {
+        heartbeatLocalRuntimeEntry(runtimeId, {
+            agentId,
+            agentName: profileAgentName,
+            cwd: workingDir,
+            baseCwd: workingDir,
+        });
         if (!streamConnected)
             return;
         await refreshKnownConversationIds().catch((error) => {
@@ -683,6 +797,7 @@ export async function main() {
                 descriptor: runtimeDescriptor.runtimeDescriptor ?? buildCodexRuntimeDescriptor({
                     models: runtimeDescriptor.availableModels ?? [],
                     workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                    workspaceRoots: workspaceRootMetadata,
                     executionModes: hostAvailableExecutionModes,
                     permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
                     defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
@@ -699,10 +814,18 @@ export async function main() {
                         label: 'Live output',
                         value: 'Thinking, tools, and completed-message previews',
                     },
+                    {
+                        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,
@@ -710,6 +833,7 @@ export async function main() {
                 },
                 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 writeRuntimeInfo(conversationId, agentId, payload);
@@ -733,6 +857,13 @@ export async function main() {
                     behavior: payload.behavior,
                     workSessions: payload.workSessions,
                 });
+                if (message.id) {
+                    saveRuntimeSessionState(runtimeId, {
+                        conversationId: payload.conversationId,
+                        baseCwd: workingDir,
+                        lastInboundMessageId: message.id,
+                    });
+                }
             },
             onConnected: () => {
                 streamConnected = true;
@@ -760,6 +891,7 @@ export async function main() {
             runtimeDescriptor: buildCodexRuntimeDescriptor({
                 models: [],
                 workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                workspaceRoots: workspaceRootMetadata,
                 executionModes: hostAvailableExecutionModes,
                 permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
                 defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
@@ -778,6 +910,7 @@ export async function main() {
             runtimeDescriptor: buildCodexRuntimeDescriptor({
                 models: [],
                 workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                workspaceRoots: workspaceRootMetadata,
                 executionModes: hostAvailableExecutionModes,
                 permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
                 defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
@@ -795,34 +928,51 @@ export async function main() {
             clearTurnState(conversation.id, agentId).catch(() => { });
         }
         for (const conversation of conversations) {
-            if (!conversation.lastMessage || conversation.lastMessage.senderId === agentId)
-                continue;
-            const latestPage = await client.getMessagesPage(conversation.id, 1);
-            const latestMessage = latestPage.messages[0];
-            if (!latestMessage || latestMessage.senderId === agentId)
-                continue;
-            const senderTurnState = latestMessage.senderType === 'ai_agent'
-                ? await loadSenderRuntimeState(conversation.id, latestMessage.senderId)
-                : null;
-            const triggerDecision = shouldTriggerAgentTurn({
-                senderType: latestMessage.senderType ?? 'human',
-                metadata: latestMessage.metadata,
-                senderTurnState,
-            });
-            if (!triggerDecision.allow) {
-                console.error(`[canon-codex] [${conversation.id.slice(0, 8)}] Skipping startup recovery for suppressed message (${triggerDecision.reason})`);
-                continue;
-            }
-            console.error(`[canon-codex] [${conversation.id.slice(0, 8)}] Recovering latest inbound message on startup`);
-            await enqueueInboundMessage({
+            const cursor = loadRuntimeSessionState(runtimeId, {
                 conversationId: conversation.id,
-                message: latestMessage,
-                senderName: latestMessage.senderId,
-                isOwner: ownerId != null && latestMessage.senderId === ownerId,
-                behavior: latestPage.behavior,
-                workSessions: latestPage.workSessions,
-                hydratedPage: latestPage,
-            });
+                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 senderTurnState = latestMessage.senderType === 'ai_agent'
+                    ? await loadSenderRuntimeState(conversation.id, latestMessage.senderId)
+                    : null;
+                const triggerDecision = shouldTriggerAgentTurn({
+                    senderType: latestMessage.senderType ?? 'human',
+                    metadata: latestMessage.metadata,
+                    senderTurnState,
+                });
+                if (!triggerDecision.allow) {
+                    console.error(`[canon-codex] [${conversation.id.slice(0, 8)}] Skipping startup recovery for suppressed message (${triggerDecision.reason})`);
+                    continue;
+                }
+                console.error(`[canon-codex] [${conversation.id.slice(0, 8)}] Recovering inbound message on startup`);
+                await enqueueInboundMessage({
+                    conversationId: conversation.id,
+                    message: latestMessage,
+                    senderName: latestMessage.senderId,
+                    isOwner: ownerId != null && latestMessage.senderId === ownerId,
+                    behavior: latestPage.behavior,
+                    workSessions: latestPage.workSessions,
+                    hydratedPage: latestPage,
+                });
+                if (latestMessage.id) {
+                    saveRuntimeSessionState(runtimeId, {
+                        conversationId: conversation.id,
+                        baseCwd: workingDir,
+                        lastInboundMessageId: latestMessage.id,
+                    });
+                }
+            }
         }
     }
     catch (error) {
@@ -921,20 +1071,18 @@ export async function main() {
             await session.adapter.interrupt().catch(() => { });
             closeSession(session.conversationId);
         }
-        const activeProfile = getActiveProfile();
-        if (activeProfile)
-            releaseLock(activeProfile);
+        markLocalRuntimeStopped(runtimeId);
+        (lockHandle ?? getActiveProfileLock())?.release();
         process.exit(0);
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    process.on('SIGHUP', shutdown);
     console.error('[canon-codex] Ready — sessions created on demand');
     await new Promise(() => { });
 }
 runCli(import.meta.url, main, (error) => {
     console.error('[canon-codex] Fatal error:', error);
-    const activeProfile = getActiveProfile();
-    if (activeProfile)
-        releaseLock(activeProfile);
+    getActiveProfileLock()?.release();
     process.exit(1);
 });

package/dist/register.js

@@ -1,13 +1,9 @@
 #!/usr/bin/env node
 import { setDefaultResultOrder } from 'node:dns';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
-import { registerAndWaitForApproval } from '@canonmsg/core';
+import { ackRegistrationApproval, clearPendingRegistration, getOrCreatePendingRegistration, registerAndWaitForApproval, updatePendingRegistration, upsertAgentProfile, AGENTS_PATH, } from '@canonmsg/core';
 import { runCli } from './cli-entry.js';
-const CANON_DIR = join(homedir(), '.canon');
-const AGENTS_PATH = join(CANON_DIR, 'agents.json');
 export async function main() {
     setDefaultResultOrder('ipv4first');
     const { values } = parseArgs({
@@ -34,6 +30,7 @@ export async function main() {
         // No existing profile state.
     }
     console.log(`Registering Codex agent "${values.name}" (profile: ${profileName})...`);
+    const pending = getOrCreatePendingRegistration(profileName, 'codex');
     const result = await registerAndWaitForApproval({
         name: values.name,
         description: values.description,
@@ -42,8 +39,14 @@ export async function main() {
         clientType: 'codex',
         baseUrl: values['base-url'],
         requestedAgentId: existingAgentId,
+        localRegistrationId: pending.localRegistrationId,
     }, {
-        onSubmitted: (requestId) => {
+        onSubmitted: (requestId, pollToken) => {
+            updatePendingRegistration(profileName, {
+                requestId,
+                pollToken,
+                clientType: 'codex',
+            });
             console.log(`Registration submitted (request ID: ${requestId}).`);
             console.log('Waiting for approval in Canon app...');
         },
@@ -54,24 +57,26 @@ export async function main() {
     console.log('');
     switch (result.status) {
         case 'approved': {
-            mkdirSync(CANON_DIR, { recursive: true });
-            let profiles = {};
-            try {
-                profiles = JSON.parse(readFileSync(AGENTS_PATH, 'utf-8'));
+            if (!result.apiKey || !result.agentId || !result.agentName) {
+                console.error('Approval completed but Canon did not return a usable API key. Run this command again to resume key pickup.');
+                process.exit(1);
             }
-            catch {
-                // File does not exist yet.
-            }
-            profiles[profileName] = {
+            upsertAgentProfile(profileName, {
                 apiKey: result.apiKey,
                 agentId: result.agentId,
                 agentName: result.agentName,
                 registeredAt: new Date().toISOString(),
-            };
-            writeFileSync(AGENTS_PATH, JSON.stringify(profiles, null, 2));
+                clientType: 'codex',
+                ...(typeof values['base-url'] === 'string' ? { baseUrl: values['base-url'] } : {}),
+            });
+            if (result.requestId) {
+                await ackRegistrationApproval(values['base-url'], result.requestId, result.pollToken);
+            }
+            clearPendingRegistration(profileName);
             console.log(`Approved! Agent: ${result.agentName} (${result.agentId})`);
             console.log(`Saved as profile "${profileName}" in ~/.canon/agents.json`);
-            console.log('Start it with: canon-codex --cwd /path/to/project');
+            console.log('Start it with: CANON_AGENT=' + profileName + ' canon-codex --cwd /path/to/project');
+            console.log('Keep that terminal open. Closing it takes this local agent offline.');
             break;
         }
         case 'rejected':

package/dist/session-store.d.ts

@@ -1,3 +1,4 @@
-export declare function loadStoredThreadId(agentId: string, conversationId: string, cwd: string): string | null;
-export declare function saveStoredThreadId(agentId: string, conversationId: string, cwd: string, threadId: string): void;
-export declare function clearStoredThreadId(agentId: string, conversationId: string): void;
+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 clearStoredThreadId(runtimeId: string | null, agentId: string, conversationId: string, baseCwd?: string, executionMode?: ExecutionEnvironmentMode): void;

package/dist/session-store.js

@@ -1,6 +1,6 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { CANON_DIR } from '@canonmsg/core';
+import { CANON_DIR, clearRuntimeSessionState, loadRuntimeSessionState, saveRuntimeSessionState, } from '@canonmsg/core';
 const STORE_PATH = join(CANON_DIR, 'codex-sessions.json');
 function loadStore() {
     try {
@@ -14,24 +14,50 @@ function saveStore(store) {
     mkdirSync(CANON_DIR, { recursive: true });
     writeFileSync(STORE_PATH, JSON.stringify(store, null, 2));
 }
-export function loadStoredThreadId(agentId, conversationId, cwd) {
+export function loadStoredThreadId(runtimeId, agentId, conversationId, baseCwd, executionMode) {
+    if (runtimeId) {
+        const state = loadRuntimeSessionState(runtimeId, {
+            conversationId,
+            baseCwd,
+            executionMode,
+        });
+        if (state?.threadId)
+            return state.threadId;
+    }
     const store = loadStore();
     const record = store.agents[agentId]?.[conversationId];
-    if (!record || record.cwd !== cwd)
+    if (!record || record.cwd !== baseCwd)
         return null;
     return record.threadId;
 }
-export function saveStoredThreadId(agentId, conversationId, cwd, threadId) {
+export function saveStoredThreadId(runtimeId, agentId, conversationId, baseCwd, threadId, executionMode) {
+    if (runtimeId) {
+        saveRuntimeSessionState(runtimeId, {
+            conversationId,
+            baseCwd,
+            executionMode,
+            threadId,
+        });
+        return;
+    }
     const store = loadStore();
     store.agents[agentId] ??= {};
     store.agents[agentId][conversationId] = {
         threadId,
-        cwd,
+        cwd: baseCwd,
         updatedAt: new Date().toISOString(),
     };
     saveStore(store);
 }
-export function clearStoredThreadId(agentId, conversationId) {
+export function clearStoredThreadId(runtimeId, agentId, conversationId, baseCwd, executionMode) {
+    if (runtimeId) {
+        clearRuntimeSessionState(runtimeId, {
+            conversationId,
+            baseCwd,
+            executionMode,
+        });
+        return;
+    }
     const store = loadStore();
     if (!store.agents[agentId]?.[conversationId])
         return;

package/dist/setup.js

@@ -21,8 +21,10 @@ export function main() {
     console.log('');
     console.log('  2. Start the host in a project directory and keep it running');
     console.log('     canon-codex --cwd /path/to/project');
+    console.log('     canon-codex --cwd ~/dev --workspace-root ~/dev');
     console.log('');
     console.log('     A git repo is not required; any readable directory works.');
+    console.log('     Use --workspace-root to let Canon offer discovered projects inside an approved root.');
     console.log('');
     console.log('Optional flags:');
     console.log('  --model gpt-5.4');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.7.0",
+  "version": "0.9.1",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@canonmsg/agent-sdk": "^0.9.0",
-    "@canonmsg/core": "^0.8.0"
+    "@canonmsg/agent-sdk": "^0.10.1",
+    "@canonmsg/core": "^0.13.0"
   },
   "engines": {
     "node": ">=18.0.0"