@foxden-app/foxclaw 0.3.13 → 0.3.15

package/README.md

@@ -84,7 +84,7 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 配置文件默认在 `~/.foxclaw/.env`。想放别处的话设 `FOXCLAW_ENV=/path/to/.env`。
 
-`foxclaw start` 会自动检查环境并安装/重启后台服务，幂等操作，升级后再跑一次就行。
+`foxclaw start` 会自动检查环境并安装/重启后台服务。后续升级直接运行 `foxclaw update`，它会沿用当前的 npm/pnpm 全局安装方式，完成安装、自检和服务重启。
 
 FoxClaw 只响应 `TG_ALLOWED_USER_ID` 的消息——把机器人拉进群不代表群里所有人都能用。
 
@@ -150,6 +150,7 @@ journalctl --user -u foxclaw.service -f
 ```bash
 foxclaw status
 foxclaw restart
+foxclaw update
 foxclaw stop
 ```
 
@@ -238,7 +239,7 @@ FoxClaw 会把 `codex app-server` 作为 detached 子进程启动，记录其 pi
 - `/setup` — 统一设置面板
 - `/fast <on|off|toggle>`
 - `/active <steer|queue>`
-- `/status`、`/account`、`/quota`
+- `/status`、`/account`、`/quota`、`/update`
 - `/quota_nudge <credits|usage_limit> confirm`
 - `/login_device`、`/login_cancel [id]`、`/logout confirm`
 - `/auth [list|use <n>|enable <n>|disable <n>|reload|add <name>]`
@@ -290,6 +291,7 @@ foxclaw doctor
 foxclaw status
 foxclaw start
 foxclaw restart
+foxclaw update
 foxclaw stop
 foxclaw uninstall-systemd
 ```

package/README_EN.md

@@ -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. It is idempotent — run it again after upgrading.
+`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 accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a group does not make it available to every group member.
 
@@ -150,6 +150,7 @@ You can also use the wrapper commands:
 ```bash
 foxclaw status
 foxclaw restart
+foxclaw update
 foxclaw stop
 ```
 
@@ -238,7 +239,7 @@ No static Codex app-server port is required in normal installs.
 - `/setup` — unified preference panel
 - `/fast <on|off|toggle>`
 - `/active <steer|queue>`
-- `/status`, `/account`, `/quota`
+- `/status`, `/account`, `/quota`, `/update`
 - `/quota_nudge <credits|usage_limit> confirm`
 - `/login_device`, `/login_cancel [id]`, `/logout confirm`
 - `/auth [list|use <n>|enable <n>|disable <n>|reload|add <name>]`
@@ -290,6 +291,7 @@ foxclaw doctor
 foxclaw status
 foxclaw start
 foxclaw restart
+foxclaw update
 foxclaw stop
 foxclaw uninstall-systemd
 ```

package/dist/controller/controller.d.ts

@@ -5,12 +5,14 @@ import type { RuntimeStatus } from '../types.js';
 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 declare class BridgeSessionCore {
     private readonly config;
     private readonly store;
     private readonly logger;
     private readonly bot;
     private readonly app;
+    private readonly selfUpdater;
     private activeTurns;
     private activeTurnsByTurnId;
     private observedThreadWatchers;
@@ -38,13 +40,14 @@ export declare class BridgeSessionCore {
     private locks;
     private approvalTimers;
     private submittedUserInputTimers;
+    private selfUpdatePollTimer;
     private attachedThreads;
     private botUsername;
     private lastError;
     /** 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);
+    constructor(config: AppConfig, store: BridgeStore, logger: Logger, bot: TelegramGateway, app: CodexAppClient, outbound: BridgeMessagingRouter, selfUpdater?: SelfUpdateRuntime | null);
     /** Wire Telegram inbound events. Call before {@link startCodexApp}. */
     registerTelegramInboundHandlers(): void;
     /**
@@ -203,6 +206,11 @@ export declare class BridgeSessionCore {
     private handleFastCommand;
     private setCollaborationMode;
     private handleAuthReloadCommand;
+    private handleSelfUpdateCommand;
+    private scheduleSelfUpdateStatusPoll;
+    private clearSelfUpdateStatusPoll;
+    private pollSelfUpdateStatus;
+    private formatSelfUpdateResult;
     private handleAuthCommand;
     private handleAuthUseCommand;
     private handleAuthToggleCommand;

package/dist/controller/controller.js

@@ -25,6 +25,7 @@ const OBSERVED_CLI_USER_LABEL = 'codex-cli-user';
 const DEFAULT_COLLABORATION_MODE = 'default';
 const CODEX_LOCAL_USAGE_CACHE_MS = 30_000;
 const USER_INPUT_SUBMITTED_NOTICE_MS = 90_000;
+const SELF_UPDATE_STATUS_POLL_MS = 1000;
 const PLAN_IMPLEMENTATION_CODING_MESSAGE = 'Implement the plan.';
 const PLAN_IMPLEMENTATION_CLEAR_CONTEXT_PREFIX = 'A previous agent produced the plan below to accomplish the user\'s task. Implement the plan in a fresh context. Treat the plan as the source of user intent, re-read files as needed, and carry the work through implementation and verification.';
 const PINNED_HELP_COMMANDS = [
@@ -39,6 +40,7 @@ const DYNAMIC_HELP_COMMANDS = [
     { key: 'active', line: '/active <steer|queue>' },
     { key: 'account', line: '/account' },
     { key: 'quota', line: '/quota' },
+    { key: 'update', line: '/update' },
     { key: 'login_device', line: '/login_device' },
     { key: 'threads_archived', line: '/threads archived [query]' },
     { key: 'open', line: '/open <n>' },
@@ -88,6 +90,7 @@ export class BridgeSessionCore {
     logger;
     bot;
     app;
+    selfUpdater;
     activeTurns = new Map();
     activeTurnsByTurnId = new Map();
     observedThreadWatchers = new Map();
@@ -115,18 +118,20 @@ export class BridgeSessionCore {
     locks = new Map();
     approvalTimers = new Map();
     submittedUserInputTimers = new Map();
+    selfUpdatePollTimer = null;
     attachedThreads = new Set();
     botUsername = null;
     lastError = null;
     /** Last threads-panel pagination state per scope (Telegram inline nav + /open index alignment). */
     threadListPresentationState = new Map();
     messaging;
-    constructor(config, store, logger, bot, app, outbound) {
+    constructor(config, store, logger, bot, app, outbound, selfUpdater = null) {
         this.config = config;
         this.store = store;
         this.logger = logger;
         this.bot = bot;
         this.app = app;
+        this.selfUpdater = selfUpdater;
         this.messaging = outbound;
     }
     /** Wire Telegram inbound events. Call before {@link startCodexApp}. */
@@ -188,6 +193,7 @@ export class BridgeSessionCore {
         await this.bot.start();
         this.botUsername = this.bot.username;
         this.updateStatus();
+        this.scheduleSelfUpdateStatusPoll(0);
     }
     /** Telegram-only default startup (single channel). */
     async start() {
@@ -223,6 +229,7 @@ export class BridgeSessionCore {
             clearTimeout(timer);
         }
         this.submittedUserInputTimers.clear();
+        this.clearSelfUpdateStatusPoll();
         await this.app.stop({ terminateServer: false });
         this.updateStatus();
     }
@@ -382,6 +389,10 @@ export class BridgeSessionCore {
                 await this.handleQuotaCommand(scopeId, locale);
                 return;
             }
+            case 'update': {
+                await this.handleSelfUpdateCommand(scopeId, locale);
+                return;
+            }
             case 'quota_nudge': {
                 await this.handleQuotaNudgeCommand(scopeId, locale, args);
                 return;
@@ -3641,6 +3652,74 @@ export class BridgeSessionCore {
         lines.push(...await this.buildCodexUsageStatusLines(locale));
         await this.sendMessage(scopeId, lines.join('\n'));
     }
+    async handleSelfUpdateCommand(scopeId, locale) {
+        if (!this.selfUpdater) {
+            await this.sendMessage(scopeId, t(locale, 'update_unavailable'));
+            return;
+        }
+        if (this.activeTurns.size > 0 || this.store.countPendingApprovals() > 0 || this.pendingUserInputs.size > 0 || this.pendingMcpElicitations.size > 0) {
+            await this.sendMessage(scopeId, t(locale, 'update_blocked_active'));
+            return;
+        }
+        const status = await this.selfUpdater.readStatus();
+        if (status?.state === 'pending') {
+            await this.sendMessage(scopeId, t(locale, 'update_already_running'));
+            this.scheduleSelfUpdateStatusPoll();
+            return;
+        }
+        if (status) {
+            await this.selfUpdater.clearStatus();
+        }
+        await this.sendMessage(scopeId, t(locale, 'update_started'));
+        try {
+            await this.selfUpdater.launch(scopeId, locale);
+            this.scheduleSelfUpdateStatusPoll();
+        }
+        catch (error) {
+            await this.selfUpdater.clearStatus().catch(() => undefined);
+            await this.sendMessage(scopeId, t(locale, 'update_failed', { error: formatUserError(error) }));
+        }
+    }
+    scheduleSelfUpdateStatusPoll(delay = SELF_UPDATE_STATUS_POLL_MS) {
+        if (!this.selfUpdater || this.selfUpdatePollTimer) {
+            return;
+        }
+        this.selfUpdatePollTimer = setTimeout(() => {
+            this.selfUpdatePollTimer = null;
+            void this.pollSelfUpdateStatus().catch((error) => {
+                this.logger.error('self_update.poll_failed', { error: toErrorMeta(error) });
+                this.scheduleSelfUpdateStatusPoll();
+            });
+        }, delay);
+    }
+    clearSelfUpdateStatusPoll() {
+        if (!this.selfUpdatePollTimer) {
+            return;
+        }
+        clearTimeout(this.selfUpdatePollTimer);
+        this.selfUpdatePollTimer = null;
+    }
+    async pollSelfUpdateStatus() {
+        const status = await this.selfUpdater?.readStatus();
+        if (!status) {
+            return;
+        }
+        if (status.state === 'pending') {
+            this.scheduleSelfUpdateStatusPoll();
+            return;
+        }
+        await this.sendMessage(status.scopeId, this.formatSelfUpdateResult(status));
+        await this.selfUpdater?.clearStatus();
+    }
+    formatSelfUpdateResult(status) {
+        if (status.state === 'succeeded') {
+            return t(status.locale, 'update_succeeded', {
+                from: status.fromVersion,
+                to: status.toVersion ?? t(status.locale, 'unknown'),
+            });
+        }
+        return t(status.locale, 'update_failed', { error: status.error ?? t(status.locale, 'unknown') });
+    }
     async handleAuthCommand(scopeId, locale, args) {
         const action = args[0]?.toLowerCase() ?? 'list';
         if (action === 'reload' || action === 'restart') {

package/dist/i18n.d.ts

@@ -46,6 +46,7 @@ declare const MESSAGES: {
         readonly cmd_desc_fast: "Toggle Fast mode";
         readonly cmd_desc_active: "Active-turn message behavior";
         readonly cmd_desc_status: "Bridge status";
+        readonly cmd_desc_update: "Update and restart FoxClaw";
         readonly cmd_desc_account: "Codex account";
         readonly cmd_desc_quota: "Codex quota";
         readonly cmd_desc_login_device: "ChatGPT device login";
@@ -115,6 +116,12 @@ declare const MESSAGES: {
         readonly status_codex_local_usage_unavailable: "Codex local history: unavailable ({error})";
         readonly status_codex_credits: "Codex credits: {value}";
         readonly status_codex_limit_reached: "Codex limit: {value}";
+        readonly update_started: "FoxClaw update started. I will report here after installation, checks, and service restart complete.";
+        readonly update_succeeded: "FoxClaw updated and restarted: {from} -> {to}.";
+        readonly update_failed: "FoxClaw update failed: {error}\nRun foxclaw update in a terminal for details.";
+        readonly update_unavailable: "Self-update is unavailable in this runtime. Run foxclaw update in a terminal.";
+        readonly update_already_running: "A FoxClaw update is already running. I will report here when it finishes.";
+        readonly update_blocked_active: "Cannot update FoxClaw while a turn, approval, or question is active. Wait or use /interrupt first.";
         readonly auth_reload_restarting: "Restarting Codex app-server to reload auth...";
         readonly auth_reload_done: "Codex app-server restarted. Current auth has been reloaded.";
         readonly auth_reload_blocked_active: "Cannot reload Codex auth while a turn, approval, or question is active. Wait or use /interrupt first.";
@@ -600,6 +607,7 @@ declare const MESSAGES: {
         readonly cmd_desc_fast: "切换 Fast 模式";
         readonly cmd_desc_active: "运行中新消息处理方式";
         readonly cmd_desc_status: "查看桥接状态";
+        readonly cmd_desc_update: "升级并重启 FoxClaw";
         readonly cmd_desc_account: "Codex 账号";
         readonly cmd_desc_quota: "Codex 用量";
         readonly cmd_desc_login_device: "ChatGPT 设备登录";
@@ -669,6 +677,12 @@ declare const MESSAGES: {
         readonly status_codex_local_usage_unavailable: "Codex 本地历史：无法获取（{error}）";
         readonly status_codex_credits: "Codex 额度：{value}";
         readonly status_codex_limit_reached: "Codex 限制：{value}";
+        readonly update_started: "已开始升级 FoxClaw。安装、自检和服务重启完成后，我会在这里回报结果。";
+        readonly update_succeeded: "FoxClaw 已升级并重启：{from} -> {to}。";
+        readonly update_failed: "FoxClaw 升级失败：{error}\n请在终端运行 foxclaw update 查看详情。";
+        readonly update_unavailable: "当前运行方式不支持自升级，请在终端运行 foxclaw update。";
+        readonly update_already_running: "FoxClaw 升级已经在进行中，结束后我会在这里回报结果。";
+        readonly update_blocked_active: "当前有回复、审批或问题在进行中，不能升级 FoxClaw。请先等待，或使用 /interrupt。";
         readonly auth_reload_restarting: "正在重启 Codex app-server 以重新读取 auth...";
         readonly auth_reload_done: "Codex app-server 已重启，当前 auth 已重新读取。";
         readonly auth_reload_blocked_active: "当前有回复、审批或问题在进行中，不能重载 Codex auth。请先等待，或使用 /interrupt。";

package/dist/i18n.js

@@ -44,6 +44,7 @@ const MESSAGES = {
         cmd_desc_fast: 'Toggle Fast mode',
         cmd_desc_active: 'Active-turn message behavior',
         cmd_desc_status: 'Bridge status',
+        cmd_desc_update: 'Update and restart FoxClaw',
         cmd_desc_account: 'Codex account',
         cmd_desc_quota: 'Codex quota',
         cmd_desc_login_device: 'ChatGPT device login',
@@ -113,6 +114,12 @@ const MESSAGES = {
         status_codex_local_usage_unavailable: 'Codex local history: unavailable ({error})',
         status_codex_credits: 'Codex credits: {value}',
         status_codex_limit_reached: 'Codex limit: {value}',
+        update_started: 'FoxClaw update started. I will report here after installation, checks, and service restart complete.',
+        update_succeeded: 'FoxClaw updated and restarted: {from} -> {to}.',
+        update_failed: 'FoxClaw update failed: {error}\nRun foxclaw update in a terminal for details.',
+        update_unavailable: 'Self-update is unavailable in this runtime. Run foxclaw update in a terminal.',
+        update_already_running: 'A FoxClaw update is already running. I will report here when it finishes.',
+        update_blocked_active: 'Cannot update FoxClaw while a turn, approval, or question is active. Wait or use /interrupt first.',
         auth_reload_restarting: 'Restarting Codex app-server to reload auth...',
         auth_reload_done: 'Codex app-server restarted. Current auth has been reloaded.',
         auth_reload_blocked_active: 'Cannot reload Codex auth while a turn, approval, or question is active. Wait or use /interrupt first.',
@@ -598,6 +605,7 @@ const MESSAGES = {
         cmd_desc_fast: '切换 Fast 模式',
         cmd_desc_active: '运行中新消息处理方式',
         cmd_desc_status: '查看桥接状态',
+        cmd_desc_update: '升级并重启 FoxClaw',
         cmd_desc_account: 'Codex 账号',
         cmd_desc_quota: 'Codex 用量',
         cmd_desc_login_device: 'ChatGPT 设备登录',
@@ -667,6 +675,12 @@ const MESSAGES = {
         status_codex_local_usage_unavailable: 'Codex 本地历史：无法获取（{error}）',
         status_codex_credits: 'Codex 额度：{value}',
         status_codex_limit_reached: 'Codex 限制：{value}',
+        update_started: '已开始升级 FoxClaw。安装、自检和服务重启完成后，我会在这里回报结果。',
+        update_succeeded: 'FoxClaw 已升级并重启：{from} -> {to}。',
+        update_failed: 'FoxClaw 升级失败：{error}\n请在终端运行 foxclaw update 查看详情。',
+        update_unavailable: '当前运行方式不支持自升级，请在终端运行 foxclaw update。',
+        update_already_running: 'FoxClaw 升级已经在进行中，结束后我会在这里回报结果。',
+        update_blocked_active: '当前有回复、审批或问题在进行中，不能升级 FoxClaw。请先等待，或使用 /interrupt。',
         auth_reload_restarting: '正在重启 Codex app-server 以重新读取 auth...',
         auth_reload_done: 'Codex app-server 已重启，当前 auth 已重新读取。',
         auth_reload_blocked_active: '当前有回复、审批或问题在进行中，不能重载 Codex auth。请先等待，或使用 /interrupt。',
@@ -1121,6 +1135,7 @@ export function getTelegramCommands(locale) {
         { command: 'help', description: t(locale, 'cmd_desc_help') },
         { command: 'setup', description: t(locale, 'cmd_desc_setup') },
         { command: 'status', description: t(locale, 'cmd_desc_status') },
+        { command: 'update', description: t(locale, 'cmd_desc_update') },
         { command: 'threads', description: t(locale, 'cmd_desc_threads') },
         { command: 'auth', description: t(locale, 'cmd_desc_auth') },
         { command: 'fast', description: t(locale, 'cmd_desc_fast') },

package/dist/main.js

@@ -9,6 +9,7 @@ import { APP_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PATH, DEFAULT_STATUS_PATH, getL
 import { acquireProcessLock, LockHeldError } from './lock.js';
 import { readRuntimeStatus, writeRuntimeStatus } from './runtime.js';
 import { refreshFoxclawExecStartDropIns, removeFoxclawExecStartDropIns } from './systemd.js';
+import { createSelfUpdateRuntime, inferPnpmHomeFromEntryPoint, performSelfUpdate } from './update.js';
 const rawCommand = process.argv[2];
 const command = rawCommand || 'serve';
 loadEnv();
@@ -53,6 +54,18 @@ async function main() {
         startService('restart');
         return;
     }
+    if (command === 'update') {
+        requireNode24(command);
+        const notificationFile = readOptionValue('--notification-file');
+        const options = {
+            entryPoint,
+            nodePath: process.execPath,
+            version: readPackageVersion(),
+            ...(notificationFile ? { notificationFile } : {}),
+        };
+        const outcome = performSelfUpdate(options);
+        process.exit(outcome.ok ? 0 : 1);
+    }
     if (command === 'stop') {
         stopService();
         return;
@@ -116,6 +129,7 @@ Usage:
   foxclaw doctor
   foxclaw status
   foxclaw start|restart|stop
+  foxclaw update
   foxclaw install-systemd|uninstall-systemd
   foxclaw install-launchd
   foxclaw weixin-login [account-id]
@@ -152,7 +166,14 @@ async function runServeCli() {
             ? new WeixinMessagingPort(store, (id) => loadWeixinAccount(config.weixinAccountsDir, id))
             : null;
         const outbound = new BridgeMessagingRouter(telegramMessaging, weixinMessaging);
-        const core = new BridgeSessionCore(config, store, logger, bot, app, outbound);
+        const selfUpdater = createSelfUpdateRuntime({
+            entryPoint,
+            nodePath: process.execPath,
+            version: readPackageVersion(),
+            statusPath: config.statusPath,
+            logPath: path.join(APP_HOME, 'logs', 'update.log'),
+        });
+        const core = new BridgeSessionCore(config, store, logger, bot, app, outbound, selfUpdater);
         const telegram = new TelegramChannelAdapter(core);
         if (config.wxEnabled) {
             weixinAdapter = new WeixinChannelAdapter(core, store, config, logger);
@@ -436,6 +457,11 @@ function escapeRegExp(value) {
 function editorCommand(envPath) {
     return `${process.env.EDITOR?.trim() || '$EDITOR'} ${envPath}`;
 }
+function readOptionValue(option) {
+    const index = process.argv.indexOf(option);
+    const value = index >= 0 ? process.argv[index + 1] : undefined;
+    return value && !value.startsWith('--') ? value : undefined;
+}
 function startService(action) {
     if (!runDoctorChecks()) {
         console.error('');
@@ -750,9 +776,17 @@ function stopLaunchd() {
     console.log(`Stopped ${plist}`);
 }
 function buildServicePath(nodeDir) {
+    const pnpmPath = resolveCommand('pnpm');
+    const inferredPnpmHome = inferPnpmHomeFromEntryPoint(entryPoint) || '';
+    const configuredPnpmHome = process.env.PNPM_HOME?.trim() || '';
     const parts = [
         path.join(process.env.HOME || '', '.local', 'bin'),
         nodeDir,
+        inferredPnpmHome,
+        inferredPnpmHome ? path.join(inferredPnpmHome, 'bin') : '',
+        configuredPnpmHome,
+        configuredPnpmHome ? path.join(configuredPnpmHome, 'bin') : '',
+        pnpmPath ? path.dirname(pnpmPath) : '',
         '/usr/local/sbin',
         '/usr/local/bin',
         '/usr/sbin',

package/dist/update.d.ts

@@ -0,0 +1,50 @@
+import type { AppLocale } from './types.js';
+export type SelfUpdateState = 'pending' | 'succeeded' | 'failed';
+export interface SelfUpdateStatus {
+    state: SelfUpdateState;
+    scopeId: string;
+    locale: AppLocale;
+    fromVersion: string;
+    toVersion: string | null;
+    error: string | null;
+    updatedAt: string;
+}
+export interface SelfUpdateRuntime {
+    launch(scopeId: string, locale: AppLocale): Promise<void>;
+    readStatus(): Promise<SelfUpdateStatus | null>;
+    clearStatus(): Promise<void>;
+}
+export interface SelfUpdateInstaller {
+    manager: 'npm' | 'pnpm';
+    command: string;
+    installArgs: string[];
+    rootArgs: string[];
+}
+interface CreateSelfUpdateRuntimeOptions {
+    entryPoint: string;
+    nodePath: string;
+    version: string;
+    statusPath: string;
+    logPath: string;
+}
+interface PerformSelfUpdateOptions {
+    entryPoint: string;
+    nodePath: string;
+    version: string;
+    notificationFile?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface SelfUpdateOutcome {
+    ok: boolean;
+    fromVersion: string;
+    toVersion: string | null;
+    error: string | null;
+}
+export declare function selfUpdateStatusPath(statusPath: string): string;
+export declare function inferPnpmHomeFromEntryPoint(entryPoint: string): string | null;
+export declare function resolveSelfUpdateInstaller(entryPoint: string, nodePath?: string, exists?: (target: string) => boolean, env?: NodeJS.ProcessEnv): SelfUpdateInstaller;
+export declare function readSelfUpdateStatus(statusFile: string): SelfUpdateStatus | null;
+export declare function writeSelfUpdateStatus(statusFile: string, status: SelfUpdateStatus): void;
+export declare function createSelfUpdateRuntime(options: CreateSelfUpdateRuntimeOptions): SelfUpdateRuntime;
+export declare function performSelfUpdate(options: PerformSelfUpdateOptions): SelfUpdateOutcome;
+export {};

package/dist/update.js

@@ -0,0 +1,251 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawn, spawnSync } from 'node:child_process';
+const PACKAGE_SPEC = '@foxden-app/foxclaw@latest';
+const UPDATE_STATUS_FILENAME = 'self-update.json';
+export function selfUpdateStatusPath(statusPath) {
+    return path.join(path.dirname(statusPath), UPDATE_STATUS_FILENAME);
+}
+export function inferPnpmHomeFromEntryPoint(entryPoint) {
+    const normalizedEntryPoint = entryPoint.replace(/\\/g, '/');
+    const globalMarker = '/global/';
+    const globalIndex = normalizedEntryPoint.indexOf(globalMarker);
+    if (globalIndex <= 0 || !normalizedEntryPoint.includes('/.pnpm/')) {
+        return null;
+    }
+    return normalizedEntryPoint.slice(0, globalIndex);
+}
+export function resolveSelfUpdateInstaller(entryPoint, nodePath = process.execPath, exists = fs.existsSync, env = process.env) {
+    const pnpmHome = inferPnpmHomeFromEntryPoint(entryPoint);
+    if (pnpmHome) {
+        const commandName = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm';
+        const candidates = executableCandidates(commandName, nodePath, env, [
+            path.join(pnpmHome, commandName),
+            path.join(pnpmHome, 'bin', commandName),
+            env.PNPM_HOME?.trim() ? path.join(env.PNPM_HOME.trim(), commandName) : '',
+            env.PNPM_HOME?.trim() ? path.join(env.PNPM_HOME.trim(), 'bin', commandName) : '',
+        ]);
+        const pnpmCommand = candidates.find((candidate) => exists(candidate));
+        if (pnpmCommand) {
+            return {
+                manager: 'pnpm',
+                command: pnpmCommand,
+                installArgs: ['add', '--global', PACKAGE_SPEC],
+                rootArgs: ['root', '--global'],
+            };
+        }
+        const npmCommandName = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+        const npmCommand = executableCandidates(npmCommandName, nodePath, env)
+            .find((candidate) => exists(candidate)) ?? npmCommandName;
+        return {
+            manager: 'pnpm',
+            command: npmCommand,
+            installArgs: ['exec', '--yes', '--package=pnpm@latest', '--', 'pnpm', 'add', '--global', PACKAGE_SPEC],
+            rootArgs: ['exec', '--yes', '--package=pnpm@latest', '--', 'pnpm', 'root', '--global'],
+        };
+    }
+    const adjacentNpm = path.join(path.dirname(nodePath), process.platform === 'win32' ? 'npm.cmd' : 'npm');
+    return {
+        manager: 'npm',
+        command: exists(adjacentNpm) ? adjacentNpm : (process.platform === 'win32' ? 'npm.cmd' : 'npm'),
+        installArgs: ['install', '--global', PACKAGE_SPEC],
+        rootArgs: ['root', '--global'],
+    };
+}
+export function readSelfUpdateStatus(statusFile) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(statusFile, 'utf8'));
+        if ((parsed.state !== 'pending' && parsed.state !== 'succeeded' && parsed.state !== 'failed')
+            || typeof parsed.scopeId !== 'string'
+            || (parsed.locale !== 'en' && parsed.locale !== 'zh')
+            || typeof parsed.fromVersion !== 'string'
+            || typeof parsed.updatedAt !== 'string') {
+            return null;
+        }
+        return {
+            state: parsed.state,
+            scopeId: parsed.scopeId,
+            locale: parsed.locale,
+            fromVersion: parsed.fromVersion,
+            toVersion: typeof parsed.toVersion === 'string' ? parsed.toVersion : null,
+            error: typeof parsed.error === 'string' ? parsed.error : null,
+            updatedAt: parsed.updatedAt,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSelfUpdateStatus(statusFile, status) {
+    fs.mkdirSync(path.dirname(statusFile), { recursive: true });
+    const temporaryFile = `${statusFile}.${process.pid}.tmp`;
+    fs.writeFileSync(temporaryFile, `${JSON.stringify(status, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(temporaryFile, statusFile);
+}
+export function createSelfUpdateRuntime(options) {
+    const statusFile = selfUpdateStatusPath(options.statusPath);
+    return {
+        async launch(scopeId, locale) {
+            const current = readSelfUpdateStatus(statusFile);
+            if (current?.state === 'pending') {
+                throw new Error('A FoxClaw update is already running.');
+            }
+            writeSelfUpdateStatus(statusFile, {
+                state: 'pending',
+                scopeId,
+                locale,
+                fromVersion: options.version,
+                toVersion: null,
+                error: null,
+                updatedAt: new Date().toISOString(),
+            });
+            fs.mkdirSync(path.dirname(options.logPath), { recursive: true });
+            const logFd = fs.openSync(options.logPath, 'a', 0o600);
+            try {
+                const child = spawn(options.nodePath, [options.entryPoint, 'update', '--notification-file', statusFile], {
+                    detached: true,
+                    stdio: ['ignore', logFd, logFd],
+                    env: process.env,
+                });
+                child.unref();
+            }
+            catch (error) {
+                writeSelfUpdateStatus(statusFile, {
+                    state: 'failed',
+                    scopeId,
+                    locale,
+                    fromVersion: options.version,
+                    toVersion: null,
+                    error: formatError(error),
+                    updatedAt: new Date().toISOString(),
+                });
+                throw error;
+            }
+            finally {
+                fs.closeSync(logFd);
+            }
+        },
+        async readStatus() {
+            return readSelfUpdateStatus(statusFile);
+        },
+        async clearStatus() {
+            fs.rmSync(statusFile, { force: true });
+        },
+    };
+}
+export function performSelfUpdate(options) {
+    const env = options.env ?? process.env;
+    let toVersion = null;
+    try {
+        const installer = resolveSelfUpdateInstaller(options.entryPoint, options.nodePath, fs.existsSync, env);
+        const installerEnv = buildInstallerEnv(options.entryPoint, installer, env);
+        console.log(`[UPDATE] Installing ${PACKAGE_SPEC} with ${installer.manager}...`);
+        runInherited(installer.command, installer.installArgs, installerEnv);
+        const updatedEntryPoint = resolveUpdatedEntryPoint(installer, installerEnv);
+        toVersion = readInstalledPackageVersion(updatedEntryPoint);
+        console.log('[UPDATE] Running checks and restarting the FoxClaw service...');
+        runInherited(options.nodePath, [updatedEntryPoint, 'start'], installerEnv);
+        completeNotification(options.notificationFile, 'succeeded', toVersion, null);
+        console.log(`[OK] FoxClaw updated and restarted: ${options.version} -> ${toVersion}`);
+        return {
+            ok: true,
+            fromVersion: options.version,
+            toVersion,
+            error: null,
+        };
+    }
+    catch (error) {
+        const message = formatError(error);
+        completeNotification(options.notificationFile, 'failed', toVersion, message);
+        console.error(`[FAIL] FoxClaw update failed: ${message}`);
+        return {
+            ok: false,
+            fromVersion: options.version,
+            toVersion,
+            error: message,
+        };
+    }
+}
+function executableCandidates(commandName, nodePath, env, preferred = []) {
+    return [
+        ...preferred,
+        path.join(path.dirname(nodePath), commandName),
+        ...(env.PATH || '').split(path.delimiter).filter(Boolean).map((dir) => path.join(dir, commandName)),
+    ].filter((candidate, index, all) => candidate && all.indexOf(candidate) === index);
+}
+function buildInstallerEnv(entryPoint, installer, env) {
+    const pnpmHome = installer.manager === 'pnpm' ? inferPnpmHomeFromEntryPoint(entryPoint) : null;
+    if (!pnpmHome) {
+        return env;
+    }
+    const configuredPnpmHome = env.PNPM_HOME?.trim() || pnpmHome;
+    const pathEntries = [
+        configuredPnpmHome,
+        path.join(configuredPnpmHome, 'bin'),
+        pnpmHome,
+        path.join(pnpmHome, 'bin'),
+        ...(env.PATH || '').split(path.delimiter).filter(Boolean),
+    ];
+    return {
+        ...env,
+        PNPM_HOME: configuredPnpmHome,
+        PATH: pathEntries.filter((entry, index, all) => all.indexOf(entry) === index).join(path.delimiter),
+    };
+}
+function runInherited(command, args, env) {
+    const result = spawnSync(command, args, { stdio: 'inherit', env });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        throw new Error(`${command} ${args.join(' ')} exited with status ${result.status ?? 'unknown'}.`);
+    }
+}
+function resolveUpdatedEntryPoint(installer, env) {
+    const result = spawnSync(installer.command, installer.rootArgs, { encoding: 'utf8', env });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        throw new Error(`Could not locate the updated global package root using ${installer.manager}.`);
+    }
+    const globalRoot = result.stdout.trim().split(/\r?\n/).filter(Boolean).at(-1);
+    if (!globalRoot) {
+        throw new Error(`Could not locate the updated global package root using ${installer.manager}.`);
+    }
+    const updatedEntryPoint = path.join(globalRoot, '@foxden-app', 'foxclaw', 'dist', 'main.js');
+    if (!fs.existsSync(updatedEntryPoint)) {
+        throw new Error(`Updated FoxClaw entry point was not found at ${updatedEntryPoint}.`);
+    }
+    return updatedEntryPoint;
+}
+function readInstalledPackageVersion(updatedEntryPoint) {
+    try {
+        const packageFile = path.resolve(path.dirname(updatedEntryPoint), '..', 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+        return typeof pkg.version === 'string' && pkg.version.trim() ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function completeNotification(notificationFile, state, toVersion, error) {
+    if (!notificationFile) {
+        return;
+    }
+    const pending = readSelfUpdateStatus(notificationFile);
+    if (!pending) {
+        return;
+    }
+    writeSelfUpdateStatus(notificationFile, {
+        ...pending,
+        state,
+        toVersion,
+        error,
+        updatedAt: new Date().toISOString(),
+    });
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/docs/install-for-beginners.md

@@ -277,10 +277,11 @@ foxclaw uninstall-systemd
 Update FoxClaw later:
 
 ```bash
-npm install -g @foxden-app/foxclaw@latest
-foxclaw start
+foxclaw update
 ```
 
+You can also send `/update` in an authorized Telegram chat. When no turn, approval, or question is active, it upgrades, checks, restarts the service, and reports the result after restart.
+
 ## Next Step
 
 After the first install works, read the [User Manual](./user-manual.md) for `/help`, `/setup`, `/threads`, `/watch`, `/auth`, Codex login, and multi-account auth rotation.

package/docs/troubleshooting.md

@@ -223,7 +223,7 @@ Then run:
 foxclaw restart
 ```
 
-FoxClaw writes proxychains into the main service and removes stale FoxClaw `ExecStart` overrides, so later upgrades still only need the normal `pnpm install -g` and `foxclaw restart`.
+FoxClaw writes proxychains into the main service and removes stale FoxClaw `ExecStart` overrides, so later upgrades only need `foxclaw update`.
 
 ## Service Starts With The Wrong Node Version
 

package/docs/user-manual.md

@@ -136,6 +136,8 @@ foxclaw start
 foxclaw status
 ```
 
+For later upgrades, run `foxclaw update`. It uses the npm or pnpm installation method currently managing FoxClaw, upgrades globally, runs checks, and restarts the background service.
+
 Linux service logs:
 
 ```bash
@@ -226,11 +228,12 @@ For group messages:
 
 Later commands are sorted by recent usage. Plain text, photos, and files continue the currently bound thread; if no thread is bound, FoxClaw creates one.
 
-### 3.2 `/status`, `/account`, `/quota`
+### 3.2 `/status`, `/account`, `/quota`, `/update`
 
 - `/status`: FoxClaw, app-server, current thread binding, model, access, and Codex usage summary.
 - `/account`: current Codex account.
 - `/quota`: Codex usage and quota window.
+- `/update`: upgrade FoxClaw, run checks, and restart the service; it refuses while a turn, approval, or question is active, then reports the result after restart.
 
 ### 3.3 `/config`, `/requirements`, `/provider`
 

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

@@ -275,10 +275,11 @@ foxclaw uninstall-systemd
 以后升级 FoxClaw：
 
 ```bash
-npm install -g @foxden-app/foxclaw@latest
-foxclaw start
+foxclaw update
 ```
 
+也可以在已授权的 Telegram 私聊里发送 `/update`。它会在当前没有运行中回复、审批或待确认问题时，完成升级、自检和服务重启，并在重启后回报结果。
+
 如果 `~/.foxclaw/.env` 已经存在，`foxclaw init` 会先询问是否更新 Telegram 和工作目录相关字段，其它配置保持不变。
 
 ## 鸣谢

package/docs/zh/troubleshooting.md

@@ -224,7 +224,7 @@ FOXCLAW_PROXYCHAINS_CONF=/home/wuya/.proxychains-rt.conf
 foxclaw restart
 ```
 
-FoxClaw 会把 proxychains 写进主 service，并清理旧的 FoxClaw `ExecStart` 覆盖，后续升级仍然只需要正常 `pnpm install -g` 和 `foxclaw restart`。
+FoxClaw 会把 proxychains 写进主 service，并清理旧的 FoxClaw `ExecStart` 覆盖，后续升级直接运行 `foxclaw update` 即可。
 
 ## 服务用了错误的 Node 版本
 

package/docs/zh/user-manual.md

@@ -136,6 +136,8 @@ foxclaw start
 foxclaw status
 ```
 
+后续升级只需运行 `foxclaw update`；它会使用当前安装 FoxClaw 的 npm 或 pnpm，全局升级后执行自检并重启后台服务。
+
 Linux 查看服务日志：
 
 ```bash
@@ -226,11 +228,12 @@ TG_ALLOWED_TOPIC_ID=42
 
 后面的命令会按你最近使用情况排序。直接发送普通文本、图片或文件时，FoxClaw 会继续当前绑定线程；如果没有绑定线程，会自动新建线程。
 
-### 3.2 `/status`、`/account`、`/quota`
+### 3.2 `/status`、`/account`、`/quota`、`/update`
 
 - `/status`：查看 FoxClaw、app-server、当前绑定线程、模型、权限和 Codex 用量摘要。
 - `/account`：查看当前 Codex 登录账号。
 - `/quota`：查看 Codex 用量和额度窗口。
+- `/update`：升级 FoxClaw、自检并重启服务；当前有运行中回复、审批或待确认问题时会拒绝执行，重启后会回报结果。
 
 ### 3.3 `/config`、`/requirements`、`/provider`
 

package/package.json

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