@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/commands/handlers/channel-handlers.js

@@ -6,7 +6,17 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { createHash } from 'node:crypto';
+import { deriveArgumentObligations, isRuntimeEvidenceVerificationRequest, } from '../../conversation/argument-obligations.js';
+import { shouldRunSemanticResponseGate } from '../../conversation/semantic-response-gate.js';
+import { MODEL_NAME_PATTERN, clearSessionModelOverride, getSessionModelOverride, resolveChannelModel, setSessionModelOverride, __resetSessionModelOverridesForTests, } from '../../channels/channel-model-override.js';
 import { logger } from '../../utils/logger.js';
+import { channelEnvToken, resolveChannelSecret } from '../../channels/resolve-channel-secret.js';
+import { getChannelCognitivePort, } from '../../channels/channel-cognitive-port.js';
+import { assembleCompanionChannelPrompt, channelWaitNoticeMs, companionWaitNoticeText, isCompanionSurfaceEnabled, shouldUseCompanionChannelProfile, } from '../../channels/companion-channel-profile.js';
+import { runCompanionChannelTurn } from '../../channels/companion-channel-turn.js';
+import { speakChannelProviderFailure } from '../../channels/provider-failure-speech.js';
+import { prependUserFacingFailoverNotice } from '../../providers/provider-failover-user-notice.js';
 /**
  * Start every enabled channel from config and wire the inbound AI receiver loop
  * (`registerAIMessageHandler`). Shared by `buddy channels start` (CLI) and the
@@ -17,29 +27,72 @@ import { logger } from '../../utils/logger.js';
  * is the DM-pairing gate inside `registerAIMessageHandler`. Never throws on a
  * single channel failure — it collects the outcome per channel.
  */
-export async function startConfiguredChannels(configPath, onlyType) {
+export async function startConfiguredChannels(configPath, onlyType, onlyInstance) {
     const { getChannelManager } = await import('../../channels/index.js');
     const manager = getChannelManager();
     await registerAIMessageHandler(manager);
-    const result = { registered: [], skipped: [], failed: [], noConfig: false };
+    const result = {
+        registered: [],
+        skipped: [],
+        failed: [],
+        deduplicated: [],
+        noConfig: false,
+    };
     const config = loadChannelConfig(configPath);
     if (!config || config.channels.length === 0) {
         result.noConfig = true;
         return result;
     }
-    for (const chConfig of config.channels) {
-        if (onlyType && chConfig.type !== onlyType) {
-            continue;
-        }
+    const normalizedInstance = onlyInstance?.trim().toLowerCase();
+    const selected = config.channels.filter((entry) => {
+        if (onlyType && entry.type !== onlyType)
+            return false;
+        if (!normalizedInstance)
+            return true;
+        const configuredName = typeof entry.options?.name === 'string'
+            ? entry.options.name.trim().toLowerCase()
+            : '';
+        return normalizedInstance === 'default'
+            ? configuredName.length === 0
+            : configuredName === normalizedInstance;
+    });
+    if (selected.length === 0) {
+        result.noConfig = true;
+        return result;
+    }
+    const lastByType = new Map();
+    const counts = new Map();
+    for (const entry of selected) {
+        lastByType.set(entry.type, entry);
+        counts.set(entry.type, (counts.get(entry.type) ?? 0) + 1);
+    }
+    result.deduplicated = [...counts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([type]) => type);
+    for (const chConfig of lastByType.values()) {
         if (!chConfig.enabled) {
             result.skipped.push(chConfig.type);
             continue;
         }
         try {
+            // A repeated admin start or a duplicate config must never leave an old
+            // poller/socket alive behind the manager's type-keyed replacement.
+            const channelType = chConfig.type;
+            const existing = manager.getChannel(channelType);
+            if (existing) {
+                await existing.disconnect();
+                manager.unregisterChannel(channelType);
+            }
             const channel = await instantiateChannel(chConfig);
             if (channel) {
                 manager.registerChannel(channel);
-                await channel.connect();
+                try {
+                    await channel.connect();
+                }
+                catch (connectErr) {
+                    manager.unregisterChannel(channelType);
+                    throw connectErr;
+                }
                 result.registered.push(chConfig.type);
             }
         }
@@ -53,25 +106,99 @@ export async function startConfiguredChannels(configPath, onlyType) {
     return result;
 }
 function getChannelConfigPaths(configPath) {
+    const envConfigPath = process.env.CODEBUDDY_CHANNEL_CONFIG?.trim();
+    const home = process.env.HOME || process.env.USERPROFILE || '';
     return configPath
         ? [configPath]
-        : [
-            path.join(process.cwd(), '.codebuddy', 'channels.json'),
-            path.join(process.env.HOME || process.env.USERPROFILE || '', '.codebuddy', 'channels.json'),
-        ];
+        : envConfigPath
+            ? [envConfigPath]
+            : [
+                path.join(process.cwd(), '.codebuddy', 'channels.json'),
+                path.join(home, '.codebuddy', 'channels.json'),
+                path.join(process.cwd(), '.codebuddy', 'settings.json'),
+                path.join(home, '.codebuddy', 'settings.json'),
+            ];
+}
+function mapSettingsChannelEntry(key, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const entry = value;
+    const type = typeof entry.type === 'string' && entry.type.trim() ? entry.type.trim() : key;
+    const options = {
+        ...(entry.options && typeof entry.options === 'object' && !Array.isArray(entry.options)
+            ? entry.options
+            : {}),
+    };
+    if (Array.isArray(entry.adminUsers))
+        options.adminUsers = entry.adminUsers;
+    const mapped = {
+        type,
+        enabled: entry.enabled !== false,
+    };
+    if (typeof entry.token === 'string')
+        mapped.token = entry.token;
+    if (typeof entry.webhookUrl === 'string')
+        mapped.webhookUrl = entry.webhookUrl;
+    if (Array.isArray(entry.allowedUsers)) {
+        mapped.allowedUsers = entry.allowedUsers.filter((item) => typeof item === 'string');
+    }
+    if (Array.isArray(entry.allowedChannels)) {
+        mapped.allowedChannels = entry.allowedChannels.filter((item) => typeof item === 'string');
+    }
+    if (Object.keys(options).length > 0)
+        mapped.options = options;
+    return mapped;
+}
+function asChannelConfig(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const channelsField = raw.channels;
+    if (Array.isArray(channelsField)) {
+        return { channels: channelsField };
+    }
+    if (channelsField && typeof channelsField === 'object') {
+        const channels = Object.entries(channelsField)
+            .map(([key, value]) => mapSettingsChannelEntry(key, value))
+            .filter((entry) => entry !== null);
+        if (channels.length === 0)
+            return null;
+        return { channels };
+    }
+    return null;
+}
+function applyEnvChannelTokens(config) {
+    const telegramToken = channelEnvToken('telegram');
+    if (!telegramToken)
+        return config;
+    const existing = config.channels.find((channel) => channel.type === 'telegram');
+    if (existing) {
+        if (!existing.token)
+            existing.token = telegramToken;
+        return config;
+    }
+    return {
+        channels: [...config.channels, { type: 'telegram', enabled: true, token: telegramToken }],
+    };
 }
 export function loadChannelConfigWithPath(configPath) {
     for (const p of getChannelConfigPaths(configPath)) {
         try {
             if (fs.existsSync(p)) {
                 const content = fs.readFileSync(p, 'utf-8');
-                return { config: JSON.parse(content), path: p };
+                const parsed = asChannelConfig(JSON.parse(content));
+                if (!parsed)
+                    continue;
+                return { config: applyEnvChannelTokens(parsed), path: p };
             }
         }
         catch (err) {
             logger.debug(`Failed to load channel config from ${p}`, { error: err instanceof Error ? err.message : String(err) });
         }
     }
+    const fromEnv = applyEnvChannelTokens({ channels: [] });
+    if (fromEnv.channels.length > 0) {
+        return { config: fromEnv, path: 'env:TELEGRAM_BOT_TOKEN' };
+    }
     return null;
 }
 export function loadChannelConfig(configPath) {
@@ -171,6 +298,9 @@ export function buildChannelStatusReport(allStatus, configPath, generatedAt = ne
         connected: status.connected,
         authenticated: status.authenticated,
         ...(status.lastActivity ? { lastActivity: status.lastActivity.toISOString() } : {}),
+        ...(status.lastSuccessfulPoll
+            ? { lastSuccessfulPoll: status.lastSuccessfulPoll.toISOString() }
+            : {}),
         ...(status.error ? { error: status.error } : {}),
         ...(status.info ? { info: status.info } : {}),
     }))
@@ -242,7 +372,10 @@ export async function handleChannels(action, options) {
             }
             console.log('Channel Status:\n');
             for (const [type, status] of Object.entries(allStatus)) {
-                console.log(`  ${type}: ${status.connected ? 'connected' : 'disconnected'}${status.error ? ` (error: ${status.error})` : ''}`);
+                const pollStatus = type === 'telegram'
+                    ? `, last successful poll: ${status.lastSuccessfulPoll?.toISOString() ?? 'never'}`
+                    : '';
+                console.log(`  ${type}: ${status.connected ? 'connected' : 'disconnected'}${pollStatus}${status.error ? ` (error: ${status.error})` : ''}`);
             }
             if (Object.keys(allStatus).length === 0) {
                 console.log('  No channels registered.');
@@ -255,7 +388,7 @@ export async function handleChannels(action, options) {
             const channelType = options.type;
             if (!channelType) {
                 // Start all configured channels (shared with `buddy server` intake)
-                const result = await startConfiguredChannels(options.config);
+                const result = await startConfiguredChannels(options.config, undefined, options.instance);
                 if (result.noConfig) {
                     console.log('No channel configuration found. Create .codebuddy/channels.json or use --config.');
                     return;
@@ -263,25 +396,55 @@ export async function handleChannels(action, options) {
                 for (const t of result.registered) {
                     console.log(`[OK] ${t} channel started`);
                 }
+                for (const t of result.deduplicated) {
+                    console.log(`[SKIP] duplicate ${t} config collapsed (last declaration used)`);
+                }
                 for (const f of result.failed) {
                     console.log(`[FAIL] ${f.type}: ${f.error}`);
                 }
+                if (result.failed.length > 0 && result.registered.length === 0) {
+                    process.exitCode = 1;
+                }
             }
             else {
-                const result = await startConfiguredChannels(options.config, channelType);
+                const result = await startConfiguredChannels(options.config, channelType, options.instance);
                 if (result.noConfig) {
                     console.log(`No configuration found for channel type: ${channelType}`);
+                    process.exitCode = 1;
                     return;
                 }
                 for (const t of result.registered) {
                     console.log(`[OK] ${t} channel started`);
                 }
+                for (const t of result.deduplicated) {
+                    console.log(`[SKIP] duplicate ${t} config collapsed (last declaration used)`);
+                }
                 for (const t of result.skipped) {
                     console.log(`[SKIP] ${t} channel disabled`);
                 }
                 for (const f of result.failed) {
                     console.log(`[FAIL] ${f.type}: ${f.error}`);
                 }
+                if (result.failed.length > 0 && result.registered.length === 0) {
+                    process.exitCode = 1;
+                }
+            }
+            break;
+        }
+        case 'pairing': {
+            const { getDMPairing } = await import('../../channels/dm-pairing.js');
+            const pairing = getDMPairing();
+            const stats = pairing.getStats();
+            console.log(`DM pairing: ${stats.enabled ? 'on' : 'off'} (DM_PAIRING_ENABLED, default on)`);
+            console.log(`Approved senders: ${stats.totalApproved}`);
+            const pending = pairing.listPending();
+            if (pending.length === 0) {
+                console.log('No pending pairing codes. An unknown DM generates a one-time code logged server-side only.');
+                break;
+            }
+            console.log(`Pending one-time codes (${pending.length}):`);
+            for (const request of pending) {
+                console.log(`  [${request.channelType}] sender=${request.senderId} code=${request.code} expires=${request.expiresAt.toISOString()}`);
             }
             break;
         }
@@ -305,17 +468,348 @@ export async function handleChannels(action, options) {
             break;
         }
         default:
-            console.log(`Usage: buddy channels [start|stop|status|list] [--type <type>] [--config <path>]`);
+            console.log(`Usage: buddy channels [start|stop|status|list|pairing] [--type <type>] [--instance <name|default>] [--config <path>]`);
     }
 }
 let aiHandlerRegistered = false;
+const LISA_SELFIE_CONTINUATION_TTL_MS = 15 * 60_000;
+const recentLisaSelfieSessions = new Map();
 /** Reset the one-shot registration guard. Test-only — never call in production. */
 export function __resetChannelAIHandlerForTests() {
     aiHandlerRegistered = false;
+    for (const key of channelAgentCache.keys()) {
+        evictChannelAgent(key, true);
+    }
+    channelTurnTails.clear();
+    channelBotPersonas.clear();
+    companionChannelHistories.clear();
+    recentLisaSelfieSessions.clear();
+    __resetSessionModelOverridesForTests();
 }
 const channelAgentCache = new Map();
+const channelTurnTails = new Map();
+const companionChannelHistories = new Map();
 const CHANNEL_AGENT_IDLE_MS = 2 * 60 * 60 * 1000; // evict after 2h idle
 const CHANNEL_AGENT_MAX = 50;
+const DEFAULT_CHANNEL_TURN_TIMEOUT_MS = 3 * 60 * 1000;
+const MIN_CHANNEL_TURN_TIMEOUT_MS = 1_000;
+const MAX_CHANNEL_TURN_TIMEOUT_MS = 15 * 60 * 1000;
+const CHANNEL_TURN_TIMEOUT_CLEANUP_MS = 10_000;
+class ChannelTurnTimeoutError extends Error {
+    timeoutMs;
+    phase;
+    constructor(timeoutMs, phase) {
+        super(`channel turn timed out after ${timeoutMs}ms during ${phase}`);
+        this.timeoutMs = timeoutMs;
+        this.phase = phase;
+        this.name = 'ChannelTurnTimeoutError';
+    }
+}
+function channelTurnTimeoutMs(env = process.env) {
+    const configured = Number(env.CODEBUDDY_CHANNEL_TURN_TIMEOUT_MS);
+    if (!Number.isFinite(configured) || configured <= 0)
+        return DEFAULT_CHANNEL_TURN_TIMEOUT_MS;
+    return Math.min(MAX_CHANNEL_TURN_TIMEOUT_MS, Math.max(MIN_CHANNEL_TURN_TIMEOUT_MS, Math.floor(configured)));
+}
+function evictChannelAgent(sessionKey, discard = false) {
+    const cached = channelAgentCache.get(sessionKey);
+    channelAgentCache.delete(sessionKey);
+    try {
+        if (discard)
+            cached?.agent.dispose({ skipSessionLearning: true });
+        else
+            cached?.agent.dispose();
+    }
+    catch {
+        // Eviction must remain best-effort; the cache reference is already gone.
+    }
+}
+/**
+ * One in-flight generative turn per conversation. Commands and remote approval
+ * are handled before this queue, so an approval can still unblock a waiting
+ * tool while assistant drafts cannot race into the next turn's history.
+ */
+async function serializeChannelTurn(sessionKey, task, lifecycle = {}) {
+    const queuedAt = Date.now();
+    const previous = channelTurnTails.get(sessionKey) ?? Promise.resolve();
+    const run = previous.catch(() => undefined).then(async () => {
+        const startedAt = Date.now();
+        const timeoutMs = channelTurnTimeoutMs();
+        const controller = new AbortController();
+        let phase = 'starting';
+        let watchdogCount = 0;
+        const diagnosticFields = {
+            ...lifecycle.diagnostics,
+            queueWaitMs: startedAt - queuedAt,
+        };
+        logger.info('Channel turn started', diagnosticFields);
+        lifecycle.onStart?.();
+        const watchdogIntervalMs = Math.min(30_000, Math.max(1_000, Math.floor(timeoutMs / 3)));
+        const watchdog = setInterval(() => {
+            watchdogCount++;
+            logger.warn('Channel turn watchdog still active', {
+                ...diagnosticFields,
+                phase,
+                elapsedMs: Date.now() - startedAt,
+                watchdogCount,
+            });
+        }, watchdogIntervalMs);
+        watchdog.unref?.();
+        let timeout;
+        let timeoutCleanup;
+        const timeoutError = new Promise((_, reject) => {
+            timeout = setTimeout(() => {
+                const error = new ChannelTurnTimeoutError(timeoutMs, phase);
+                controller.abort(error);
+                logger.error('Channel turn watchdog timed out', {
+                    ...diagnosticFields,
+                    phase,
+                    elapsedMs: Date.now() - startedAt,
+                    timeoutMs,
+                });
+                const cleanup = Promise.resolve(lifecycle.onTimeout?.(error))
+                    .catch((cleanupError) => {
+                    logger.warn('Channel turn timeout cleanup failed', {
+                        ...diagnosticFields,
+                        error: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+                    });
+                })
+                    .then(() => true);
+                let cleanupTimer;
+                const cleanupDeadline = new Promise((resolve) => {
+                    cleanupTimer = setTimeout(() => resolve(false), CHANNEL_TURN_TIMEOUT_CLEANUP_MS);
+                    cleanupTimer.unref?.();
+                });
+                timeoutCleanup = Promise.race([cleanup, cleanupDeadline]).then((completed) => {
+                    if (cleanupTimer)
+                        clearTimeout(cleanupTimer);
+                    if (!completed) {
+                        logger.warn('Channel turn timeout cleanup exceeded deadline', {
+                            ...diagnosticFields,
+                            cleanupTimeoutMs: CHANNEL_TURN_TIMEOUT_CLEANUP_MS,
+                        });
+                    }
+                });
+                void timeoutCleanup.finally(() => reject(error));
+            }, timeoutMs);
+            timeout.unref?.();
+        });
+        const control = {
+            signal: controller.signal,
+            phase(nextPhase) {
+                phase = nextPhase;
+                logger.info('Channel turn phase', {
+                    ...diagnosticFields,
+                    phase,
+                    elapsedMs: Date.now() - startedAt,
+                });
+            },
+            throwIfAborted() {
+                if (controller.signal.aborted)
+                    throw controller.signal.reason;
+            },
+        };
+        try {
+            const controlledTask = task(control).catch(async (error) => {
+                // Abort checks inside the task can observe the timeout immediately.
+                // Keep the FIFO closed until timeout cleanup (including the visible
+                // fail-soft reply) has completed.
+                if (controller.signal.aborted && timeoutCleanup)
+                    await timeoutCleanup;
+                throw error;
+            });
+            return await Promise.race([controlledTask, timeoutError]);
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+            clearInterval(watchdog);
+            lifecycle.onSettled?.();
+            logger.info('Channel turn settled', {
+                ...diagnosticFields,
+                phase,
+                elapsedMs: Date.now() - startedAt,
+                timedOut: controller.signal.aborted,
+            });
+        }
+    });
+    const tail = run.then(() => undefined, () => undefined);
+    channelTurnTails.set(sessionKey, tail);
+    try {
+        return await run;
+    }
+    finally {
+        if (channelTurnTails.get(sessionKey) === tail)
+            channelTurnTails.delete(sessionKey);
+    }
+}
+const CONVERSATIONAL_SLASH_VERBS = new Set([
+    'analyse',
+    'analyze',
+    'cherche',
+    'compare',
+    'dis',
+    'donne',
+    'explique',
+    'find',
+    'montre',
+    'raconte',
+    'resume',
+    'résume',
+    'show',
+    'tell',
+]);
+/** Telegram users sometimes prefix a natural request with `/` as if it were a prompt box. */
+function normalizeConversationalSlashMessage(message) {
+    const match = message.content.trim().match(/^\/([^\s@]+)(?:@[^\s]+)?\s+([\s\S]+)$/u);
+    const verb = match?.[1]?.toLocaleLowerCase('fr');
+    if (!match || !verb || !CONVERSATIONAL_SLASH_VERBS.has(verb))
+        return message;
+    return {
+        ...message,
+        content: `${match[1]} ${match[2]}`.trim(),
+        contentType: 'text',
+        isCommand: false,
+        commandName: undefined,
+        commandArgs: undefined,
+    };
+}
+/** Keep long or queued channel turns visibly alive without sending chat noise. */
+function startChannelTypingHeartbeat(channel, channelId) {
+    const typingChannel = channel;
+    if (typeof typingChannel.sendTyping !== 'function')
+        return () => undefined;
+    let stopped = false;
+    let inFlight = false;
+    const reportFailure = (error) => {
+        logger.debug('Channel typing indicator unavailable', {
+            channelType: channel.type,
+            channelHash: hashForLog(channelId),
+            errorType: error instanceof Error ? error.name : 'unknown',
+        });
+    };
+    const ping = () => {
+        if (stopped || inFlight)
+            return;
+        inFlight = true;
+        void Promise.resolve()
+            .then(() => typingChannel.sendTyping(channelId))
+            .catch(reportFailure)
+            .finally(() => {
+            inFlight = false;
+        });
+    };
+    ping();
+    // Telegram displays sendChatAction for about five seconds. Refresh slightly
+    // before expiry while a turn waits in the per-session FIFO or runs the model.
+    const timer = setInterval(ping, 4_000);
+    timer.unref?.();
+    return () => {
+        stopped = true;
+        clearInterval(timer);
+    };
+}
+function channelTypingLifecycle(channel, channelId) {
+    let stopTyping = () => undefined;
+    return {
+        onStart: () => {
+            stopTyping = startChannelTypingHeartbeat(channel, channelId);
+        },
+        onSettled: () => stopTyping(),
+    };
+}
+function channelWaitNoticeLifecycle(channel, channelId, replyTo) {
+    const delayMs = channelWaitNoticeMs();
+    let timer;
+    let stopped = false;
+    return {
+        onStart: () => {
+            if (delayMs <= 0)
+                return;
+            timer = setTimeout(() => {
+                if (stopped)
+                    return;
+                void channel
+                    .send({
+                    channelId,
+                    content: companionWaitNoticeText(),
+                    ...(replyTo ? { replyTo } : {}),
+                })
+                    .catch((error) => {
+                    logger.debug('Channel wait notice skipped', {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                });
+            }, delayMs);
+            timer.unref?.();
+        },
+        onSettled: () => {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+        },
+    };
+}
+function rememberCompanionChannelTurn(sessionKey, userText, assistantText) {
+    const previous = companionChannelHistories.get(sessionKey) ?? [];
+    companionChannelHistories.set(sessionKey, [
+        ...previous,
+        { role: 'user', content: userText },
+        { role: 'assistant', content: assistantText },
+    ].slice(-20));
+}
+function hashForLog(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    return createHash('sha256').update(String(value)).digest('hex').slice(0, 12);
+}
+function isAgentFailureResponse(value) {
+    return /^Sorry, I encountered an error:/i.test(value.trim());
+}
+function channelHistoryTurn(entry) {
+    const role = entry.role ?? entry.type;
+    if (role !== 'user' && role !== 'assistant')
+        return null;
+    if (typeof entry.content !== 'string')
+        return null;
+    const content = entry.content
+        .replace(/<companion_turn>[\s\S]*?<\/companion_turn>\s*/g, '')
+        .replace(/^Message de l'utilisateur\s*:\s*/i, '')
+        .trim();
+    return content ? { role, content } : null;
+}
+/**
+ * Read the real Telegram/channel discussion before choosing the companion
+ * model. Warm agents are authoritative; a cold daemon falls back to the same
+ * persisted SessionStore used by restoreChannelSession().
+ */
+async function resolveChannelRoutingHistory(sessionKey, sharedHistory) {
+    if (sharedHistory.length > 0)
+        return sharedHistory.slice(-12);
+    const cached = channelAgentCache.get(sessionKey)?.agent;
+    if (cached) {
+        return cached
+            .getChatHistory()
+            .flatMap((entry) => {
+            const turn = channelHistoryTurn(entry);
+            return turn ? [turn] : [];
+        })
+            .slice(-12);
+    }
+    try {
+        const { getSessionStore } = await import('../../persistence/session-store.js');
+        const session = await getSessionStore().loadSession(sessionKey);
+        return (session?.messages ?? [])
+            .flatMap((entry) => {
+            const turn = channelHistoryTurn(entry);
+            return turn ? [turn] : [];
+        })
+            .slice(-12);
+    }
+    catch {
+        return [];
+    }
+}
 const channelBotPersonas = new Map();
 export function registerChannelBotPersona(botId, persona) {
     if (botId)
@@ -368,20 +862,54 @@ async function persistChannelSession(agent, sessionKey) {
         logger.warn(`channel session persist failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-async function getOrCreateChannelAgent(sessionKey, resolved, agentConfig, botId) {
+async function getOrCreateChannelAgent(sessionKey, resolved, agentConfig, botId, routeModel, companionRoute) {
     const now = Date.now();
     // Evict idle agents first.
     for (const [key, cached] of channelAgentCache) {
         if (now - cached.lastUsed > CHANNEL_AGENT_IDLE_MS)
-            channelAgentCache.delete(key);
+            evictChannelAgent(key);
     }
+    // Per-bot persona (multi-bot): a bot may define its own model + system prompt.
+    const persona = botId ? channelBotPersonas.get(botId) : undefined;
+    // Hermes-style tiers, finest scope first: /model session override > matched
+    // route > bot persona > merged route default (includes the router-wide
+    // defaultAgent fallback — kept below persona) > provider default.
+    const { model, source } = resolveChannelModel({
+        sessionOverride: getSessionModelOverride(sessionKey),
+        routeModel,
+        personaModel: persona?.model,
+        companionModel: companionRoute?.model,
+        routeDefaultModel: agentConfig.model,
+        globalModel: resolved.model,
+    });
+    const runtimeResolved = source === 'companion-profile' && companionRoute
+        ? {
+            apiKey: companionRoute.apiKey,
+            baseUrl: companionRoute.baseURL,
+            model: companionRoute.model,
+            egress: companionRoute.egress,
+        }
+        : resolved;
+    const runtimeIdentity = createHash('sha256')
+        .update(`${runtimeResolved.apiKey}:${runtimeResolved.baseUrl}`)
+        .digest('hex')
+        .slice(0, 16);
     const hit = channelAgentCache.get(sessionKey);
-    if (hit) {
+    if (hit && hit.runtimeIdentity === runtimeIdentity) {
         hit.lastUsed = now;
-        return hit.agent;
+        // Reconcile a changed override on the cached agent (no eviction — the
+        // in-memory conversation history is what makes the chat feel continuous).
+        if (hit.agent.getCurrentModel() !== model)
+            hit.agent.setModel(model);
+        return {
+            agent: hit.agent,
+            effectiveRuntime: { ...runtimeResolved, model, egress: runtimeResolved.egress ?? 'cloud' },
+        };
     }
-    // Per-bot persona (multi-bot): a bot may define its own model + system prompt.
-    const persona = botId ? channelBotPersonas.get(botId) : undefined;
+    // A provider/endpoint change cannot be applied through setModel(). Recreate
+    // the agent, then restore its persisted transcript below.
+    if (hit)
+        evictChannelAgent(sessionKey);
     // Opt-in Code Explorer nudge (set CODE_EXPLORER_BIN): some models won't reach
     // for the code-graph MCP tools on their own and just say "I can't" — tell them
     // plainly that they can, and give the CLI fallback. No-op when the env is unset.
@@ -394,13 +922,19 @@ async function getOrCreateChannelAgent(sessionKey, resolved, agentConfig, botId)
     // path it names — the handler then delivers that file to the chat as a photo.
     const pythonHint = 'ACTING vs SHOWING: when the user asks you to draw, plot, generate, create, compute or build something, you MUST actually DO it by running tools/code now — do NOT just print the code or instructions and stop. Execute it and deliver the real artifact. ' +
         'For Python work needing packages (plotting, data, etc.): do NOT use `pip`/`pip3 install` (system Python is PEP 668-locked). Use `uv` — e.g. write the script to a file then run `uv run --with matplotlib --with pandas --with numpy python /tmp/plot.py` (matplotlib must use the Agg backend). When you produce a chart/image, SAVE it to an absolute path like `/tmp/<name>.png` and state that exact path in your reply — it is then sent to the user automatically as a photo.';
-    const channelSystemPromptAppend = [persona?.systemPrompt, codeExplorerHint, pythonHint].filter(Boolean).join('\n\n') || undefined;
+    // System prompts APPEND (constructor arg 8, wrapped in <runtime_persona>) —
+    // never the full-replace arg 9, which would drop the tool-calling base prompt
+    // and break tools on the channel path. Persona (bot identity) first, then the
+    // matched route's prompt (conversation instruction — more specific, later =
+    // higher salience). Both are complementary, not competing.
+    const channelSystemPromptAppend = [persona?.systemPrompt, agentConfig.systemPrompt, codeExplorerHint, pythonHint].filter(Boolean).join('\n\n') ||
+        undefined;
     const { CodeBuddyAgent } = await import('../../agent/codebuddy-agent.js');
-    const model = persona?.model || agentConfig.model || resolved.model;
-    const agent = new CodeBuddyAgent(resolved.apiKey || 'local', resolved.baseUrl, model, agentConfig.maxToolRounds ?? 6, // bounded (vs the 50-round default)
+    const agent = new CodeBuddyAgent(runtimeResolved.apiKey || 'local', runtimeResolved.baseUrl, model, agentConfig.maxToolRounds ?? 6, // bounded (vs the 50-round default)
     true, // useRAGToolSelection — relevant tools on demand, not all ~194
     process.env.CODEBUDDY_CHANNEL_PROMPT_ID || 'auto', // minimal/adaptive prompt, not the 73KB legacy
     process.cwd(), channelSystemPromptAppend);
+    agent.setRecoverySessionId?.(sessionKey);
     // Scope per-bot state (memory/lessons) to this bot so bots don't share facts.
     agent.setChannelBotId(botId);
     // Persistence: reload prior conversation from disk on a cold agent (after a
@@ -417,36 +951,202 @@ async function getOrCreateChannelAgent(sessionKey, resolved, agentConfig, botId)
             }
         }
         if (lruKey)
-            channelAgentCache.delete(lruKey);
+            evictChannelAgent(lruKey);
     }
-    channelAgentCache.set(sessionKey, { agent, lastUsed: now });
-    return agent;
+    channelAgentCache.set(sessionKey, { agent, lastUsed: now, runtimeIdentity });
+    return {
+        agent,
+        effectiveRuntime: { ...runtimeResolved, model, egress: runtimeResolved.egress ?? 'cloud' },
+    };
+}
+function isChannelAllowlistedSender(channel, message) {
+    if (typeof channel.getAllowedUsers !== 'function')
+        return false;
+    const listed = channel.getAllowedUsers();
+    if (!listed || listed.length === 0)
+        return false;
+    const identities = [message.sender?.id, message.sender?.username].filter((value) => Boolean(value));
+    if (identities.length === 0)
+        return false;
+    const allowed = new Set(listed.map((entry) => entry.trim().replace(/^@/, '').toLowerCase()));
+    return identities.some((identity) => allowed.has(identity.trim().replace(/^@/, '').toLowerCase()));
 }
 export async function registerAIMessageHandler(manager) {
     if (aiHandlerRegistered)
         return;
     aiHandlerRegistered = true;
     manager.onMessage(async (message, channel) => {
+        let releaseTranscriptSnapshotHold;
+        let generativeSessionKey;
+        let generativeTurnEngaged = false;
+        let cognitiveTurn = null;
+        let deliveryState = 'not_started';
         try {
             // 1. DM pairing gate — unapproved senders get a code, then we stop.
+            // A sender already on the channel static allowlist skipped pairing in the
+            // adapter; do not re-gate them here (pairing default-on would otherwise
+            // refuse the operator's own Telegram id).
             const { checkDMPairing, getDMPairing } = await import('../../channels/core.js');
-            const pairingStatus = await checkDMPairing(message);
-            if (!pairingStatus.approved) {
-                if (pairingStatus.code) {
+            if (!isChannelAllowlistedSender(channel, message)) {
+                const pairingStatus = await checkDMPairing(message);
+                if (!pairingStatus.approved) {
                     const pairing = getDMPairing();
                     const pairingMsg = pairing.getPairingMessage(pairingStatus);
-                    await channel.send({
-                        channelId: message.channel.id,
-                        content: pairingMsg,
-                        replyTo: message.id,
-                    });
+                    if (pairingMsg) {
+                        await channel.send({
+                            channelId: message.channel.id,
+                            content: pairingMsg,
+                            replyTo: message.id,
+                        });
+                    }
+                    return;
                 }
-                return;
             }
             // Nothing to answer (e.g. a non-text message with no transcription).
             if (!message.content || !message.content.trim()) {
                 return;
             }
+            try {
+                const { observeInboundForAwayPause } = await import('../../companion/away-mode.js');
+                observeInboundForAwayPause(channel.type, message.content);
+            }
+            catch {
+                /* travel-mode pause is optional and must never block inbound chat */
+            }
+            const sessionKey = message.sessionKey || 'default-global';
+            // On-demand camera share (« qu'est-ce que tu vois ? ») — Telegram only.
+            // The photo sender is scoped to the requesting chat, not the global alert chat.
+            if (channel.type === 'telegram') {
+                try {
+                    const { maybeHandleCameraShareRequest } = await import('../../companion/camera-share.js');
+                    const share = await maybeHandleCameraShareRequest(message.content, {
+                        surface: 'telegram',
+                        inboundChatId: message.channel.id,
+                        rootDir: process.cwd(),
+                        sendPhoto: async (caption, imagePath) => {
+                            const imageChannel = channel;
+                            if (typeof imageChannel.sendImageFile === 'function') {
+                                await imageChannel.sendImageFile(message.channel.id, imagePath, caption);
+                                return true;
+                            }
+                            const path = await import('node:path');
+                            const extension = path.extname(imagePath).slice(1).toLowerCase();
+                            const sent = await imageChannel.send({
+                                channelId: message.channel.id,
+                                content: caption,
+                                replyTo: message.id,
+                                attachments: [{
+                                        type: 'image',
+                                        filePath: imagePath,
+                                        fileName: path.basename(imagePath),
+                                        mimeType: extension === 'jpg' || extension === 'jpeg'
+                                            ? 'image/jpeg'
+                                            : `image/${extension || 'png'}`,
+                                    }],
+                            });
+                            return Boolean(sent?.success);
+                        },
+                    });
+                    if (share) {
+                        await channel.send({
+                            channelId: message.channel.id,
+                            content: share.spokenReply,
+                            replyTo: message.id,
+                        });
+                        return;
+                    }
+                }
+                catch (cameraShareErr) {
+                    logger.warn('Camera share channel path failed', {
+                        error: cameraShareErr instanceof Error ? cameraShareErr.message : String(cameraShareErr),
+                    });
+                }
+            }
+            // Lisa selfie — cache-first, BEFORE the LLM. Companion profile has no tools,
+            // so a description of lisa_selfie / image_generate never fires here.
+            if (process.env.CODEBUDDY_LISA_SELFIE !== 'false'
+                && isCompanionSurfaceEnabled()) {
+                try {
+                    const { tryServeCompanionSelfie } = await import('../../companion/lisa-selfie-router.js');
+                    const previousSelfie = recentLisaSelfieSessions.get(sessionKey);
+                    const hasRecentSelfie = previousSelfie !== undefined
+                        && Date.now() - previousSelfie.at <= LISA_SELFIE_CONTINUATION_TTL_MS;
+                    if (previousSelfie && !hasRecentSelfie)
+                        recentLisaSelfieSessions.delete(sessionKey);
+                    const served = await tryServeCompanionSelfie(message.content, {
+                        surface: channel.type === 'telegram' ? 'telegram' : 'mobile',
+                        hasRecentSelfie,
+                        includeImageBytes: false,
+                    });
+                    if (served) {
+                        if (served.imagePath) {
+                            const ch = channel;
+                            if (typeof ch.sendImageFile === 'function') {
+                                await ch.sendImageFile(message.channel.id, served.imagePath, served.caption);
+                            }
+                            else {
+                                const pathMod = await import('node:path');
+                                const ext = pathMod.extname(served.imagePath).slice(1) || 'png';
+                                await ch.send({
+                                    channelId: message.channel.id,
+                                    content: served.caption,
+                                    replyTo: message.id,
+                                    attachments: [
+                                        {
+                                            type: 'image',
+                                            filePath: served.imagePath,
+                                            fileName: pathMod.basename(served.imagePath),
+                                            mimeType: served.mimeType
+                                                ?? (ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : `image/${ext}`),
+                                        },
+                                    ],
+                                });
+                            }
+                            recentLisaSelfieSessions.set(sessionKey, {
+                                at: Date.now(),
+                                mood: served.style ?? 'portrait',
+                                contentTier: served.contentTier,
+                            });
+                        }
+                        else {
+                            await channel.send({
+                                channelId: message.channel.id,
+                                content: served.caption,
+                                replyTo: message.id,
+                            });
+                        }
+                        // The selfie IS a turn of the conversation: without this the next
+                        // companion prompt has no trace of the photo that was just sent.
+                        rememberCompanionChannelTurn(sessionKey, message.content, served.caption);
+                        return;
+                    }
+                }
+                catch (selfieErr) {
+                    logger.warn('Lisa selfie channel path failed', {
+                        error: selfieErr instanceof Error ? selfieErr.message : String(selfieErr),
+                    });
+                    // fall through to normal AI handler
+                }
+            }
+            const botId = message.channel?.botId;
+            logger.info('Channel inbound message', {
+                channelType: channel.type,
+                sessionHash: hashForLog(sessionKey),
+                botHash: hashForLog(botId),
+                messageHash: hashForLog(message.id),
+                contentType: message.contentType || 'text',
+                contentLength: message.content.length,
+                attachmentCount: message.attachments?.length ?? 0,
+            });
+            const normalizedMessage = normalizeConversationalSlashMessage(message);
+            if (normalizedMessage !== message) {
+                message = normalizedMessage;
+                logger.info('Channel slash prompt reclassified as conversation', {
+                    channelType: channel.type,
+                    sessionHash: hashForLog(sessionKey),
+                    messageHash: hashForLog(message.id),
+                });
+            }
             // /council <task> — convene the multi-LLM council (ask several capable
             // LLMs, an impartial judge keeps the best, and it learns which model is
             // best per task type over time). `/council` alone shows the scoreboard.
@@ -546,97 +1246,978 @@ export async function registerAIMessageHandler(manager) {
                 ? process.env.CODEBUDDY_PROVIDER
                 : 'auto';
             const resolved = resolveProviderFromEnv(preferredProvider);
-            if (!resolved) {
-                logger.warn('No LLM provider for channel chat — set CODEBUDDY_PROVIDER + a provider key/env');
+            const { getRouteAgentConfig, resolveRoute } = await import('../../channels/core.js');
+            const agentConfig = getRouteAgentConfig(message);
+            // The "route" tier only counts an EXPLICITLY matched route — a
+            // matchType of 'default' is the router-wide fallback and must not
+            // outrank a bot persona (it lands in the route-default tier instead).
+            const resolvedRoute = resolveRoute(message);
+            const routeModel = resolvedRoute && resolvedRoute.matchType !== 'default' ? resolvedRoute.agent?.model : undefined;
+            // /model — per-conversation model override (Hermes parity: session tier).
+            // `/model` shows the effective model + source, `/model <name>` overrides
+            // this chat, `/model reset` reverts to the channel/global tiers. Handled
+            // before the agent so it never burns an LLM turn. `(?:@\S+)?` accepts
+            // Telegram's `/model@BotName` group form.
+            const modelCmd = message.content.trim().match(/^\/model(?:@\S+)?(?:\s+(\S+))?\s*$/i);
+            if (modelCmd) {
+                const arg = modelCmd[1];
+                const personaForShow = botId ? channelBotPersonas.get(botId) : undefined;
+                const effective = () => {
+                    const { model, source } = resolveChannelModel({
+                        sessionOverride: getSessionModelOverride(sessionKey),
+                        routeModel,
+                        personaModel: personaForShow?.model,
+                        routeDefaultModel: agentConfig.model,
+                        globalModel: resolved?.model || 'indisponible',
+                    });
+                    return `${model} (source : ${source})`;
+                };
+                let reply;
+                if (!arg) {
+                    reply = `Modèle : ${effective()} — /model <nom> pour changer, /model reset pour annuler`;
+                }
+                else if (arg.toLowerCase() === 'reset') {
+                    clearSessionModelOverride(sessionKey);
+                    reply = `Override retiré. Modèle effectif : ${effective()}`;
+                }
+                else if (!MODEL_NAME_PATTERN.test(arg)) {
+                    reply = 'Nom de modèle invalide. Usage : /model <nom> | /model reset | /model';
+                }
+                else {
+                    setSessionModelOverride(sessionKey, arg);
+                    reply = `✅ Modèle de cette conversation : ${arg} — appliqué dès le prochain message. Si le modèle est invalide, /model reset pour revenir.`;
+                }
+                await channel.send({ channelId: message.channel.id, content: reply, replyTo: message.id });
                 return;
             }
-            const { getRouteAgentConfig } = await import('../../channels/core.js');
-            const agentConfig = getRouteAgentConfig(message);
-            const sessionKey = message.sessionKey || 'default-global';
-            // Reuse ONE agent per chat (cached by sessionKey) so multi-turn context
-            // persists in-memory across messages; restored from disk on a cold start.
-            // botId selects the per-bot persona and is already baked into sessionKey,
-            // so different bots keep separate agents + histories.
-            const botId = message.channel?.botId;
-            const agent = await getOrCreateChannelAgent(sessionKey, resolved, agentConfig, botId);
-            const entries = await agent.processUserMessage(message.content);
-            const lastEntry = entries[entries.length - 1];
-            const response = lastEntry ? String(lastEntry.content) : '';
-            // 6. Deliver the reply. On Telegram, render the agent's markdown to the
-            //    robust HTML subset (bold / code / tables / links) so it doesn't show
-            //    raw; if Telegram rejects the HTML (success:false) fall back to plain
-            //    text. Other channels keep native markdown (Discord/Slack render it).
-            if (channel.type === 'telegram' && response.trim()) {
-                const { renderTelegramHtml } = await import('../../rendering/telegram-html.js');
-                const chunks = renderTelegramHtml(response);
-                let ok = chunks.length > 0;
-                for (let i = 0; i < chunks.length; i++) {
-                    const res = await channel.send({
+            const queuedAt = Date.now();
+            await serializeChannelTurn(sessionKey, async (turn) => {
+                const queueWaitMs = Date.now() - queuedAt;
+                if (queueWaitMs >= 1_000) {
+                    logger.info('Channel turn dequeued after waiting', {
+                        channelType: channel.type,
+                        sessionHash: hashForLog(sessionKey),
+                        messageHash: hashForLog(message.id),
+                        queueWaitMs,
+                    });
+                }
+                turn.phase('continuity');
+                turn.throwIfAborted();
+                // Reuse ONE agent per chat (cached by sessionKey) so multi-turn context
+                // persists in-memory across messages; restored from disk on a cold start.
+                // botId selects the per-bot persona and is already baked into sessionKey,
+                // so different bots keep separate agents + histories.
+                const { getCrossChannelConversationBridge } = await import('../../conversation/cross-channel-bridge.js');
+                const conversationBridge = getCrossChannelConversationBridge();
+                const continuesVoiceConversation = !message.isCommand &&
+                    !message.content.trim().startsWith('/') &&
+                    conversationBridge.matchesChannel(channel.type, message.channel.id, message.threadId);
+                // Snapshot BEFORE appending the current user turn. The current message is
+                // supplied separately to the agent and must not appear twice in its prompt.
+                const sharedConversationHistory = continuesVoiceConversation
+                    ? conversationBridge.history()
+                    : [];
+                if (continuesVoiceConversation) {
+                    const claim = await conversationBridge.claimChannelTurnDurably({
+                        role: 'user',
+                        content: message.content,
+                        channel: channel.type,
                         channelId: message.channel.id,
-                        content: chunks[i],
-                        parseMode: 'html',
-                        replyTo: i === 0 ? message.id : undefined,
+                        ...(message.threadId ? { threadId: message.threadId } : {}),
+                        externalId: message.id,
                     });
-                    if (!res?.success) {
-                        ok = false;
-                        break;
+                    turn.throwIfAborted();
+                    if (claim === 'duplicate') {
+                        logger.info('Duplicate channel turn skipped before generation', {
+                            channelType: channel.type,
+                            sessionHash: hashForLog(sessionKey),
+                            messageHash: hashForLog(message.id),
+                        });
+                        return;
+                    }
+                    if (claim === 'failed') {
+                        throw new Error('shared conversation journal claim failed');
                     }
                 }
-                if (!ok) {
-                    await channel.send({ channelId: message.channel.id, content: response, replyTo: message.id });
+                // Derived after appending the current turn, so an affect/support signal
+                // observed on Telegram is available immediately to this very response.
+                // The renderer is raw-free: it never repeats transcript text or personal
+                // facts and is only used for the explicitly linked companion thread.
+                const sharedRelationshipContext = continuesVoiceConversation
+                    ? conversationBridge.renderRelationshipContext()
+                    : '';
+                const channelPersona = botId ? channelBotPersonas.get(botId) : undefined;
+                const companionPersona = /\b(lisa|compagne|compagnon|companion)\b/i.test(`${channelPersona?.name ?? ''} ${channelPersona?.systemPrompt ?? ''}`);
+                const companionConversation = (companionPersona || Boolean(channelPersona?.systemPrompt) || continuesVoiceConversation) &&
+                    process.env.CODEBUDDY_CHANNEL_CONVERSATION !== 'false';
+                let companionRoute;
+                const hasExplicitModel = Boolean(getSessionModelOverride(sessionKey) || routeModel || channelPersona?.model);
+                if ((companionPersona || continuesVoiceConversation) &&
+                    companionConversation &&
+                    channel.type === 'telegram' &&
+                    !hasExplicitModel) {
+                    try {
+                        const routingHistory = await resolveChannelRoutingHistory(sessionKey, sharedConversationHistory);
+                        const { resolveCompanionModelRoute } = await import('../../conversation/companion-model-routing.js');
+                        companionRoute =
+                            (await resolveCompanionModelRoute({
+                                surface: 'telegram',
+                                text: message.content,
+                                history: routingHistory,
+                                env: process.env,
+                            })) ?? undefined;
+                        turn.throwIfAborted();
+                    }
+                    catch (error) {
+                        logger.debug('Companion pilot routing unavailable on channel', {
+                            channelType: channel.type,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
                 }
-            }
-            else {
-                await channel.send({
-                    channelId: message.channel.id,
-                    content: response,
-                    replyTo: message.id,
+                const runtimeResolved = resolved ??
+                    (companionRoute
+                        ? {
+                            apiKey: companionRoute.apiKey,
+                            baseUrl: companionRoute.baseURL,
+                            model: companionRoute.model,
+                            egress: companionRoute.egress,
+                        }
+                        : null);
+                if (!runtimeResolved) {
+                    logger.warn('No LLM provider for channel chat — set CODEBUDDY_PROVIDER or activate an available companion route');
+                    const { conversationFailureReply } = await import('../../conversation/conversation-orchestrator.js');
+                    await channel.send({
+                        channelId: message.channel.id,
+                        content: conversationFailureReply(message.content),
+                        replyTo: message.id,
+                    });
+                    return;
+                }
+                const useCompanionProfile = shouldUseCompanionChannelProfile({
+                    text: message.content,
+                    isCommand: message.isCommand === true,
                 });
-            }
-            // 7. If the user SPOKE (voice note), answer by voice too — mirror the
-            //    modality. Best-effort: the text reply already landed, so a TTS/upload
-            //    failure (or a channel without voice support) is a no-op, never fatal.
-            const userSpoke = message.attachments?.some((a) => a.type === 'voice' || a.type === 'audio');
-            const voiceChannel = channel;
-            if (userSpoke && response.trim() && typeof voiceChannel.sendVoiceReply === 'function') {
-                try {
-                    await voiceChannel.sendVoiceReply(message.channel.id, response);
+                turn.phase('runtime');
+                let agent;
+                let effectiveRuntime = {
+                    apiKey: runtimeResolved.apiKey,
+                    baseUrl: runtimeResolved.baseUrl,
+                    model: runtimeResolved.model,
+                    egress: runtimeResolved.egress ?? 'cloud',
+                };
+                if (!useCompanionProfile) {
+                    const created = await getOrCreateChannelAgent(sessionKey, runtimeResolved, agentConfig, botId, routeModel, companionRoute);
+                    agent = created.agent;
+                    effectiveRuntime = created.effectiveRuntime;
+                }
+                turn.throwIfAborted();
+                turn.phase('grounding');
+                let attachedImageEvidence;
+                // A photo shared with the companion is not an analysis request: it goes
+                // through the shared-photo pipeline (privacy posture, reaction contract,
+                // album, memory) instead of the analytical evidence card the agent path
+                // uses. See `companion/companion-photo.ts`.
+                let companionPhotos = null;
+                const imageAttachmentCount = message.attachments?.filter((attachment) => attachment.type === 'image').length ?? 0;
+                const telegramFileResolver = channel.type === 'telegram' &&
+                    typeof channel.getFileUrl === 'function'
+                    ? (reference) => channel.getFileUrl(reference)
+                    : undefined;
+                if (imageAttachmentCount > 0 && useCompanionProfile) {
+                    try {
+                        const [{ loadChannelPhotos }, { prepareCompanionPhotos }] = await Promise.all([
+                            import('../../companion/companion-photo-intake.js'),
+                            import('../../companion/companion-photo.js'),
+                        ]);
+                        const loaded = await loadChannelPhotos(message.attachments, {
+                            ...(telegramFileResolver ? { resolveUrl: telegramFileResolver } : {}),
+                            signal: turn.signal,
+                        });
+                        turn.throwIfAborted();
+                        companionPhotos = await prepareCompanionPhotos(loaded, {
+                            caption: message.content,
+                            model: effectiveRuntime.model,
+                            baseUrl: effectiveRuntime.baseUrl,
+                        });
+                        logger.info('Companion shared-photo perception completed', {
+                            channelType: channel.type,
+                            sessionHash: hashForLog(sessionKey),
+                            messageHash: hashForLog(message.id),
+                            mode: companionPhotos?.mode,
+                            accepted: companionPhotos?.photos.length ?? 0,
+                            rejected: companionPhotos?.rejected.length ?? 0,
+                        });
+                    }
+                    catch (error) {
+                        turn.throwIfAborted();
+                        companionPhotos = null;
+                        logger.warn('Companion shared-photo perception unavailable', {
+                            channelType: channel.type,
+                            sessionHash: hashForLog(sessionKey),
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
                 }
-                catch (voiceErr) {
-                    logger.warn(`Voice reply skipped: ${voiceErr instanceof Error ? voiceErr.message : String(voiceErr)}`);
+                else if (imageAttachmentCount > 0) {
+                    const { groundAttachedImages, renderAttachedImageEvidence, } = await import('../../companion/attached-image-grounding.js');
+                    const visual = await groundAttachedImages(message.attachments, message.content, {
+                        ...(telegramFileResolver ? { resolveUrl: telegramFileResolver } : {}),
+                    });
+                    turn.throwIfAborted();
+                    attachedImageEvidence = renderAttachedImageEvidence(visual) || undefined;
+                    logger.info('Channel attached-image perception completed', {
+                        channelType: channel.type,
+                        sessionHash: hashForLog(sessionKey),
+                        messageHash: hashForLog(message.id),
+                        imageCount: visual.imageCount,
+                        status: visual.status,
+                        model: visual.model,
+                        reason: visual.reason,
+                    });
                 }
-            }
-            // 7b. Deliver image artifacts: if the reply names image paths that exist
-            //     on disk (e.g. a chart the agent just generated), send them as photos.
-            const imageChannel = channel;
-            if (typeof imageChannel.sendImageFile === 'function') {
-                const os = await import('node:os');
-                const fsp = await import('node:fs/promises');
-                const matches = response.match(/(?:~\/|\/)[\w./-]+\.(?:png|jpe?g|gif|webp)/gi) || [];
-                const seen = new Set();
-                for (const raw of matches) {
-                    const p = raw.startsWith('~/') ? os.homedir() + raw.slice(1) : raw;
-                    if (seen.has(p) || seen.size >= 4)
-                        continue;
-                    seen.add(p);
+                if (companionConversation && !useCompanionProfile) {
+                    cognitiveTurn = await getChannelCognitivePort().begin({
+                        channelType: channel.type,
+                        sessionKey,
+                        messageId: message.id,
+                        content: message.content,
+                        egress: effectiveRuntime.egress,
+                    });
+                    turn.throwIfAborted();
+                }
+                const agentInput = companionPhotos
+                    ? companionPhotos.userText
+                    : attachedImageEvidence
+                        ? `${message.content}\n\n${attachedImageEvidence}\n\n` +
+                            'Réponds à la demande en t’appuyant sur cette fiche visuelle. Distingue les faits visibles des incertitudes.'
+                        : imageAttachmentCount > 0
+                            ? `${message.content}\n\nL’analyse des images jointes a échoué. Dis-le honnêtement et demande un nouvel envoi net si nécessaire.`
+                            : message.content;
+                let transientConversationContext;
+                let preparedConversation;
+                let companionConversationHistory = [];
+                let companionFreshEvidence;
+                let prefetchedGroundedFallback;
+                let prefetchedDirectResponse;
+                if (companionConversation) {
+                    const [conversation, prefetchedContext, prefetchEngine] = await Promise.all([
+                        import('../../conversation/conversation-orchestrator.js'),
+                        import('../../conversation/prefetched-turn-context.js'),
+                        import('../../companion/prefetch-engine.js'),
+                    ]);
+                    const history = sharedConversationHistory.length
+                        ? sharedConversationHistory.slice(-12)
+                        : useCompanionProfile
+                            ? (companionChannelHistories.get(sessionKey) ?? []).slice(-12)
+                            : (agent
+                                ?.getChatHistory()
+                                .filter((entry) => entry.type === 'user' || entry.type === 'assistant')
+                                .slice(-12)
+                                .map((entry) => {
+                                const content = String(entry.content ?? '')
+                                    .replace(/<companion_turn>[\s\S]*?<\/companion_turn>\s*/g, '')
+                                    .replace(/^Message de l'utilisateur\s*:\s*/i, '')
+                                    .trim();
+                                return {
+                                    role: entry.type === 'user' ? 'user' : 'assistant',
+                                    content,
+                                };
+                            })
+                                .filter((entry) => entry.content) ?? []);
+                    companionConversationHistory = history;
+                    const freshContext = process.env.CODEBUDDY_PREFETCH === 'false'
+                        ? null
+                        : prefetchedContext.resolvePrefetchedTurnContextForConversation(message.content, history, { allowStale: true });
+                    if (process.env.CODEBUDDY_PREFETCH !== 'false' &&
+                        (freshContext?.freshness === 'stale' ||
+                            (!freshContext && prefetchedContext.isPrefetchedTurnRequest(message.content)))) {
+                        void prefetchEngine.runPrefetchCycle().catch(() => undefined);
+                    }
+                    companionFreshEvidence =
+                        prefetchedContext.semanticReviewEvidenceFromPrefetch(freshContext);
+                    companionFreshEvidence = [companionFreshEvidence, attachedImageEvidence]
+                        .filter((part) => Boolean(part?.trim()))
+                        .join('\n\n') || undefined;
+                    prefetchedGroundedFallback = freshContext
+                        ? freshContext.text.trim() || freshContext.speech.trim() || undefined
+                        : undefined;
+                    if (freshContext &&
+                        prefetchedContext.shouldUsePrefetchedAnswerDirectly(message.content, freshContext)) {
+                        prefetchedDirectResponse = prefetchedGroundedFallback;
+                    }
+                    preparedConversation = conversation.prepareConversationTurn(message.content, history, {
+                        ...(sharedRelationshipContext
+                            ? { relationshipContext: sharedRelationshipContext }
+                            : {}),
+                        ...(freshContext ? { freshContext: freshContext.promptGuidance } : {}),
+                    });
+                    transientConversationContext = [
+                        preparedConversation.systemGuidance,
+                        cognitiveTurn?.turnContext,
+                        cognitiveTurn?.evidence,
+                    ].filter((part) => Boolean(part?.trim())).join('\n\n') || undefined;
+                }
+                const semanticReviewProfile = isRuntimeEvidenceVerificationRequest(message.content)
+                    ? 'factual_analytical'
+                    : undefined;
+                const semanticReviewPlanned = !useCompanionProfile &&
+                    companionConversation &&
+                    !prefetchedDirectResponse &&
+                    preparedConversation !== undefined &&
+                    shouldRunSemanticResponseGate({
+                        plan: preparedConversation.plan,
+                        ...(semanticReviewProfile ? { profile: semanticReviewProfile } : {}),
+                    }) &&
+                    deriveArgumentObligations(preparedConversation.plan, message.content).length > 0;
+                if (semanticReviewPlanned && agent) {
+                    const snapshotAgent = agent;
+                    snapshotAgent.suspendTranscriptSnapshots();
+                    let released = false;
+                    releaseTranscriptSnapshotHold = () => {
+                        if (released)
+                            return;
+                        released = true;
+                        if (channelAgentCache.get(sessionKey)?.agent === snapshotAgent) {
+                            snapshotAgent.resumeTranscriptSnapshots();
+                        }
+                    };
+                }
+                // From this point onward the cached agent may contain a user turn or an
+                // assistant draft. Any later exception (including a rejected transport
+                // promise) must discard that private state unless delivery and
+                // persistence complete normally.
+                generativeSessionKey = sessionKey;
+                generativeTurnEngaged = Boolean(agent);
+                let response = '';
+                let rawAgentFailure = false;
+                let hasGeneratedResponse = false;
+                let successfulLisaSelfieToolResult = false;
+                let shouldPersistChannelSession = Boolean(agent);
+                let telegramWidget;
+                let companionMediaResult;
+                let companionHistorySuffix;
+                if (prefetchedDirectResponse) {
+                    response = prefetchedDirectResponse;
+                    if (agent && !agent.recordTrustedExternalConversationTurn(agentInput, response)) {
+                        throw new Error('trusted prefetched turn could not be recorded');
+                    }
+                    logger.info('Channel served trusted prefetched companion response directly', {
+                        channelType: channel.type,
+                        sessionHash: hashForLog(sessionKey),
+                        messageHash: hashForLog(message.id),
+                        responseLength: response.length,
+                    });
+                }
+                else if (useCompanionProfile) {
+                    turn.phase('generation');
+                    const hasSharedPhotos = (companionPhotos?.photos.length ?? 0) > 0;
+                    const prompt = await assembleCompanionChannelPrompt({
+                        userText: agentInput,
+                        history: companionConversationHistory.length
+                            ? companionConversationHistory
+                            : companionChannelHistories.get(sessionKey),
+                        ...(hasSharedPhotos && companionPhotos
+                            ? { extraSystem: companionPhotos.guidance }
+                            : {}),
+                    });
+                    let companionMessages = prompt.messages;
+                    if (hasSharedPhotos && companionPhotos?.mode === 'cloud') {
+                        const { attachPhotoParts } = await import('../../companion/companion-photo.js');
+                        companionMessages = attachPhotoParts(prompt.messages, companionPhotos.photos);
+                    }
+                    logger.info('Companion channel profile prompt', {
+                        channelType: channel.type,
+                        sessionHash: hashForLog(sessionKey),
+                        tokenEstimate: prompt.tokenEstimate,
+                        messageCount: prompt.messages.length,
+                        sharedPhotos: companionPhotos?.photos.length ?? 0,
+                    });
                     try {
-                        await fsp.access(p);
-                        await imageChannel.sendImageFile(message.channel.id, p);
+                        let companionIdentity;
+                        if (channel.type === 'telegram') {
+                            const { resolveCompanionIdentity } = await import('../../companion/companion-identity.js');
+                            const telegramChannel = channel;
+                            companionIdentity = resolveCompanionIdentity({
+                                channel: 'telegram',
+                                chatId: message.channel.id,
+                                senderId: message.sender?.id,
+                                senderUsername: message.sender?.username,
+                                allowedUsers: telegramChannel.config?.allowedUsers ?? [],
+                                env: process.env,
+                            });
+                        }
+                        const generated = await runCompanionChannelTurn({
+                            apiKey: effectiveRuntime.apiKey,
+                            baseUrl: effectiveRuntime.baseUrl,
+                            model: effectiveRuntime.model,
+                            messages: companionMessages,
+                            signal: turn.signal,
+                            ...(companionIdentity ? { identity: companionIdentity } : {}),
+                            surface: channel.type,
+                            env: process.env,
+                        });
+                        turn.throwIfAborted();
+                        response = generated.text;
+                        hasGeneratedResponse = response.trim() !== '';
+                        companionMediaResult = generated.media;
+                        companionHistorySuffix = generated.historySuffix;
+                        if (hasSharedPhotos && companionPhotos) {
+                            // The album write is deliberately after the reply: a full disk must
+                            // cost the memory, never the reaction.
+                            const { rememberSharedPhotos } = await import('../../companion/shared-photo-memory.js');
+                            const stored = await rememberSharedPhotos(companionPhotos.photos, {
+                                surface: 'telegram',
+                                caption: message.content,
+                            });
+                            logger.info('Companion shared photos filed', {
+                                channelType: channel.type,
+                                sessionHash: hashForLog(sessionKey),
+                                stored: stored.length,
+                            });
+                        }
+                    }
+                    catch (error) {
+                        turn.throwIfAborted();
+                        response = speakChannelProviderFailure(error, {
+                            copine: Boolean(process.env.CODEBUDDY_COMPANION_PERSONA),
+                        });
+                        logger.warn('Companion channel provider failure spoken to conversation', {
+                            channelType: channel.type,
+                            sessionHash: hashForLog(sessionKey),
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+                else {
+                    turn.phase('generation');
+                    const entries = await agent.processUserMessage(agentInput, {
+                        surface: channel.type,
+                        ...(attachedImageEvidence || imageAttachmentCount > 0
+                            ? { introspectionText: message.content }
+                            : {}),
+                        ...(transientConversationContext
+                            ? {
+                                transientContext: transientConversationContext,
+                                relationshipSafety: companionConversation,
+                            }
+                            : {}),
+                    });
+                    successfulLisaSelfieToolResult = entries.some((entry) => entry.type === 'tool_result' &&
+                        entry.toolResult?.success === true &&
+                        entry.toolCall?.function?.name === 'lisa_selfie');
+                    turn.throwIfAborted();
+                    const lastEntry = entries[entries.length - 1];
+                    response = lastEntry ? String(lastEntry.content) : '';
+                    if (channel.type === 'telegram') {
+                        const { autoWidget } = await import('../../widgets/auto-widget.js');
+                        const widget = await autoWidget(response, entries
+                            .filter((entry) => entry.type === 'tool_result')
+                            .map((entry) => entry.toolResult ?? { output: entry.content }));
+                        if (widget.widgetHtml || widget.candidate) {
+                            telegramWidget = {
+                                ...(widget.widgetHtml ? { widgetHtml: widget.widgetHtml } : {}),
+                                ...(widget.candidate?.kind === 'payload' ? { data: widget.candidate.data } : {}),
+                            };
+                        }
+                    }
+                    rawAgentFailure = isAgentFailureResponse(response);
+                    hasGeneratedResponse = response.trim() !== '' && !rawAgentFailure;
+                }
+                if (hasGeneratedResponse) {
+                    response = prependUserFacingFailoverNotice(response, `channel:${channel.type}`);
+                }
+                if (!response.trim() || rawAgentFailure) {
+                    const { conversationFailureReply } = await import('../../conversation/conversation-orchestrator.js');
+                    const replacement = prefetchedGroundedFallback ??
+                        (rawAgentFailure
+                            ? speakChannelProviderFailure(response, {
+                                copine: Boolean(process.env.CODEBUDDY_COMPANION_PERSONA),
+                            })
+                            : conversationFailureReply(message.content, companionConversationHistory));
+                    if (prefetchedGroundedFallback) {
+                        logger.info('Channel provider failure recovered from prefetched companion context', {
+                            channelType: channel.type,
+                            sessionHash: hashForLog(sessionKey),
+                        });
+                    }
+                    if (rawAgentFailure) {
+                        if (agent && !agent.replaceLastAssistantResponse(response, replacement)) {
+                            evictChannelAgent(sessionKey, true);
+                            shouldPersistChannelSession = false;
+                            logger.error('Channel provider failure rewrite missed agent history', {
+                                channelType: channel.type,
+                                sessionHash: hashForLog(sessionKey),
+                            });
+                        }
+                        logger.warn('Channel provider failure spoken to conversation', {
+                            channelType: channel.type,
+                            sessionHash: hashForLog(sessionKey),
+                        });
+                    }
+                    response = replacement;
+                }
+                const semanticReviewEligible = semanticReviewPlanned &&
+                    hasGeneratedResponse &&
+                    !successfulLisaSelfieToolResult &&
+                    preparedConversation !== undefined;
+                // The semantic reviewer may resolve to a different provider/egress than
+                // the main model. Cognitive evidence was projected for the main route,
+                // so it cannot cross this second model boundary without a new projection.
+                const semanticEvidence = companionFreshEvidence?.trim() || undefined;
+                if (semanticReviewEligible && preparedConversation) {
+                    turn.phase('review');
+                    try {
+                        const { reviewSemanticResponse } = await import('../../conversation/semantic-response-runtime.js');
+                        const unreviewedResponse = response;
+                        const reviewed = await reviewSemanticResponse({
+                            request: message.content,
+                            draft: unreviewedResponse,
+                            plan: preparedConversation.plan,
+                            ...(semanticReviewProfile ? { profile: semanticReviewProfile } : {}),
+                            history: companionConversationHistory,
+                            ...(semanticEvidence ? { evidence: semanticEvidence } : {}),
+                            mainProvider: {
+                                apiKey: effectiveRuntime.apiKey,
+                                baseURL: effectiveRuntime.baseUrl,
+                                model: effectiveRuntime.model,
+                            },
+                        });
+                        turn.throwIfAborted();
+                        const rejectedFreshGrounding = reviewed.outcome === 'fail_open' &&
+                            (reviewed.audit?.issueCodes.includes('ungrounded_fresh_claim') === true ||
+                                reviewed.verificationAudit?.issueCodes.includes('ungrounded_fresh_claim') === true);
+                        const groundedRecovery = rejectedFreshGrounding
+                            ? prefetchedGroundedFallback ??
+                                "Je n’ai pas réussi à vérifier cette information fraîche avec une source exploitable. " +
+                                    'Je préfère ne pas l’inventer ; redemande-moi dans un instant.'
+                            : undefined;
+                        response = groundedRecovery ?? (reviewed.response.trim() || unreviewedResponse);
+                        if (response !== unreviewedResponse) {
+                            if (agent && !agent.replaceLastAssistantResponse(unreviewedResponse, response)) {
+                                // Delivery may continue with the reviewed text, but an agent
+                                // containing the rejected draft can neither be cached nor saved.
+                                evictChannelAgent(sessionKey, true);
+                                shouldPersistChannelSession = false;
+                                logger.error('Companion semantic rewrite missed agent history', {
+                                    channelType: channel.type,
+                                    sessionHash: hashForLog(sessionKey),
+                                });
+                            }
+                        }
+                        if (groundedRecovery) {
+                            logger.warn('Companion rejected ungrounded fresh response before delivery', {
+                                channelType: channel.type,
+                                sessionHash: hashForLog(sessionKey),
+                                recovery: prefetchedGroundedFallback ? 'prefetched_evidence' : 'honest_retry',
+                            });
+                        }
+                        logger.info('Companion semantic response gate completed', {
+                            channelType: channel.type,
+                            sessionHash: hashForLog(sessionKey),
+                            outcome: reviewed.outcome,
+                            reason: reviewed.reason,
+                            revisionAttempts: reviewed.revisionAttempts,
+                            issueCodes: reviewed.audit?.issueCodes ?? [],
+                            lowDimensions: reviewed.audit?.lowDimensions ?? [],
+                        });
+                    }
+                    catch (error) {
+                        // The shared runtime is fail-open; retain that property if module
+                        // loading itself is unavailable in an older packaged installation.
+                        logger.warn('Companion semantic response gate unavailable', {
+                            channelType: channel.type,
+                            sessionHash: hashForLog(sessionKey),
+                            errorType: error instanceof Error ? error.name : 'unknown',
+                        });
+                    }
+                }
+                if ((companionConversation || useCompanionProfile) && response.trim()) {
+                    const { guardRelationshipReply } = await import('../../conversation/relationship-safety.js');
+                    const guarded = guardRelationshipReply(response);
+                    const unguardedResponse = response;
+                    response = guarded.response;
+                    try {
+                        const { applyLimitsContract } = await import('../../companion/reply-augment.js');
+                        response = applyLimitsContract(response, { heard: message.content }).text;
                     }
                     catch {
-                        // path isn't a real/accessible image — skip
+                        /* limits contract is optional */
+                    }
+                    try {
+                        const { rememberSaid } = await import('../../companion/recent-said.js');
+                        rememberSaid(response, 'telegram');
+                    }
+                    catch {
+                        /* recent-said is optional */
+                    }
+                    if (guarded.intervened) {
+                        if (agent && !agent.replaceLastAssistantResponse(unguardedResponse, response)) {
+                            // Never retain a response that the delivery gate rejected. A cold
+                            // agent will restore the safe persisted transcript on the next turn.
+                            evictChannelAgent(sessionKey, true);
+                            shouldPersistChannelSession = false;
+                            logger.error('Companion relationship safety rewrite missed agent history', {
+                                channelType: channel.type,
+                                sessionHash: hashForLog(sessionKey),
+                            });
+                        }
+                        logger.warn('Companion relationship safety gate intervened on channel reply', {
+                            channelType: channel.type,
+                            sessionHash: hashForLog(sessionKey),
+                            issues: guarded.issues,
+                        });
                     }
                 }
-            }
-            // 8. Persist the conversation so it survives a daemon restart / cache eviction.
-            await persistChannelSession(agent, sessionKey);
+                let deliveryMode = response.trim() ? 'native' : 'fallback';
+                let deliveredChunks = 0;
+                let delivered = false;
+                let deliveredAssistantContent = '';
+                // 6. Deliver the reply. On Telegram, render the agent's markdown to the
+                //    robust HTML subset (bold / code / tables / links) so it doesn't show
+                //    raw; if Telegram rejects the HTML (success:false) fall back to plain
+                //    text. Other channels keep native markdown (Discord/Slack render it).
+                turn.throwIfAborted();
+                turn.phase('delivery');
+                deliveryState = 'started';
+                if (channel.type === 'telegram' && response.trim() && companionMediaResult && companionMediaResult.length > 0) {
+                    const media = companionMediaResult[0];
+                    if (media) {
+                        const pathMod = await import('path');
+                        const ext = pathMod.extname(media.imagePath).slice(1) || 'png';
+                        const result = await channel.send({
+                            channelId: message.channel.id,
+                            content: response,
+                            replyTo: message.id,
+                            attachments: [
+                                {
+                                    type: 'image',
+                                    filePath: media.imagePath,
+                                    fileName: pathMod.basename(media.imagePath),
+                                    mimeType: ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : `image/${ext}`,
+                                },
+                            ],
+                        });
+                        delivered = result?.success === true;
+                        deliveredChunks = delivered ? 1 : 0;
+                        if (delivered)
+                            deliveredAssistantContent = response;
+                        if (delivered)
+                            deliveryMode = 'telegram-photo';
+                        else
+                            deliveryMode = 'failed';
+                    }
+                }
+                else if (channel.type === 'telegram' && response.trim() && telegramWidget) {
+                    const result = await channel.send({
+                        channelId: message.channel.id,
+                        content: response,
+                        parseMode: 'plain',
+                        replyTo: message.id,
+                        channelData: { telegram: telegramWidget },
+                    });
+                    delivered = result?.success === true;
+                    deliveredChunks = delivered ? 1 : 0;
+                    if (delivered)
+                        deliveredAssistantContent = response;
+                    if (delivered)
+                        deliveryMode = 'telegram-widget';
+                    else
+                        deliveryMode = 'failed';
+                }
+                else if (channel.type === 'telegram' && response.trim()) {
+                    const { renderTelegramHtml, renderPlain, telegramHtmlChunkToPlain, } = await import('../../rendering/index.js');
+                    const chunks = renderTelegramHtml(response);
+                    const acceptedChunks = [];
+                    let ok = chunks.length > 0;
+                    for (let i = 0; i < chunks.length; i++) {
+                        let res;
+                        try {
+                            res = await channel.send({
+                                channelId: message.channel.id,
+                                content: chunks[i],
+                                parseMode: 'html',
+                                replyTo: i === 0 ? message.id : undefined,
+                            });
+                        }
+                        catch (error) {
+                            logger.warn('Telegram HTML chunk transport rejected', {
+                                sessionHash: hashForLog(sessionKey),
+                                messageHash: hashForLog(message.id),
+                                chunk: i + 1,
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                            ok = false;
+                            break;
+                        }
+                        if (!res?.success) {
+                            ok = false;
+                            break;
+                        }
+                        deliveredChunks++;
+                        acceptedChunks.push(chunks[i]);
+                    }
+                    if (!ok) {
+                        if (deliveredChunks === 0) {
+                            // First HTML chunk rejected: no user-visible prefix exists, so a
+                            // complete plain fallback is safe and cannot duplicate content.
+                            const fallback = await channel.send({
+                                channelId: message.channel.id,
+                                content: renderPlain(response),
+                                replyTo: message.id,
+                            });
+                            delivered = fallback?.success === true;
+                            deliveryMode = delivered ? 'plain-fallback' : 'failed';
+                            if (delivered) {
+                                deliveredChunks++;
+                                deliveredAssistantContent = response;
+                            }
+                        }
+                        else {
+                            // A later chunk failed. Re-sending the whole answer would repeat
+                            // every preceding chunk. Preserve only the prefix the person
+                            // actually saw; the generated full draft is still evicted below.
+                            delivered = false;
+                            deliveryMode = 'partial-failure';
+                            deliveredAssistantContent = acceptedChunks
+                                .map(telegramHtmlChunkToPlain)
+                                .filter(Boolean)
+                                .join('\n\n')
+                                .trim();
+                        }
+                    }
+                    else {
+                        deliveryMode = 'telegram-html';
+                        delivered = chunks.length > 0;
+                        if (delivered)
+                            deliveredAssistantContent = response;
+                    }
+                }
+                else {
+                    const result = await channel.send({
+                        channelId: message.channel.id,
+                        content: response,
+                        replyTo: message.id,
+                    });
+                    delivered = result?.success === true;
+                    deliveredChunks = delivered && response.trim() ? 1 : 0;
+                    if (delivered)
+                        deliveredAssistantContent = response;
+                    if (!delivered)
+                        deliveryMode = 'failed';
+                }
+                logger.info('Channel response delivered', {
+                    channelType: channel.type,
+                    sessionHash: hashForLog(sessionKey),
+                    botHash: hashForLog(botId),
+                    messageHash: hashForLog(message.id),
+                    responseLength: response.length,
+                    deliveryMode,
+                    deliveredChunks,
+                    delivered,
+                });
+                if (delivered)
+                    deliveryState = 'delivered';
+                if (!delivered) {
+                    // The cached agent already contains the generated assistant turn. Drop
+                    // it and skip persistence so the next request cannot build on a reply
+                    // the user never received.
+                    evictChannelAgent(sessionKey, true);
+                    shouldPersistChannelSession = false;
+                    logger.warn('Channel response was not delivered; evicting transient agent state', {
+                        channelType: channel.type,
+                        sessionHash: hashForLog(sessionKey),
+                        messageHash: hashForLog(message.id),
+                    });
+                }
+                releaseTranscriptSnapshotHold?.();
+                releaseTranscriptSnapshotHold = undefined;
+                turn.phase('settlement');
+                if (continuesVoiceConversation && deliveredAssistantContent) {
+                    const assistantClaim = await conversationBridge.claimChannelTurnDurably({
+                        role: 'assistant',
+                        content: deliveredAssistantContent,
+                        channel: channel.type,
+                        channelId: message.channel.id,
+                        ...(message.threadId ? { threadId: message.threadId } : {}),
+                        externalId: `${message.id}:assistant`,
+                    });
+                    turn.throwIfAborted();
+                    if (assistantClaim === 'failed') {
+                        logger.warn('Delivered channel turn could not be committed to shared continuity', {
+                            channelType: channel.type,
+                            sessionHash: hashForLog(sessionKey),
+                            messageHash: hashForLog(message.id),
+                        });
+                    }
+                }
+                if (cognitiveTurn) {
+                    // Remove ownership before awaiting: a post-delivery network failure is
+                    // a commit-uncertain state and must never fall through to release.
+                    const turnToSettle = cognitiveTurn;
+                    cognitiveTurn = null;
+                    try {
+                        if (delivered) {
+                            await turnToSettle.complete(deliveredAssistantContent);
+                        }
+                        else if (deliveredAssistantContent) {
+                            await turnToSettle.complete(deliveredAssistantContent, { cancelAfter: true });
+                        }
+                        else {
+                            await turnToSettle.fail();
+                        }
+                        turn.throwIfAborted();
+                    }
+                    catch (error) {
+                        logger.warn('Channel cognitive settlement uncertain', {
+                            channelType: channel.type,
+                            sessionHash: hashForLog(sessionKey),
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+                // 7. If the user SPOKE (voice note), answer by voice too — mirror the
+                //    modality. Best-effort: the text reply already landed, so a TTS/upload
+                //    failure (or a channel without voice support) is a no-op, never fatal.
+                const userSpoke = message.attachments?.some((a) => a.type === 'voice' || a.type === 'audio');
+                const voiceChannel = channel;
+                if (delivered &&
+                    userSpoke &&
+                    response.trim() &&
+                    typeof voiceChannel.sendVoiceReply === 'function') {
+                    try {
+                        await voiceChannel.sendVoiceReply(message.channel.id, response);
+                    }
+                    catch (voiceErr) {
+                        logger.warn(`Voice reply skipped: ${voiceErr instanceof Error ? voiceErr.message : String(voiceErr)}`);
+                    }
+                }
+                // 7b. Deliver image artifacts: if the reply names image paths that exist
+                //     on disk (e.g. a chart the agent just generated), send them as photos.
+                const imageChannel = channel;
+                if (delivered && typeof imageChannel.sendImageFile === 'function') {
+                    const os = await import('node:os');
+                    const fsp = await import('node:fs/promises');
+                    const matches = response.match(/(?:~\/|\/)[\w./-]+\.(?:png|jpe?g|gif|webp)/gi) || [];
+                    const seen = new Set();
+                    for (const raw of matches) {
+                        const p = raw.startsWith('~/') ? os.homedir() + raw.slice(1) : raw;
+                        if (seen.has(p) || seen.size >= 4)
+                            continue;
+                        seen.add(p);
+                        try {
+                            await fsp.access(p);
+                            await imageChannel.sendImageFile(message.channel.id, p);
+                        }
+                        catch {
+                            // path isn't a real/accessible image — skip
+                        }
+                    }
+                }
+                // 8. Persist the conversation so it survives a daemon restart / cache eviction.
+                turn.throwIfAborted();
+                turn.phase('persistence');
+                if (useCompanionProfile && response.trim()) {
+                    const recordedResponse = companionHistorySuffix
+                        ? `${response}${companionHistorySuffix}`
+                        : response;
+                    rememberCompanionChannelTurn(sessionKey, message.content, recordedResponse);
+                }
+                if (shouldPersistChannelSession && agent)
+                    await persistChannelSession(agent, sessionKey);
+                turn.throwIfAborted();
+            }, {
+                ...(() => {
+                    const typing = channelTypingLifecycle(channel, message.channel.id);
+                    const wait = channelWaitNoticeLifecycle(channel, message.channel.id, message.id);
+                    return {
+                        onStart: () => {
+                            typing.onStart();
+                            wait.onStart();
+                        },
+                        onSettled: () => {
+                            wait.onSettled();
+                            typing.onSettled();
+                        },
+                    };
+                })(),
+                onTimeout: async () => {
+                    await cognitiveTurn?.fail().catch(() => undefined);
+                    cognitiveTurn = null;
+                    releaseTranscriptSnapshotHold?.();
+                    releaseTranscriptSnapshotHold = undefined;
+                    if (generativeTurnEngaged && generativeSessionKey) {
+                        evictChannelAgent(generativeSessionKey, true);
+                    }
+                    if (deliveryState === 'not_started') {
+                        deliveryState = 'started';
+                        const result = await channel.send({
+                            channelId: message.channel.id,
+                            content: speakChannelProviderFailure(Object.assign(new Error('channel turn timed out after timeout during generation'), {
+                                name: 'ChannelTurnTimeoutError',
+                            }), { copine: Boolean(process.env.CODEBUDDY_COMPANION_PERSONA) }),
+                            replyTo: message.id,
+                        });
+                        if (result?.success)
+                            deliveryState = 'delivered';
+                    }
+                },
+                diagnostics: {
+                    channelType: channel.type,
+                    sessionHash: hashForLog(sessionKey),
+                    messageHash: hashForLog(message.id),
+                },
+            });
         }
         catch (err) {
-            logger.error('Channel AI response failed', { error: err instanceof Error ? err.message : String(err) });
+            await cognitiveTurn?.fail().catch(() => undefined);
+            cognitiveTurn = null;
+            releaseTranscriptSnapshotHold?.();
+            releaseTranscriptSnapshotHold = undefined;
+            if (generativeTurnEngaged && generativeSessionKey) {
+                evictChannelAgent(generativeSessionKey, true);
+            }
+            const timedOut = err instanceof ChannelTurnTimeoutError;
+            logger.error('Channel AI response failed', {
+                error: err instanceof Error ? err.message : String(err),
+                errorType: err instanceof Error ? err.name : 'unknown',
+                deliveryState,
+            });
+            if (timedOut && deliveryState !== 'not_started') {
+                // Delivery is either confirmed or transport-uncertain. Retrying here
+                // could duplicate a late Telegram send, so only release the FIFO.
+                return;
+            }
+            try {
+                const { conversationFailureReply } = await import('../../conversation/conversation-orchestrator.js');
+                const raw = err instanceof Error ? err.message : String(err);
+                const spoken = timedOut || /sorry, i encountered an error/i.test(raw)
+                    ? speakChannelProviderFailure(err, {
+                        copine: Boolean(process.env.CODEBUDDY_COMPANION_PERSONA),
+                    })
+                    : conversationFailureReply(message.content);
+                await channel.send({
+                    channelId: message.channel.id,
+                    content: spoken,
+                    replyTo: message.id,
+                });
+            }
+            catch {
+                /* delivery itself is unavailable; the error is already logged */
+            }
         }
     });
 }
-export async function instantiateChannel(config) {
+export async function instantiateChannel(configEntry) {
+    // Resolve the auth token BEFORE building the channel config so every branch
+    // below sees the effective token. Priority: an explicit literal `token` wins
+    // (full backwards compat), otherwise fall back to the encrypted secret the
+    // Cowork GUI stores under `channel:<type>:token`, otherwise no token. Never
+    // throws, never logs the secret. See src/channels/resolve-channel-secret.ts.
+    const config = {
+        ...configEntry,
+        token: resolveChannelSecret(configEntry.type, configEntry),
+    };
     const opts = config.options ?? {};
     const channelConfig = {
         type: config.type,
@@ -647,6 +2228,13 @@ export async function instantiateChannel(config) {
         allowedChannels: config.allowedChannels,
         options: opts,
     };
+    const optsAllowlist = Array.isArray(opts.allowedUsers)
+        ? opts.allowedUsers.filter((item) => typeof item === 'string')
+        : undefined;
+    const inboundAllowlist = {
+        allowedUsers: config.allowedUsers ?? optsAllowlist,
+        allowedChannels: config.allowedChannels,
+    };
     switch (config.type) {
         case 'telegram': {
             const { TelegramChannel } = await import('../../channels/telegram/index.js');
@@ -665,15 +2253,32 @@ export async function instantiateChannel(config) {
             // TelegramChannel reads `config.token` (client.ts) — pass `token`, not
             // `botToken`, or it throws "Telegram bot token is required" and the
             // channel never starts from channels.json / server intake.
-            return new TelegramChannel({ token: config.token || '', ...opts });
+            // Root `allowedUsers` used to be dropped here (only `...opts` was passed).
+            return new TelegramChannel({
+                ...channelConfig,
+                token: config.token || '',
+                ...opts,
+                ...inboundAllowlist,
+            });
         }
         case 'discord': {
             const { DiscordChannel } = await import('../../channels/discord/index.js');
-            return new DiscordChannel({ token: config.token || '', ...opts });
+            return new DiscordChannel({
+                ...channelConfig,
+                token: config.token || '',
+                ...opts,
+                ...inboundAllowlist,
+            });
         }
         case 'slack': {
             const { SlackChannel } = await import('../../channels/slack/index.js');
-            return new SlackChannel({ botToken: config.token || '', ...opts });
+            return new SlackChannel({
+                ...channelConfig,
+                token: config.token || '',
+                botToken: config.token || '',
+                ...opts,
+                ...inboundAllowlist,
+            });
         }
         case 'whatsapp': {
             const { WhatsAppChannel } = await import('../../channels/whatsapp/index.js');