cli-wechat-bridge 1.1.2 → 1.1.4

package/dist/bridge/wechat-bridge.js

@@ -5,11 +5,12 @@ import { delay } from "./bridge-adapters.shared.js";
 import { t } from "../i18n/index.js";
 import { BridgeController } from "./bridge-controller.js";
 import { forwardWechatFinalReply } from "./bridge-final-reply.js";
+import { WECHAT_SEND_MAX_ATTEMPTS, computeWechatSendRetryDelayMs, formatUserFacingBridgeFatalError, formatUserFacingInboundError, formatWechatContextTokenStaleLogEntry, formatWechatSendFailureLogEntry, formatWechatSendRetryLogEntry, isRetryableWechatSendError, shouldForwardBridgeEventToWechat, } from "./wechat-forwarding.js";
 import { ensureWechatCredentials } from "../wechat/setup.js";
 import { BridgeStateStore } from "./bridge-state.js";
-import { reapOrphanedOpencodeProcesses, reapPeerBridgeProcesses } from "./bridge-process-reaper.js";
+import { getProcessRecordByPid, reapOrphanedOpencodeProcesses, reapPeerBridgeProcesses, } from "./bridge-process-reaper.js";
 import { createRuntimeHost } from "../runtime/create-runtime-host.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 { buildWechatInboundPrompt, buildOneTimeCode, formatApprovalMessage, formatPendingApprovalReminder, formatPendingUserInputReminder, formatDuration, formatMirroredUserInputMessage, formatResumeSessionList, 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, isWechatContextTokenStaleError, } from "../wechat/wechat-transport.js";
 import { checkForUpdate, formatUpdateMessage, } from "../utils/version-checker.js";
 import { clearDaemonEndpoint, isDaemonEndpointAlive, readDaemonEndpoint, } from "../daemon/daemon-link.js";
@@ -17,8 +18,11 @@ import { formatBindCommandUsage, formatBindingsListMessage, isBindCommandPrefix,
 const POLL_RETRY_BASE_MS = 1_000;
 const POLL_RETRY_MAX_MS = 30_000;
 const PARENT_PROCESS_POLL_MS = 5_000;
-const WECHAT_SEND_MAX_ATTEMPTS = 3;
-const WECHAT_SEND_RETRY_BASE_MS = 750;
+// Hard ceiling for the whole shutdown cleanup sequence before a forced exit.
+const SHUTDOWN_FORCE_EXIT_TIMEOUT_MS = 10_000;
+// Re-verify the parent's command line every N polls (5s each → ~60s) to keep
+// the full-process probe off the hot path.
+const PARENT_IDENTITY_CHECK_INTERVAL = 12;
 function log(message) {
     process.stderr.write(`[wechat-bridge] ${message}\n`);
 }
@@ -42,63 +46,6 @@ function isPidAlive(pid) {
         return false;
     }
 }
-export function formatUserFacingBridgeFatalError(message) {
-    return `Bridge error: ${message.replace(/\s+Recent app-server log:.*$/s, "").trim()}`;
-}
-export function shouldForwardBridgeEventToWechat(adapter, eventType, options = {}) {
-    if (adapter !== "opencode") {
-        return true;
-    }
-    switch (eventType) {
-        case "stdout":
-        case "stderr":
-        case "thread_switched":
-            return false;
-        case "notice":
-            return /^OpenCode local draft:\s*/i.test(options.text ?? "");
-        case "mirrored_user_input":
-            return true;
-        default:
-            return true;
-    }
-}
-export function formatUserFacingInboundError(params) {
-    const { adapter, cwd, errorText, isUserFacingShellRejection } = params;
-    if (isUserFacingShellRejection) {
-        return errorText;
-    }
-    if (adapter === "opencode" &&
-        /opencode companion is not connected/i.test(errorText)) {
-        return cwd
-            ? `OpenCode companion is not connected for bridge workspace:\n${cwd}\nRun "wechat-opencode" in that directory to reconnect the current local terminal, or run "wechat-bridge-opencode" and then "wechat-opencode" in your target project to replace this bridge.`
-            : 'OpenCode companion is not connected. Start "wechat-opencode" in this directory to reconnect it, then retry.';
-    }
-    return `Bridge error: ${errorText}`;
-}
-export function formatWechatSendFailureLogEntry(params) {
-    return `wechat_send_failed: context=${params.context} recipient=${params.recipientId} error=${truncatePreview(describeWechatTransportError(params.error), 400)}`;
-}
-export function formatWechatContextTokenStaleLogEntry(params) {
-    return `wechat_context_token_stale: context=${params.context} recipient=${params.recipientId} action=wechat_message_required error=${truncatePreview(describeWechatTransportError(params.error), 400)}`;
-}
-function formatWechatSendRetryLogEntry(params) {
-    return `wechat_send_retry: context=${params.context} recipient=${params.recipientId} attempt=${params.attempt} delay_ms=${params.delayMs} error=${truncatePreview(describeWechatTransportError(params.error), 400)}`;
-}
-export function isRetryableWechatSendError(error) {
-    if (isWechatContextTokenStaleError(error)) {
-        return false;
-    }
-    const classification = classifyWechatTransportError(error);
-    if (classification.retryable) {
-        return true;
-    }
-    const details = describeWechatTransportError(error);
-    return /^(?:Error|WechatApiResponseError): sendmessage failed:/i.test(details) &&
-        !/errcode=-14\b.*session timeout/i.test(details);
-}
-function computeWechatSendRetryDelayMs(attempt) {
-    return WECHAT_SEND_RETRY_BASE_MS * attempt;
-}
 export function shouldWatchParentProcess(options) {
     return (options.startupParentPid > 1 &&
         (options.attachedToTerminal || options.lifecycle === "companion_bound"));
@@ -159,7 +106,7 @@ export function parseCliArgs(argv) {
         const next = argv[i + 1];
         switch (arg) {
             case "--adapter":
-                if (!next || !["codex", "claude", "opencode", "shell"].includes(next)) {
+                if (!next || !["codex", "claude", "opencode", "pi"].includes(next)) {
                     throw new Error(`Invalid adapter: ${next ?? "(missing)"}`);
                 }
                 adapter = next;
@@ -212,7 +159,7 @@ export function parseCliArgs(argv) {
         }
     }
     if (!adapter) {
-        throw new Error("Missing required --adapter <codex|claude|opencode|shell>");
+        throw new Error("Missing required --adapter <codex|claude|opencode|pi>");
     }
     const defaultCommand = resolveDefaultAdapterCommand(adapter);
     return {
@@ -226,17 +173,10 @@ export function parseCliArgs(argv) {
 }
 function printUsageAndExit() {
     process.stdout.write([
-        "Usage: wechat-bridge --adapter <codex|claude|opencode|shell> [--cmd <executable>] [--cwd <path>] [--profile <name-or-path>] [--lifecycle <persistent|companion_bound>] [--session-start-mode <restore|new>]",
+        "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>]",
         "",
-        "Examples:",
-        "  wechat-bridge-codex",
-        "  wechat-bridge-claude --cwd ~/work/my-project",
-        "  wechat-bridge-opencode --cwd ~/work/my-project",
-        "  wechat-bridge-shell --cmd pwsh   # headless shell executor for non-interactive commands/scripts",
-        "  wechat-bridge-shell --cmd bash   # headless shell executor for non-interactive commands/scripts",
-        "  wechat-bridge-codex --lifecycle companion_bound",
-        "  bun run bridge:codex            # repo-local development entrypoint",
-        "  bun run bridge:opencode          # repo-local development entrypoint",
+        "This entry is internal. Users should run wechat-codex, wechat-claude, wechat-opencode, wechat-pi, or wechat-daemon.",
         "",
     ].join("\n"));
     process.exit(0);
@@ -338,8 +278,6 @@ async function main() {
     let activeTask = null;
     const deferredInboundMessages = [];
     let drainingDeferredInboundMessages = false;
-    let lastOutputAt = 0;
-    let lastHeartbeatAt = 0;
     let consecutivePollFailures = 0;
     let backlogNoticeSent = false;
     const queueWechatTextAction = (action) => {
@@ -446,7 +384,6 @@ async function main() {
                 adapter,
             });
             activeTask = nextTask;
-            lastHeartbeatAt = 0;
         }
         catch (err) {
             const errorText = err instanceof Error ? err.message : String(err);
@@ -461,7 +398,6 @@ async function main() {
                 adapter: options.adapter,
                 cwd: options.cwd,
                 errorText,
-                isUserFacingShellRejection: false,
             }), "inbound_error");
         }
         finally {
@@ -473,6 +409,10 @@ async function main() {
     let shutdownPromise = null;
     let requestedExitCode = 0;
     let stdinDetached = false;
+    // Snapshot of the parent process command line at bridge startup (null when
+    // unresolvable). Compared against periodic re-probes to detect OS pid reuse.
+    const parentStartupCommandLine = getProcessRecordByPid(startupParentPid)?.commandLine ?? null;
+    let parentWatchPollCount = 0;
     const parentWatchTimer = shouldWatchParentProcess({
         startupParentPid,
         attachedToTerminal,
@@ -480,6 +420,19 @@ async function main() {
     })
         ? setInterval(() => {
             if (shutdownPromise || isPidAlive(startupParentPid)) {
+                // Periodically re-verify the parent's command line so an OS pid
+                // reuse (dead parent's pid handed to an unrelated long-running
+                // process) cannot keep this companion-bound bridge alive forever.
+                parentWatchPollCount += 1;
+                if (parentWatchPollCount % PARENT_IDENTITY_CHECK_INTERVAL === 0) {
+                    const record = getProcessRecordByPid(startupParentPid);
+                    if (parentStartupCommandLine !== null &&
+                        record !== null &&
+                        record.commandLine !== parentStartupCommandLine) {
+                        log(`Parent pid ${startupParentPid} was reused by another process. Stopping bridge.`);
+                        void shutdown(0);
+                    }
+                }
                 return;
             }
             log(`Parent process ${startupParentPid} exited. Stopping bridge.`);
@@ -529,7 +482,17 @@ async function main() {
             return;
         }
         log(message);
-        void shutdown(exitCode).finally(() => process.exit(requestedExitCode));
+        // Bound the whole cleanup: a dispose that hangs (child process refusing
+        // to exit) would otherwise keep the process alive indefinitely after the
+        // one-shot signal handlers are consumed.
+        const forceExitTimer = setTimeout(() => {
+            logError(`Shutdown cleanup exceeded ${formatDuration(SHUTDOWN_FORCE_EXIT_TIMEOUT_MS)}; forcing exit.`);
+            process.exit(requestedExitCode);
+        }, SHUTDOWN_FORCE_EXIT_TIMEOUT_MS);
+        void shutdown(exitCode).finally(() => {
+            clearTimeout(forceExitTimer);
+            process.exit(requestedExitCode);
+        });
     };
     process.once("SIGINT", () => {
         requestShutdown("Received SIGINT. Stopping bridge.");
@@ -578,13 +541,8 @@ async function main() {
             queueWechatMessage,
             trackWechatForwardTask,
             maybeDrainDeferredInboundMessages,
-            getActiveTask: () => activeTask,
             clearActiveTask: () => {
                 activeTask = null;
-                lastHeartbeatAt = 0;
-            },
-            updateLastOutputAt: () => {
-                lastOutputAt = Date.now();
             },
             syncSharedSessionState: () => {
                 syncSharedSessionState(stateStore, adapter);
@@ -608,25 +566,33 @@ async function main() {
         }
         log(`Authorized WeChat user: ${credentials.userId}`);
         if (options.adapter === "codex") {
-            log('Start the visible Codex panel in a second terminal with: wechat-codex');
+            log("For source-mode debugging, open the visible Codex client with: npm run codex:panel");
         }
         else if (options.adapter === "opencode") {
-            log('Start the visible OpenCode companion in a second terminal with: wechat-opencode');
+            log("For source-mode debugging, open the visible OpenCode client with: npm run opencode:panel");
         }
         else if (options.adapter === "claude") {
-            log('Start the visible Claude companion in a second terminal with: wechat-claude');
+            log("For source-mode debugging, open the visible Claude client with: npm run claude:companion");
         }
-        else if (options.adapter === "shell") {
-            log("Shell mode runs as a headless remote executor for non-interactive commands and scripts.");
+        else if (options.adapter === "pi") {
+            log("For source-mode debugging, open the visible Pi client with: npm run pi:companion");
         }
         loadEmojiBindings();
+        // Keep the standalone bridge's WeChat welcome brief: command and emoji
+        // reference material belongs to /status and /bindings, which users can
+        // request on demand. The daemon sends its own, fuller welcome.
         const welcomeText = t("bridge.welcome", {
             adapter: options.adapter,
             cwd: options.cwd,
-            bindings: formatBindingsListMessage(listBindings()),
         });
         await queueWechatMessage(credentials.userId, welcomeText);
         while (true) {
+            if (shutdownPromise) {
+                // Shutdown (e.g. SIGINT) was requested while we were awaiting the
+                // previous poll: stop consuming inbound messages instead of racing
+                // the concurrent cleanup/dispose with new sends.
+                break;
+            }
             if (!ensureRuntimeOwnership()) {
                 break;
             }
@@ -653,7 +619,7 @@ async function main() {
                 await delay(delayMs);
                 continue;
             }
-            if (!ensureRuntimeOwnership()) {
+            if (shutdownPromise || !ensureRuntimeOwnership()) {
                 break;
             }
             if (consecutivePollFailures > 0) {
@@ -698,32 +664,20 @@ async function main() {
                 }
                 catch (err) {
                     const errorText = err instanceof Error ? err.message : String(err);
-                    const isUserFacingShellRejection = err instanceof Error && err.name === "ShellCommandRejectedError";
                     logError(errorText);
-                    stateStore.appendLog(`${isUserFacingShellRejection ? "inbound_rejected" : "inbound_error"}: ${errorText}`);
+                    stateStore.appendLog(`inbound_error: ${errorText}`);
                     await queueWechatMessage(message.senderId, formatUserFacingInboundError({
                         adapter: options.adapter,
                         cwd: options.cwd,
                         errorText,
-                        isUserFacingShellRejection,
                     }), "inbound_error");
                 }
                 if (nextTask) {
                     activeTask = nextTask;
-                    lastHeartbeatAt = 0;
                 }
                 syncSharedSessionState(stateStore, adapter);
                 await maybeDrainDeferredInboundMessages();
             }
-            const adapterState = adapter.getState();
-            const lastSignalAt = Math.max(lastHeartbeatAt, lastOutputAt || activeTask?.startedAt || 0);
-            if (activeTask &&
-                options.adapter === "shell" &&
-                adapterState.status === "busy" &&
-                Date.now() - lastSignalAt >= 30_000) {
-                lastHeartbeatAt = Date.now();
-                await queueWechatMessage(stateStore.getState().authorizedUserId, `${options.adapter} is still running. Waiting for more output...`);
-            }
         }
     }
     finally {
@@ -755,7 +709,7 @@ function syncSharedSessionState(stateStore, adapter) {
     }
 }
 function wireAdapterEvents(params) {
-    const { adapter, options, transport, stateStore, outputBatcher, queueWechatAttachmentAction, queueWechatMessage, trackWechatForwardTask, maybeDrainDeferredInboundMessages, getActiveTask, clearActiveTask, updateLastOutputAt, syncSharedSessionState, syncLocalClientEndpoint, requestShutdown, } = params;
+    const { adapter, options, transport, stateStore, outputBatcher, queueWechatAttachmentAction, queueWechatMessage, trackWechatForwardTask, maybeDrainDeferredInboundMessages, clearActiveTask, syncSharedSessionState, syncLocalClientEndpoint, requestShutdown, } = params;
     adapter.setEventSink((event) => {
         syncSharedSessionState();
         syncLocalClientEndpoint();
@@ -771,7 +725,6 @@ function wireAdapterEvents(params) {
         switch (event.type) {
             case "stdout":
             case "stderr":
-                updateLastOutputAt();
                 if (shouldForwardBridgeEventToWechat(options.adapter, event.type)) {
                     outputBatcher.push(event.text);
                 }
@@ -809,7 +762,6 @@ function wireAdapterEvents(params) {
                 void maybeDrainDeferredInboundMessages();
                 break;
             case "notice":
-                updateLastOutputAt();
                 stateStore.appendLog(`${event.level}_notice: ${truncatePreview(event.text)}`);
                 if (shouldForwardBridgeEventToWechat(options.adapter, event.type, { text: event.text })) {
                     trackWechatForwardTask(outputBatcher.flushNow().then(async () => {
@@ -818,7 +770,6 @@ function wireAdapterEvents(params) {
                 }
                 break;
             case "thinking":
-                updateLastOutputAt();
                 if (event.text) {
                     const thinkingPreview = formatThinkingForWechat(event.text, 500);
                     if (thinkingPreview) {
@@ -884,15 +835,6 @@ function wireAdapterEvents(params) {
                 trackWechatForwardTask(outputBatcher.flushNow().then(async () => {
                     stateStore.clearPendingConfirmation();
                     stateStore.clearPendingUserInput();
-                    if (options.adapter === "shell") {
-                        const summary = buildCompletionSummary({
-                            adapter: options.adapter,
-                            activeTask: getActiveTask(),
-                            exitCode: event.exitCode,
-                            recentOutput: outputBatcher.getRecentSummary(),
-                        });
-                        await queueWechatMessage(authorizedUserId, summary);
-                    }
                     clearActiveTask();
                     await maybeDrainDeferredInboundMessages();
                 }));
@@ -924,18 +866,6 @@ function wireAdapterEvents(params) {
         }
     });
 }
-function buildCompletionSummary(params) {
-    const lines = [`${params.adapter} task complete.`];
-    if (params.activeTask) {
-        lines.push(`duration: ${formatDuration(Date.now() - params.activeTask.startedAt)}`);
-        lines.push(`input: ${params.activeTask.inputPreview}`);
-    }
-    if (typeof params.exitCode === "number") {
-        lines.push(`exit_code: ${params.exitCode}`);
-    }
-    lines.push(`recent_output:\n${params.recentOutput}`);
-    return lines.join("\n");
-}
 function formatInboundMessagePreview(message) {
     if (message.text.trim()) {
         return message.text;
@@ -1005,7 +935,23 @@ async function handleInboundMessage(params) {
                 return null;
             }
             if (options.adapter === "opencode") {
-                await queueWechatMessage(message.senderId, 'WeChat /resume is disabled in opencode mode. Use /resume directly inside "wechat-opencode"; WeChat will follow the active local session.');
+                try {
+                    if (systemCommand.target) {
+                        await adapter.resumeSession(systemCommand.target);
+                        await queueWechatMessage(message.senderId, `Resumed OpenCode session ${systemCommand.target}.`);
+                    }
+                    else {
+                        const candidates = await adapter.listResumeSessions(8);
+                        await queueWechatMessage(message.senderId, formatResumeSessionList({
+                            adapter: options.adapter,
+                            candidates,
+                            currentSessionId: adapter.getState().sharedSessionId,
+                        }));
+                    }
+                }
+                catch (error) {
+                    await queueWechatMessage(message.senderId, `Failed to resume OpenCode session: ${error instanceof Error ? error.message : String(error)}`);
+                }
                 return null;
             }
             await queueWechatMessage(message.senderId, `/resume is not available in ${options.adapter} mode.`);
@@ -1122,9 +1068,9 @@ async function handleInboundMessage(params) {
         return null;
     }
     if (adapterState.status === "busy") {
-        if ((options.adapter === "codex" || options.adapter === "opencode") &&
+        if ((options.adapter === "codex" || options.adapter === "opencode" || options.adapter === "pi") &&
             adapterState.activeTurnOrigin === "local") {
-            await queueWechatMessage(message.senderId, `${options.adapter === "opencode" ? "OpenCode" : "codex"} is currently busy with a local terminal turn. Wait for it to finish or use /stop.`);
+            await queueWechatMessage(message.senderId, `${options.adapter === "opencode" ? "OpenCode" : options.adapter === "pi" ? "Pi" : "codex"} is currently busy with a local terminal turn. Wait for it to finish or use /stop.`);
             return null;
         }
         await queueWechatMessage(message.senderId, `${options.adapter} is still working. Wait for the current reply or use /stop.`);

package/dist/bridge/wechat-forwarding.js

@@ -0,0 +1,58 @@
+import { truncatePreview } from "./bridge-utils.js";
+import { classifyWechatTransportError, describeWechatTransportError, isWechatContextTokenStaleError, } from "../wechat/wechat-transport.js";
+export const WECHAT_SEND_MAX_ATTEMPTS = 3;
+const WECHAT_SEND_RETRY_BASE_MS = 750;
+export function formatUserFacingBridgeFatalError(message) {
+    return `Bridge error: ${message.replace(/\s+Recent app-server log:.*$/s, "").trim()}`;
+}
+export function shouldForwardBridgeEventToWechat(adapter, eventType, options = {}) {
+    if (adapter !== "opencode" && adapter !== "pi") {
+        return true;
+    }
+    switch (eventType) {
+        case "stdout":
+        case "stderr":
+        case "thread_switched":
+            return false;
+        case "notice":
+            return adapter === "pi" || /^OpenCode local draft:\s*/i.test(options.text ?? "");
+        case "mirrored_user_input":
+            return true;
+        default:
+            return true;
+    }
+}
+export function formatUserFacingInboundError(params) {
+    const { adapter, cwd, errorText } = params;
+    if (adapter === "opencode" &&
+        /opencode companion is not connected/i.test(errorText)) {
+        return cwd
+            ? `OpenCode is not connected for workspace:\n${cwd}\nRun "wechat-opencode" in that directory to recreate or reconnect the visible terminal.`
+            : 'OpenCode is not connected. Run "wechat-opencode" in this directory, then retry.';
+    }
+    return `Bridge error: ${errorText}`;
+}
+export function formatWechatSendFailureLogEntry(params) {
+    return `wechat_send_failed: context=${params.context} recipient=${params.recipientId} error=${truncatePreview(describeWechatTransportError(params.error), 400)}`;
+}
+export function formatWechatContextTokenStaleLogEntry(params) {
+    return `wechat_context_token_stale: context=${params.context} recipient=${params.recipientId} action=wechat_message_required error=${truncatePreview(describeWechatTransportError(params.error), 400)}`;
+}
+export function formatWechatSendRetryLogEntry(params) {
+    return `wechat_send_retry: context=${params.context} recipient=${params.recipientId} attempt=${params.attempt} delay_ms=${params.delayMs} error=${truncatePreview(describeWechatTransportError(params.error), 400)}`;
+}
+export function isRetryableWechatSendError(error) {
+    if (isWechatContextTokenStaleError(error)) {
+        return false;
+    }
+    const classification = classifyWechatTransportError(error);
+    if (classification.retryable) {
+        return true;
+    }
+    const details = describeWechatTransportError(error);
+    return /^(?:Error|WechatApiResponseError): sendmessage failed:/i.test(details) &&
+        !/errcode=-14\b.*session timeout/i.test(details);
+}
+export function computeWechatSendRetryDelayMs(attempt) {
+    return WECHAT_SEND_RETRY_BASE_MS * attempt;
+}

package/dist/companion/codex-remote-client.js

@@ -10,6 +10,7 @@ function log(message) {
 }
 export function parseCliArgs(argv) {
     let cwd = process.cwd();
+    let sessionStartMode;
     const cliArgs = [];
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -19,9 +20,10 @@ export function parseCliArgs(argv) {
         const next = argv[i + 1];
         if (arg === "--help" || arg === "-h") {
             process.stdout.write([
-                "Usage: wechat-codex [--cwd <path>] [...codex args]",
+                "Internal Codex client usage: npm run codex:panel -- [--cwd <path>] [--session-start-mode <restore|new>] [...codex args]",
                 "",
-                'Starts the visible native Codex client and connects it to the running "wechat-bridge-codex" instance for the current directory.',
+                "Connects the visible native Codex client to the bridge runtime for the current directory.",
+                "Use --session-start-mode new to open the client without resuming the shared thread.",
                 "Unknown arguments are forwarded to the Codex client.",
                 "",
             ].join("\n"));
@@ -35,17 +37,25 @@ export function parseCliArgs(argv) {
             i += 1;
             continue;
         }
+        if (arg === "--session-start-mode") {
+            if (next !== "restore" && next !== "new") {
+                throw new Error(`Invalid --session-start-mode value: ${next ?? "(missing)"}`);
+            }
+            sessionStartMode = next;
+            i += 1;
+            continue;
+        }
         cliArgs.push(arg);
     }
-    return { cwd, cliArgs };
+    return { cwd, cliArgs, sessionStartMode };
 }
 export function readCodexRuntimeEndpoint(cwd) {
     const endpoint = readLocalCompanionEndpoint(cwd, { adapter: "codex" });
     if (!endpoint || endpoint.kind !== "codex") {
-        throw new Error(`No active Codex bridge endpoint was found for ${cwd}. Start "wechat-bridge-codex" in that directory first.`);
+        throw new Error(`No active Codex runtime was found for ${cwd}. Run "wechat-codex" in that directory to recreate it.`);
     }
     if (endpoint.runtimeKind !== "codex_runtime_host" || (!endpoint.serverUrl && !endpoint.serverPort)) {
-        throw new Error(`The running Codex bridge for ${cwd} is using an older local companion protocol. Restart "wechat-bridge-codex" in that directory first.`);
+        throw new Error(`The running Codex runtime for ${cwd} uses an older local client protocol. Run "wechat-codex" in that directory to replace it.`);
     }
     return endpoint;
 }
@@ -55,7 +65,9 @@ export function buildRemoteCodexClientArgs(endpoint, options = {}) {
     const remoteUrl = endpoint.serverUrl ?? `ws://127.0.0.1:${endpoint.serverPort ?? endpoint.port}`;
     const args = buildCodexCliArgs(remoteUrl, {
         profile: endpoint.profile,
-        resumeThreadId: endpoint.sharedThreadId,
+        // "new" skips resume so the visible client opens a fresh Codex session
+        // instead of rejoining the shared thread.
+        resumeThreadId: options.sessionStartMode === "new" ? undefined : endpoint.sharedThreadId,
     });
     const tokenEnvName = endpoint.remoteAuthTokenEnv ?? CODEX_REMOTE_AUTH_TOKEN_ENV;
     return [...args, "--remote-auth-token-env", tokenEnvName, ...extraCliArgs];
@@ -70,6 +82,7 @@ export async function runCodexRemoteClientFromEndpoint(endpoint, options = {}) {
     const spawnTarget = resolveSpawnTarget(endpoint.command, "codex");
     const args = buildRemoteCodexClientArgs(endpoint, {
         extraCliArgs: options.extraCliArgs,
+        sessionStartMode: options.sessionStartMode,
     });
     const env = buildRemoteCodexClientEnv(endpoint);
     return await new Promise((resolve, reject) => {
@@ -107,6 +120,7 @@ export async function runCodexRemoteClient(options) {
     const endpoint = readCodexRuntimeEndpoint(options.cwd);
     return await runCodexRemoteClientFromEndpoint(endpoint, {
         extraCliArgs: options.cliArgs,
+        sessionStartMode: options.sessionStartMode,
     });
 }
 async function main() {

package/dist/companion/local-companion-link.js

@@ -1,13 +1,18 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import { ensureWorkspaceChannelDir, getWorkspaceAdapterEndpointFile, getWorkspaceChannelPaths, } from "../wechat/channel-config.js";
+import { writeJsonFileAtomic } from "../utils/atomic-file.js";
 import { LOCAL_CLIENT_PROTOCOL_VERSION, } from "../runtime/runtime-types.js";
 function normalizeEndpoint(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return null;
     }
     const record = value;
-    const kind = record.kind === "codex" || record.kind === "claude" || record.kind === "opencode" || record.kind === "shell"
+    const kind = record.kind === "codex" ||
+        record.kind === "claude" ||
+        record.kind === "opencode" ||
+        record.kind === "pi" ||
+        record.kind === "shell"
         ? record.kind
         : "codex";
     const sharedSessionId = typeof record.sharedSessionId === "string"
@@ -86,9 +91,13 @@ export function writeLocalCompanionEndpoint(endpoint, options = {}) {
     const payload = {
         ...serializeEndpoint(endpoint),
     };
-    fs.writeFileSync(getWorkspaceAdapterEndpointFile(endpoint.cwd, endpoint.kind), JSON.stringify(payload, null, 2), "utf8");
+    // Atomic writes: the endpoint files are rewritten on every adapter event
+    // while companions poll them concurrently; a torn write reads as JSON.parse
+    // failure → "no endpoint" → healthy bridges get restarted or duplicate
+    // clients launched.
+    writeJsonFileAtomic(getWorkspaceAdapterEndpointFile(endpoint.cwd, endpoint.kind), payload);
     if (options.writeLegacy !== false) {
-        fs.writeFileSync(endpointFile, JSON.stringify(payload, null, 2), "utf8");
+        writeJsonFileAtomic(endpointFile, payload);
     }
 }
 export function readLocalCompanionEndpoint(cwd, options = {}) {
@@ -118,6 +127,7 @@ export function clearLocalCompanionEndpoint(cwd, instanceId, options = {}) {
                 getWorkspaceAdapterEndpointFile(cwd, "codex"),
                 getWorkspaceAdapterEndpointFile(cwd, "claude"),
                 getWorkspaceAdapterEndpointFile(cwd, "opencode"),
+                getWorkspaceAdapterEndpointFile(cwd, "pi"),
                 getWorkspaceAdapterEndpointFile(cwd, "shell"),
             ];
         for (const filePath of files) {