cli-wechat-bridge 1.2.2 → 1.2.3

package/dist/bridge/bridge-adapters.codex.js

@@ -6,9 +6,12 @@
 // LICENSE.txt. Network services built on it must offer source to users.
 import fs from "node:fs";
 import { t } from "../i18n/index.js";
+import net from "node:net";
+import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { spawn as spawnChild, spawnSync } from "node:child_process";
+import { WebSocket as WsPackageWebSocket } from "ws";
 import { detectCliApproval, } from "./bridge-utils.js";
 import { normalizeOutput, nowIso, summarizeOutput, truncatePreview, } from "../core/text-utils.js";
 import { AbstractPtyAdapter } from "./bridge-adapters.core.js";
@@ -32,6 +35,86 @@ export function isCodexVersionInCompatibilityRange(version) {
     const minor = parts[1] ?? -1;
     return major === 0 && minor >= 149 && minor <= 161;
 }
+/** Resolve the shared Codex app-server daemon control socket path. */
+export function resolveCodexDaemonControlSocketPath(codexHomeEnv = process.env.CODEX_HOME) {
+    const codexHome = codexHomeEnv && codexHomeEnv.trim()
+        ? codexHomeEnv
+        : path.join(os.homedir(), ".codex");
+    return path.join(codexHome, "app-server-control", "app-server-control.sock");
+}
+/**
+ * Pick attachable threads from a `thread/list` response: only threads that are
+ * live in the shared daemon (`status.type !== "notLoaded"`), belong to the
+ * requested cwd, are root threads, accept direct input, and were not started
+ * by a bridge (`originator === "wechat-bridge"`). Newest activity wins.
+ */
+export function selectCodexDaemonAttachCandidates(response, cwd) {
+    if (!isRecord(response) || !Array.isArray(response.data)) {
+        return [];
+    }
+    const candidates = [];
+    for (const entry of response.data) {
+        if (!isRecord(entry))
+            continue;
+        const id = typeof entry.id === "string" ? entry.id : null;
+        if (!id)
+            continue;
+        const threadCwd = typeof entry.cwd === "string" ? entry.cwd : null;
+        if (!threadCwd || normalizeComparablePath(threadCwd) !== normalizeComparablePath(cwd)) {
+            continue;
+        }
+        if (entry.parentThreadId !== null && entry.parentThreadId !== undefined)
+            continue;
+        if (entry.canAcceptDirectInput === false)
+            continue;
+        const status = isRecord(entry.status) ? entry.status.type : undefined;
+        if (typeof status !== "string" || status === "notLoaded")
+            continue;
+        const originator = typeof entry.originator === "string" ? entry.originator : null;
+        if (originator === "wechat-bridge")
+            continue;
+        const updatedAt = typeof entry.updatedAt === "number"
+            ? entry.updatedAt
+            : typeof entry.lastUpdatedAt === "number"
+                ? entry.lastUpdatedAt
+                : 0;
+        candidates.push({ id, updatedAt, originator });
+    }
+    return candidates.sort((left, right) => right.updatedAt - left.updatedAt);
+}
+/**
+ * Resume params for the bridge's app-server client. In daemon-attach mode the
+ * thread already has an owner with its own settings; sending cwd/approval/
+ * sandbox overrides would rewrite the shared thread's settings
+ * (`thread/settings/updated`), so attach mode resumes without overrides.
+ */
+export function buildCodexThreadResumeParams(params) {
+    if (params.attachDaemon) {
+        return { threadId: params.threadId, excludeTurns: true };
+    }
+    return {
+        threadId: params.threadId,
+        cwd: params.cwd,
+        approvalPolicy: "on-request",
+        approvalsReviewer: "user",
+        sandbox: "workspace-write",
+        excludeTurns: true,
+    };
+}
+/** Turn params; daemon-attach mode inherits the thread's existing settings. */
+export function buildCodexTurnStartParams(params) {
+    const input = [{ type: "text", text: params.text }];
+    if (params.attachDaemon) {
+        return { threadId: params.threadId, input };
+    }
+    return {
+        threadId: params.threadId,
+        cwd: params.cwd,
+        approvalPolicy: "on-request",
+        approvalsReviewer: "user",
+        input,
+    };
+}
 const { CODEX_APP_SERVER_HOST, CODEX_APP_SERVER_READY_TIMEOUT_MS, CODEX_FINAL_REPLY_SETTLE_DELAY_MS, CODEX_RECENT_SESSION_KEY_LIMIT, CODEX_RPC_CONNECT_RETRY_MS, CODEX_RPC_RECONNECT_TIMEOUT_MS, CODEX_SESSION_FALLBACK_SCAN_INTERVAL_MS, CODEX_SESSION_LOCAL_MIRROR_FALLBACK_WINDOW_MS, CODEX_SESSION_POLL_INTERVAL_MS, CODEX_STARTUP_WARMUP_MS, CODEX_THREAD_SIGNAL_TTL_MS, INTERRUPT_SETTLE_DELAY_MS, appendBoundedLog, buildCodexApprovalRequest, buildCodexCliArgs, buildCodexDynamicToolCallFailureResponse, buildCodexMcpServerElicitationDeclineResponse, buildCodexPermissionsRequestApprovalResponse, buildCodexUserInputRequest, coerceWebSocketMessageData, delay, describeUnknownError, extractCodexFinalTextFromItem, extractCodexThreadFollowIdFromStatusChanged, extractCodexThreadStartedThreadId, extractCodexUserMessageText, findCodexSessionFile, findRecentCodexSessionFileForCwd, getCodexRpcRequestId, getCodexApprovalAutoResponse, getCodexWechatOutboundAttachmentDenyMessage, getNotificationThreadId, getNotificationTurnId, isRecord, isRecentIsoTimestamp, listCodexResumeSessions, normalizeComparablePath, normalizeCodexRpcError, reserveLocalPort, resolveSpawnTarget, shouldAutoCompleteCodexWechatTurnAfterFinalReply, shouldIgnoreCodexSessionReplayEntry, shouldRecoverCodexStaleBusyState, waitForTcpPort, } = shared;
 const CODEX_LOCAL_THREAD_ANNOUNCE_SETTLE_MS = 150;
 const CODEX_NON_BLOCKING_USER_INPUT_TIMEOUT_MS = 120_000;
@@ -157,6 +240,11 @@ export class CodexPtyAdapter extends AbstractPtyAdapter {
         this.resumeThreadId = options.sessionStartMode === "new"
             ? null
             : options.initialSharedSessionId ?? options.initialSharedThreadId ?? null;
+        if (options.codexAttachDaemon) {
+            // Daemon attach binds an explicit (or discovered) live thread; stale
+            // persisted session ids must not leak into the attach target.
+            this.resumeThreadId = options.codexAttachThreadId?.trim() || null;
+        }
         if (this.resumeThreadId && options.renderMode !== "panel") {
             this.state.sharedSessionId = this.resumeThreadId;
             this.state.sharedThreadId = this.resumeThreadId;
@@ -176,6 +264,10 @@ export class CodexPtyAdapter extends AbstractPtyAdapter {
                 : `outside-supported-range=${this.codexCliVersion}`
             : "unknown-version";
         this.setStatus("starting", `Codex protocol compatibility: ${compatibility}.`);
+        if (this.options.codexAttachDaemon) {
+            await this.startDaemonAttach();
+            return;
+        }
         await this.startAppServer();
         await this.connectRpcClient();
         try {
@@ -284,8 +376,56 @@ export class CodexPtyAdapter extends AbstractPtyAdapter {
         if (!this.isHeadlessRuntimeMode()) {
             throw new Error('WeChat /resume requires the managed "wechat-codex" visible client.');
         }
+        if (this.options.codexAttachDaemon) {
+            await this.resumeDaemonAttachedThread(threadId);
+            return;
+        }
         await this.resumeVisibleSharedThread(threadId);
     }
+    /**
+     * WeChat /resume in daemon-attach mode: rejoin another thread on the shared
+     * daemon. Live threads rejoin in place; cold threads are loaded by the
+     * daemon (the bridge never becomes the rollout writer for an embedded
+     * desktop session — that resume fails with an active-writer error).
+     */
+    async resumeDaemonAttachedThread(threadId) {
+        const trimmedThreadId = threadId.trim();
+        if (!trimmedThreadId) {
+            throw new Error("A thread id is required to resume a Codex thread.");
+        }
+        if (this.pendingApproval) {
+            throw new Error(t("adapter.codex.approvalPending"));
+        }
+        if (this.pendingTurnStart ||
+            this.activeTurn ||
+            this.state.status === "busy" ||
+            this.state.status === "awaiting_approval") {
+            throw new Error(t("adapter.codex.busy"));
+        }
+        const response = await this.sendRpcRequest("thread/resume", buildCodexThreadResumeParams({
+            threadId: trimmedThreadId,
+            cwd: this.options.cwd,
+            attachDaemon: true,
+        }));
+        this.validateCodexResumeThread(response, trimmedThreadId);
+        if (isRecord(response) && isRecord(response.thread) && typeof response.thread.path === "string") {
+            this.sessionFilePath = response.thread.path;
+        }
+        const previousThreadId = this.sharedThreadId;
+        this.subscribedThreadIds.add(trimmedThreadId);
+        this.sessionReadOffset = 0;
+        this.sessionPartialLine = "";
+        this.sessionFinalText = null;
+        this.pendingThreadFollowId = null;
+        this.updateSharedThread(trimmedThreadId, {
+            source: "wechat",
+            reason: "wechat_resume",
+            notify: true,
+        });
+        if (previousThreadId && previousThreadId !== trimmedThreadId) {
+            await this.unsubscribeCodexThreadBestEffort(previousThreadId);
+        }
+    }
     async listModels() {
         if (!this.usesRpcTurnTransport() || !this.sharedThreadId) {
             throw new Error(t("adapter.codex.modelThreadRequired"));
@@ -564,6 +704,9 @@ export class CodexPtyAdapter extends AbstractPtyAdapter {
     }
     isCodexClientRunning() {
         if (this.isHeadlessRuntimeMode()) {
+            if (this.options.codexAttachDaemon) {
+                return Boolean(this.rpcSocket);
+            }
             return Boolean(this.appServer);
         }
         return this.isNativePanelMode() ? Boolean(this.nativeProcess) : Boolean(this.pty);
@@ -1082,18 +1225,12 @@ export class CodexPtyAdapter extends AbstractPtyAdapter {
         this.state.activeTurnOrigin = "wechat";
         this.setStatus("busy");
         try {
-            const response = await this.sendRpcRequest("turn/start", {
+            const response = await this.sendRpcRequest("turn/start", buildCodexTurnStartParams({
                 threadId,
+                text,
                 cwd: this.options.cwd,
-                approvalPolicy: "on-request",
-                approvalsReviewer: "user",
-                input: [
-                    {
-                        type: "text",
-                        text,
-                    },
-                ],
-            });
+                attachDaemon: Boolean(this.options.codexAttachDaemon),
+            }));
             const turnId = this.extractTurnIdFromResponse(response);
             if (!turnId) {
                 throw new Error("Codex did not return a turn id for the requested turn.");
@@ -1147,6 +1284,178 @@ export class CodexPtyAdapter extends AbstractPtyAdapter {
         this.armInterruptFallback();
         return true;
     }
+    /**
+     * Daemon-attach mode: instead of spawning an owned app-server, join the
+     * shared Codex app-server daemon (codex >= 0.162) as an additional client
+     * and rebind the bridge to a live thread in this workspace. The daemon and
+     * the owning TUI keep their lifecycle; the bridge is a guest connection.
+     */
+    async startDaemonAttach() {
+        this.setStatus("starting", "Attaching to the shared Codex app-server daemon...");
+        await this.connectDaemonRpcClient();
+        try {
+            await this.attachDaemonThread();
+        }
+        catch (error) {
+            await this.disconnectRpcClient();
+            throw error;
+        }
+        this.shuttingDown = false;
+        this.cleanPanelExitInProgress = false;
+        this.hasAcceptedInput = true;
+        this.state.startedAt = nowIso();
+        this.state.pendingApproval = null;
+        this.afterStart();
+        this.setStatus("idle", "Attached to the live Codex daemon session.");
+    }
+    async connectDaemonRpcClient() {
+        if (this.rpcSocket) {
+            return;
+        }
+        const socket = await this.openDaemonRpcSocket();
+        this.attachRpcSocket(socket);
+        await this.initializeRpcClient();
+    }
+    async openDaemonRpcSocket() {
+        const socketPath = resolveCodexDaemonControlSocketPath();
+        if (!fs.existsSync(socketPath)) {
+            throw new Error(`No shared Codex app-server daemon socket at ${socketPath}. Attach mode requires Codex >= 0.162 with its shared background server (the default). Sessions started with --no-daemon, --oss, or a --profile, and desktop-app embedded sessions, cannot be attached.`);
+        }
+        return await new Promise((resolve, reject) => {
+            // ws 8.22 ignores the `agent` option and installs its own TCP
+            // createConnection; passing createConnection at the top level is
+            // forwarded to http.request and takes precedence, which is how the
+            // Unix control socket is dialed.
+            const socket = new WsPackageWebSocket("ws://localhost/", {
+                createConnection: () => net.connect(socketPath),
+            });
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                try {
+                    socket.close();
+                }
+                catch {
+                    // Best effort cleanup after timeout.
+                }
+                reject(new Error(`Timed out connecting to the Codex daemon socket ${socketPath}.`));
+            }, CODEX_APP_SERVER_READY_TIMEOUT_MS);
+            const cleanup = () => {
+                clearTimeout(timer);
+            };
+            socket.once("open", () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                resolve(socket);
+            });
+            socket.once("error", (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                reject(new Error(`Failed to connect to the Codex daemon socket ${socketPath}: ${String(error)}`));
+            });
+        });
+    }
+    /**
+     * Bind the bridge to a live daemon thread. An explicit thread id wins;
+     * otherwise the newest live interactive thread in the workspace cwd is
+     * selected. `thread/resume` on a running thread rejoins it (history plus a
+     * live subscription) without taking the rollout writer lock, which stays
+     * with the owning client.
+     */
+    async attachDaemonThread() {
+        const targetThreadId = this.resumeThreadId ?? await this.discoverDaemonAttachThreadId();
+        this.setStatus("starting", `Attaching Codex daemon thread ${targetThreadId.slice(0, 12)}...`);
+        const response = await this.sendRpcRequest("thread/resume", buildCodexThreadResumeParams({
+            threadId: targetThreadId,
+            cwd: this.options.cwd,
+            attachDaemon: true,
+        }));
+        const resumedThreadId = this.extractThreadIdFromResponse(response);
+        if (!resumedThreadId) {
+            throw new Error("Codex daemon did not confirm the attached thread id.");
+        }
+        if (resumedThreadId !== targetThreadId) {
+            throw new Error(`Codex daemon opened ${resumedThreadId}, expected ${targetThreadId}.`);
+        }
+        this.validateCodexThreadWorkspaceIfPresent(response, resumedThreadId);
+        if (isRecord(response) && isRecord(response.thread) && typeof response.thread.path === "string") {
+            this.sessionFilePath = response.thread.path;
+        }
+        this.subscribedThreadIds.add(resumedThreadId);
+        this.resumeThreadId = null;
+        this.updateSharedThread(resumedThreadId, {
+            source: "restore",
+            reason: "startup_restore",
+            notify: true,
+        });
+    }
+    async discoverDaemonAttachThreadId() {
+        const response = await this.sendRpcRequest("thread/list", {
+            limit: 50,
+            sortKey: "updated_at",
+            sortDirection: "desc",
+            sourceKinds: ["cli", "vscode"],
+            archived: false,
+            cwd: this.options.cwd,
+        });
+        const candidates = selectCodexDaemonAttachCandidates(response, this.options.cwd);
+        if (candidates.length === 0) {
+            throw new Error(`No live Codex daemon session found for ${this.options.cwd}. Open codex (>= 0.162, default shared-server mode) in this directory, then retry. Embedded sessions (desktop app, --no-daemon, --oss, --profile) cannot be attached.`);
+        }
+        if (candidates.length > 1) {
+            const listed = candidates
+                .slice(0, 5)
+                .map((candidate) => candidate.id.slice(0, 8))
+                .join(", ");
+            this.setStatus("starting", `Multiple live Codex daemon sessions for ${this.options.cwd}; attaching the newest (${listed}).`);
+        }
+        return candidates[0].id;
+    }
+    /** Reconnect after the daemon socket dropped unexpectedly. */
+    async reconnectDaemonRpcClient() {
+        const reconnectDeadline = Date.now() + CODEX_RPC_RECONNECT_TIMEOUT_MS;
+        let lastError = "Codex daemon connection closed.";
+        while (!this.shuttingDown &&
+            !this.cleanPanelExitInProgress &&
+            Date.now() < reconnectDeadline) {
+            try {
+                await this.connectDaemonRpcClient();
+                // The daemon may have restarted; rejoin the bound thread. Cold threads
+                // are reloaded from disk, so this also recovers after daemon restarts.
+                if (this.state.sharedThreadId) {
+                    await this.ensureSharedThreadSubscribed(this.state.sharedThreadId);
+                }
+                return true;
+            }
+            catch (error) {
+                lastError = describeUnknownError(error);
+                await delay(CODEX_RPC_CONNECT_RETRY_MS);
+            }
+        }
+        if (shouldSuppressCodexTransportFatalError({
+            transportShuttingDown: this.rpcShuttingDown,
+            shuttingDown: this.shuttingDown,
+            cleanPanelExitInProgress: this.cleanPanelExitInProgress,
+        })) {
+            return false;
+        }
+        this.emit({
+            type: "fatal_error",
+            message: `Lost the connection to the shared Codex app-server daemon (${this.lastRpcCloseDetail || lastError}). The attached session may have closed; restart the attach bridge.`,
+            timestamp: nowIso(),
+        });
+        this.terminateCodexClient();
+        return false;
+    }
     async startAppServer() {
         if (this.appServer) {
             return;
@@ -1398,6 +1707,9 @@ export class CodexPtyAdapter extends AbstractPtyAdapter {
             })) {
                 return false;
             }
+            if (this.options.codexAttachDaemon) {
+                return await this.reconnectDaemonRpcClient();
+            }
             if (!this.appServer || !this.appServerPort) {
                 if (shouldSuppressCodexTransportFatalError({
                     transportShuttingDown: this.appServerShuttingDown,
@@ -1539,14 +1851,11 @@ export class CodexPtyAdapter extends AbstractPtyAdapter {
         if (this.subscribedThreadIds.has(threadId)) {
             return;
         }
-        const response = await this.sendRpcRequest("thread/resume", {
+        const response = await this.sendRpcRequest("thread/resume", buildCodexThreadResumeParams({
             threadId,
             cwd: this.options.cwd,
-            approvalPolicy: "on-request",
-            approvalsReviewer: "user",
-            sandbox: "workspace-write",
-            excludeTurns: true,
-        });
+            attachDaemon: Boolean(this.options.codexAttachDaemon),
+        }));
         const resumedThreadId = this.extractThreadIdFromResponse(response);
         if (!resumedThreadId) {
             throw new Error("Codex did not return a thread id while subscribing the bridge client.");

package/dist/bridge/bridge-state.js

@@ -85,7 +85,9 @@ export function normalizeBridgeLockPayload(value) {
         startedAt: record.startedAt,
         lifecycle: record.lifecycle === "companion_bound" ? "companion_bound" : "persistent",
         legacyLifecycleFallback: hasExplicitLifecycle ? undefined : true,
-        ...(record.channelId === "wechat" || record.channelId === "wecom"
+        ...(record.channelId === "wechat" ||
+            record.channelId === "wecom" ||
+            record.channelId === "telegram"
             ? { channelId: record.channelId }
             : {}),
     };

package/dist/bridge/wechat-bridge.js

@@ -28,10 +28,15 @@ import { forwardBridgeEvent } from "../core/bridge-event-forwarder.js";
 import { isDirectModuleRun } from "../core/direct-run.js";
 import { WechatChannelPort } from "../channels/wechat/wechat-channel-port.js";
 import { ensureWecomAccount } from "../channels/wecom/setup.js";
+import { ensureTelegramAccount } from "../channels/telegram/setup.js";
+import { TelegramTransport } from "../channels/telegram/telegram-transport.js";
+import { TelegramChannelDriver } from "../channels/telegram/telegram-driver.js";
+import { TelegramChannelPort } from "../channels/telegram/telegram-channel-port.js";
 import { WecomChannelPort } from "../channels/wecom/wecom-channel-port.js";
 import { WecomTransport } from "../channels/wecom/wecom-transport.js";
 import { WecomChannelDriver } from "../channels/wecom/wecom-driver.js";
 import { WechatChannelDriver } from "../channels/wechat/wechat-driver.js";
+import { isBridgeChannelId } from "../core/channel-types.js";
 import { buildWechatInboundPrompt, buildOneTimeCode, formatApprovalMessage, formatPendingApprovalReminder, formatPendingUserInputReminder, formatDuration, formatMirroredUserInputMessage, formatSessionSwitchMessage, formatStatusReport, formatTaskFailedMessage, formatThinkingForWechat, formatUserInputRequestMessage, MESSAGE_START_GRACE_MS, nowIso, OutputBatcher, parsePendingUserInputAnswerCommand, parseWechatControlCommand, truncatePreview, } from "./bridge-utils.js";
 import { classifyWechatTransportError, DEFAULT_LONG_POLL_TIMEOUT_MS, WeChatTransport, describeWechatTransportError, } from "../wechat/wechat-transport.js";
 import { getPendingChannelMessagesFile, getPendingWechatMessagesFile, PendingWechatMessageStore, } from "../channels/wechat/wechat-outbound-queue.js";
@@ -100,6 +105,8 @@ export function parseCliArgs(argv) {
     let lifecycle = "persistent";
     let sessionStartMode = "restore";
     let channelId = "wechat";
+    let codexAttachDaemon = false;
+    let codexAttachThreadId;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         const next = argv[i + 1];
@@ -147,7 +154,7 @@ export function parseCliArgs(argv) {
                 i += 1;
                 break;
             case "--channel":
-                if (!next || (next !== "wechat" && next !== "wecom")) {
+                if (!isBridgeChannelId(next) || next === "local") {
                     throw new Error(`Invalid channel: ${next ?? "(missing)"}`);
                 }
                 channelId = next;
@@ -156,6 +163,16 @@ export function parseCliArgs(argv) {
             case "--shutdown-on-parent-exit":
                 lifecycle = "companion_bound";
                 break;
+            case "--codex-attach-daemon":
+                codexAttachDaemon = true;
+                break;
+            case "--codex-thread-id":
+                if (!next) {
+                    throw new Error("--codex-thread-id requires a value");
+                }
+                codexAttachThreadId = next;
+                i += 1;
+                break;
             case "--help":
             case "-h":
                 printUsageAndExit();
@@ -167,6 +184,9 @@ export function parseCliArgs(argv) {
     if (!adapter) {
         throw new Error("Missing required --adapter <codex|claude|opencode|pi>");
     }
+    if (codexAttachDaemon && adapter !== "codex") {
+        throw new Error("--codex-attach-daemon requires --adapter codex");
+    }
     const defaultCommand = resolveDefaultAdapterCommand(adapter);
     return {
         adapter,
@@ -176,6 +196,8 @@ export function parseCliArgs(argv) {
         lifecycle,
         sessionStartMode,
         channelId,
+        codexAttachDaemon,
+        codexAttachThreadId,
     };
 }
 function toWechatSendContext(kind) {
@@ -207,7 +229,7 @@ function toLegacyInboundWechatMessage(message) {
 function printUsageAndExit() {
     process.stdout.write([
         "Internal bridge runtime usage:",
-        "  npm run bridge -- --adapter <codex|claude|opencode|pi> [--cmd <executable>] [--cwd <path>] [--profile <name-or-path>] [--lifecycle <persistent|companion_bound>] [--session-start-mode <restore|new>]",
+        "  npm run bridge -- --adapter <codex|claude|opencode|pi> [--cmd <executable>] [--cwd <path>] [--profile <name-or-path>] [--lifecycle <persistent|companion_bound>] [--session-start-mode <restore|new>] [--codex-attach-daemon [--codex-thread-id <id>]]",
         "",
         "This entry is internal. Users should run a wechat-* or wecom-* launcher.",
         "",
@@ -232,17 +254,24 @@ async function main() {
     const wecomAccount = options.channelId === "wecom"
         ? await ensureWecomAccount({ log })
         : null;
+    const telegramAccount = options.channelId === "telegram"
+        ? await ensureTelegramAccount({ log })
+        : null;
     const credentials = wecomAccount
         ? { userId: wecomAccount.operatorUserId }
-        : await ensureWechatCredentials({
-            requireUserId: true,
-            validateExisting: true,
-            log,
-        });
+        : telegramAccount
+            ? { userId: telegramAccount.operatorUserId }
+            : await ensureWechatCredentials({
+                requireUserId: true,
+                validateExisting: true,
+                log,
+            });
     if (!credentials.userId) {
         throw new Error(options.channelId === "wecom"
             ? "Saved WeCom credentials are missing operatorUserId."
-            : "Saved WeChat credentials are missing userId.");
+            : options.channelId === "telegram"
+                ? "Saved Telegram credentials are missing operatorUserId."
+                : "Saved WeChat credentials are missing userId.");
     }
     const transport = new WeChatTransport({ log, logError });
     const wecomTransport = wecomAccount
@@ -254,6 +283,15 @@ async function main() {
             },
         })
         : null;
+    const telegramTransport = telegramAccount
+        ? new TelegramTransport({
+            account: telegramAccount,
+            logger: {
+                log: (message) => log(message),
+                error: (message) => logError(message),
+            },
+        })
+        : null;
     const channelDriver = wecomTransport
         ? new WecomChannelDriver({
             transport: wecomTransport,
@@ -261,11 +299,18 @@ async function main() {
             operatorId: credentials.userId,
             logError,
         })
-        : new WechatChannelDriver({
-            transport,
-            logError,
-            buildInboundPrompt: (text, attachments) => buildWechatInboundPrompt(text, attachments.filter((attachment) => attachment.kind === "image" || attachment.kind === "file")),
-        });
+        : telegramTransport
+            ? new TelegramChannelDriver({
+                transport: telegramTransport,
+                accountId: telegramAccount?.botUsername,
+                operatorId: credentials.userId,
+                logError,
+            })
+            : new WechatChannelDriver({
+                transport,
+                logError,
+                buildInboundPrompt: (text, attachments) => buildWechatInboundPrompt(text, attachments.filter((attachment) => attachment.kind === "image" || attachment.kind === "file")),
+            });
     // 非阻塞地检查更新（不影响启动速度，也避免首次登录时打断二维码输出）
     // unref：不能让这个延迟检查把 event loop 挂活（如 --doctor 或快速退出场景），
     // 否则会与强制退出 teardown 竞态。
@@ -327,9 +372,15 @@ async function main() {
         profile: options.profile,
         lifecycle: options.lifecycle,
         sessionStartMode: options.sessionStartMode,
-        initialSharedSessionId: stateStore.getState().sharedSessionId ?? stateStore.getState().sharedThreadId,
+        // Daemon attach binds an explicit or discovered live thread; a stale
+        // persisted session id must not leak into the attach target.
+        initialSharedSessionId: options.codexAttachDaemon
+            ? options.codexAttachThreadId
+            : stateStore.getState().sharedSessionId ?? stateStore.getState().sharedThreadId,
         initialResumeConversationId: stateStore.getState().resumeConversationId,
         initialTranscriptPath: stateStore.getState().transcriptPath,
+        codexAttachDaemon: options.codexAttachDaemon,
+        codexAttachThreadId: options.codexAttachThreadId,
     });
     const pendingWechatMessages = new PendingWechatMessageStore(options.channelId === "wechat"
         ? getPendingWechatMessagesFile(options.cwd)
@@ -416,8 +467,8 @@ async function main() {
     const trackWechatForwardTask = (task) => {
         const tracked = task
             .catch((error) => {
-            logError(`WeChat forward task failed: ${describeWechatTransportError(error)}`);
-            stateStore.appendLog(`wechat_forward_failed: error=${truncatePreview(describeWechatTransportError(error), 400)}`);
+            logError(`${channelDriver.displayName} forward task failed: ${describeWechatTransportError(error)}`);
+            stateStore.appendLog(`${channelDriver.id}_forward_failed: error=${truncatePreview(describeWechatTransportError(error), 400)}`);
         })
             .finally(() => {
             pendingWechatForwardTasks.delete(tracked);
@@ -663,6 +714,7 @@ async function main() {
             },
             requestShutdown,
             wecomTransport,
+            telegramTransport,
             getWecomTarget: () => turns.resolveTarget(operatorConversation),
         });
         await adapter.start();
@@ -957,28 +1009,43 @@ function syncSharedSessionState(stateStore, adapter) {
     }
 }
 export function wireAdapterEvents(params) {
-    const { adapter, channelDriver, resumeCoordinator, options, transport, stateStore, outputBatcher, queueWechatAttachmentAction, queueWechatMessage, trackWechatForwardTask, maybeDrainDeferredInboundMessages, getActiveTask, clearActiveTask, syncSharedSessionState, syncLocalClientEndpoint, requestShutdown, wecomTransport, getWecomTarget, } = params;
-    const channelPort = options.channelId === "wecom"
-        ? new WecomChannelPort({
-            transport: wecomTransport,
-            sendText: (target, text, kind) => queueWechatMessage(stateStore.getState().authorizedUserId, text, toWechatSendContext(kind), target),
-            onEmptyVisibleReply: (adapter, rawText) => {
-                stateStore.appendLog(`empty_visible_final_reply: adapter=${adapter ?? options.adapter} raw=${truncatePreview(rawText)}`);
-            },
-        })
-        : new WechatChannelPort({
+    const { adapter, channelDriver, resumeCoordinator, options, transport, stateStore, outputBatcher, queueWechatAttachmentAction, queueWechatMessage, trackWechatForwardTask, maybeDrainDeferredInboundMessages, getActiveTask, clearActiveTask, syncSharedSessionState, syncLocalClientEndpoint, requestShutdown, wecomTransport, telegramTransport, getWecomTarget, } = params;
+    const remotePortCallbacks = {
+        sendText: (target, text, kind) => queueWechatMessage(stateStore.getState().authorizedUserId, text, toWechatSendContext(kind), target),
+        onEmptyVisibleReply: (adapter, rawText) => {
+            stateStore.appendLog(`empty_visible_final_reply: adapter=${adapter ?? options.adapter} raw=${truncatePreview(rawText)}`);
+        },
+    };
+    // Every remote channel must provide its own port; never fall back to WeChat.
+    const portFactories = {
+        wecom: () => {
+            if (!wecomTransport) {
+                throw new Error("The wecom channel port requires a WeCom transport.");
+            }
+            return new WecomChannelPort({ transport: wecomTransport, ...remotePortCallbacks });
+        },
+        telegram: () => {
+            if (!telegramTransport) {
+                throw new Error("The telegram channel port requires a Telegram transport.");
+            }
+            return new TelegramChannelPort({ transport: telegramTransport, ...remotePortCallbacks });
+        },
+        wechat: () => new WechatChannelPort({
             sendText: (recipientId, text, context) => queueWechatMessage(recipientId, text, context),
             sendImage: (recipientId, filePath) => queueWechatAttachmentAction(() => transport.sendImage(filePath, { recipientId })),
             sendFile: (recipientId, filePath) => queueWechatAttachmentAction(() => transport.sendFile(filePath, { recipientId })),
             sendVoice: (recipientId, filePath) => queueWechatAttachmentAction(() => transport.sendVoice(filePath, recipientId)),
             sendVideo: (recipientId, filePath) => queueWechatAttachmentAction(() => transport.sendVideo(filePath, { recipientId })),
-            onEmptyVisibleReply: (adapter, rawText) => {
-                stateStore.appendLog(`empty_visible_final_reply: adapter=${adapter ?? options.adapter} raw=${truncatePreview(rawText)}`);
-            },
+            onEmptyVisibleReply: remotePortCallbacks.onEmptyVisibleReply,
             onTextSent: (_adapter, text) => {
                 stateStore.appendLog(`final_reply_sent: chars=${Array.from(text).length}`);
             },
-        });
+        }),
+    };
+    if (options.channelId === "local") {
+        throw new Error("The local channel does not support standalone bridge output.");
+    }
+    const channelPort = portFactories[options.channelId]();
     let lastFinalReplyAtMs = 0;
     let eventForwardChain = Promise.resolve();
     adapter.setEventSink((event) => {