@canonmsg/claude-code-plugin 0.15.1 → 0.19.0

package/dist/host.js

@@ -24,11 +24,17 @@ import { parseArgs } from 'node:util';
 import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { query, } from '@anthropic-ai/claude-agent-sdk';
-import { isAnthropicImageAttachment, materializeMessageMedia, materializeReplyContextMedia, toAnthropicImageBlock, } from '@canonmsg/agent-sdk';
-import { CLAUDE_EFFORT_OPTIONS, CLAUDE_PERMISSION_MODE_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildConversationEnvironmentKey, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPlanApprovalRequest, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, createConversationMetadataLoader, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, EXECUTION_ENVIRONMENT_MODES, CanonClient, CanonStream, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, ApprovalManager, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, buildLocalRuntimeId, getActiveProfileLock, heartbeatLocalRuntimeEntry, normalizeTurnMetadata, prepareConversationEnvironment, resolveCanonAgent, initRTDBAuth, rtdbRead, rtdbWrite, sendMessageWithRetry, loadHostSessionConfig, loadRuntimeSessionState, markLocalRuntimeStopped, releaseConversationEnvironment, saveRuntimeSessionState, clearRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCanonTurnBriefPrompt, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
+import { readFile, stat } from 'node:fs/promises';
+import { basename, isAbsolute, join } from 'node:path';
+import { createSdkMcpServer, query, tool, } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { isAnthropicImageAttachment, materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, toAnthropicImageBlock, } from '@canonmsg/agent-sdk';
+import { CLAUDE_EFFORT_OPTIONS, CLAUDE_PERMISSION_MODE_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildConversationEnvironmentKey, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPlanApprovalRequest, resolveQuestionAllowOther, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, createConversationMetadataLoader, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, EXECUTION_ENVIRONMENT_MODES, CanonClient, CanonStream, ControlChannelPoller, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, ApprovalManager, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, buildLocalRuntimeId, getActiveProfileLock, heartbeatLocalRuntimeEntry, normalizeTurnMetadata, prepareConversationEnvironment, resolveCanonAgent, initRTDBAuth, sendMessageWithRetry, loadHostSessionConfig, loadRuntimeSessionState, markLocalRuntimeStopped, releaseConversationEnvironment, saveRuntimeSessionState, clearRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCanonTurnBriefPrompt, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { decideAutoReply, } from './inbound-policy.js';
 import { runCli } from './cli-entry.js';
+import { OUTBOX_MAX_FILE_BYTES, buildOutboxContextLine, ensureOutboxDir, flushOutbox, resolveOutboxDir, } from './outbox.js';
+import { collectMissedInboundMessages, STARTUP_RECOVERY_MAX_MESSAGES, STARTUP_RECOVERY_PAGE_SIZE, } from './startup-recovery.js';
+import { synthesizeClaudeApprovalDiff } from './approval-diff.js';
 import { decideClaudeToolPermissionForMode, parseAllowedNonOwnerClaudeTools, } from './tool-policy.js';
 import { buildClaudeFinalMessageId, createClaudeInputEnvelope, formatClaudeControlError, mergeClaudeModelOptions, resetClaudeCompletedTurnState, shouldDeliverClaudeFinal, } from './session-state.js';
 function parseRuntimeVisibilityPreset(value) {
@@ -85,6 +91,38 @@ let runtimeMetadata = {
     loadedAt: 0,
 };
 let runtimeMetadataRefresh = null;
+/** Bound on native slash commands exposed to the composer palette. */
+const MAX_NATIVE_SLASH_COMMANDS = 50;
+/**
+ * Claude Code's own slash commands (built-ins, plugins, project .claude/
+ * commands) are executable when sent as prompt text, so the runtime's command
+ * inventory is exposed as composer slash entries that pass the raw slash text
+ * through. Canon-injected aliases keep precedence over native names.
+ */
+export function buildNativeSlashCommandDescriptors(native, reservedAliases) {
+    const seen = new Set(reservedAliases);
+    const descriptors = [];
+    for (const command of native.slice(0, MAX_NATIVE_SLASH_COMMANDS)) {
+        const name = String(command.name ?? '').replace(/^\//, '').trim();
+        if (!name || !/^[A-Za-z0-9:_-]+$/.test(name) || seen.has(name))
+            continue;
+        seen.add(name);
+        descriptors.push({
+            id: `claude-native-${name}`,
+            label: `/${name}`,
+            description: command.description
+                ?? ('argumentHint' in command ? command.argumentHint : undefined)
+                ?? 'Claude Code command (runs in the runtime).',
+            aliases: [name],
+            category: 'runtime',
+            placements: ['composer_slash', 'command_palette'],
+            availability: ['always'],
+            trailingTextBehavior: 'send_as_prompt',
+            dispatch: { kind: 'text_passthrough', template: `/${name}` },
+        });
+    }
+    return descriptors;
+}
 function buildClaudeRuntimeDescriptor(input) {
     const commands = [
         {
@@ -166,6 +204,7 @@ function buildClaudeRuntimeDescriptor(input) {
         RUNTIME_STOP_ACTION,
         RUNTIME_STOP_AND_DROP_ACTION,
     ];
+    commands.push(...buildNativeSlashCommandDescriptors(runtimeMetadata.commands, new Set(commands.flatMap((command) => [command.id, ...(command.aliases ?? [])]))));
     return buildFirstPartyCodingRuntimeDescriptor({
         clientType: 'claude-code',
         models: input.models,
@@ -174,6 +213,7 @@ function buildClaudeRuntimeDescriptor(input) {
         executionModes: input.executionModes,
         permissionModes: CLAUDE_PERMISSION_MODE_OPTIONS,
         defaultPermissionMode: 'default',
+        effortOptions: [...CLAUDE_EFFORT_OPTIONS],
         streamingTextMode: 'delta',
         turnModes: [
             {
@@ -422,12 +462,17 @@ function mapClaudeQuestions(value) {
             const optionValue = typeof optionRecord.value === 'string' && optionRecord.value.trim()
                 ? optionRecord.value.trim().slice(0, 120)
                 : label;
+            const description = typeof optionRecord.description === 'string' && optionRecord.description.trim()
+                ? optionRecord.description.trim().slice(0, 240)
+                : undefined;
+            const preview = typeof optionRecord.preview === 'string' && optionRecord.preview.trim()
+                ? optionRecord.preview.trim().slice(0, 4000)
+                : undefined;
             return [{
                     label,
                     value: optionValue,
-                    ...(typeof optionRecord.description === 'string' && optionRecord.description.trim()
-                        ? { description: optionRecord.description.trim().slice(0, 240) }
-                        : {}),
+                    ...(description ? { description } : {}),
+                    ...(preview ? { preview } : {}),
                 }];
         });
         return [{
@@ -435,7 +480,12 @@ function mapClaudeQuestions(value) {
                 question,
                 ...(header ? { header } : {}),
                 ...(choices.length ? { choices } : {}),
-                ...(record.isOther === true || record.allowOther === true ? { allowOther: true } : {}),
+                // Mac-app parity: AskUserQuestion always offers a free-text "Other" escape
+                // hatch (the SDK adds it client-side, not via the tool schema). Default it
+                // on for choice questions unless the agent explicitly opted out.
+                ...(resolveQuestionAllowOther(choices.length > 0, record.allowOther ?? record.isOther)
+                    ? { allowOther: true }
+                    : {}),
                 ...(record.isSecret === true ? { isSecret: true } : {}),
                 ...(record.multiSelect === true ? { multiSelect: true } : {}),
             }];
@@ -449,6 +499,17 @@ function flattenRuntimeInputAnswers(answers) {
     }
     return flattened;
 }
+/** Pre-image reader for approval diff synthesis: missing file → null (Write creates it). */
+async function readApprovalDiffPreImage(filePath) {
+    try {
+        return await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
 function mapClaudeMcpStatus(status) {
     switch (status) {
         case 'connected':
@@ -518,6 +579,12 @@ function buildClaudeRuntimeInfo(input) {
             value: 'Runtime policy',
             tier: 'detail',
         },
+        {
+            id: 'mediaOut',
+            label: 'Media out',
+            value: 'Turn-end outbox + canon_send_file',
+            tier: 'detail',
+        },
     ].filter((item) => Boolean(item));
     return {
         descriptor,
@@ -604,10 +671,6 @@ const CLAUDE_RUNTIME_CAPABILITIES = {
     supportsRequiresAction: 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);
-}
 function buildCanonPrompt(input) {
     const sessionContextLines = input.session ? buildClaudeSessionContextLines(input.session) : undefined;
     return renderCanonTurnBriefPrompt(buildCanonTurnContextV2({
@@ -643,6 +706,7 @@ function buildClaudeSessionContextLines(session) {
         `Working directory: ${session.cwd}`,
         session.environment.branch ? `Git branch: ${session.environment.branch}` : null,
         session.environment.worktreePath ? `Worktree: ${session.environment.worktreePath}` : null,
+        `${buildOutboxContextLine(session.cwd)} To send one file immediately mid-turn, use the canon_send_file tool instead.`,
     ].filter((line) => Boolean(line));
 }
 function renderInboundContent(message, materialized) {
@@ -785,10 +849,67 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         }
         return { status: 'timeout' };
     }
+    function buildOutboxMediaMetadata() {
+        return {
+            ...(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',
+        };
+    }
+    function sendOutboxMediaFile(filePath, caption = '') {
+        return sendMediaFileMessage(client, conversationId, filePath, caption, {
+            ...(session.activeSelfContextId ? { selfContextId: session.activeSelfContextId } : {}),
+            metadata: buildOutboxMediaMetadata(),
+        });
+    }
+    // Immediate explicit media-out channel: the agent calls this tool with a
+    // path, the host uploads + sends right away. Permission flows through
+    // canUseTool like every other MCP tool (owner approval in default mode).
+    const canonMediaServer = createSdkMcpServer({
+        name: 'canon',
+        tools: [
+            tool('canon_send_file', 'Send a local file (screenshot, plot, artifact) to the current Canon conversation immediately as a media attachment.', {
+                path: z.string().describe('Path of the file to send; relative paths resolve against the session working directory.'),
+                caption: z.string().optional().describe('Optional caption shown with the attachment.'),
+            }, async (args) => {
+                try {
+                    const filePath = isAbsolute(args.path) ? args.path : join(cwd, args.path);
+                    const info = await stat(filePath);
+                    if (!info.isFile()) {
+                        throw new Error(`${filePath} is not a regular file`);
+                    }
+                    if (info.size > OUTBOX_MAX_FILE_BYTES) {
+                        throw new Error(`File is ${info.size} bytes; the Canon media limit is ${OUTBOX_MAX_FILE_BYTES} bytes`);
+                    }
+                    const { messageId } = await sendOutboxMediaFile(filePath, args.caption ?? '');
+                    console.error(`[canon-host] [${conversationId.slice(0, 8)}] canon_send_file sent ${basename(filePath)} (${messageId})`);
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `Sent ${basename(filePath)} to the Canon conversation (message ${messageId}).`,
+                            }],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `canon_send_file failed: ${error instanceof Error ? error.message : String(error)}`,
+                            }],
+                        isError: true,
+                    };
+                }
+            }),
+        ],
+    });
     const claudeCliPath = resolveClaudeCliPath();
     const queryOptions = {
         systemPrompt: { type: 'preset', preset: 'claude_code' },
         tools: { type: 'preset', preset: 'claude_code' },
+        mcpServers: { canon: canonMediaServer },
         permissionMode: parseClaudePermissionMode(config.permissionMode) ?? 'default',
         allowDangerouslySkipPermissions: true,
         cwd,
@@ -872,13 +993,16 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                         })
                             .filter((entry) => Boolean(entry))
                         : [];
-                    const planApproval = buildPlanApprovalRequest(planId, 'Plan ready for review.', allowedPrompts.length > 0 ? {
-                        summary: 'Claude has prepared a plan and is asking permission to continue.',
-                        ...(cardResponseUser ?? {}),
-                        allowedPrompts,
-                    } : {
+                    // Surface the actual plan markdown on the card so the owner reviews
+                    // the plan inline (Mac-app parity), not just a generic summary.
+                    const planBody = typeof input.plan === 'string' && input.plan.trim()
+                        ? input.plan.trim()
+                        : undefined;
+                    const planApproval = buildPlanApprovalRequest(planId, 'Plan ready for review.', {
                         summary: 'Claude has prepared a plan and is asking permission to continue.',
+                        ...(planBody ? { body: planBody } : {}),
                         ...(cardResponseUser ?? {}),
+                        ...(allowedPrompts.length > 0 ? { allowedPrompts } : {}),
                     });
                     await sendMessageWithRetry(client, conversationId, planApproval.text, {
                         messageId: `claude-plan-${planId}`,
@@ -894,11 +1018,57 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                     console.error(`[canon-host] [${conversationId.slice(0, 8)}] Plan approval sent (${planId.slice(0, 8)})`);
                     const reply = await waitForReply('plan_approval_reply', planId);
                     if (reply.decision === 'approve') {
+                        // Honor opt-in selective grants: when the card sent an explicit
+                        // granted subset, pre-approve those tools as session rules so they
+                        // do not re-prompt. Owner-turn only; absent grants preserve the
+                        // legacy behavior (each tool still prompts individually).
+                        const isOwnerTurn = session.activeInput?.kind === 'canon'
+                            ? session.activeInput.isOwnerTurn === true
+                            : true;
+                        if (isOwnerTurn && config.approvalManager && Array.isArray(reply.grantedPrompts)) {
+                            // Only pre-approve tools the plan actually offered, and bound the
+                            // count/length to match parseSessionRule's caps — grantedPrompts
+                            // is untrusted wire metadata, not the validated approval path.
+                            const offeredTools = new Set(allowedPrompts.map((entry) => entry.tool));
+                            const grantedTools = new Set();
+                            for (const grant of reply.grantedPrompts) {
+                                if (grantedTools.size >= 32)
+                                    break;
+                                const tool = typeof grant?.tool === 'string' ? grant.tool.trim() : '';
+                                if (tool && tool !== 'Tool' && tool.length <= 128 && offeredTools.has(tool)) {
+                                    grantedTools.add(tool);
+                                }
+                            }
+                            for (const tool of grantedTools) {
+                                config.approvalManager.addSessionRule(conversationId, {
+                                    type: 'approve-tool',
+                                    toolPattern: tool.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+                                });
+                            }
+                            if (grantedTools.size > 0) {
+                                console.error(`[canon-host] [${conversationId.slice(0, 8)}] Plan granted ${grantedTools.size} tool(s) for session`);
+                            }
+                        }
+                        // The SDK leaves plan mode when we allow ExitPlanMode, but it does
+                        // not notify the host, so reset the mirrored permission mode here so
+                        // the composer turn-mode toggle and permission chip stop reporting
+                        // 'plan'. Approve-only: on reject/revise the SDK stays in plan mode.
+                        if (session.state.permissionMode === 'plan') {
+                            session.state.permissionMode = 'default';
+                            writeState();
+                        }
                         return { behavior: 'allow' };
                     }
+                    if (reply.decision === 'reject') {
+                        return {
+                            behavior: 'deny',
+                            message: reply.feedback?.trim()
+                                || 'Plan declined — keep planning and wait for guidance before proceeding.',
+                        };
+                    }
                     return {
                         behavior: 'deny',
-                        message: reply.feedback || 'User requested changes',
+                        message: reply.feedback?.trim() || 'User requested changes to the plan.',
                     };
                 }
                 catch {
@@ -918,6 +1088,21 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                 approvalManager: config.approvalManager,
                 canRequestApproval: config.canRequestApproval,
                 allowedNonOwnerTools: allowedNonOwnerClaudeTools,
+                // File-change preview for Edit/Write-class approvals: canUseTool fires
+                // before the mutation lands, so read the pre-image from disk and splice
+                // the edit in memory. Best-effort — failure logs and omits the diff.
+                buildApprovalDiff: async () => {
+                    try {
+                        return await synthesizeClaudeApprovalDiff(toolName, input, {
+                            cwd,
+                            readFile: readApprovalDiffPreImage,
+                        });
+                    }
+                    catch (error) {
+                        console.error(`[canon-host] [${conversationId.slice(0, 8)}] Approval diff synthesis failed (${toolName}): ${error instanceof Error ? error.message : String(error)}`);
+                        return undefined;
+                    }
+                },
             });
         },
     };
@@ -1115,6 +1300,34 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             return false;
         }
     }
+    /**
+     * 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() {
+        try {
+            const result = await flushOutbox({
+                outboxDir: resolveOutboxDir(cwd),
+                send: (file) => sendOutboxMediaFile(file.path),
+            });
+            for (const entry of result.sent) {
+                console.error(`[canon-host] [${conversationId.slice(0, 8)}] 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(`[canon-host] [${conversationId.slice(0, 8)}] 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(`[canon-host] [${conversationId.slice(0, 8)}] Outbox skipped ${skipped.fileName} (${skipped.reason}); left in place`);
+                }
+            }
+        }
+        catch (error) {
+            console.error(`[canon-host] [${conversationId.slice(0, 8)}] Outbox flush failed:`, error instanceof Error ? error.message : error);
+        }
+    }
     function scheduleFinalDeliveryRetry(pending = session.pendingFinalDelivery) {
         if (!pending || session.closed || session.pendingFinalDelivery?.turnKey !== pending.turnKey)
             return;
@@ -1401,6 +1614,12 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                             session.sdkSessionId = resultSessionId;
                         const completedInput = session.activeInput;
                         console.error(`[canon-host] [${conversationId.slice(0, 8)}] Turn complete (${msg.subtype})`);
+                        // Turn-end outbox flush — media lands before the final text reply.
+                        // Interrupted turns keep their files for the next completed turn.
+                        if (completedInput?.kind === 'canon'
+                            && !session.interruptedTurnKeys.has(completedInput.turnKey)) {
+                            await flushSessionOutbox();
+                        }
                         const resultText = typeof msg.result === 'string'
                             ? msg.result.trim()
                             : '';
@@ -1462,6 +1681,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
     // Start processing loop and initialize session
     const init = async () => {
         processMessages().catch((err) => console.error(`[canon-host] [${conversationId.slice(0, 8)}] processMessages crashed:`, err));
+        ensureOutboxDir(cwd).catch((err) => console.error(`[canon-host] [${conversationId.slice(0, 8)}] Failed to create media outbox:`, err));
         await q.initializationResult();
         if (config.model) {
             try {
@@ -1570,7 +1790,7 @@ export async function main() {
     console.error(`[canon-host] Starting${profile ? ` (profile: ${profile})` : ''} in ${workingDir}`);
     // ── Canon API client + RTDB auth ──
     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)
@@ -1711,6 +1931,21 @@ export async function main() {
         }).catch((error) => {
             console.error('[canon-host] Failed to publish session snapshots:', error);
         });
+        // Rebuild so the descriptor picks up native slash commands from the
+        // metadata refresh above — the initial descriptor is built before the
+        // command inventory has loaded.
+        if (runtimeDescriptor.runtimeDescriptor) {
+            runtimeDescriptor = {
+                ...runtimeDescriptor,
+                runtimeDescriptor: buildClaudeRuntimeDescriptor({
+                    models: runtimeModels,
+                    workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                    workspaceRoots: workspaceRootMetadata,
+                    executionModes: hostAvailableExecutionModes,
+                    presentation: runtimePresentation,
+                }),
+            };
+        }
         await Promise.all(Array.from(knownConversationIds).map(async (conversationId) => {
             const session = sessions.get(conversationId);
             const workspaceId = session
@@ -1793,9 +2028,39 @@ export async function main() {
     const sessions = new Map();
     const approvalManager = ownerId ? new ApprovalManager(client, agentId, ownerId) : null;
     const pendingSessionCreations = new Map();
-    let controlStopped = false;
-    const lastSeenControl = new Map();
-    const lastSeenSignal = new Map();
+    // Shared /control channel poller (claude host profile): session + signal
+    // keys, sequential conversations, active/idle cadence + jitter sampled at
+    // cycle start, eager baselines at session creation, and nodes left in place
+    // when a handler throws (consumeOnError defaults to false for both keys).
+    const controlPoller = new ControlChannelPoller({
+        rtdb,
+        agentId,
+        conversationIds: () => sessions.keys(),
+        cadence: {
+            kind: 'adaptive',
+            activeMs: CONTROL_POLL_MS,
+            idleMs: IDLE_CONTROL_POLL_MS,
+            jitterMs: CONTROL_POLL_JITTER_MS,
+            hasActiveWork: () => [...sessions.values()].some((session) => !session.closed
+                && (session.state.state === 'running'
+                    || session.state.state === 'requires_action'
+                    || session.pendingInputs.length > 0
+                    || Boolean(session.pendingFinalDelivery))),
+            activitySample: 'cycle-start',
+        },
+        pollOnStart: true,
+        conversationConcurrency: 'sequential',
+        handlers: {
+            session: { handle: applyRuntimeSessionControl },
+            signal: { handle: handleRuntimeControlSignal },
+        },
+        onError: ({ scope, key, conversationId, error }) => {
+            if (scope === 'read')
+                return; // Transient RTDB errors — retry next cycle
+            const convo = conversationId ? ` [${conversationId.slice(0, 8)}]` : '';
+            console.error(`[canon-host]${convo} Control ${key ?? 'poll'} ${scope} error:`, error);
+        },
+    });
     /** Saved SDK session IDs for resume after idle eviction, keyed by conversation + workspace */
     const savedSessionIds = new Map();
     const { getConversationMeta } = createConversationMetadataLoader({
@@ -2072,10 +2337,7 @@ export async function main() {
                     ownerId,
                 }, resumeId);
                 sessions.set(conversationId, session);
-                await Promise.all([
-                    baselineControlSignal(conversationId),
-                    baselineSessionControl(conversationId),
-                ]);
+                await controlPoller.baseline([conversationId]);
                 return session;
             }
             catch (error) {
@@ -2091,28 +2353,6 @@ export async function main() {
             pendingSessionCreations.delete(conversationId);
         }
     }
-    async function baselineControlSignal(conversationId) {
-        if (lastSeenSignal.has(conversationId))
-            return;
-        const raw = await rtdbRead(`/control/${conversationId}/${agentId}/signal`).catch(() => null);
-        if (!raw || typeof raw !== 'object')
-            return;
-        const timestamp = Number(raw.updatedAt ?? 0);
-        if (timestamp > 0) {
-            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);
-        }
-    }
     async function enqueueRecoveredInboundMessage(input) {
         const m = input.message;
         if (m.senderId === agentId)
@@ -2217,22 +2457,23 @@ export async function main() {
                 conversationId: conversation.id,
                 baseCwd: workingDir,
             })?.lastInboundMessageId;
-            const page = await client.getMessagesPage(conversation.id, 25);
-            const inboundMessages = page.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 message of messagesToRecover) {
+            const recovery = await collectMissedInboundMessages({
+                fetchPage: (before) => client.getMessagesPage(conversation.id, STARTUP_RECOVERY_PAGE_SIZE, before),
+                cursor,
+                agentId,
+            });
+            if (recovery.mode === 'truncated-window') {
+                console.error(`[canon-host] [${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-host] [${conversation.id.slice(0, 8)}] Recovered ${recovery.messages.length} missed messages in ${conversation.id}`);
+            }
+            for (const message of recovery.messages) {
                 console.error(`[canon-host] [${conversation.id.slice(0, 8)}] Recovering inbound message on startup`);
                 await enqueueRecoveredInboundMessage({
                     conversationId: conversation.id,
                     message: message,
-                    hydratedPage: page,
+                    hydratedPage: recovery.newestPage,
                 });
             }
         }
@@ -2425,139 +2666,107 @@ export async function main() {
         console.error('[canon-host] SSE start error:', err instanceof Error ? err.message : err);
     });
     // ── Control signal watcher ──
-    const pollControl = async () => {
-        while (!controlStopped) {
-            const hadActiveWork = [...sessions.values()].some((session) => !session.closed
-                && (session.state.state === 'running'
-                    || session.state.state === 'requires_action'
-                    || session.pendingInputs.length > 0
-                    || Boolean(session.pendingFinalDelivery)));
-            for (const convoId of [...sessions.keys()]) {
-                try {
-                    // Session control signals (model, mode)
-                    const data = await rtdbRead(`/control/${convoId}/${agentId}/session`);
-                    if (data && typeof data === 'object') {
-                        const ctrl = data;
-                        const ts = ctrl.updatedAt ?? 0;
-                        if (ts > (lastSeenControl.get(convoId) ?? 0)) {
-                            lastSeenControl.set(convoId, ts);
-                            const session = sessions.get(convoId);
-                            if (session && !session.closed) {
-                                console.error(`[canon-host] [${convoId.slice(0, 8)}] Control:`, ctrl);
-                                if (ctrl.model && ctrl.model !== session.state.model) {
-                                    try {
-                                        await session.query.setModel(ctrl.model);
-                                        session.state.model = ctrl.model;
-                                        session.clearRuntimeControlError('model');
-                                        console.error(`[canon-host] [${convoId.slice(0, 8)}] Model → ${ctrl.model}`);
-                                    }
-                                    catch (err) {
-                                        session.setRuntimeControlError('model', ctrl.model, err);
-                                        console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to set model:`, err);
-                                    }
-                                }
-                                const nextPermissionMode = parseClaudePermissionMode(ctrl.permissionMode);
-                                if (ctrl.permissionMode && !nextPermissionMode) {
-                                    session.setRuntimeControlError('permissionMode', ctrl.permissionMode, new Error(`Unsupported Claude permission mode: ${ctrl.permissionMode}`));
-                                    console.error(`[canon-host] [${convoId.slice(0, 8)}] Unsupported mode: ${ctrl.permissionMode}`);
-                                }
-                                else if (nextPermissionMode && nextPermissionMode !== session.state.permissionMode) {
-                                    try {
-                                        await session.query.setPermissionMode(nextPermissionMode);
-                                        session.state.permissionMode = nextPermissionMode;
-                                        session.clearRuntimeControlError('permissionMode');
-                                        console.error(`[canon-host] [${convoId.slice(0, 8)}] Mode → ${nextPermissionMode}`);
-                                    }
-                                    catch (err) {
-                                        session.setRuntimeControlError('permissionMode', nextPermissionMode, err);
-                                        console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to set mode:`, err);
-                                    }
-                                }
-                                const nextEffort = normalizeClaudeEffortLevel(ctrl.effort);
-                                if (nextEffort && nextEffort !== session.state.effort) {
-                                    try {
-                                        await applyClaudeEffortLevel(session.query, nextEffort);
-                                        session.state.effort = nextEffort;
-                                        session.clearRuntimeControlError('effort');
-                                        console.error(`[canon-host] [${convoId.slice(0, 8)}] Effort → ${nextEffort}`);
-                                    }
-                                    catch (err) {
-                                        session.setRuntimeControlError('effort', nextEffort, err);
-                                        console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to set effort:`, err);
-                                    }
-                                }
-                                else if (ctrl.effort && !nextEffort) {
-                                    session.setRuntimeControlError('effort', String(ctrl.effort), new Error('Unsupported Claude thinking level.'));
-                                }
-                                session.writeState();
-                                await rtdbWrite(`/control/${convoId}/${agentId}/session`, null).catch(() => { });
-                            }
-                        }
-                    }
-                    // Interrupt/stop-clear signal
-                    const sig = await rtdbRead(`/control/${convoId}/${agentId}/signal`);
-                    if (sig && typeof sig === 'object') {
-                        const s = sig;
-                        const ts = s.updatedAt ?? 0;
-                        if ((s.type === 'interrupt' || s.type === 'stop_and_drop' || s.type === 'new_session')
-                            && ts > (lastSeenSignal.get(convoId) ?? 0)) {
-                            lastSeenSignal.set(convoId, ts);
-                            const session = sessions.get(convoId);
-                            if (session && !session.closed) {
-                                if (s.type === 'new_session') {
-                                    console.error(`[canon-host] [${convoId.slice(0, 8)}] new_session signal`);
-                                    await resetRuntimeSession(session);
-                                    await rtdbWrite(`/control/${convoId}/${agentId}/signal`, null).catch(() => { });
-                                    continue;
-                                }
-                                const isActive = session.state.state === 'running';
-                                if (!isActive && (s.type !== 'stop_and_drop' || session.pendingInputs.length === 0)) {
-                                    await rtdbWrite(`/control/${convoId}/${agentId}/signal`, null).catch(() => { });
-                                    continue;
-                                }
-                                console.error(`[canon-host] [${convoId.slice(0, 8)}] ${s.type} signal`);
-                                try {
-                                    if (s.type === 'stop_and_drop') {
-                                        const droppedInputs = session.pendingInputs.splice(0);
-                                        await markSessionPendingInputsRejected(convoId, droppedInputs);
-                                    }
-                                    if (session.activeInput) {
-                                        session.interruptedTurnKeys.add(session.activeInput.turnKey);
-                                    }
-                                    session.pendingFinalText = null;
-                                    session.turnState = 'interrupted';
-                                    session.clearStreaming().catch(() => { });
-                                    typingSignals.clear(convoId).catch(() => { });
-                                    runtimeState.writeTurnState(convoId, {
-                                        turnId: session.currentTurnId,
-                                        state: 'interrupted',
-                                        queueDepth: session.pendingInputs.length,
-                                        currentSpeakerId: agentId,
-                                        lastAcceptedIntent: session.lastAcceptedIntent,
-                                        capabilities: CLAUDE_RUNTIME_CAPABILITIES,
-                                        ...(session.currentTurnOpenedAt ? { openedAt: session.currentTurnOpenedAt } : {}),
-                                        completedAt: { '.sv': 'timestamp' },
-                                    }).catch(() => { });
-                                    if (isActive) {
-                                        await session.query.interrupt();
-                                    }
-                                    await rtdbWrite(`/control/${convoId}/${agentId}/signal`, null).catch(() => { });
-                                }
-                                catch (err) {
-                                    console.error(`[canon-host] [${convoId.slice(0, 8)}] ${s.type} failed:`, err);
-                                }
-                            }
-                        }
-                    }
-                }
-                catch {
-                    // Transient RTDB errors — ignore and retry next cycle
-                }
+    // Session control signals (model, mode, effort). A missing/closed session
+    // leaves the node in place; lastSeen still advances, so a stale control is
+    // never replayed once a session exists.
+    async function applyRuntimeSessionControl(event) {
+        const convoId = event.conversationId;
+        const session = sessions.get(convoId);
+        if (!session || session.closed)
+            return { consume: false };
+        const ctrl = event.control;
+        console.error(`[canon-host] [${convoId.slice(0, 8)}] Control:`, ctrl);
+        if (ctrl.model && ctrl.model !== session.state.model) {
+            try {
+                await session.query.setModel(ctrl.model);
+                session.state.model = ctrl.model;
+                session.clearRuntimeControlError('model');
+                console.error(`[canon-host] [${convoId.slice(0, 8)}] Model → ${ctrl.model}`);
+            }
+            catch (err) {
+                session.setRuntimeControlError('model', ctrl.model, err);
+                console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to set model:`, err);
             }
-            await new Promise((r) => setTimeout(r, controlPollDelayMs(hadActiveWork)));
         }
-    };
-    pollControl().catch((err) => console.error('[canon-host] Control poll crashed:', err));
+        const nextPermissionMode = parseClaudePermissionMode(ctrl.permissionMode);
+        if (ctrl.permissionMode && !nextPermissionMode) {
+            session.setRuntimeControlError('permissionMode', ctrl.permissionMode, new Error(`Unsupported Claude permission mode: ${ctrl.permissionMode}`));
+            console.error(`[canon-host] [${convoId.slice(0, 8)}] Unsupported mode: ${ctrl.permissionMode}`);
+        }
+        else if (nextPermissionMode && nextPermissionMode !== session.state.permissionMode) {
+            try {
+                await session.query.setPermissionMode(nextPermissionMode);
+                session.state.permissionMode = nextPermissionMode;
+                session.clearRuntimeControlError('permissionMode');
+                console.error(`[canon-host] [${convoId.slice(0, 8)}] Mode → ${nextPermissionMode}`);
+            }
+            catch (err) {
+                session.setRuntimeControlError('permissionMode', nextPermissionMode, err);
+                console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to set mode:`, err);
+            }
+        }
+        const nextEffort = normalizeClaudeEffortLevel(ctrl.effort);
+        if (nextEffort && nextEffort !== session.state.effort) {
+            try {
+                await applyClaudeEffortLevel(session.query, nextEffort);
+                session.state.effort = nextEffort;
+                session.clearRuntimeControlError('effort');
+                console.error(`[canon-host] [${convoId.slice(0, 8)}] Effort → ${nextEffort}`);
+            }
+            catch (err) {
+                session.setRuntimeControlError('effort', nextEffort, err);
+                console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to set effort:`, err);
+            }
+        }
+        else if (ctrl.effort && !nextEffort) {
+            session.setRuntimeControlError('effort', String(ctrl.effort), new Error('Unsupported Claude thinking level.'));
+        }
+        session.writeState();
+    }
+    // Interrupt/stop-clear signal. Throwing leaves the node in place
+    // (consumeOnError: false); lastSeen has already advanced, so the failed
+    // signal is reported but never retried.
+    async function handleRuntimeControlSignal(event) {
+        const convoId = event.conversationId;
+        const session = sessions.get(convoId);
+        if (!session || session.closed)
+            return { consume: false };
+        if (event.type === 'new_session') {
+            console.error(`[canon-host] [${convoId.slice(0, 8)}] new_session signal`);
+            await resetRuntimeSession(session);
+            return;
+        }
+        const isActive = session.state.state === 'running';
+        if (!isActive && (event.type !== 'stop_and_drop' || session.pendingInputs.length === 0)) {
+            return; // Nothing to interrupt — consume the stale signal
+        }
+        console.error(`[canon-host] [${convoId.slice(0, 8)}] ${event.type} signal`);
+        if (event.type === 'stop_and_drop') {
+            const droppedInputs = session.pendingInputs.splice(0);
+            await markSessionPendingInputsRejected(convoId, droppedInputs);
+        }
+        if (session.activeInput) {
+            session.interruptedTurnKeys.add(session.activeInput.turnKey);
+        }
+        session.pendingFinalText = null;
+        session.turnState = 'interrupted';
+        session.clearStreaming().catch(() => { });
+        typingSignals.clear(convoId).catch(() => { });
+        runtimeState.writeTurnState(convoId, {
+            turnId: session.currentTurnId,
+            state: 'interrupted',
+            queueDepth: session.pendingInputs.length,
+            currentSpeakerId: agentId,
+            lastAcceptedIntent: session.lastAcceptedIntent,
+            capabilities: CLAUDE_RUNTIME_CAPABILITIES,
+            ...(session.currentTurnOpenedAt ? { openedAt: session.currentTurnOpenedAt } : {}),
+            completedAt: { '.sv': 'timestamp' },
+        }).catch(() => { });
+        if (isActive) {
+            await session.query.interrupt();
+        }
+    }
+    controlPoller.start();
     // ── Heartbeat (per-session) ──
     const heartbeat = setInterval(() => {
         for (const session of sessions.values()) {
@@ -2584,7 +2793,7 @@ export async function main() {
     // ── Graceful shutdown ──
     const shutdown = async () => {
         console.error('[canon-host] Shutting down...');
-        controlStopped = true;
+        controlPoller.stop();
         clearInterval(heartbeat);
         clearInterval(idleCheck);
         stream.stop();