@foxden-app/foxclaw 0.3.12 → 0.3.14

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/codex_app/local_usage.d.ts

@@ -11,6 +11,14 @@ export interface CodexLocalUsageStats {
     turns: number;
     usageEvents: number;
     totals: CodexLocalUsageTotals;
+    outputSpeed: CodexLocalOutputSpeedStats;
     latestSessionMtimeMs: number | null;
 }
+export interface CodexLocalOutputSpeedStats {
+    samples: number;
+    outputTokens: number;
+    seconds: number;
+    latestTokensPerSecond: number | null;
+    latestSampleAtMs: number | null;
+}
 export declare function readCodexLocalUsageStats(codexHome?: string): Promise<CodexLocalUsageStats>;

package/dist/codex_app/local_usage.js

@@ -13,6 +13,7 @@ export async function readCodexLocalUsageStats(codexHome = resolveCodexHome()) {
     let sessionsWithUsage = 0;
     let usageEvents = 0;
     let latestSessionMtimeMs = null;
+    const outputSpeed = emptyOutputSpeedStats();
     for (const filePath of sessionFiles) {
         const stat = await fs.stat(filePath).catch(() => null);
         if (stat) {
@@ -20,6 +21,7 @@ export async function readCodexLocalUsageStats(codexHome = resolveCodexHome()) {
         }
         const fileUsage = await readSessionUsage(filePath, turnIds);
         usageEvents += fileUsage.usageEvents;
+        addOutputSpeed(outputSpeed, fileUsage.outputSpeed);
         if (fileUsage.totalUsage) {
             sessionsWithUsage += 1;
             addUsage(totals, fileUsage.totalUsage);
@@ -31,6 +33,7 @@ export async function readCodexLocalUsageStats(codexHome = resolveCodexHome()) {
         turns: turnIds.size,
         usageEvents,
         totals,
+        outputSpeed,
         latestSessionMtimeMs,
     };
 }
@@ -66,6 +69,8 @@ async function readSessionUsage(filePath, turnIds) {
     const reader = readline.createInterface({ input: stream, crlfDelay: Infinity });
     let totalUsage = null;
     let usageEvents = 0;
+    let generationStartMs = null;
+    const outputSpeed = emptyOutputSpeedStats();
     try {
         for await (const line of reader) {
             if (!line.trim())
@@ -77,13 +82,22 @@ async function readSessionUsage(filePath, turnIds) {
             catch {
                 continue;
             }
+            const timestampMs = parseTimestampMs(event?.timestamp);
             const turnId = typeof event?.payload?.turn_id === 'string' ? event.payload.turn_id : null;
             if (turnId) {
                 turnIds.add(turnId);
             }
+            if (timestampMs !== null && isGenerationBoundary(event)) {
+                generationStartMs = timestampMs;
+            }
             const info = event?.payload?.info;
-            if (info?.last_token_usage || info?.lastTokenUsage) {
+            const lastTokenUsage = info?.last_token_usage ?? info?.lastTokenUsage;
+            if (lastTokenUsage) {
                 usageEvents += 1;
+                addOutputSpeedSample(outputSpeed, lastTokenUsage, generationStartMs, timestampMs);
+                if (timestampMs !== null) {
+                    generationStartMs = timestampMs;
+                }
             }
             const totalTokenUsage = info?.total_token_usage ?? info?.totalTokenUsage;
             if (totalTokenUsage) {
@@ -94,7 +108,7 @@ async function readSessionUsage(filePath, turnIds) {
     finally {
         reader.close();
     }
-    return { usageEvents, totalUsage };
+    return { usageEvents, totalUsage, outputSpeed };
 }
 function emptyTotals() {
     return {
@@ -105,6 +119,15 @@ function emptyTotals() {
         totalTokens: 0,
     };
 }
+function emptyOutputSpeedStats() {
+    return {
+        samples: 0,
+        outputTokens: 0,
+        seconds: 0,
+        latestTokensPerSecond: null,
+        latestSampleAtMs: null,
+    };
+}
 function addUsage(totals, usage) {
     const inputTokens = numberField(usage, 'input_tokens', 'inputTokens');
     const outputTokens = numberField(usage, 'output_tokens', 'outputTokens');
@@ -115,9 +138,57 @@ function addUsage(totals, usage) {
     totals.reasoningOutputTokens += numberField(usage, 'reasoning_output_tokens', 'reasoningOutputTokens');
     totals.totalTokens += totalTokens || inputTokens + outputTokens;
 }
+function addOutputSpeed(target, source) {
+    target.samples += source.samples;
+    target.outputTokens += source.outputTokens;
+    target.seconds += source.seconds;
+    if (source.latestTokensPerSecond !== null
+        && source.latestSampleAtMs !== null
+        && (target.latestSampleAtMs === null || source.latestSampleAtMs > target.latestSampleAtMs)) {
+        target.latestTokensPerSecond = source.latestTokensPerSecond;
+        target.latestSampleAtMs = source.latestSampleAtMs;
+    }
+}
+function addOutputSpeedSample(stats, usage, generationStartMs, timestampMs) {
+    if (generationStartMs === null || timestampMs === null || timestampMs <= generationStartMs) {
+        return;
+    }
+    const outputTokens = numberField(usage, 'output_tokens', 'outputTokens');
+    if (outputTokens <= 0) {
+        return;
+    }
+    const seconds = (timestampMs - generationStartMs) / 1000;
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        return;
+    }
+    stats.samples += 1;
+    stats.outputTokens += outputTokens;
+    stats.seconds += seconds;
+    stats.latestTokensPerSecond = outputTokens / seconds;
+    stats.latestSampleAtMs = timestampMs;
+}
 function numberField(source, snakeKey, camelKey) {
     const snakeValue = source[snakeKey];
     const value = snakeValue === undefined || snakeValue === null ? source[camelKey] : snakeValue;
     const numeric = Number(value);
     return Number.isFinite(numeric) ? numeric : 0;
 }
+function parseTimestampMs(value) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return null;
+    }
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) ? timestamp : null;
+}
+function isGenerationBoundary(event) {
+    const payload = event?.payload;
+    if (event?.type === 'response_item' && payload?.type === 'function_call_output') {
+        return true;
+    }
+    if (event?.type !== 'event_msg') {
+        return false;
+    }
+    return payload?.type === 'task_started'
+        || payload?.type === 'exec_command_end'
+        || payload?.type === 'user_message';
+}

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;
@@ -255,8 +263,10 @@ export declare class BridgeSessionCore {
     private buildNativeCollaborationMode;
     private buildCodexUsageStatusLines;
     private buildCodexLocalUsageStatusLines;
+    private formatCodexLocalOutputSpeedStatusLines;
     private resolveFastStatusLabel;
     private readCachedCodexLocalUsageStats;
+    private sendThreadContextSummary;
     private handleModelCommand;
     private handleEffortCommand;
     private handleThreadOpenCallback;

package/dist/controller/controller.js

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { normalizeLocale, t } from '../i18n.js';
 import { parseCommand } from './commands.js';
-import { buildAccessSettingsKeyboard, buildModelSettingsKeyboard, buildSetupPanelKeyboard, buildThreadListKeyboard, buildThreadsKeyboard, clampEffortToModel, formatAccessPresetLabel, formatActiveTurnMessageModeLabel, formatAccessSettingsMessage, formatApprovalPolicyLabel, formatCollaborationModeLabel, formatModelSettingsMessage, formatSandboxModeLabel, formatServiceTierStatusLabel, formatSetupPanelMessage, formatThreadsMessage, formatWeixinAccessCopyPaste, formatWeixinModelCopyPaste, formatWeixinThreadsCopyPaste, formatWeixinWhereNavCopyPaste, formatWhereMessage, normalizeRequestedEffort, resolveCurrentModel, resolveActiveTurnMessageMode, resolveRequestedModel, } from './presentation.js';
+import { buildAccessSettingsKeyboard, buildModelSettingsKeyboard, buildSetupPanelKeyboard, buildThreadListKeyboard, buildThreadsKeyboard, clampEffortToModel, formatAccessPresetLabel, formatActiveTurnMessageModeLabel, formatAccessSettingsMessage, formatApprovalPolicyLabel, formatCollaborationModeLabel, formatModelSettingsMessage, formatSandboxModeLabel, formatServiceTierStatusLabel, formatSetupPanelMessage, formatThreadContextSummary, formatThreadsMessage, formatWeixinAccessCopyPaste, formatWeixinModelCopyPaste, formatWeixinThreadsCopyPaste, formatWeixinWhereNavCopyPaste, formatWhereMessage, normalizeRequestedEffort, resolveCurrentModel, resolveActiveTurnMessageMode, resolveRequestedModel, } from './presentation.js';
 import { clampServiceTierToModel, resolveFastTierForModel } from './service_tier.js';
 import { TELEGRAM_BOT_API_DOWNLOAD_LIMIT_BYTES, buildAttachmentPrompt, isNativeImageAttachment, planAttachmentStoragePath, summarizeTelegramInput, } from '../telegram/media.js';
 import { TELEGRAM_MESSAGE_LIMIT, chunkTelegramMessage, chunkTelegramStreamMessage, clipTelegramDraftMessage, } from '../telegram/text.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;
@@ -505,6 +516,7 @@ export class BridgeSessionCore {
                     lines.push(revealError ? t(locale, 'codex_sync_failed', { error: revealError }) : t(locale, 'opened_in_codex'));
                 }
                 await this.sendMessage(scopeId, lines.join('\n'));
+                await this.sendThreadContextSummary(scopeId, locale, binding.threadId);
                 return;
             }
             case 'watch': {
@@ -831,13 +843,16 @@ export class BridgeSessionCore {
         const mode = watch.mode;
         if (mode === 'already') {
             await this.sendMessage(scopeId, t(locale, 'watch_already_enabled', { threadId: watchedThreadId }));
+            await this.sendThreadContextSummary(scopeId, locale, watchedThreadId);
             return;
         }
         if (mode === 'active') {
             await this.sendMessage(scopeId, t(locale, 'watch_started_active', { threadId: watchedThreadId }));
+            await this.sendThreadContextSummary(scopeId, locale, watchedThreadId);
             return;
         }
         await this.sendMessage(scopeId, t(locale, 'watch_started_idle', { threadId: watchedThreadId }));
+        await this.sendThreadContextSummary(scopeId, locale, watchedThreadId);
     }
     async handleThreadArchiveIndexCommand(scopeId, locale, args) {
         const index = Number.parseInt(args[0] || '', 10);
@@ -3637,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') {
@@ -4439,6 +4522,7 @@ export class BridgeSessionCore {
                     cached: formatTokenCount(stats.totals.cachedInputTokens),
                     reasoning: formatTokenCount(stats.totals.reasoningOutputTokens),
                 }),
+                ...this.formatCodexLocalOutputSpeedStatusLines(locale, stats),
             ];
         }
         catch (error) {
@@ -4446,6 +4530,18 @@ export class BridgeSessionCore {
             return [t(locale, 'status_codex_local_usage_unavailable', { error: formatShortStatusError(error) })];
         }
     }
+    formatCodexLocalOutputSpeedStatusLines(locale, stats) {
+        const speed = stats.outputSpeed;
+        if (speed.samples === 0 || speed.outputTokens <= 0 || speed.seconds <= 0) {
+            return [];
+        }
+        const avg = speed.outputTokens / speed.seconds;
+        return [t(locale, 'status_codex_local_speed', {
+                avg: formatCompactNumber(avg),
+                latest: speed.latestTokensPerSecond === null ? t(locale, 'unknown') : formatCompactNumber(speed.latestTokensPerSecond),
+                samples: formatTokenCount(speed.samples),
+            })];
+    }
     async resolveFastStatusLabel(locale, settings) {
         try {
             const models = await this.app.listModels();
@@ -4466,6 +4562,22 @@ export class BridgeSessionCore {
         this.localUsageCache = { stats, expiresAt: now + CODEX_LOCAL_USAGE_CACHE_MS };
         return stats;
     }
+    async sendThreadContextSummary(scopeId, locale, threadId) {
+        try {
+            const turns = await this.app.listThreadTurns(threadId, 5);
+            const text = formatThreadContextSummary(locale, turns);
+            if (text) {
+                await this.sendMessage(scopeId, text);
+            }
+        }
+        catch (error) {
+            this.logger.warn('codex.thread_context_summary_failed', {
+                scopeId,
+                threadId,
+                error: formatUserError(error),
+            });
+        }
+    }
     async handleModelCommand(event, locale, args) {
         const scopeId = event.scopeId;
         if (args.length === 0) {
@@ -4627,6 +4739,7 @@ export class BridgeSessionCore {
             callbackText = revealError ? t(locale, 'opened_sync_failed_short') : t(locale, 'opened_in_codex_short');
         }
         await this.messaging.answerCallback(event.callbackQueryId, callbackText);
+        await this.sendThreadContextSummary(scopeId, locale, binding.threadId);
     }
     async handleThreadActionCallback(event, action, threadId, locale) {
         const scopeId = event.scopeId;
@@ -4673,6 +4786,7 @@ export class BridgeSessionCore {
             const watch = await this.watchThread(scopeId, target.chatId, target.chatType, target.topicId, binding);
             await this.showThreadsPanelFromStoredState(scopeId, event.messageId, locale, false);
             await this.messaging.answerCallback(event.callbackQueryId, formatWatchCallbackText(locale, watch.mode, watch.threadId));
+            await this.sendThreadContextSummary(scopeId, locale, watch.threadId);
             return;
         }
         if (action === 'archive') {

package/dist/controller/presentation.d.ts

@@ -1,4 +1,4 @@
-import type { AccessPresetValue, ActiveTurnMessageMode, AppLocale, AppThread, ApprovalPolicyValue, ChatSessionSettings, CollaborationModeValue, ModelInfo, ReasoningEffortValue, SandboxModeValue } from '../types.js';
+import type { AccessPresetValue, ActiveTurnMessageMode, AppLocale, AppThread, AppTurnSnapshot, ApprovalPolicyValue, ChatSessionSettings, CollaborationModeValue, ModelInfo, ReasoningEffortValue, SandboxModeValue } from '../types.js';
 import type { ResolvedAccessMode } from './access.js';
 type InlineButton = {
     text: string;
@@ -60,6 +60,7 @@ pageOffset?: number): string;
 export declare function formatWeixinModelCopyPaste(locale: AppLocale, models: ModelInfo[], settings: ChatSessionSettings | null): string;
 export declare function formatWeixinAccessCopyPaste(locale: AppLocale): string;
 export declare function formatWeixinWhereNavCopyPaste(locale: AppLocale, hasBinding: boolean, defaultCwd?: string): string;
+export declare function formatThreadContextSummary(locale: AppLocale, turns: AppTurnSnapshot[]): string | null;
 export declare function formatSetupPanelMessage(locale: AppLocale, ctx: SetupPanelContext): string;
 export declare function buildSetupPanelKeyboard(locale: AppLocale, ctx: SetupPanelContext): InlineButton[][];
 export declare function resolveSetupSummaryLine(ctx: SetupPanelContext, locale?: AppLocale): string;

package/dist/controller/presentation.js

@@ -225,6 +225,20 @@ export function formatWeixinWhereNavCopyPaste(locale, hasBinding, defaultCwd) {
     }
     return lines.join('\n');
 }
+export function formatThreadContextSummary(locale, turns) {
+    const context = selectRecentThreadContext(turns);
+    if (!context) {
+        return null;
+    }
+    return [
+        t(locale, 'thread_context_title'),
+        t(locale, 'thread_context_user'),
+        context.userText || t(locale, 'empty'),
+        '',
+        t(locale, 'thread_context_codex'),
+        context.codexText || t(locale, 'empty'),
+    ].join('\n');
+}
 export function formatSetupPanelMessage(locale, ctx) {
     const currentModel = resolveCurrentModel(ctx.models, ctx.settings?.model ?? null);
     const fastTier = resolveFastTierForModel(currentModel);
@@ -393,6 +407,52 @@ function formatFastSetupLabel(locale, supported, enabled, tierName) {
 function resolveCollaborationMode(mode) {
     return mode === 'plan' ? 'plan' : 'default';
 }
+function selectRecentThreadContext(turns) {
+    for (const turn of turns) {
+        const userText = lastItemText(turn.items, isUserTurnItem);
+        const codexText = lastItemText(turn.items, isCodexTurnItem);
+        if (userText || codexText) {
+            return { userText, codexText };
+        }
+    }
+    return null;
+}
+function lastItemText(items, predicate) {
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        const item = items[index];
+        if (!predicate(item)) {
+            continue;
+        }
+        const text = normalizeThreadContextText(item.text ?? item.aggregatedOutput ?? item.command ?? '');
+        if (text) {
+            return text;
+        }
+    }
+    return null;
+}
+function isUserTurnItem(item) {
+    const type = normalizeTurnItemType(item.type);
+    return type === 'user'
+        || type === 'usermessage'
+        || type === 'humanmessage'
+        || type === 'userinput'
+        || type === 'userrequest';
+}
+function isCodexTurnItem(item) {
+    const type = normalizeTurnItemType(item.type);
+    return type === 'agent'
+        || type === 'assistant'
+        || type === 'agentmessage'
+        || type === 'assistantmessage'
+        || type === 'plan';
+}
+function normalizeTurnItemType(value) {
+    return value.replace(/[^a-z]/gi, '').toLowerCase();
+}
+function normalizeThreadContextText(value) {
+    const trimmed = value.replace(/\r\n/g, '\n').trim().replace(/\n{3,}/g, '\n\n');
+    return truncate(trimmed, 1200);
+}
 function selectedButtonText(selected, label) {
     return `${selected ? '• ' : ''}${label}`;
 }

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";
@@ -111,9 +112,16 @@ declare const MESSAGES: {
         readonly status_codex_usage_unavailable: "Codex usage: unavailable ({error})";
         readonly status_codex_local_history: "Codex local history: {sessions} sessions, {turns} turns, {events} usage records";
         readonly status_codex_local_tokens: "Codex local tokens: total {total}; input {input}, output {output}, cached input {cached}, reasoning output {reasoning}";
+        readonly status_codex_local_speed: "Codex local output speed: avg {avg} token/s, latest {latest} token/s ({samples} samples)";
         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.";
@@ -315,6 +323,9 @@ declare const MESSAGES: {
         readonly threads_filter: "Filter: <code>{searchTerm}</code>";
         readonly threads_range: "Showing {start}-{end}";
         readonly threads_filter_cleared_short: "Filter cleared";
+        readonly thread_context_title: "Recent context:";
+        readonly thread_context_user: "User:";
+        readonly thread_context_codex: "Codex:";
         readonly button_prev_page: "⬅️ Prev";
         readonly button_next_page: "➡️ Next";
         readonly button_clear_filter: "🧹 Clear";
@@ -596,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 设备登录";
@@ -661,9 +673,16 @@ declare const MESSAGES: {
         readonly status_codex_usage_unavailable: "Codex 用量：无法获取（{error}）";
         readonly status_codex_local_history: "Codex 本地历史：{sessions} 个会话，{turns} 轮，{events} 条用量记录";
         readonly status_codex_local_tokens: "Codex 本地 Token：总计 {total}；输入 {input}，输出 {output}，缓存输入 {cached}，推理输出 {reasoning}";
+        readonly status_codex_local_speed: "Codex 本地输出速度：平均 {avg} token/s，最近 {latest} token/s（{samples} 个样本）";
         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。";
@@ -865,6 +884,9 @@ declare const MESSAGES: {
         readonly threads_filter: "筛选：<code>{searchTerm}</code>";
         readonly threads_range: "显示第 {start}-{end} 条";
         readonly threads_filter_cleared_short: "已清除筛选";
+        readonly thread_context_title: "最近上下文：";
+        readonly thread_context_user: "用户指令：";
+        readonly thread_context_codex: "Codex 最后输出：";
         readonly button_prev_page: "⬅️ 上一页";
         readonly button_next_page: "➡️ 下一页";
         readonly button_clear_filter: "🧹 清除";

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',
@@ -109,9 +110,16 @@ const MESSAGES = {
         status_codex_usage_unavailable: 'Codex usage: unavailable ({error})',
         status_codex_local_history: 'Codex local history: {sessions} sessions, {turns} turns, {events} usage records',
         status_codex_local_tokens: 'Codex local tokens: total {total}; input {input}, output {output}, cached input {cached}, reasoning output {reasoning}',
+        status_codex_local_speed: 'Codex local output speed: avg {avg} token/s, latest {latest} token/s ({samples} samples)',
         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.',
@@ -313,6 +321,9 @@ const MESSAGES = {
         threads_filter: 'Filter: <code>{searchTerm}</code>',
         threads_range: 'Showing {start}-{end}',
         threads_filter_cleared_short: 'Filter cleared',
+        thread_context_title: 'Recent context:',
+        thread_context_user: 'User:',
+        thread_context_codex: 'Codex:',
         button_prev_page: '⬅️ Prev',
         button_next_page: '➡️ Next',
         button_clear_filter: '🧹 Clear',
@@ -594,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 设备登录',
@@ -659,9 +671,16 @@ const MESSAGES = {
         status_codex_usage_unavailable: 'Codex 用量：无法获取（{error}）',
         status_codex_local_history: 'Codex 本地历史：{sessions} 个会话，{turns} 轮，{events} 条用量记录',
         status_codex_local_tokens: 'Codex 本地 Token：总计 {total}；输入 {input}，输出 {output}，缓存输入 {cached}，推理输出 {reasoning}',
+        status_codex_local_speed: 'Codex 本地输出速度：平均 {avg} token/s，最近 {latest} token/s（{samples} 个样本）',
         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。',
@@ -863,6 +882,9 @@ const MESSAGES = {
         threads_filter: '筛选：<code>{searchTerm}</code>',
         threads_range: '显示第 {start}-{end} 条',
         threads_filter_cleared_short: '已清除筛选',
+        thread_context_title: '最近上下文：',
+        thread_context_user: '用户指令：',
+        thread_context_codex: 'Codex 最后输出：',
         button_prev_page: '⬅️ 上一页',
         button_next_page: '➡️ 下一页',
         button_clear_filter: '🧹 清除',
@@ -1113,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, 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('');

package/dist/update.d.ts

@@ -0,0 +1,49 @@
+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 resolveSelfUpdateInstaller(entryPoint: string, nodePath?: string, exists?: (target: string) => boolean): 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,203 @@
+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 resolveSelfUpdateInstaller(entryPoint, nodePath = process.execPath, exists = fs.existsSync) {
+    const normalizedEntryPoint = entryPoint.replace(/\\/g, '/');
+    const globalMarker = '/global/';
+    const globalIndex = normalizedEntryPoint.indexOf(globalMarker);
+    if (globalIndex > 0 && normalizedEntryPoint.includes('/.pnpm/')) {
+        const pnpmHome = normalizedEntryPoint.slice(0, globalIndex);
+        const pnpmCommand = path.join(pnpmHome, process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm');
+        if (!exists(pnpmCommand)) {
+            throw new Error(`Current installation is managed by pnpm, but pnpm was not found at ${pnpmCommand}.`);
+        }
+        return {
+            manager: 'pnpm',
+            command: pnpmCommand,
+            installArgs: ['add', '--global', PACKAGE_SPEC],
+            rootArgs: ['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);
+        console.log(`[UPDATE] Installing ${PACKAGE_SPEC} with ${installer.manager}...`);
+        runInherited(installer.command, installer.installArgs, env);
+        const updatedEntryPoint = resolveUpdatedEntryPoint(installer, env);
+        toVersion = readInstalledPackageVersion(updatedEntryPoint);
+        console.log('[UPDATE] Running checks and restarting the FoxClaw service...');
+        runInherited(options.nodePath, [updatedEntryPoint, 'start'], env);
+        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 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.12",
+  "version": "0.3.14",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",