@foxden-app/foxclaw 0.12.0 → 0.13.1

package/dist/update.d.ts

@@ -68,6 +68,11 @@ export interface PendingClusterUpdateBroadcast {
     fromVersion: string;
     updatedAt: string;
 }
+interface CodexCliUpdateResult {
+    message: string;
+    fromVersion: string | null;
+    toVersion: string | null;
+}
 export declare function selfUpdateStatusPath(statusPath: string): string;
 export declare function inferPnpmHomeFromEntryPoint(entryPoint: string): string | null;
 export declare function inferPnpmFallbackPackageFromEntryPoint(entryPoint: string): string;
@@ -88,11 +93,31 @@ export declare function buildSelfUpdateLaunchCommand(options: {
     systemdRunPath?: string | null;
     unitName?: string;
 }): SelfUpdateLaunchCommand;
-export declare function performSelfUpdate(options: PerformSelfUpdateOptions): SelfUpdateOutcome;
+export declare function assertSelfUpdateVersion(current: string, candidate: string, expected?: string): void;
+interface SelfUpdateOperations {
+    latestVersion: (installer: SelfUpdateInstaller, env: NodeJS.ProcessEnv) => string;
+    run: typeof runInherited;
+    entryPoint: typeof resolveUpdatedEntryPoint;
+    readVersion: typeof readInstalledPackageVersion;
+    updateCodex: typeof updateManagedCodexCli;
+    updateAgy: typeof updateManagedAgyCli;
+}
+export declare function performSelfUpdate(options: PerformSelfUpdateOptions, overrides?: Partial<SelfUpdateOperations>): SelfUpdateOutcome;
 export declare function readPendingClusterUpdateBroadcast(filePath: string): PendingClusterUpdateBroadcast | null;
 export declare function writePendingClusterUpdateBroadcast(filePath: string, value: PendingClusterUpdateBroadcast): void;
 export declare function clearPendingClusterUpdateBroadcast(filePath: string): void;
+declare function updateManagedCodexCli(codexCliBin: string, nodePath: string, env: NodeJS.ProcessEnv): CodexCliUpdateResult;
+interface AgyCliUpdateResult {
+    message: string;
+    fromVersion: string | null;
+    toVersion: string | null;
+}
+declare function updateManagedAgyCli(agyCliBin: string, env: NodeJS.ProcessEnv): AgyCliUpdateResult;
+declare function runInherited(command: string, args: string[], env: NodeJS.ProcessEnv): void;
 export declare function resolveFoxclawEntryPointFromGlobalRoot(globalRoot: string, exists?: (target: string) => boolean): string | null;
-export declare function resolveFoxclawEntryPointFromPnpmHome(pnpmHome: string, preferBin?: boolean, exists?: (target: string) => boolean, readText?: (target: string) => string): string | null;
+export declare function resolveFoxclawEntryPointFromPnpmHome(pnpmHome: string, preferBin?: boolean, exists?: (target: string) => boolean, readText?: (target: string) => string, installationRoot?: string): string | null;
+export declare function resolveFoxclawEntryPointFromInstallation(globalRoot: string, pnpmHome?: string, exists?: (target: string) => boolean, readText?: (target: string) => string): string | null;
+declare function resolveUpdatedEntryPoint(installer: SelfUpdateInstaller, env: NodeJS.ProcessEnv): string;
+declare function readInstalledPackageVersion(updatedEntryPoint: string): string;
 export declare function extractReleaseNotes(changelog: string, version: string, locale: AppLocale): string[] | null;
 export {};

package/dist/update.js

@@ -3,7 +3,10 @@ import path from 'node:path';
 import os from 'node:os';
 import process from 'node:process';
 import { spawn, spawnSync } from 'node:child_process';
-const PACKAGE_SPEC = '@foxden-app/foxclaw@latest';
+import { valid, lt } from 'semver';
+const PACKAGE_NAME = '@foxden-app/foxclaw';
+const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
+const PACKAGE_REGISTRY = 'https://registry.npmjs.org';
 const CODEX_PACKAGE_SPEC = '@openai/codex@latest';
 const UPDATE_STATUS_FILENAME = 'self-update.json';
 export const SELF_UPDATE_PENDING_TIMEOUT_MS = 15 * 60_000;
@@ -153,6 +156,9 @@ export function readSelfUpdateStatus(statusFile) {
             ...(typeof parsed.codexUpdate === 'string' ? { codexUpdate: parsed.codexUpdate } : {}),
             ...(typeof parsed.codexFromVersion === 'string' ? { codexFromVersion: parsed.codexFromVersion } : {}),
             ...(typeof parsed.codexToVersion === 'string' ? { codexToVersion: parsed.codexToVersion } : {}),
+            ...(typeof parsed.agyUpdate === 'string' ? { agyUpdate: parsed.agyUpdate } : {}),
+            ...(typeof parsed.agyFromVersion === 'string' ? { agyFromVersion: parsed.agyFromVersion } : {}),
+            ...(typeof parsed.agyToVersion === 'string' ? { agyToVersion: parsed.agyToVersion } : {}),
             error: typeof parsed.error === 'string' ? parsed.error : null,
             updatedAt: parsed.updatedAt,
         };
@@ -311,25 +317,73 @@ export function buildSelfUpdateLaunchCommand(options) {
         viaSystemdRun: false,
     };
 }
-export function performSelfUpdate(options) {
+export function assertSelfUpdateVersion(current, candidate, expected) {
+    const from = valid(current);
+    const to = valid(candidate);
+    if (!from || !to) {
+        throw new Error(`Cannot verify FoxClaw update versions: ${current} -> ${candidate}.`);
+    }
+    if (lt(to, from)) {
+        throw new Error(`Refusing FoxClaw downgrade: ${current} -> ${candidate}.`);
+    }
+    if (expected && to !== valid(expected)) {
+        throw new Error(`Installed FoxClaw ${candidate} does not match requested ${expected}; service restart refused.`);
+    }
+}
+function readLatestFoxclawVersion(installer, env) {
+    // Read the same registry used by the exact-version install, bypassing stale local metadata.
+    const result = spawnSync(installer.command, ['view', PACKAGE_SPEC, 'version', '--json', `--registry=${PACKAGE_REGISTRY}`, '--prefer-online'], { encoding: 'utf8', env, timeout: 30_000 });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0)
+        throw new Error('Could not read the latest FoxClaw version from the npm registry.');
+    let version;
+    try {
+        version = JSON.parse(result.stdout.trim());
+    }
+    catch {
+        throw new Error('Invalid latest FoxClaw version response.');
+    }
+    if (typeof version !== 'string' || !valid(version))
+        throw new Error('Invalid latest FoxClaw version response.');
+    return valid(version);
+}
+export function performSelfUpdate(options, overrides = {}) {
     const env = options.env ?? process.env;
+    const operations = {
+        latestVersion: readLatestFoxclawVersion,
+        run: runInherited,
+        entryPoint: resolveUpdatedEntryPoint,
+        readVersion: readInstalledPackageVersion,
+        updateCodex: updateManagedCodexCli,
+        updateAgy: updateManagedAgyCli,
+        ...overrides,
+    };
     let toVersion = null;
     let codexUpdate = null;
     let agyUpdate = null;
     try {
-        codexUpdate = updateManagedCodexCli(options.codexCliBin ?? env.CODEX_CLI_BIN ?? '', options.nodePath, env);
-        console.log(`[UPDATE] ${codexUpdate.message}`);
-        agyUpdate = updateManagedAgyCli(options.agyCliBin ?? env.AGY_CLI_BIN ?? '', env);
-        console.log(`[UPDATE] ${agyUpdate.message}`);
         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);
+        const targetVersion = operations.latestVersion(installer, installerEnv);
+        assertSelfUpdateVersion(options.version, targetVersion);
+        const spec = `${PACKAGE_NAME}@${targetVersion}`;
+        const installArgs = [
+            ...installer.installArgs.map(arg => arg === PACKAGE_SPEC ? spec : arg),
+            `--registry=${PACKAGE_REGISTRY}`,
+        ];
+        console.log(`[UPDATE] Installing ${spec} with ${installer.manager}...`);
+        operations.run(installer.command, installArgs, installerEnv);
+        const updatedEntryPoint = operations.entryPoint(installer, installerEnv);
+        toVersion = operations.readVersion(updatedEntryPoint);
+        assertSelfUpdateVersion(options.version, toVersion, targetVersion);
+        codexUpdate = operations.updateCodex(options.codexCliBin ?? env.CODEX_CLI_BIN ?? '', options.nodePath, env);
+        console.log(`[UPDATE] ${codexUpdate.message}`);
+        agyUpdate = operations.updateAgy(options.agyCliBin ?? env.AGY_CLI_BIN ?? '', env);
+        console.log(`[UPDATE] ${agyUpdate.message}`);
         const releaseNotes = readInstalledReleaseNotes(updatedEntryPoint, toVersion, options.notificationFile);
         console.log('[UPDATE] Running checks and restarting the FoxClaw service...');
-        runInherited(options.nodePath, [updatedEntryPoint, 'start'], installerEnv);
+        operations.run(options.nodePath, [updatedEntryPoint, 'start'], installerEnv);
         completeNotification(options.notificationFile, 'succeeded', toVersion, codexUpdate, null, releaseNotes, agyUpdate);
         if (options.clusterBroadcastFile && env.FOXCLAW_SUPPRESS_UPDATE_BROADCAST !== '1') {
             writePendingClusterUpdateBroadcast(options.clusterBroadcastFile, {
@@ -339,23 +393,13 @@ export function performSelfUpdate(options) {
             });
         }
         console.log(`[OK] FoxClaw updated and restarted: ${options.version} -> ${toVersion}`);
-        return {
-            ok: true,
-            fromVersion: options.version,
-            toVersion,
-            error: null,
-        };
+        return { ok: true, fromVersion: options.version, toVersion, error: null };
     }
     catch (error) {
         const message = formatError(error);
         completeNotification(options.notificationFile, 'failed', toVersion, codexUpdate, message, null, agyUpdate);
         console.error(`[FAIL] FoxClaw update failed: ${message}`);
-        return {
-            ok: false,
-            fromVersion: options.version,
-            toVersion,
-            error: message,
-        };
+        return { ok: false, fromVersion: options.version, toVersion, error: message };
     }
 }
 export function readPendingClusterUpdateBroadcast(filePath) {
@@ -563,7 +607,7 @@ export function resolveFoxclawEntryPointFromGlobalRoot(globalRoot, exists = fs.e
     ];
     return candidates.find(candidate => exists(candidate)) ?? null;
 }
-export function resolveFoxclawEntryPointFromPnpmHome(pnpmHome, preferBin = false, exists = fs.existsSync, readText = (target) => fs.readFileSync(target, 'utf8')) {
+export function resolveFoxclawEntryPointFromPnpmHome(pnpmHome, preferBin = false, exists = fs.existsSync, readText = (target) => fs.readFileSync(target, 'utf8'), installationRoot) {
     const commandName = process.platform === 'win32' ? 'foxclaw.cmd' : 'foxclaw';
     const rootShim = path.join(pnpmHome, commandName);
     const binShim = path.join(pnpmHome, 'bin', commandName);
@@ -581,11 +625,23 @@ export function resolveFoxclawEntryPointFromPnpmHome(pnpmHome, preferBin = false
         const matches = contents.match(/(?:[A-Za-z]:[\\/]|\/)[^\r\n"']*?[\\/]node_modules[\\/]@foxden-app[\\/]foxclaw[\\/]dist[\\/]main\.js/g);
         const entryPoint = matches?.at(-1) ?? null;
         if (entryPoint && exists(entryPoint)) {
+            const relative = installationRoot ? path.relative(path.resolve(installationRoot), path.resolve(entryPoint)) : null;
+            if (relative !== null && (path.isAbsolute(relative) || relative === '..' || relative.startsWith(`..${path.sep}`))) {
+                continue;
+            }
             return entryPoint;
         }
     }
     return null;
 }
+export function resolveFoxclawEntryPointFromInstallation(globalRoot, pnpmHome, exists = fs.existsSync, readText = target => fs.readFileSync(target, 'utf8')) {
+    // The installer-owned root is authoritative. Another pnpm layout may have a stale shim.
+    const direct = resolveFoxclawEntryPointFromGlobalRoot(globalRoot, exists);
+    if (direct || !pnpmHome)
+        return direct;
+    const installationRoot = path.basename(globalRoot) === 'node_modules' ? path.dirname(globalRoot) : globalRoot;
+    return resolveFoxclawEntryPointFromPnpmHome(pnpmHome, /^v\d+$/.test(path.basename(globalRoot)), exists, readText, installationRoot);
+}
 function resolveUpdatedEntryPoint(installer, env) {
     const result = spawnSync(installer.command, installer.rootArgs, { encoding: 'utf8', env });
     if (result.error) {
@@ -598,10 +654,7 @@ function resolveUpdatedEntryPoint(installer, env) {
     if (!globalRoot) {
         throw new Error(`Could not locate the updated global package root using ${installer.manager}.`);
     }
-    const updatedEntryPoint = (installer.pnpmHome
-        ? resolveFoxclawEntryPointFromPnpmHome(installer.pnpmHome, /^v\d+$/.test(path.basename(globalRoot)))
-        : null)
-        ?? resolveFoxclawEntryPointFromGlobalRoot(globalRoot);
+    const updatedEntryPoint = resolveFoxclawEntryPointFromInstallation(globalRoot, installer.pnpmHome);
     if (!updatedEntryPoint) {
         throw new Error(`Updated FoxClaw entry point was not found below ${globalRoot} (checked direct and node_modules layouts).`);
     }

package/docs/release.md

@@ -16,38 +16,40 @@ Check the worktree and remote state:
 
 ```bash
 git status --short --branch
-npm pkg get name version
-npm view @foxden-app/foxclaw version
+node -p "require('./package.json').name + '@' + require('./package.json').version"
+pnpm view @foxden-app/foxclaw version
 git tag --list 'v*' --sort=-v:refname | head
 ```
 
 Confirm the target version and remote tag do not already exist:
 
 ```bash
-npm view @foxden-app/foxclaw@0.5.10 version 2>/dev/null || true
+pnpm view @foxden-app/foxclaw@0.5.10 version 2>/dev/null || true
 git ls-remote --tags origin refs/tags/v0.5.10
 ```
 
+Use the version pinned in `packageManager` and install with `pnpm install --frozen-lockfile`. npm is used only by the publishing workflow for registry authentication and publication.
+
 Run the same local checks as the publish workflow:
 
 ```bash
-npm run lint
-npm run typecheck
-npm test
-npm pack --dry-run
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm pack --pack-destination /tmp/foxclaw-release
 git diff --check
 ```
 
-`npm pack --dry-run` runs `prepack` and lists the package contents. Confirm `CHANGELOG.md` is included.
+`pnpm pack` runs `prepack` and creates the release archive. Inspect it with `tar -tzf /tmp/foxclaw-release/*.tgz` and confirm `CHANGELOG.md` is included.
 
 ## Prepare The Version
 
-1. Update `package.json` and `package-lock.json`.
+1. Update `package.json` and `pnpm-lock.yaml`.
 2. Add a new top entry to `CHANGELOG.md` with both `### 中文` and `### English` sections.
 3. Commit the release metadata:
 
 ```bash
-git add package.json package-lock.json CHANGELOG.md
+git add package.json pnpm-lock.yaml CHANGELOG.md
 git commit -m "发布 0.5.10：short release summary"
 ```
 
@@ -71,7 +73,7 @@ gh run watch <run-id> --repo foxden-app/foxclaw --exit-status
 After success, verify npm and GitHub Releases:
 
 ```bash
-npm view @foxden-app/foxclaw version
+pnpm view @foxden-app/foxclaw version
 gh release view v0.5.10 --repo foxden-app/foxclaw --json tagName,name,url,publishedAt,isDraft,isPrerelease
 ```
 

package/docs/zh/architecture-review.md

@@ -0,0 +1,106 @@
+# FoxClaw 架构复审与重构
+
+日期：2026-10-06。基线：v0.12.0。
+
+## 判断
+
+保留后端适配器 + 共享调度的方向，但 v0.12.0 还没有形成完整的后端边界。新增 DSH 时必须同时修改 Antigravity 控制器、调度器、启动逻辑及多处面板分支。问题不是目录名称，而是执行身份、会话状态、界面入口和资源清理由不同地方分别决定。
+
+本轮改动任务调度、通道契约、持久任务日志、资源归属，并提取存量控制器的独立功能。Telegram 为主通道；微信保留文字入口，完整迁移等待观察消息方案落定。存量数据库和导入路径继续兼容。
+
+## 当前边界
+
+```mermaid
+flowchart TD
+    Main[main.ts：运行时组装] --> Bridge[bridge/unified_bridge：存量 Codex / AGY 功能接入]
+    Main --> Definition[后端定义：adapter / defaults / commands / createUi]
+    Bridge --> Registry[BackendRegistry：注册与面板生命周期]
+    Definition --> Registry
+    Registry --> UI[BackendUi：模型、权限、历史与审批面板]
+    UI --> Host[BackendUiHost：有限的界面操作]
+    Host --> Orchestrator[Orchestrator：任务调度与交付]
+    Orchestrator --> ScopeOps[ScopeOperations：每会话串行操作]
+    Orchestrator --> SPI[Engine SPI：后端执行、事件、取消]
+    Orchestrator --> Store[BridgeStore：会话、任务日志、持久队列]
+    Orchestrator --> Channel[ChannelPort：消息与交互能力]
+    Main --> Supervisor[RuntimeSupervisor：依赖逆序清理]
+```
+
+- `core/engine_spi.ts` 定义执行契约和后端声明；原生推理档位使用字符串，不受 Codex 枚举限制。
+- `core/backend_registry.ts` 保持后端执行身份稳定，允许发现逻辑刷新展示元数据；注册失败不会残留半个后端，清理统一执行且只执行一次。
+- `core/backend_ui.ts` 定义面板接口与操作端口。后端面板不再依赖整个调度器实现。全局服务命令优先于后端命令；后端回调归属由注册的界面声明。
+- `dsh/backend.ts` 提供一份 DSH 定义，共享 Bot 与独立 Bot 均复用它。统一控制器无需导入或构造 DSH。
+- `bridge/unified_bridge.ts` 是存量后端的组合层，不再挂在 Antigravity 引擎目录下。旧导入路径保留为兼容转发。
+- `core/access.ts` 是权限策略的领域逻辑，Codex 适配器将当前设置传入原生线程和任务请求。
+
+新增后端应在组装处注入定义。调度器不应再增加 `adapter.id === 某后端` 来处理附件、取消、默认推理档位或菜单。
+
+## 状态约束与修复
+
+### 会话操作
+
+启动、插话、中断、新会话、切换后端和队列领取按 scope 串行执行；不同 scope 独立。任务从启动准备到最终回答交付都保留占用状态，避免两个消息在准备阶段同时启动任务。
+
+所有事件回调验证任务对象的所有权，忽略已取消或被替换任务的会话 ID、增量、错误和终态。取消前先屏蔽旧任务回调，并等待适配器返回的取消承诺完成后释放槽位。取消失败保留占用，不能自动启动重叠任务。Codex / OpenCode 的启动阶段取消也会结束等待者并释放监听器；DSH 无法及时取消时关闭其自有进程。
+
+执行中或仍有排队任务时不能切换后端。未启用的已选后端不会静默退回其他执行器，原会话与设置保留，用户可通过 `/backend` 重新选择。新后端的首次使用清除旧后端权限及模型覆盖；返回时恢复该后端保存的配置。
+
+### 通道收件箱与持久队列
+
+Telegram 更新在分类、准备附件和等待会话锁之前写入持久收件箱。通道只在处理完成后推进收取位置；重启先恢复未完成收件，再接收新更新。处理成功后清除原始载荷，保留收件标识用于去重；原生任务日志另行去重，避免收件重放导致重复执行工具。
+
+新队列载荷记录版本、原始 prompt、后端、工作目录和已落盘附件。已有文本数组格式继续可读。
+
+队列状态为 `queued → processing → completed / failed / cancelled`，只有实际执行和交付结束才进入终态。任务日志为 `accepted → queued / running → delivery_pending → completed / failed / cancelled`，另外记录 `awaiting_confirmation`。普通输入、显式排队和插话在等待会话锁之前保存原始输入、附件引用、模型、权限和后端配置；队列写入与任务关联使用同一数据库事务。队列已领取、任务日志仍为 queued 时可确认尚未调用执行器，重启重新排队。上下文不匹配会失败并提示。
+
+附件只在通道入口落盘，原始文本与附件清单交给适配器；适配器决定使用原生图片还是文件提示。JSON 文件不再被调度器统一过滤。OAuth 文件导入仅由 Antigravity 的入站界面处理。
+
+### 重启与交付行为（本地实现，尚未部署）
+
+- 已接受但尚未启动：恢复原始输入与配置，再准备附件。
+- 已保存原生结果：只重试剩余结果交付，不再次执行工具。
+- 已开始但结果未知：保留输入与附件，暂停该会话队列，提供 `/recover continue|retry|cancel` 和按钮。继续会要求模型检查已有工作；重试可能重复操作。该保守恢复策略随 v0.13.0 启用。
+- 最终消息逐块保存交付进度。消息平台成功发送却丢失确认时，恢复可能重复一条回答；不能保证平台交付恰好一次，但不会为了补发结果重跑工具。
+- 启动时按 scope 归属导入旧预览和 processing 队列，不触碰其他 Bot 的记录。
+
+### 通道与资源
+
+`ChannelPort`、入站事件和附件类型独立于 Telegram。Telegram 自行处理寻址、命令菜单与原生消息编号；无按钮通道可把操作转换成有 scope 归属、有效期、单次使用约束的文字选择。不可编辑通道不推送每段增量。
+
+`RuntimeSupervisor` 从分配起登记资源，覆盖部分启动失败，按消费者到依赖逆序关闭，继续清理其他资源并收集错误。数据库最后关闭、进程锁最后释放。关闭信号只执行一次；Telegram 长轮询可取消并等待退出。原生 RPC 监听器由控制面拥有，停止时移除并等待已开始的审批、通知、观察轮询及定时后台操作完成；共享原生客户端由运行时组装层关闭。客户端分配后立即登记，即使后续初始化失败也会清理。
+
+Codex 控制面挂在后端注册界面下，负责账号、原生面板和审批，不再启动另一套任务恢复逻辑，也不会为统一调度器拥有的任务启动第二个渲染器。多 Bot 共享 RPC 时只处理自己拥有的会话。Antigravity 账号面板与会话/观察服务已独立提取，观察轮询在停止时等待结束。
+
+### 展示依据
+
+默认档位、Boost 和逐轮 token 统计由后端定义声明，模型可携带自己的推理档位。Codex 模型列表完全使用服务端返回结果，移除硬编码补入的模型。状态与模型入口使用共享回调，具体面板由已选后端渲染。
+
+## 已拆分与明确保留的边界
+
+- Codex 提取用量缓存服务、配额服务、原生面板服务，以及账号文件、账号展示、交互解析、工具展示等模块。控制器约从 14,000 行降至 10,000 行，仍保留存量会话、观察与鉴权协调，不能称为全部技术债归零。
+- AGY 提取账号面板和会话/观察服务，统一组合层约从 2,500 行降至 1,600 行。DSH 继续通过独立后端定义接入。
+- 微信仍使用存量 Codex 会话核心，已增加文字选择；没有自动获得完整多后端能力。按用户优先级暂不迁移其观察执行路径。
+- 调度器本身仍承担较多任务恢复和交付工作，后续可沿任务日志与交付服务边界提取。通道收件箱已补齐收取到分类之间的恢复缺口；平台消息交付仍不承诺恰好一次。
+- 独立 OpenCode 控制器仍使用存量任务流程，未完整迁移持久任务日志；已有 OpenCode 执行适配器与统一执行契约兼容，但不能据此声称独立 Bot 已达标。
+- `main.ts` 仍组装鉴权同步与各 Bot 状态；资源退出责任已集中，组装代码可继续按运行时工厂提取。
+
+## 四项完成标准的验收范围
+
+| 标准 | Telegram 统一任务路径 | 证据与边界 |
+| --- | --- | --- |
+| 新增后端不改其他后端 | 达到 | 注入后端定义与界面工厂；未知后端的默认档位、面板、回调和执行通过契约测试 |
+| 新增通道不改执行器 | 达到 | 入站事件、附件与消息能力为通用契约；未知通道可使用同一个后端，执行器不导入 Telegram 文件工具 |
+| 任务全程可恢复 | 达到有边界的恢复要求 | 持久收件箱 → 接受与排队 → 原生配置 → 结果与交付游标；原生结果未知时暂停并要求确认，不能承诺任意外部工具恰好执行一次 |
+| 资源有唯一负责人 | 达到已迁移路径要求 | 运行时拥有共享客户端和数据库；控制面拥有监听与后台操作；调度器拥有任务槽位；Telegram 通道拥有草稿和停止关联；部分启动失败和停止竞态已有测试 |
+
+验收范围为 Telegram 的 Codex / Antigravity / DSH 统一任务路径。微信存量执行路径、独立 OpenCode 控制器和外部会话观察展示仍有遗留边界，因此全仓库四项标准尚未全部达成。
+
+Telegram 已实现单条进度卡、停止操作与完成后的折叠执行摘要。私聊优先使用原生临时草稿，不支持时回退持久消息卡；群聊编辑同一持久消息。停止保留排队任务，并保留已生成内容；最终移除旧停止操作。草稿编号不写成持久消息编号，最终交付前等待正在进行的预览编辑。大工具摘要按完整格式行限长，避免拆坏折叠标签。个人临时设置面板和微信观察摘要尚未启用。
+
+官方功能依据和接入状态见 [Telegram 主通道](telegram-experience.md)。
+
+## 验证
+
+回归覆盖每会话并发启动、跨会话独立执行、取消完成屏障、取消失败、旧回调隔离、新会话与启动竞态、终态重复事件、最终回答交付期间排队、附件队列重启恢复、所有后端切换限制、原生权限 RPC、注册清理与禁用后端保护。另保留全量测试，并运行真实 DSH ACP 控制面集成测试。
+
+v0.13.0 发布前全量回归 547 项：545 通过、2 跳过。任务生命周期、长摘要、控制面审批与后台清理专项 40 项全部通过；准备阶段预览释放测试也已纳入全量回归。pnpm lint、typecheck、build 通过；使用编译产物的真实 DSH ACP 控制面集成测试通过（模型切换、权限保存、恢复、取消、桥接插件加载）。Telegram 新停止字段、收取确认顺序、草稿与卡片降级、过期按钮隔离均有模拟接口验证；未向真实 Bot 发送测试消息，手机交互尚需上线验收。上述改动纳入 v0.13.0 正式版。

package/docs/zh/release.md

@@ -16,38 +16,40 @@
 
 ```bash
 git status --short --branch
-npm pkg get name version
-npm view @foxden-app/foxclaw version
+node -p "require('./package.json').name + '@' + require('./package.json').version"
+pnpm view @foxden-app/foxclaw version
 git tag --list 'v*' --sort=-v:refname | head
 ```
 
 确认目标版本还没有发布，也没有远端 tag：
 
 ```bash
-npm view @foxden-app/foxclaw@0.5.10 version 2>/dev/null || true
+pnpm view @foxden-app/foxclaw@0.5.10 version 2>/dev/null || true
 git ls-remote --tags origin refs/tags/v0.5.10
 ```
 
+使用 `packageManager` 固定的 pnpm 版本，以 `pnpm install --frozen-lockfile` 安装依赖。发布流水线仅在 registry 鉴权和发布步骤使用 npm。
+
 运行与发布 workflow 对齐的本地校验：
 
 ```bash
-npm run lint
-npm run typecheck
-npm test
-npm pack --dry-run
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm pack --pack-destination /tmp/foxclaw-release
 git diff --check
 ```
 
-`npm pack --dry-run` 会执行 `prepack` 构建，并列出 npm 包内容。确认输出里有 `CHANGELOG.md`。
+`pnpm pack` 会执行 `prepack` 构建并创建发布包。使用 `tar -tzf /tmp/foxclaw-release/*.tgz` 检查包含 `CHANGELOG.md`。
 
 ## 准备版本
 
-1. 更新 `package.json` 和 `package-lock.json` 的版本号。
+1. 更新 `package.json` 和 `pnpm-lock.yaml` 的版本号。
 2. 在 `CHANGELOG.md` 顶部新增版本条目，包含 `### 中文` 和 `### English` 小节。
 3. 提交发布 commit，推荐格式：
 
 ```bash
-git add package.json package-lock.json CHANGELOG.md
+git add package.json pnpm-lock.yaml CHANGELOG.md
 git commit -m "发布 0.5.10：一句话说明"
 ```
 
@@ -71,7 +73,7 @@ gh run watch <run-id> --repo foxden-app/foxclaw --exit-status
 成功后确认 npm 和 GitHub Release：
 
 ```bash
-npm view @foxden-app/foxclaw version
+pnpm view @foxden-app/foxclaw version
 gh release view v0.5.10 --repo foxden-app/foxclaw --json tagName,name,url,publishedAt,isDraft,isPrerelease
 ```
 

package/docs/zh/telegram-experience.md

@@ -0,0 +1,40 @@
+# Telegram 主通道：能力评估与接入顺序
+
+日期：2026-10-06。Telegram 是主使用通道；微信保留文字菜单基础，观察模式的消息收纳方案明确后再扩展。
+
+## 官方能力与 FoxClaw 的用途
+
+官方最新列出的版本为 Bot API 10.3（2026-08-24）。10.1 加入富消息，10.2 加入群内定向临时消息，10.3 增加草稿停止控制和禁用按钮。[官方更新记录](https://core.telegram.org/bots/api#recent-changes)
+
+| 优先级 | 能力 | 产品用途 | 当前状态与边界 |
+| --- | --- | --- | --- |
+| P0 | 编辑消息、富消息 | 一条任务进度卡，完成后换成结果；保留模型、权限、审批入口 | 统一任务路径已实现；私聊草稿与群聊持久卡分别管理，结果交付前结束预览。存量观察展示待收敛 |
+| P1 | 草稿原生停止按钮 | 手机直接停止正在生成的回复 | 已接入。只停止对应任务，保留排队任务；群聊和草稿不支持时使用卡片按钮。等待原生取消完成后释放任务槽位 |
+| P1 | 折叠内容、结构化块 | 摘要常驻，工具过程和长日志折叠；需要时查看完整结果 | 统一任务已实现回答在前、执行摘要折叠在后；长摘要限长，长回答按需分块。外部观察卡待统一 |
+| P1 | 禁用按钮 | 正在切换账号、启动或取消任务时明确展示暂不可用的操作 | 待接入。后端仍必须验证操作有效性，展示状态不能代替校验 |
+| P2 | 群内仅本人可见的临时面板 | 账号、模型和个人设置不占公共群消息流 | 待接入；需要独立处理临时消息标识、回调用户与删除/编辑接口 |
+| P2 | 复制文本按钮 | 复制工作目录、恢复命令、任务编号 | 按场景加入，优先采用菜单可直接完成的操作 |
+
+草稿停止使用 `can_stop`、`keep_on_stop` 和 `stopped_message_generation` 更新。草稿限私聊且是临时预览，最终回答仍需发送持久消息。停止事件只携带聊天、主题和草稿编号，必须与当前任务匹配，忽略过期事件。[草稿接口](https://core.telegram.org/bots/api#sendrichmessagedraft)、[停止事件](https://core.telegram.org/bots/api#messagegenerationstopped)
+
+禁用按钮和颜色由 Telegram 键盘类型支持；群内个人面板需要定向临时消息及其专用编辑接口。[键盘按钮](https://core.telegram.org/bots/api#inlinekeyboardbutton)、[临时消息参数](https://core.telegram.org/bots/api#ephemeralmessageparameters)
+
+不把这些功能一次性塞入共享调度器。Telegram 通道声明展示能力并转换事件；调度器只处理任务状态、操作归属和取消结果；各后端提供自己的模型、权限与审批能力。
+
+## 推荐的任务与观察展示
+
+1. 每项任务维护一条进度卡：引擎、阶段、耗时、最近一项工具活动、停止入口。
+2. 增量内容合并、节流编辑，普通工具活动不新增聊天消息。
+3. 审批单独展示，保持明确的任务归属；完成后更新或撤销过期操作。
+4. 最终结果显示结论与必要证据，长过程折叠；文件按需提供。
+5. 观察外部会话沿用相同的信息结构，但保持只读语义。新增输入应明确排队或接管，不因展示重构而暗改。
+
+本轮已落地“单条进度卡 → 停止操作 → 完成后折叠摘要”，覆盖 Telegram 的 Codex / AGY / DSH 统一任务路径。草稿使用同一个编号刷新，运行期间保持更新；完成或停止后清除草稿并发送持久结果。停止事件验证允许的私聊、主题和当前草稿；群聊停止回调还验证用户与具体任务编号。旧按钮与旧草稿不会停止后来启动的任务。
+
+暂未接入定向临时设置面板和禁用按钮，存量外部会话观察展示也未统一。原生 API 能力有自动化模拟验证，手机上的实际交互效果需要上线后由用户验收。
+
+## 微信进入实用阶段的条件
+
+微信无法原地编辑进度卡，建议采用“开始提示 → 必要里程碑 → 最终摘要”。合并重复工具消息，不逐段推送生成文本；失败、审批和需要用户介入时即时提示。
+
+已接受使用文字菜单和命令。本轮增加有会话归属、有效期和单次使用约束的 `/choose` 操作。统一观察摘要、历史整理和完整多后端接入保留为后续工作，不先扩大微信使用范围。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Foxden local execution claw for controlling Codex, OpenCode, Antigravity, and DeepSeek Harness from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",
@@ -35,7 +35,7 @@
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
     "dev": "tsx src/main.ts serve",
     "serve": "node dist/main.js serve",
     "start-service": "node dist/main.js start",
@@ -52,20 +52,23 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "test": "node --test --import tsx $(find src -name '*.test.ts' -print)",
-    "prepack": "npm run build"
+    "prepack": "pnpm build"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.4.0",
     "@opencode-ai/sdk": "1.18.15",
     "dotenv": "^16.6.1",
-    "qrcode-terminal": "^0.12.0"
+    "qrcode-terminal": "^0.12.0",
+    "semver": "7.7.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.0",
     "@types/node": "^24.12.0",
+    "@types/semver": "7.7.1",
     "eslint": "^9.39.0",
     "tsx": "^4.19.3",
     "typescript": "5.9.3",
     "typescript-eslint": "^8.58.0"
-  }
+  },
+  "packageManager": "pnpm@10.33.2"
 }