@foxden-app/foxclaw 0.4.0 → 0.4.2

package/.env.example

@@ -1,7 +1,9 @@
-# Required for new installs: one or more bot tokens for this host
-# Comma-separated bot tokens. Each bot gets an independent Codex runtime/auth selection.
+# Required for new installs: one or more bot tokens for this host.
+# Comma-separated bot tokens. By default, each bot gets an independent Codex runtime/auth selection.
 TG_BOT_TOKENS=<telegram_bot_token>
-# Backward-compatible single-runtime setup:
+# Backward-compatible single-runtime setup.
+# In TG_BOT_TOKENS mode, if this exact token is also present in TG_BOT_TOKENS,
+# that bot uses the default terminal CODEX_HOME/auth instead of an isolated home.
 # TG_BOT_TOKEN=<telegram_bot_token>
 
 # Required: only this Telegram user can control the bridge
@@ -16,7 +18,8 @@ TG_ALLOWED_TOPIC_ID=
 
 # Optional Codex Desktop bridge settings.
 # In TG_BOT_TOKENS mode isolated Telegram runtimes start app-server directly and
-# do not auto-launch Codex Desktop; this remains applicable to the default/Weixin runtime.
+# do not auto-launch Codex Desktop; this remains applicable to the default/shared
+# terminal runtime and Weixin runtime.
 CODEX_APP_AUTOLAUNCH=true
 CODEX_APP_LAUNCH_CMD=codex app
 # Optional: persist the managed app-server pid/port and collect its stdout/stderr

package/README.md

@@ -40,7 +40,7 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex，
 - Git、Node、`.env` 都玩得转？直接往下看快速设置。
 - 卡住了？看 [故障排查](./docs/zh/troubleshooting.md)。
 
-最低要求：一个或多个 Telegram bot token、你的 Telegram 数字用户 ID、Node.js 24+、一份已登录的 `codex` CLI。首次安装大约 10–20 分钟。新安装请使用 `TG_BOT_TOKENS`；`TG_BOT_TOKEN` 只用于兼容旧的单 runtime 配置。
+最低要求：一个或多个 Telegram bot token、你的 Telegram 数字用户 ID、Node.js 24+、一份已登录的 `codex` CLI。首次安装大约 10–20 分钟。新安装请使用 `TG_BOT_TOKENS`；`TG_BOT_TOKEN` 兼容旧的单 runtime 配置，也可在多 bot 模式中标记一个“默认/终端共享”bot。
 
 **30 秒体验**：启动 FoxClaw 后，给你的 Telegram 机器人发一句 `List files in DEFAULT_CWD`。Codex 会在本地检查那个目录，然后把结果发回 Telegram。
 
@@ -111,7 +111,8 @@ FoxClaw 只响应 `TG_ALLOWED_USER_ID` 的消息——把机器人拉进群不
 **可靠性：**
 - SQLite 持久化：绑定、offset、审批、待处理提示、审计日志
 - 单实例进程锁，防止同一 bot token 重复 polling
-- `TG_BOT_TOKENS` 支持一台机器同时运行多个 Telegram bot；每个 bot 使用独立 Codex app-server、会话和 `/auth` 选择
+- `TG_BOT_TOKENS` 支持一台机器同时运行多个 Telegram bot；默认每个 bot 使用独立 Codex app-server、会话和 `/auth` 选择
+- 如果同时设置 `TG_BOT_TOKEN`，且它的值也出现在 `TG_BOT_TOKENS` 中，匹配的那个 bot 会共享终端默认 `CODEX_HOME` 和 auth，其他 bot 继续隔离
 
 </details>
 
@@ -201,9 +202,13 @@ TG_ALLOWED_TOPIC_ID=42
 
 ```dotenv
 TG_BOT_TOKENS=123456:token_a,234567:token_b
+# Optional: mark token_a as the bot sharing terminal/default CODEX_HOME and auth
+TG_BOT_TOKEN=123456:token_a
 ```
 
-FoxClaw 仍然只运行一个系统服务，但会为每个 bot 启动独立 `codex app-server` 和独立 `CODEX_HOME`。因此 A 私聊运行 turn 时，B 私聊仍可独立切换自己的 `/auth`。候选凭据由 FoxClaw 在登录或刷新验证后镜像同步，各 bot 的当前选择互不影响。每个 bot 首次私聊发送 `/help` 和 `/status`；`/auth` 会标明正在操作的 bot runtime，`/status` 会列出全部 bot 的连接、当前 auth 和活动 turn 摘要。
+FoxClaw 仍然只运行一个系统服务。默认情况下，它会为每个 bot 启动独立 `codex app-server` 和独立 `CODEX_HOME`。因此 A 私聊运行 turn 时，B 私聊仍可独立切换自己的 `/auth`。候选凭据由 FoxClaw 在登录或刷新验证后镜像同步，各 bot 的当前选择互不影响。每个 bot 首次私聊发送 `/help` 和 `/status`；`/auth` 会标明正在操作的 bot runtime，`/status` 会列出全部 bot 的连接、runtime 类型、当前 auth 和活动 turn 摘要。
+
+如果你需要一路 Telegram 与终端互通 session，把同一个 token 同时填入 `TG_BOT_TOKENS` 和 `TG_BOT_TOKEN`。这个 bot 使用默认 `CODEX_HOME`（未设置时通常是 `~/.codex`）和默认 auth，因此能看到终端 Codex 的本地线程；它不再享有隔离 runtime 的“互不影响”保证，切换 auth 会影响终端和其他默认 runtime。
 
 **怎么找群组和话题 ID：**
 
@@ -239,7 +244,7 @@ CODEX_APP_SYNC_ON_OPEN=true
 CODEX_APP_SYNC_ON_TURN_COMPLETE=false
 ```
 
-FoxClaw 会把 `codex app-server` 作为 detached 子进程启动，记录其 pid 和端口。使用 `TG_BOT_TOKENS` 时，每个 bot 都有自己的 app-server 与 Codex home，并在该隔离 runtime 内强制使用文件凭据存储；隔离 bot 不自动拉起 Codex Desktop，避免多个新 home 同时初始化桌面状态。重启时如果对应进程还活着就直接重连，否则拉起新进程。`/auth_reload` 和认证切换只重启发起操作的 bot runtime。
+FoxClaw 会把 `codex app-server` 作为 detached 子进程启动，记录其 pid 和端口。使用 `TG_BOT_TOKENS` 时，默认每个 bot 都有自己的 app-server 与 Codex home，并在该隔离 runtime 内强制使用文件凭据存储；隔离 bot 不自动拉起 Codex Desktop，避免多个新 home 同时初始化桌面状态。用 `TG_BOT_TOKEN` 标记的默认/终端共享 bot 例外：它使用默认 Codex home、默认 auth 和默认 app-server 配置。重启时如果对应进程还活着就直接重连，否则拉起新进程。`/auth_reload` 和认证切换只重启发起操作的 bot runtime。
 
 一般不需要手动固定 app-server 端口。
 

package/README_EN.md

@@ -40,7 +40,7 @@ FoxClaw is more than message forwarding. It provides Telegram panels for Codex w
 - Already comfortable with Git, Node, and `.env` files? Use the quick setup below.
 - Something failed? Check [Troubleshooting](./docs/troubleshooting.md).
 
-The minimum install needs one or more Telegram bot tokens, your numeric Telegram user id, Node.js 24+, and a logged-in `codex` CLI. A first install usually takes 10–20 minutes. New installs should use `TG_BOT_TOKENS`; `TG_BOT_TOKEN` exists only for legacy single-runtime compatibility.
+The minimum install needs one or more Telegram bot tokens, your numeric Telegram user id, Node.js 24+, and a logged-in `codex` CLI. A first install usually takes 10–20 minutes. New installs should use `TG_BOT_TOKENS`; `TG_BOT_TOKEN` remains compatible with legacy single-runtime setups and can mark one multi-bot runtime as default/shared-terminal.
 
 **30-second demo**: after FoxClaw is running, send `List files in DEFAULT_CWD` to your Telegram bot. FoxClaw asks local Codex to inspect that folder on your computer and sends the answer back to Telegram.
 
@@ -111,7 +111,8 @@ FoxClaw accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a gr
 **Reliability:**
 - SQLite persistence for bindings, offsets, approvals, pending input prompts, and audit logs
 - Single-instance process lock to prevent duplicate Telegram polling on the same bot token
-- `TG_BOT_TOKENS` runs multiple Telegram bots on one host with independent Codex app-servers, sessions, and `/auth` selections
+- `TG_BOT_TOKENS` runs multiple Telegram bots on one host with independent Codex app-servers, sessions, and `/auth` selections by default
+- If `TG_BOT_TOKEN` is also set and exactly matches one token in `TG_BOT_TOKENS`, that bot shares the terminal/default `CODEX_HOME` and auth while the other bots stay isolated
 
 </details>
 
@@ -201,9 +202,13 @@ Parallel bot example:
 
 ```dotenv
 TG_BOT_TOKENS=123456:token_a,234567:token_b
+# Optional: mark token_a as the bot sharing terminal/default CODEX_HOME and auth
+TG_BOT_TOKEN=123456:token_a
 ```
 
-FoxClaw remains one system service, but starts an independent `codex app-server` and `CODEX_HOME` for each bot. While bot A is running a turn, bot B can switch its own `/auth` selection. Candidate credentials are mirrored only after validated login or refresh; current selections remain independent. Send `/help` and `/status` in a private chat with each bot after installation; `/auth` names the runtime being managed, and `/status` summarizes every bot's connection, selected auth, and active turns.
+FoxClaw remains one system service. By default, it starts an independent `codex app-server` and `CODEX_HOME` for each bot. While bot A is running a turn, bot B can switch its own `/auth` selection. Candidate credentials are mirrored only after validated login or refresh; current selections remain independent. Send `/help` and `/status` in a private chat with each bot after installation; `/auth` names the runtime being managed, and `/status` summarizes every bot's connection, runtime type, selected auth, and active turns.
+
+To keep one Telegram bot interoperable with terminal Codex sessions, put the same token in both `TG_BOT_TOKENS` and `TG_BOT_TOKEN`. That bot uses the default `CODEX_HOME` (usually `~/.codex` when unset) and default auth, so it can see local terminal sessions. It no longer has the isolated runtime guarantee: `/auth` switches also affect the terminal and other default runtimes.
 
 **How to find group and topic IDs:**
 
@@ -239,7 +244,7 @@ CODEX_APP_SYNC_ON_OPEN=true
 CODEX_APP_SYNC_ON_TURN_COMPLETE=false
 ```
 
-FoxClaw starts `codex app-server` as a detached, bridge-managed process and records its pid and port. With `TG_BOT_TOKENS`, each bot has its own app-server and Codex home, and its isolated runtime is forced to use file-backed credentials. Isolated Telegram runtimes do not auto-launch Codex Desktop, avoiding simultaneous desktop-state initialization for fresh homes. On restart, FoxClaw reconnects to each live recorded app-server or starts a replacement. `/auth_reload` and auth switching restart only the requesting bot runtime.
+FoxClaw starts `codex app-server` as a detached, bridge-managed process and records its pid and port. With `TG_BOT_TOKENS`, each bot has its own app-server and Codex home by default, and its isolated runtime is forced to use file-backed credentials. Isolated Telegram runtimes do not auto-launch Codex Desktop, avoiding simultaneous desktop-state initialization for fresh homes. The default/shared-terminal bot marked with `TG_BOT_TOKEN` is the exception: it uses the default Codex home, default auth, and default app-server settings. On restart, FoxClaw reconnects to each live recorded app-server or starts a replacement. `/auth_reload` and auth switching restart only the requesting bot runtime.
 
 No static Codex app-server port is required in normal installs.
 

package/dist/auth/mirror.d.ts

@@ -4,6 +4,7 @@ export interface AuthMirrorRuntime {
     label?: string;
     authDir: string;
     notify?: (message: string) => Promise<void>;
+    validate?: (context: AuthMirrorValidationContext) => Promise<AuthMirrorValidationResult | boolean>;
 }
 export interface AuthMirrorStatus {
     candidateName: string;
@@ -11,6 +12,15 @@ export interface AuthMirrorStatus {
     sourceLabel: string;
     syncedAt: string;
 }
+export interface AuthMirrorValidationContext {
+    candidateName: string;
+    accountId: string;
+    lastRefreshMs: number;
+}
+export interface AuthMirrorValidationResult {
+    ok: boolean;
+    reason?: string | null;
+}
 export declare class AuthCandidateMirror {
     private readonly canonicalDir;
     private readonly runtimes;
@@ -29,6 +39,7 @@ export declare class AuthCandidateMirror {
     syncRuntimeCandidate(runtimeId: string, candidateName: string): Promise<boolean>;
     private scan;
     private propagateValidatedCandidate;
+    private validateRuntimeCandidate;
     private withActivity;
     private ensureCanonicalDefaultCandidate;
     private collectCandidateNames;

package/dist/auth/mirror.js

@@ -96,6 +96,15 @@ export class AuthCandidateMirror {
         if (record.lastRefreshMs <= previousRefresh) {
             return false;
         }
+        const validation = await this.validateRuntimeCandidate(runtime, name, record);
+        if (!validation.ok) {
+            this.logger.warn('auth.mirror.validation_failed', {
+                runtimeId: runtime.id,
+                name,
+                reason: validation.reason ?? 'unknown',
+            });
+            return false;
+        }
         await atomicWrite(canonicalPath, record.raw);
         for (const target of this.runtimes) {
             if (target.id !== runtime.id) {
@@ -116,6 +125,25 @@ export class AuthCandidateMirror {
         await Promise.allSettled(this.runtimes.map((target) => target.notify?.(message)));
         return true;
     }
+    async validateRuntimeCandidate(runtime, name, record) {
+        if (!runtime.validate) {
+            return { ok: true };
+        }
+        try {
+            const result = await runtime.validate({
+                candidateName: name,
+                accountId: record.accountId,
+                lastRefreshMs: record.lastRefreshMs,
+            });
+            if (typeof result === 'boolean') {
+                return { ok: result };
+            }
+            return { ok: Boolean(result.ok), reason: result.reason ?? null };
+        }
+        catch (error) {
+            return { ok: false, reason: formatError(error) };
+        }
+    }
     async withActivity(operation) {
         this.activeOperations += 1;
         try {

package/dist/config.d.ts

@@ -16,6 +16,7 @@ export interface AppConfig {
     tgBotToken: string;
     tgBotTokens: string[];
     tgMultiBotMode: boolean;
+    tgDefaultRuntimeBotToken: string | null;
     tgScopeBotId: string | null;
     tgRequireExplicitGroupAddressing: boolean;
     tgAllowedUserId: string;
@@ -52,4 +53,5 @@ export interface AppConfig {
     wxIlinkRouteTag: string | null;
 }
 export declare function loadConfig(): AppConfig;
+export declare function selectDefaultRuntimeBotToken(configuredTokens: string[], legacyToken: string | null): string | null;
 export declare function ensureAppDirs(config: AppConfig): void;

package/dist/config.js

@@ -40,6 +40,7 @@ export function loadConfig() {
     loadEnv();
     const configuredTokens = parseCommaSeparatedIds(process.env.TG_BOT_TOKENS);
     const legacyToken = optional('TG_BOT_TOKEN');
+    const tgDefaultRuntimeBotToken = selectDefaultRuntimeBotToken(configuredTokens, legacyToken);
     const tgBotTokens = configuredTokens.length > 0
         ? configuredTokens
         : legacyToken
@@ -52,6 +53,7 @@ export function loadConfig() {
         tgBotToken: tgBotTokens[0],
         tgBotTokens,
         tgMultiBotMode: configuredTokens.length > 0,
+        tgDefaultRuntimeBotToken,
         tgScopeBotId: null,
         tgRequireExplicitGroupAddressing: configuredTokens.length > 1,
         tgAllowedUserId: required('TG_ALLOWED_USER_ID'),
@@ -87,6 +89,11 @@ export function loadConfig() {
     ensureAppDirs(config);
     return config;
 }
+export function selectDefaultRuntimeBotToken(configuredTokens, legacyToken) {
+    if (configuredTokens.length === 0 || !legacyToken)
+        return null;
+    return configuredTokens.includes(legacyToken) ? legacyToken : null;
+}
 export function ensureAppDirs(config) {
     const dirs = [
         path.dirname(config.storePath),

package/dist/controller/controller.js

@@ -403,6 +403,7 @@ export class BridgeSessionCore {
                         lines.push(t(locale, 'status_runtime_bot', {
                             bot: runtime.username ? `@${runtime.username}` : runtime.id,
                             connected: t(locale, runtime.connected ? 'yes' : 'no'),
+                            runtime: t(locale, runtime.runtimeKind === 'default' ? 'status_runtime_kind_default' : 'status_runtime_kind_isolated'),
                             auth: runtime.currentAuth ?? t(locale, 'none'),
                             turns: runtime.activeTurns,
                         }));

package/dist/i18n.d.ts

@@ -119,7 +119,9 @@ declare const MESSAGES: {
         readonly status_codex_credits: "Codex credits: {value}";
         readonly status_codex_limit_reached: "Codex limit: {value}";
         readonly status_runtime_overview: "Telegram bot runtimes:";
-        readonly status_runtime_bot: "- {bot}: connected {connected}, auth {auth}, active turns {turns}";
+        readonly status_runtime_bot: "- {bot}: connected {connected}, runtime {runtime}, auth {auth}, active turns {turns}";
+        readonly status_runtime_kind_default: "default/shared terminal";
+        readonly status_runtime_kind_isolated: "isolated";
         readonly status_runtime_weixin: "- Weixin default runtime: connected {connected}, active turns {turns}";
         readonly status_auth_mirror_none: "Last auth mirror: none recorded";
         readonly status_auth_mirror_synced: "Last auth mirror: {candidate} from {source} at {time}";
@@ -692,7 +694,9 @@ declare const MESSAGES: {
         readonly status_codex_credits: "Codex 额度：{value}";
         readonly status_codex_limit_reached: "Codex 限制：{value}";
         readonly status_runtime_overview: "Telegram bot 运行时：";
-        readonly status_runtime_bot: "- {bot}：连接 {connected}，auth {auth}，进行中回复 {turns}";
+        readonly status_runtime_bot: "- {bot}：连接 {connected}，runtime {runtime}，auth {auth}，进行中回复 {turns}";
+        readonly status_runtime_kind_default: "默认/终端共享";
+        readonly status_runtime_kind_isolated: "隔离";
         readonly status_runtime_weixin: "- 微信默认运行时：连接 {connected}，进行中回复 {turns}";
         readonly status_auth_mirror_none: "最近 auth 镜像：暂无记录";
         readonly status_auth_mirror_synced: "最近 auth 镜像：{candidate} 由 {source} 于 {time} 同步";

package/dist/i18n.js

@@ -117,7 +117,9 @@ const MESSAGES = {
         status_codex_credits: 'Codex credits: {value}',
         status_codex_limit_reached: 'Codex limit: {value}',
         status_runtime_overview: 'Telegram bot runtimes:',
-        status_runtime_bot: '- {bot}: connected {connected}, auth {auth}, active turns {turns}',
+        status_runtime_bot: '- {bot}: connected {connected}, runtime {runtime}, auth {auth}, active turns {turns}',
+        status_runtime_kind_default: 'default/shared terminal',
+        status_runtime_kind_isolated: 'isolated',
         status_runtime_weixin: '- Weixin default runtime: connected {connected}, active turns {turns}',
         status_auth_mirror_none: 'Last auth mirror: none recorded',
         status_auth_mirror_synced: 'Last auth mirror: {candidate} from {source} at {time}',
@@ -690,7 +692,9 @@ const MESSAGES = {
         status_codex_credits: 'Codex 额度：{value}',
         status_codex_limit_reached: 'Codex 限制：{value}',
         status_runtime_overview: 'Telegram bot 运行时：',
-        status_runtime_bot: '- {bot}：连接 {connected}，auth {auth}，进行中回复 {turns}',
+        status_runtime_bot: '- {bot}：连接 {connected}，runtime {runtime}，auth {auth}，进行中回复 {turns}',
+        status_runtime_kind_default: '默认/终端共享',
+        status_runtime_kind_isolated: '隔离',
         status_runtime_weixin: '- 微信默认运行时：连接 {connected}，进行中回复 {turns}',
         status_auth_mirror_none: '最近 auth 镜像：暂无记录',
         status_auth_mirror_synced: '最近 auth 镜像：{candidate} 由 {source} 于 {time} 同步',

package/dist/main.js

@@ -170,33 +170,47 @@ async function runServeCli() {
         store = new BridgeStore(config.storePath);
         if (config.tgMultiBotMode) {
             const seeds = [];
+            const canonicalAuthDir = config.codexAuthDir ?? config.codexHome ?? path.join(os.homedir(), '.codex');
             for (const token of config.tgBotTokens) {
                 const bot = new TelegramGateway(token, config.tgAllowedUserId, config.tgAllowedChatId, config.telegramPollIntervalMs, store, logger, true);
                 const id = await bot.initializeIdentity();
                 if (seeds.some((runtime) => runtime.id === id)) {
                     throw new Error(`TG_BOT_TOKENS contains duplicate Telegram bot identity: ${id}`);
                 }
-                const home = path.join(DEFAULT_CODEX_TELEGRAM_HOME, id, 'home');
-                fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+                const sharedDefaultRuntime = config.tgDefaultRuntimeBotToken === token;
+                const home = sharedDefaultRuntime
+                    ? (config.codexHome ?? path.join(os.homedir(), '.codex'))
+                    : path.join(DEFAULT_CODEX_TELEGRAM_HOME, id, 'home');
+                const authDir = sharedDefaultRuntime ? canonicalAuthDir : home;
+                if (!sharedDefaultRuntime) {
+                    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+                }
                 const runtimeConfig = {
                     ...config,
                     tgBotToken: token,
                     tgBotTokens: [token],
                     tgScopeBotId: id,
-                    codexAuthDir: home,
-                    codexHome: home,
-                    codexAppAutolaunch: false,
-                    codexAppServerStatePath: path.join(APP_HOME, 'runtime', `codex-app-server-${id}.json`),
-                    codexAppServerLogPath: path.join(APP_HOME, 'logs', `codex-app-server-${id}.log`),
+                    codexAuthDir: sharedDefaultRuntime ? config.codexAuthDir : home,
+                    codexHome: sharedDefaultRuntime ? config.codexHome : home,
+                    codexAppAutolaunch: sharedDefaultRuntime ? config.codexAppAutolaunch : false,
+                    codexAppServerStatePath: sharedDefaultRuntime
+                        ? config.codexAppServerStatePath
+                        : path.join(APP_HOME, 'runtime', `codex-app-server-${id}.json`),
+                    codexAppServerLogPath: sharedDefaultRuntime
+                        ? config.codexAppServerLogPath
+                        : path.join(APP_HOME, 'logs', `codex-app-server-${id}.log`),
                 };
-                const app = new CodexAppClient(runtimeConfig.codexCliBin, runtimeConfig.codexAppLaunchCmd, runtimeConfig.codexAppAutolaunch, runtimeConfig.codexAppServerStatePath, runtimeConfig.codexAppServerLogPath, logger, { CODEX_HOME: home }, ['cli_auth_credentials_store="file"']);
-                seeds.push({ id, home, config: runtimeConfig, bot, app });
+                const childEnv = sharedDefaultRuntime
+                    ? (config.codexHome ? { CODEX_HOME: config.codexHome } : null)
+                    : { CODEX_HOME: home };
+                const app = new CodexAppClient(runtimeConfig.codexCliBin, runtimeConfig.codexAppLaunchCmd, runtimeConfig.codexAppAutolaunch, runtimeConfig.codexAppServerStatePath, runtimeConfig.codexAppServerLogPath, logger, childEnv, sharedDefaultRuntime ? [] : ['cli_auth_credentials_store="file"']);
+                seeds.push({ id, home, authDir, sharedDefaultRuntime, config: runtimeConfig, bot, app });
             }
-            const canonicalAuthDir = config.codexAuthDir ?? config.codexHome ?? path.join(os.homedir(), '.codex');
             const mirror = new AuthCandidateMirror(canonicalAuthDir, seeds.map((runtime) => ({
                 id: runtime.id,
                 label: runtime.bot.username ? `@${runtime.bot.username}` : runtime.id,
-                authDir: runtime.home,
+                authDir: runtime.authDir,
+                validate: async (context) => validateRefreshedAuthCandidate(runtime, context.candidateName),
                 notify: async (message) => {
                     const chatId = store.getTelegramPrivateChatId(runtime.id);
                     if (chatId) {
@@ -246,6 +260,7 @@ async function runServeCli() {
                         username: statuses[index]?.botUsername ?? runtime.bot.username,
                         connected: running && Boolean(statuses[index]?.connected),
                         activeTurns: running ? (statuses[index]?.activeTurns ?? 0) : 0,
+                        runtimeKind: runtime.sharedDefaultRuntime ? 'default' : 'isolated',
                         ...(statuses[index]?.codexAppServer ? { codexAppServer: statuses[index].codexAppServer } : {}),
                     })),
                     ...(weixinStatus ? {
@@ -273,6 +288,7 @@ async function runServeCli() {
                             username: status.botUsername ?? runtime.bot.username,
                             connected: status.connected,
                             activeTurns: status.activeTurns,
+                            runtimeKind: runtime.sharedDefaultRuntime ? 'default' : 'isolated',
                             currentAuth: await runtime.core.getCurrentAuthLabel().catch(() => null),
                             ...(status.codexAppServer ? { codexAppServer: status.codexAppServer } : {}),
                         };
@@ -412,6 +428,26 @@ async function runServeCli() {
         throw error;
     }
 }
+async function validateRefreshedAuthCandidate(runtime, candidateName) {
+    const authPath = path.join(runtime.authDir, 'auth.json');
+    const candidatePath = path.join(runtime.authDir, candidateName);
+    const [currentTarget, candidateTarget] = await Promise.all([
+        fs.promises.realpath(authPath).catch(() => null),
+        fs.promises.realpath(candidatePath).catch(() => null),
+    ]);
+    if (!currentTarget || !candidateTarget || currentTarget !== candidateTarget) {
+        return { ok: false, reason: 'candidate is not the current auth target' };
+    }
+    if (!runtime.app.isConnected()) {
+        return { ok: false, reason: 'source app-server is not connected' };
+    }
+    const account = await runtime.app.readAccount();
+    if (!account || account.type !== 'chatgpt' || account.requiresOpenaiAuth) {
+        return { ok: false, reason: 'source app-server did not report an active ChatGPT account' };
+    }
+    await runtime.app.readAccountRateLimits();
+    return { ok: true };
+}
 async function initConfig() {
     const envPath = process.env.FOXCLAW_ENV?.trim() || DEFAULT_ENV_PATH;
     fs.mkdirSync(path.dirname(envPath), { recursive: true });

package/dist/types.d.ts

@@ -345,6 +345,7 @@ export interface RuntimeStatus {
         username: string | null;
         connected: boolean;
         activeTurns: number;
+        runtimeKind?: 'default' | 'isolated';
         currentAuth?: string | null;
         codexAppServer?: RuntimeStatus['codexAppServer'];
     }>;

package/docs/install-for-beginners.md

@@ -162,6 +162,15 @@ TG_BOT_TOKENS=123456789:token_a,234567890:token_b,345678901:token_c
 
 FoxClaw still installs one service, but each bot receives its own app-server, session home, and current auth selection. After startup, privately send `/help` and `/status` to each bot.
 
+If you want one of those bots to share terminal Codex sessions and the default auth, also set `TG_BOT_TOKEN` to the exact same token:
+
+```dotenv
+TG_BOT_TOKENS=123456789:token_a,234567890:token_b
+TG_BOT_TOKEN=123456789:token_a
+```
+
+Only the matching bot uses the default/shared-terminal runtime; the others stay isolated.
+
 `DEFAULT_CWD` must be a real folder. Examples:
 
 ```dotenv

package/docs/troubleshooting.md

@@ -184,7 +184,7 @@ tail -f ~/.foxclaw/logs/service.log
 
 ## Checking Multi-Bot Mode
 
-After configuring `TG_BOT_TOKENS`, `foxclaw status` should contain one bot id, connection status, and independent app-server for each token. Send `/status` privately to any bot to see the runtime summary; send `/auth` to confirm the panel names the current `@botname` and its auth directory.
+After configuring `TG_BOT_TOKENS`, `foxclaw status` should contain one bot id, connection status, and runtime type for each token. Send `/status` privately to any bot to see the runtime summary; send `/auth` to confirm the panel names the current `@botname` and its auth directory. If `TG_BOT_TOKEN` exactly matches one token in `TG_BOT_TOKENS`, that bot should appear as the default/shared-terminal runtime; the others should appear as isolated.
 
 Each isolated app-server log is stored at:
 

package/docs/user-manual.md

@@ -120,7 +120,7 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 Fields:
 
-- `TG_BOT_TOKENS`: one or more `@BotFather` tokens separated by commas. The legacy single-bot `TG_BOT_TOKEN` setting remains compatible.
+- `TG_BOT_TOKENS`: one or more `@BotFather` tokens separated by commas. The legacy single-bot `TG_BOT_TOKEN` setting remains compatible. In multi-bot mode, if the exact `TG_BOT_TOKEN` value also appears in `TG_BOT_TOKENS`, that bot uses the default/shared-terminal runtime.
 - `TG_ALLOWED_USER_ID`: your numeric Telegram user id.
 - `TG_ALLOWED_CHAT_ID`: leave empty for the first private-chat setup.
 - `TG_ALLOWED_TOPIC_ID`: leave empty unless binding a Telegram topic.
@@ -335,11 +335,13 @@ Watch mode mirrors live turn progress and approval requests. The watching chat i
 
 ## 6. Codex Login And Auth Rotation
 
-This is a key FoxClaw feature. Codex auth is usually stored at `~/.codex/auth.json`. FoxClaw stores multiple accounts as candidate files and switches which candidate the active `auth.json` points to. In `TG_BOT_TOKENS` mode, each bot has an isolated Codex home, app-server, and current candidate, so bots can run and switch accounts independently; isolated Telegram runtimes force file-backed credential storage. Validated login/refresh credentials are safely mirrored between bot homes, but sessions are never shared.
+This is a key FoxClaw feature. Codex auth is usually stored at `~/.codex/auth.json`. FoxClaw stores multiple accounts as candidate files and switches which candidate the active `auth.json` points to. In `TG_BOT_TOKENS` mode, each bot has an isolated Codex home, app-server, and current candidate by default, so bots can run and switch accounts independently; isolated Telegram runtimes force file-backed credential storage. Validated login/refresh credentials are safely mirrored between bot homes, but isolated sessions are never shared.
+
+To keep one Telegram bot interoperable with terminal Codex sessions, put the same token in both `TG_BOT_TOKENS` and `TG_BOT_TOKEN`. That bot uses the default `CODEX_HOME` and default auth, so `/threads` can see local terminal sessions; its `/auth` switches also affect the terminal default auth. Bots listed only in `TG_BOT_TOKENS` stay isolated.
 
 ### 6.1 File Format
 
-In single-bot compatibility mode, candidate files live in the Codex auth directory, usually `~/.codex/`. If `CODEX_AUTH_DIR` is set, FoxClaw uses that directory. Multi-bot mode treats that directory as its candidate source and stores isolated bot copies under `~/.foxclaw/codex/telegram/bot<id>/home/`.
+In single-bot compatibility mode, candidate files live in the Codex auth directory, usually `~/.codex/`. If `CODEX_AUTH_DIR` is set, FoxClaw uses that directory. Multi-bot mode treats that directory as its candidate source and stores isolated bot copies under `~/.foxclaw/codex/telegram/bot<id>/home/`. A default/shared-terminal bot does not get an isolated copy; it uses the default auth directory directly.
 
 Recommended layout:
 

package/docs/zh/foxclaw-skill.md

@@ -19,6 +19,7 @@
 ## 注意事项
 
 - 不要让 agent 把完整 bot token 打印到日志或提交到仓库。
+- FoxClaw 仓库收尾提交默认使用 `中文 | English` 的双语 subject，方便国内和国际协作者同时阅读。
 - 第一次请先用私聊模式跑通。
 - 多个 token 会在同一服务中建立多个独立 Codex home、session 与 auth 选择；群组中必须点名或回复目标 bot。
 - 同时启用微信时，微信仍使用默认 Codex runtime，不共享隔离 Telegram bot 的线程。

package/docs/zh/install-for-beginners.md

@@ -160,6 +160,15 @@ TG_BOT_TOKENS=123456789:token_a,234567890:token_b,345678901:token_c
 
 FoxClaw 仍只安装一个服务，但每个 bot 会有独立 app-server、会话目录和当前 auth。服务启动后请分别私聊每个 bot 发送 `/help` 与 `/status`。
 
+如果你希望其中一个 bot 和终端 Codex 共享 session 与默认 auth，再把 `TG_BOT_TOKEN` 设置为同一个 token：
+
+```dotenv
+TG_BOT_TOKENS=123456789:token_a,234567890:token_b
+TG_BOT_TOKEN=123456789:token_a
+```
+
+只有匹配的 bot 使用默认/终端共享 runtime，其他 bot 仍然隔离。
+
 `DEFAULT_CWD` 必须是真实存在的目录，例如：
 
 ```dotenv

package/docs/zh/troubleshooting.md

@@ -185,7 +185,7 @@ tail -f ~/.foxclaw/logs/service.log
 
 ## 多 bot 模式核查
 
-配置 `TG_BOT_TOKENS` 后，`foxclaw status` 的 `bots` 列表应为每个 token 显示一个 bot id、连接状态和独立 app-server。私聊任一 bot 发送 `/status` 会显示全部 runtime 摘要；发送 `/auth` 应显示当前 `@botname` 和该 bot 的 auth 目录。
+配置 `TG_BOT_TOKENS` 后，`foxclaw status` 的 `bots` 列表应为每个 token 显示一个 bot id、连接状态和 runtime 类型。私聊任一 bot 发送 `/status` 会显示全部 runtime 摘要；发送 `/auth` 应显示当前 `@botname` 和该 bot 的 auth 目录。如果 `TG_BOT_TOKEN` 精确匹配 `TG_BOT_TOKENS` 中的一个 token，该 bot 应显示为默认/终端共享 runtime；其他 bot 应显示为隔离 runtime。
 
 每个隔离 app-server 的日志路径为：
 

package/docs/zh/user-manual.md

@@ -120,7 +120,7 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 字段说明：
 
-- `TG_BOT_TOKENS`：从 `@BotFather` 拿到的一个或多个 bot token，多项用英文逗号分隔。旧版单 bot 配置 `TG_BOT_TOKEN` 仍兼容。
+- `TG_BOT_TOKENS`：从 `@BotFather` 拿到的一个或多个 bot token，多项用英文逗号分隔。旧版单 bot 配置 `TG_BOT_TOKEN` 仍兼容；多 bot 模式下，如果 `TG_BOT_TOKEN` 的值也出现在 `TG_BOT_TOKENS` 中，匹配的 bot 会使用默认/终端共享 runtime。
 - `TG_ALLOWED_USER_ID`：你的 Telegram 数字用户 ID。
 - `TG_ALLOWED_CHAT_ID`：第一次保持为空，表示私聊模式。
 - `TG_ALLOWED_TOPIC_ID`：第一次保持为空，表示不绑定 Telegram 话题。
@@ -335,11 +335,13 @@ FoxClaw 的聊天是“绑定线程”的。你在手机上打开某个 Codex
 
 ## 6. Codex 登录和 auth 轮转
 
-这是 FoxClaw 的特色功能。Codex 的登录状态通常保存在 `~/.codex/auth.json`。FoxClaw 把多个账号保存成候选文件，并通过切换 `auth.json` 指向哪个候选来换号。启用 `TG_BOT_TOKENS` 多 bot 模式后，每个 bot 使用独立 Codex home、独立 app-server 和独立当前候选，因此可以并行运行、单独切号；隔离 Telegram runtime 会强制使用文件凭据存储。已验证的登录/刷新凭据会安全镜像到其他 bot home，但不会共享 session。
+这是 FoxClaw 的特色功能。Codex 的登录状态通常保存在 `~/.codex/auth.json`。FoxClaw 把多个账号保存成候选文件，并通过切换 `auth.json` 指向哪个候选来换号。启用 `TG_BOT_TOKENS` 多 bot 模式后，默认每个 bot 使用独立 Codex home、独立 app-server 和独立当前候选，因此可以并行运行、单独切号；隔离 Telegram runtime 会强制使用文件凭据存储。已验证的登录/刷新凭据会安全镜像到其他 bot home，但不会共享 session。
+
+如果你想保留一路和终端互通 session 的 Telegram bot，把该 token 同时写入 `TG_BOT_TOKENS` 和 `TG_BOT_TOKEN`。这个 bot 使用默认 `CODEX_HOME` 和默认 auth，因此能看到终端 Codex 的本地线程；它的 `/auth` 切换也会影响终端默认 auth。其他只出现在 `TG_BOT_TOKENS` 的 bot 仍然完全隔离。
 
 ### 6.1 文件格式
 
-单 bot 兼容模式的候选文件放在 Codex auth 目录，默认是 `~/.codex/`。如果你设置了 `CODEX_AUTH_DIR`，则使用那个目录。多 bot 模式以这个目录作为候选源，并在 `~/.foxclaw/codex/telegram/bot<id>/home/` 下为每个 bot 保存隔离副本。
+单 bot 兼容模式的候选文件放在 Codex auth 目录，默认是 `~/.codex/`。如果你设置了 `CODEX_AUTH_DIR`，则使用那个目录。多 bot 模式以这个目录作为候选源，并在 `~/.foxclaw/codex/telegram/bot<id>/home/` 下为隔离 bot 保存副本。默认/终端共享 bot 不创建隔离副本，而是直接使用这个默认 auth 目录。
 
 推荐命名：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",

package/skills/foxclaw/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: foxclaw
-description: Deploy, configure, validate, develop, and release FoxClaw. Use when Codex needs to clone or update the FoxClaw repo, collect Telegram values, write `.env`, enable launchd/systemd, guide first-message tests, or perform FoxClaw repo wrap-up actions such as Chinese commit messages, push, npm publish, and local install/service update.
+description: Deploy, configure, validate, develop, and release FoxClaw. Use when Codex needs to clone or update the FoxClaw repo, collect Telegram values, write `.env`, enable launchd/systemd, guide first-message tests, or perform FoxClaw repo wrap-up actions such as bilingual Chinese | English commit messages, push, npm publish, and local install/service update.
 ---
 
 # FoxClaw
@@ -66,6 +66,7 @@ Telegram behavior:
 - `TG_ALLOWED_CHAT_ID` and `TG_ALLOWED_TOPIC_ID` choose the default group or topic scope; they do not disable private chat
 - when `TG_BOT_TOKENS` contains multiple bots, one FoxClaw service starts independent Codex app-servers and auth selections per bot
 - isolated Telegram runtimes use independent `CODEX_HOME` directories and file-backed credentials; they do not share Codex sessions
+- if `TG_BOT_TOKEN` is also set to one exact token from `TG_BOT_TOKENS`, that bot uses the default/shared-terminal runtime instead of an isolated Telegram home
 - if Weixin is enabled alongside multiple Telegram bots, it remains on the default Codex runtime instead of borrowing a Telegram bot runtime
 - in a group with multiple configured bots, address a bot by mention, reply, or suffixed command such as `/status@botname`
 
@@ -169,7 +170,7 @@ Do not describe the setup as "done" until this smoke test has either passed or b
 
 ## Development Wrap-Up
 
-Use this checklist when the user asks for standard closing actions, release wrap-up, local install updates, npm publish, or says things like "收尾动作", "中文 commit msg", "push", "npm publish", or "本地安装更新".
+Use this checklist when the user asks for standard closing actions, release wrap-up, local install updates, npm publish, or says things like "收尾动作", "中文 commit msg", "中英双语 commit msg", "push", "npm publish", or "本地安装更新".
 
 1. Inspect scope before staging:
    - `git status -sb`
@@ -183,7 +184,9 @@ Use this checklist when the user asks for standard closing actions, release wrap
    - `npm run build`
 4. Commit intentionally:
    - Stage only the changed files that belong to the task.
-   - Use a Chinese commit message when the user asked in Chinese or explicitly said "中文 commit msg".
+   - For this repo, prefer a bilingual one-line subject in the form `中文 | English`.
+   - Put Chinese first, keep the English half semantically equivalent, and keep both halves concise.
+   - For release commits, use the same format, for example `发布 0.4.0：支持多机器人隔离 | Release 0.4.0: support multi-bot isolation`.
    - Never stage unrelated local changes.
 5. Push the current branch after a successful commit:
    - `git push origin <branch>`

package/skills/npm-publish/SKILL.md

@@ -37,7 +37,7 @@ Use this skill to publish an npm package from a repo. Prefer CI trusted publishi
 5. Commit and push source changes before `npm publish` when the user asked to push or when this is a normal release:
    ```bash
    git add <changed-files>
-   git commit -m "<release message>"
+   git commit -m "<Chinese | English release message>"
    git push
    ```
 
@@ -56,7 +56,7 @@ Use this path when the repo has `.github/workflows/publish.yml` and npmjs.com ha
    ```bash
    npm version patch --no-git-tag-version
    git add package.json package-lock.json
-   git commit -m "<Chinese release message when appropriate>"
+   git commit -m "<Chinese | English release message when appropriate>"
    git push origin <branch>
    ```