@foxden-app/foxclaw 0.3.18 → 0.3.19

package/.env.example

@@ -1,5 +1,8 @@
-# Required: one bot token per device
-TG_BOT_TOKEN=<telegram_bot_token>
+# Required: one or more bot tokens for this host
+# Comma-separated bot tokens. Each bot gets an independent Codex runtime/auth selection.
+TG_BOT_TOKENS=<telegram_bot_token>
+# Backward-compatible single-runtime setup:
+# TG_BOT_TOKEN=<telegram_bot_token>
 
 # Required: only this Telegram user can control the bridge
 TG_ALLOWED_USER_ID=<telegram_user_id>

package/README.md

@@ -75,7 +75,7 @@ foxclaw start
 跑 `doctor` 或 `start` 之前先把 `.env` 填好。私聊模式最小配置：
 
 ```dotenv
-TG_BOT_TOKEN=123456:telegram-token
+TG_BOT_TOKENS=123456:telegram-token
 TG_ALLOWED_USER_ID=123456789
 DEFAULT_CWD=/absolute/path/to/workspace
 DEFAULT_APPROVAL_POLICY=on-request
@@ -84,7 +84,7 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 配置文件默认在 `~/.foxclaw/.env`。想放别处的话设 `FOXCLAW_ENV=/path/to/.env`。
 
-`foxclaw start` 会自动检查环境并安装/重启后台服务。后续升级直接运行 `foxclaw update`，它会沿用当前的 npm/pnpm 全局安装方式，完成安装、自检和服务重启。
+`foxclaw start` 会自动检查环境并安装/重启后台服务。后续升级直接运行 `foxclaw update`，它会沿用当前的 npm/pnpm 全局安装方式，尝试同步升级 npm/pnpm 安装的 Codex CLI，再完成安装、自检和服务重启。
 
 FoxClaw 只响应 `TG_ALLOWED_USER_ID` 的消息——把机器人拉进群不代表群里所有人都能用。
 
@@ -111,6 +111,7 @@ FoxClaw 只响应 `TG_ALLOWED_USER_ID` 的消息——把机器人拉进群不
 **可靠性：**
 - SQLite 持久化：绑定、offset、审批、待处理提示、审计日志
 - 单实例进程锁，防止同一 bot token 重复 polling
+- `TG_BOT_TOKENS` 支持一台机器同时运行多个 Telegram bot；每个 bot 使用独立 Codex app-server、会话和 `/auth` 选择
 
 </details>
 
@@ -178,7 +179,7 @@ FoxClaw 最初基于 `Gan-Xing/telegram-codex-app-bridge` fork 演进而来，
 
 ## Telegram 设置
 
-1. 用 `@BotFather` 创建机器人，token 填入 `TG_BOT_TOKEN`。
+1. 用 `@BotFather` 创建一个或多个机器人，token 以逗号分隔填入 `TG_BOT_TOKENS`。
 2. 拿到你的 Telegram 数字用户 ID，填入 `TG_ALLOWED_USER_ID`。
 3. `foxclaw start` 启动。
 4. 打开和机器人的私聊，发 `/help`。
@@ -194,6 +195,15 @@ TG_ALLOWED_TOPIC_ID=42
 - 只填 `TG_ALLOWED_CHAT_ID` → 允许一个群组作为默认会话范围。
 - 两个都填 → 绑定到某个话题。
 - 配了群组后，`TG_ALLOWED_USER_ID` 的私聊依然可用。
+- 配置多个 bot 时，同一个授权群内只有 `@botname` 命令、mention 或回复该 bot 的消息会被它处理，避免多个 Codex 会话同时响应。
+
+多 bot 并行示例：
+
+```dotenv
+TG_BOT_TOKENS=123456:token_a,234567:token_b
+```
+
+FoxClaw 仍然只运行一个系统服务，但会为每个 bot 启动独立 `codex app-server` 和独立 `CODEX_HOME`。因此 A 私聊运行 turn 时，B 私聊仍可独立切换自己的 `/auth`。候选凭据由 FoxClaw 在登录或刷新验证后镜像同步，各 bot 的当前选择互不影响。
 
 **怎么找群组和话题 ID：**
 
@@ -229,7 +239,7 @@ CODEX_APP_SYNC_ON_OPEN=true
 CODEX_APP_SYNC_ON_TURN_COMPLETE=false
 ```
 
-FoxClaw 会把 `codex app-server` 作为 detached 子进程启动，记录其 pid 和端口。重启时如果进程还活着就直接重连，否则拉起新进程。`/auth_reload` 和认证切换会重启 app-server 以重新加载 `auth.json`。
+FoxClaw 会把 `codex app-server` 作为 detached 子进程启动，记录其 pid 和端口。使用 `TG_BOT_TOKENS` 时，每个 bot 都有自己的 app-server 与 Codex home；重启时如果对应进程还活着就直接重连，否则拉起新进程。`/auth_reload` 和认证切换只重启发起操作的 bot runtime。
 
 一般不需要手动固定 app-server 端口。
 

package/README_EN.md

@@ -75,7 +75,7 @@ foxclaw start
 Fill `.env` before running `doctor` or `start`. Minimum private-chat config:
 
 ```dotenv
-TG_BOT_TOKEN=123456:telegram-token
+TG_BOT_TOKENS=123456:telegram-token
 TG_ALLOWED_USER_ID=123456789
 DEFAULT_CWD=/absolute/path/to/workspace
 DEFAULT_APPROVAL_POLICY=on-request
@@ -84,7 +84,7 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 The default config file is `~/.foxclaw/.env`. Set `FOXCLAW_ENV=/path/to/.env` if you want to keep it somewhere else.
 
-`foxclaw start` runs checks and installs or restarts the background service. For later upgrades, run `foxclaw update`; it preserves the current npm/pnpm global-install method, runs checks, and restarts the service.
+`foxclaw start` runs checks and installs or restarts the background service. For later upgrades, run `foxclaw update`; it preserves the current npm/pnpm global-install method, attempts to update an npm/pnpm-managed Codex CLI, runs checks, and restarts the service.
 
 FoxClaw accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a group does not make it available to every group member.
 
@@ -111,6 +111,7 @@ 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
 
 </details>
 
@@ -178,7 +179,7 @@ FoxClaw originally evolved from a fork of `Gan-Xing/telegram-codex-app-bridge` a
 
 ## Telegram Setup
 
-1. Create a bot with `@BotFather` and copy the token into `TG_BOT_TOKEN`.
+1. Create one or more bots with `@BotFather` and put their comma-separated tokens into `TG_BOT_TOKENS`.
 2. Get your Telegram numeric user id and place it into `TG_ALLOWED_USER_ID`.
 3. Start FoxClaw with `foxclaw start`.
 4. Open a private chat with the bot and send `/help`.
@@ -194,6 +195,15 @@ TG_ALLOWED_TOPIC_ID=42
 - Set `TG_ALLOWED_CHAT_ID` only to allow one group as the default conversation scope.
 - Set both `TG_ALLOWED_CHAT_ID` and `TG_ALLOWED_TOPIC_ID` to bind one topic as the default scope.
 - Private chat remains available for `TG_ALLOWED_USER_ID` even when a group is configured.
+- With multiple bots, a configured group handles only `@botname` commands, mentions, or replies addressed to each bot, preventing duplicate Codex responses.
+
+Parallel bot example:
+
+```dotenv
+TG_BOT_TOKENS=123456:token_a,234567:token_b
+```
+
+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.
 
 **How to find group and topic IDs:**
 
@@ -229,7 +239,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. On restart, it reconnects to the recorded app-server if that process is still alive; otherwise it starts a new one. `/auth_reload` and auth switching restart the managed app-server so the current `auth.json` is reloaded.
+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. 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

@@ -0,0 +1,25 @@
+import type { Logger } from '../logger.js';
+export interface AuthMirrorRuntime {
+    id: string;
+    authDir: string;
+    notify?: (message: string) => Promise<void>;
+}
+export declare class AuthCandidateMirror {
+    private readonly canonicalDir;
+    private readonly runtimes;
+    private readonly logger;
+    private timer;
+    private readonly lastSyncedRefresh;
+    constructor(canonicalDir: string, runtimes: AuthMirrorRuntime[], logger: Logger);
+    initialize(): Promise<void>;
+    start(): void;
+    stop(): void;
+    syncRuntimeCandidate(runtimeId: string, candidateName: string): Promise<boolean>;
+    private scan;
+    private propagateValidatedCandidate;
+    private ensureCanonicalDefaultCandidate;
+    private collectCandidateNames;
+    private reconcileCandidateAtStartup;
+    private resolveCanonicalCurrentCandidate;
+}
+export declare function isAuthCandidateName(name: string): boolean;

package/dist/auth/mirror.js

@@ -0,0 +1,199 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const AUTH_SCAN_INTERVAL_MS = 5_000;
+export class AuthCandidateMirror {
+    canonicalDir;
+    runtimes;
+    logger;
+    timer = null;
+    lastSyncedRefresh = new Map();
+    constructor(canonicalDir, runtimes, logger) {
+        this.canonicalDir = canonicalDir;
+        this.runtimes = runtimes;
+        this.logger = logger;
+    }
+    async initialize() {
+        await fs.mkdir(this.canonicalDir, { recursive: true, mode: 0o700 });
+        await this.ensureCanonicalDefaultCandidate();
+        const candidateNames = await this.collectCandidateNames();
+        for (const name of candidateNames) {
+            await this.reconcileCandidateAtStartup(name);
+        }
+        const canonicalCandidateNames = await listAuthCandidateNames(this.canonicalDir);
+        const defaultCandidate = await this.resolveCanonicalCurrentCandidate()
+            ?? canonicalCandidateNames.sort()[0]
+            ?? null;
+        for (const runtime of this.runtimes) {
+            await fs.mkdir(runtime.authDir, { recursive: true, mode: 0o700 });
+            for (const name of canonicalCandidateNames) {
+                const destination = path.join(runtime.authDir, name);
+                if (!(await exists(destination))) {
+                    await atomicCopy(path.join(this.canonicalDir, name), destination);
+                }
+            }
+            if (defaultCandidate && !(await exists(path.join(runtime.authDir, 'auth.json')))) {
+                await pointAuthSymlink(runtime.authDir, defaultCandidate);
+            }
+        }
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.scan().catch((error) => {
+                this.logger.warn('auth.mirror.scan_failed', { error: formatError(error) });
+            });
+        }, AUTH_SCAN_INTERVAL_MS);
+        this.timer.unref();
+    }
+    stop() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+    async syncRuntimeCandidate(runtimeId, candidateName) {
+        if (!isAuthCandidateName(candidateName))
+            return false;
+        const runtime = this.runtimes.find((entry) => entry.id === runtimeId);
+        if (!runtime)
+            return false;
+        return this.propagateValidatedCandidate(runtime, candidateName);
+    }
+    async scan() {
+        for (const runtime of this.runtimes) {
+            const names = await listAuthCandidateNames(runtime.authDir);
+            for (const name of names) {
+                await this.propagateValidatedCandidate(runtime, name);
+            }
+        }
+    }
+    async propagateValidatedCandidate(runtime, name) {
+        const sourcePath = path.join(runtime.authDir, name);
+        const record = await readChatGptAuthRecord(sourcePath);
+        if (!record)
+            return false;
+        const canonicalPath = path.join(this.canonicalDir, name);
+        const canonical = await readChatGptAuthRecord(canonicalPath);
+        if (canonical && canonical.accountId !== record.accountId) {
+            this.logger.warn('auth.mirror.account_conflict', { runtimeId: runtime.id, name });
+            return false;
+        }
+        const previousRefresh = Math.max(canonical?.lastRefreshMs ?? 0, this.lastSyncedRefresh.get(name) ?? 0);
+        if (record.lastRefreshMs <= previousRefresh) {
+            return false;
+        }
+        await atomicWrite(canonicalPath, record.raw);
+        for (const target of this.runtimes) {
+            if (target.id !== runtime.id) {
+                await atomicWrite(path.join(target.authDir, name), record.raw);
+            }
+        }
+        this.lastSyncedRefresh.set(name, record.lastRefreshMs);
+        this.logger.info('auth.mirror.synced', { sourceRuntimeId: runtime.id, name });
+        const message = `${name} has been refreshed by ${runtime.id} and synchronized to the other Codex homes.`;
+        await Promise.allSettled(this.runtimes.map((target) => target.notify?.(message)));
+        return true;
+    }
+    async ensureCanonicalDefaultCandidate() {
+        const names = await listAuthCandidateNames(this.canonicalDir);
+        if (names.length > 0)
+            return;
+        const authPath = path.join(this.canonicalDir, 'auth.json');
+        if (!(await exists(authPath)))
+            return;
+        const finalPath = await resolveFinalPath(authPath);
+        if (isAuthCandidateName(path.basename(finalPath)))
+            return;
+        await atomicCopy(authPath, path.join(this.canonicalDir, 'auth.json_default'));
+    }
+    async collectCandidateNames() {
+        const all = new Set(await listAuthCandidateNames(this.canonicalDir));
+        for (const runtime of this.runtimes) {
+            for (const name of await listAuthCandidateNames(runtime.authDir)) {
+                all.add(name);
+            }
+        }
+        return [...all];
+    }
+    async reconcileCandidateAtStartup(name) {
+        const paths = [
+            path.join(this.canonicalDir, name),
+            ...this.runtimes.map((runtime) => path.join(runtime.authDir, name)),
+        ];
+        const records = (await Promise.all(paths.map(async (sourcePath) => ({
+            sourcePath,
+            record: await readChatGptAuthRecord(sourcePath),
+        })))).filter((entry) => entry.record !== null);
+        if (records.length === 0)
+            return;
+        const accountIds = new Set(records.map((entry) => entry.record.accountId));
+        if (accountIds.size !== 1) {
+            this.logger.warn('auth.mirror.startup_conflict', { name });
+            return;
+        }
+        const newest = records.reduce((current, entry) => (entry.record.lastRefreshMs > current.record.lastRefreshMs ? entry : current));
+        this.lastSyncedRefresh.set(name, newest.record.lastRefreshMs);
+        for (const destination of paths) {
+            await atomicWrite(destination, newest.record.raw);
+        }
+    }
+    async resolveCanonicalCurrentCandidate() {
+        const finalPath = await resolveFinalPath(path.join(this.canonicalDir, 'auth.json'));
+        const name = path.basename(finalPath);
+        return isAuthCandidateName(name) ? name : null;
+    }
+}
+export function isAuthCandidateName(name) {
+    return name !== 'auth.json'
+        && !name.startsWith('.auth.json.')
+        && (name.startsWith('auth.json_') || name.startsWith('auth.json.') || name.startsWith('auth.json-'));
+}
+async function listAuthCandidateNames(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    return entries
+        .filter((entry) => (entry.isFile() || entry.isSymbolicLink()) && isAuthCandidateName(entry.name))
+        .map((entry) => entry.name);
+}
+async function readChatGptAuthRecord(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const accountId = typeof parsed.tokens?.account_id === 'string' ? parsed.tokens.account_id : '';
+        const lastRefreshMs = typeof parsed.last_refresh === 'string' ? Date.parse(parsed.last_refresh) : NaN;
+        if (!accountId || !Number.isFinite(lastRefreshMs))
+            return null;
+        return { raw, accountId, lastRefreshMs };
+    }
+    catch {
+        return null;
+    }
+}
+async function atomicCopy(source, destination) {
+    await atomicWrite(destination, await fs.readFile(source, 'utf8'));
+}
+async function atomicWrite(destination, contents) {
+    await fs.mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+    const temporary = path.join(path.dirname(destination), `.auth.json.${process.pid}.${Date.now()}.tmp`);
+    await fs.writeFile(temporary, contents, { encoding: 'utf8', mode: 0o600 });
+    await fs.rename(temporary, destination);
+}
+async function pointAuthSymlink(dir, candidateName) {
+    const temporary = path.join(dir, `.auth.json.${process.pid}.${Date.now()}.link`);
+    await fs.symlink(path.join(dir, candidateName), temporary);
+    await fs.rename(temporary, path.join(dir, 'auth.json'));
+}
+async function resolveFinalPath(sourcePath) {
+    try {
+        return await fs.realpath(sourcePath);
+    }
+    catch {
+        return sourcePath;
+    }
+}
+async function exists(filePath) {
+    return fs.lstat(filePath).then(() => true).catch(() => false);
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/codex_app/client.d.ts

@@ -65,6 +65,7 @@ export declare class CodexAppClient extends EventEmitter {
     private readonly serverStatePath;
     private readonly serverLogPath;
     private readonly logger;
+    private readonly childEnv;
     private child;
     private socket;
     private requestId;
@@ -75,7 +76,7 @@ export declare class CodexAppClient extends EventEmitter {
     private port;
     private connected;
     private userAgent;
-    constructor(codexCliBin: string, launchCommand: string, autolaunch: boolean, serverStatePath: string, serverLogPath: string, logger: Logger);
+    constructor(codexCliBin: string, launchCommand: string, autolaunch: boolean, serverStatePath: string, serverLogPath: string, logger: Logger, childEnv?: NodeJS.ProcessEnv | null);
     isConnected(): boolean;
     getUserAgent(): string | null;
     getServerStatus(): CodexAppServerRuntimeStatus;

package/dist/codex_app/client.js

@@ -13,6 +13,7 @@ export class CodexAppClient extends EventEmitter {
     serverStatePath;
     serverLogPath;
     logger;
+    childEnv;
     child = null;
     socket = null;
     requestId = 0;
@@ -23,7 +24,7 @@ export class CodexAppClient extends EventEmitter {
     port = null;
     connected = false;
     userAgent = null;
-    constructor(codexCliBin, launchCommand, autolaunch, serverStatePath, serverLogPath, logger) {
+    constructor(codexCliBin, launchCommand, autolaunch, serverStatePath, serverLogPath, logger, childEnv = null) {
         super();
         this.codexCliBin = codexCliBin;
         this.launchCommand = launchCommand;
@@ -31,6 +32,7 @@ export class CodexAppClient extends EventEmitter {
         this.serverStatePath = serverStatePath;
         this.serverLogPath = serverLogPath;
         this.logger = logger;
+        this.childEnv = childEnv;
     }
     isConnected() {
         return this.connected;
@@ -463,7 +465,12 @@ export class CodexAppClient extends EventEmitter {
             return;
         }
         if (this.autolaunch) {
-            const launcher = spawn(this.launchCommand, { shell: true, detached: true, stdio: 'ignore' });
+            const launcher = spawn(this.launchCommand, {
+                shell: true,
+                detached: true,
+                stdio: 'ignore',
+                env: this.childEnv ? { ...process.env, ...this.childEnv } : process.env,
+            });
             launcher.unref();
         }
         this.port = await reservePort();
@@ -473,6 +480,7 @@ export class CodexAppClient extends EventEmitter {
             child = spawn(this.codexCliBin, ['app-server', '--listen', `ws://127.0.0.1:${this.port}`], {
                 detached: true,
                 stdio: ['ignore', stdoutFd, stderrFd],
+                env: this.childEnv ? { ...process.env, ...this.childEnv } : process.env,
             });
         }
         finally {

package/dist/config.d.ts

@@ -7,12 +7,17 @@ export declare const DEFAULT_LOG_PATH: string;
 export declare const DEFAULT_LOCK_PATH: string;
 export declare const DEFAULT_CODEX_APP_SERVER_STATE_PATH: string;
 export declare const DEFAULT_CODEX_APP_SERVER_LOG_PATH: string;
+export declare const DEFAULT_CODEX_TELEGRAM_HOME: string;
 export declare const DEFAULT_ENV_PATH: string;
 export declare function resolveEnvPath(): string;
 export declare function getLoadedEnvPath(): string | null;
 export declare function loadEnv(): void;
 export interface AppConfig {
     tgBotToken: string;
+    tgBotTokens: string[];
+    tgMultiBotMode: boolean;
+    tgScopeBotId: string | null;
+    tgRequireExplicitGroupAddressing: boolean;
     tgAllowedUserId: string;
     tgAllowedChatId: string | null;
     tgAllowedTopicId: number | null;
@@ -21,6 +26,8 @@ export interface AppConfig {
     codexAppLaunchCmd: string;
     codexAppServerStatePath: string;
     codexAppServerLogPath: string;
+    codexAuthDir: string | null;
+    codexHome: string | null;
     codexAppSyncOnOpen: boolean;
     codexAppSyncOnTurnComplete: boolean;
     storePath: string;

package/dist/config.js

@@ -10,6 +10,7 @@ export const DEFAULT_LOG_PATH = path.join(APP_HOME, 'logs', 'service.log');
 export const DEFAULT_LOCK_PATH = path.join(APP_HOME, 'runtime', 'bridge.lock');
 export const DEFAULT_CODEX_APP_SERVER_STATE_PATH = path.join(APP_HOME, 'runtime', 'codex-app-server.json');
 export const DEFAULT_CODEX_APP_SERVER_LOG_PATH = path.join(APP_HOME, 'logs', 'codex-app-server.log');
+export const DEFAULT_CODEX_TELEGRAM_HOME = path.join(APP_HOME, 'codex', 'telegram');
 export const DEFAULT_ENV_PATH = path.join(APP_HOME, '.env');
 let envLoaded = false;
 let loadedEnvPath = null;
@@ -37,8 +38,22 @@ export function loadEnv() {
 }
 export function loadConfig() {
     loadEnv();
+    const configuredTokens = parseCommaSeparatedIds(process.env.TG_BOT_TOKENS);
+    const legacyToken = optional('TG_BOT_TOKEN');
+    const tgBotTokens = configuredTokens.length > 0
+        ? configuredTokens
+        : legacyToken
+            ? [legacyToken]
+            : [];
+    if (tgBotTokens.length === 0) {
+        throw new Error('TG_BOT_TOKENS or TG_BOT_TOKEN is required');
+    }
     const config = {
-        tgBotToken: required('TG_BOT_TOKEN'),
+        tgBotToken: tgBotTokens[0],
+        tgBotTokens,
+        tgMultiBotMode: configuredTokens.length > 0,
+        tgScopeBotId: null,
+        tgRequireExplicitGroupAddressing: configuredTokens.length > 1,
         tgAllowedUserId: required('TG_ALLOWED_USER_ID'),
         tgAllowedChatId: optional('TG_ALLOWED_CHAT_ID'),
         tgAllowedTopicId: nullableIntEnv('TG_ALLOWED_TOPIC_ID'),
@@ -47,6 +62,8 @@ export function loadConfig() {
         codexAppLaunchCmd: process.env.CODEX_APP_LAUNCH_CMD || 'codex app',
         codexAppServerStatePath: process.env.CODEX_APP_SERVER_STATE_PATH || DEFAULT_CODEX_APP_SERVER_STATE_PATH,
         codexAppServerLogPath: process.env.CODEX_APP_SERVER_LOG_PATH || DEFAULT_CODEX_APP_SERVER_LOG_PATH,
+        codexAuthDir: process.env.CODEX_AUTH_DIR?.trim() || null,
+        codexHome: process.env.CODEX_HOME?.trim() || null,
         codexAppSyncOnOpen: boolEnv('CODEX_APP_SYNC_ON_OPEN', true),
         codexAppSyncOnTurnComplete: boolEnv('CODEX_APP_SYNC_ON_TURN_COMPLETE', false),
         storePath: process.env.STORE_PATH || DEFAULT_STORE_PATH,

package/dist/controller/controller.d.ts

@@ -6,6 +6,11 @@ import type { TelegramGateway, TelegramTextEvent } from '../telegram/gateway.js'
 import { BridgeMessagingRouter } from '../channels/bridge_messaging_router.js';
 import type { CodexAppClient } from '../codex_app/client.js';
 import type { SelfUpdateRuntime } from '../update.js';
+export interface CoreCoordinator {
+    canSelfUpdate?: () => boolean;
+    authCandidateUpdated?: (runtimeId: string, candidateName: string) => Promise<void>;
+    statusUpdated?: (status: RuntimeStatus) => void;
+}
 export declare class BridgeSessionCore {
     private readonly config;
     private readonly store;
@@ -13,6 +18,7 @@ export declare class BridgeSessionCore {
     private readonly bot;
     private readonly app;
     private readonly selfUpdater;
+    private readonly coordinator;
     private activeTurns;
     private activeTurnsByTurnId;
     private observedThreadWatchers;
@@ -51,7 +57,7 @@ export declare class BridgeSessionCore {
     /** Last threads-panel pagination state per scope (Telegram inline nav + /open index alignment). */
     private threadListPresentationState;
     private readonly messaging;
-    constructor(config: AppConfig, store: BridgeStore, logger: Logger, bot: TelegramGateway, app: CodexAppClient, outbound: BridgeMessagingRouter, selfUpdater?: SelfUpdateRuntime | null);
+    constructor(config: AppConfig, store: BridgeStore, logger: Logger, bot: TelegramGateway, app: CodexAppClient, outbound: BridgeMessagingRouter, selfUpdater?: SelfUpdateRuntime | null, coordinator?: CoreCoordinator | null);
     /** Wire Telegram inbound events. Call before {@link startCodexApp}. */
     registerTelegramInboundHandlers(): void;
     /**
@@ -140,6 +146,10 @@ export declare class BridgeSessionCore {
     private stageAttachments;
     private registerActiveTurn;
     private createActiveTurnState;
+    isIdleForServiceUpdate(): boolean;
+    private hasLocalBlockingActivity;
+    private authRuntimeId;
+    private ownsScope;
     private setActiveTurn;
     private getActiveTurn;
     private getActiveTurnsForTurn;
@@ -261,6 +271,7 @@ export declare class BridgeSessionCore {
     private retryTurnAfterAuthRotation;
     private selectNextCodexAuthCandidate;
     private listCodexAuthState;
+    private resolveAuthDir;
     private readCodexAuthSwitchLabels;
     private codexAuthSwitchParams;
     private switchCodexAuthAndRestart;
@@ -277,6 +288,7 @@ export declare class BridgeSessionCore {
     private readCodexAuthQuotaSnapshots;
     private writeCodexAuthQuotaSnapshots;
     private codexAuthQuotaSnapshotPath;
+    private runtimeSnapshotFilename;
     private sendThreadContextSummary;
     private handleModelCommand;
     private handleEffortCommand;