@foxden-app/foxclaw 0.5.10 → 0.5.12

package/docs/release.md

@@ -0,0 +1,102 @@
+# FoxClaw Release Runbook
+
+This file is for maintainers. User upgrades are driven by `/update` or `foxclaw update`, but those commands install `@foxden-app/foxclaw@latest` from the npm registry. Pushing a PR branch or a normal commit does not make installed nodes receive a new version.
+
+## Release Rules
+
+- npm `latest` is the source of truth for `/update`.
+- The GitHub `Publish` workflow is triggered by `v*` tags and also supports manual dispatch; normal releases should use tags.
+- The tag name must match `v<package.json version>`. For example, `package.json` version `0.5.10` must be released with `v0.5.10`.
+- Versions already present on npm are not published again. Reinstalling the same version may report `0.5.10 -> 0.5.10` in Telegram; that means registry latest did not move.
+- `CHANGELOG.md` must contain the target version entry. `/update` reads that entry from the installed package and shows it as the upgrade notes.
+
+## Preflight
+
+Check the worktree and remote state:
+
+```bash
+git status --short --branch
+npm pkg get name version
+npm 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
+git ls-remote --tags origin refs/tags/v0.5.10
+```
+
+Run the same local checks as the publish workflow:
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm pack --dry-run
+git diff --check
+```
+
+`npm pack --dry-run` runs `prepack` and lists the package contents. Confirm `CHANGELOG.md` is included.
+
+## Prepare The Version
+
+1. Update `package.json` and `package-lock.json`.
+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 commit -m "发布 0.5.10：short release summary"
+```
+
+## Push And Publish
+
+This repository uses lightweight tags:
+
+```bash
+git tag v0.5.10
+git push origin <branch>
+git push origin v0.5.10
+```
+
+Watch the publish workflow:
+
+```bash
+gh run list --repo foxden-app/foxclaw --workflow Publish --limit 5
+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
+gh release view v0.5.10 --repo foxden-app/foxclaw --json tagName,name,url,publishedAt,isDraft,isPrerelease
+```
+
+## Verify `/update`
+
+On a node still running the previous version, send `/update`. Expected:
+
+```text
+FoxClaw upgraded and restarted: 0.5.9 -> 0.5.10.
+
+What changed:
+- ...
+```
+
+If the node is already on the latest version, another `/update` may report:
+
+```text
+FoxClaw upgraded and restarted: 0.5.10 -> 0.5.10.
+```
+
+That means it reinstalled the current npm latest, not that a newer version was available.
+
+## Failure Handling
+
+- If the workflow fails during version validation, check that the tag and `package.json` version match.
+- If npm says the version already exists, do not reuse that version; publish the next patch after fixing the metadata.
+- If npm publish succeeds but GitHub Release creation fails, rerun the workflow or repair the release notes manually.
+- Do not delete and republish npm versions. Prefer publishing a fixed patch release; use npm dist-tags for emergency latest rollback only when necessary.

package/docs/user-manual.md

@@ -359,7 +359,7 @@ FoxClaw recognizes candidate names in these forms:
 - `auth.json.<name>`
 - `auth.json-<name>`
 
-`auth.json` is what Codex currently uses. When switching accounts, FoxClaw points `auth.json` at one candidate. Candidate contents are Codex-generated JSON and should not be hand-written. In multi-bot mode, FoxClaw mirrors a candidate only when its account identity matches, its refresh timestamp is newer, and the active app-server verifies it against the ChatGPT usage endpoint, preventing a same-name candidate from overwriting a different account. Before an auth switch or reload, FoxClaw also searches the other Codex homes for a newer credential with the same account ID, restores it into the requesting runtime, then verifies and mirrors it after restart.
+`auth.json` is what Codex currently uses. When switching accounts, FoxClaw points `auth.json` at one candidate. Candidate contents are Codex-generated JSON and should not be hand-written. In multi-bot mode, FoxClaw mirrors a candidate only when its account identity and identifiable ChatGPT user/email identity are compatible, its refresh timestamp is newer, and the active app-server verifies it against the ChatGPT usage endpoint, preventing a same-name candidate from overwriting a different account or Team seat. Before an auth switch or reload, FoxClaw also searches the other Codex homes for a newer compatible credential, restores it into the requesting runtime, then verifies and mirrors it after restart.
 
 If you already have a working `auth.json`, you can save it as a candidate:
 
@@ -395,7 +395,7 @@ If the login is cancelled or fails, FoxClaw tries to restore the previous auth t
 
 `/auth` lists candidate accounts, the current account, and the auth directory. It also provides buttons for switching, disabling, login, and reload. In multi-bot mode the panel names the `@botname` runtime being managed, because private chats, groups, and topics on one bot share that bot's current auth. The panel shows 8 candidates per page and supports paging, `All / Enabled / Attention` filters, and `/auth list <keyword>` filename search for large local inventories. Panel text and buttons omit the repeated `auth.json_` prefix from standard candidate filenames, so `auth.json_personal` on disk renders as `personal`; files are not renamed, and search and commands still operate on the original candidates. `/auth use <n>` always uses the full-list candidate number, independent of panel paging.
 
-Candidate rows are prefixed with observed `window:remaining-percent` values. For example, a Plus account may show `5h:20|7d:25`, while an account with one monthly window may show `30d:97`. Buttons use a compact two-number `primary|secondary` form such as `20|25`; unknown values render as `—`. The current auth quota is refreshed when the panel opens; other candidates are not switched merely to query quota. When multiple bot runtimes have recently used the same ChatGPT account, FoxClaw combines their cached quota snapshots by verified account ID, so one bot's `/auth` panel can show quota information learned by another bot without mixing different accounts.
+Candidate rows are prefixed with observed `window:remaining-percent` values. For example, a Plus account may show `5h:20|7d:25`, while an account with one monthly window may show `30d:97`. Buttons use a compact two-number `primary|secondary` form such as `20|25`; unknown values render as `—`. The current auth quota is refreshed when the panel opens; other candidates are not switched merely to query quota. When multiple bot runtimes have recently used the same ChatGPT quota identity, FoxClaw combines their cached quota snapshots by verified user/email identity under the account, so one bot's `/auth` panel can show quota information learned by another bot without mixing different seats on the same Team account.
 
 Approximation:
 
@@ -453,7 +453,7 @@ Safety boundaries:
 - Telegram only carries ciphertext. Auth contents, candidate names, account ids, and `last_refresh` live inside the AES-256-GCM encrypted payload.
 - FoxClaw only accepts sync files from bots listed in `AUTH_SYNC_PEERS`; wrong key, cluster, nonce, or payload validation never writes files.
 - Remote imports wait for global local idleness, temporarily switch to the candidate for app-server usage validation, and only then write the candidate.
-- A same-name candidate known to belong to a different account id is never overwritten.
+- A same-name candidate known to belong to a different account id, or to a different identifiable ChatGPT user/email under the same account, is never overwritten.
 - Cross-node recovery only pulls an already-held valid peer copy and does not rotate refresh tokens during recovery. If no peer has a usable copy, it stops and asks you to maintain auth manually. The background 9-day proactive refresh separately requests the cross-node refresh lease and skips that cycle if the lease is not granted.
 
 Dual-active behavior:

package/docs/zh/cross-node-auth-sync.md

@@ -33,7 +33,7 @@
 - 只接收 `AUTH_SYNC_PEERS` 中列出的 peer bot 发来的同步文件。
 - `AUTH_SYNC_KEY`、cluster、nonce 或 payload 校验失败时不会写盘。
 - 远端导入必须等本机全局空闲，再临时验证 usage；验证成功后才写入候选。
-- 同名候选如果已知属于不同 account id，永远拒绝覆盖。
+- 同名候选如果已知属于不同 account id，或属于同一 account 下不同的可识别 ChatGPT 用户/邮箱，永远拒绝覆盖。
 - 同步包不会触发自动回复链路；FoxClaw 对包类型、nonce 和 peer allowlist 做过滤，避免 bot-to-bot 循环。
 
 Telegram 官方 Bot Features 文档说明：私聊 bot-to-bot 需要发送方和接收方都启用 Bot-to-Bot Communication Mode，并提醒开发者处理 loop prevention。参考：https://core.telegram.org/bots/features#bot-to-bot-communication
@@ -164,7 +164,7 @@ auth sync 测试完成：已发送 1，收到回应 1。
 
 确认待导入清单被处理，或候选已经出现/更新时间变新。
 
-注意：`/auth sync push all` 的“已发送”只代表本节点把加密包发给 Telegram 成功，不代表对端已经写盘。对端只有在全局空闲、usage 验证通过、同名候选 account id 一致，并且远端 `last_refresh` 比本地更新时才会覆盖文件。如果本地已经是相同或更新版本，文件不会变化，`最近导入` 也可能保持为空。
+注意：`/auth sync push all` 的“已发送”只代表本节点把加密包发给 Telegram 成功，不代表对端已经写盘。对端只有在全局空闲、usage 验证通过、同名候选 account id 一致且 ChatGPT 用户/邮箱身份兼容，并且远端 `last_refresh` 比本地更新时才会覆盖文件。如果本地已经是相同或更新版本，文件不会变化，`最近导入` 也可能保持为空。
 
 启用跨节点同步后，联系人 bot 的私聊会收到节点级通知：本机 auth 更新并开始发往哪些 peer、收到远端包后是排队还是立即验证、导入成功/跳过/失败原因、auth 恢复时正在查询哪些 peer、peer 回应了什么，以及所有 peer 都无法提供可用副本时的人工介入提示。通知不会包含 auth 内容、token 或同步密文。
 
@@ -198,7 +198,7 @@ auth sync 测试完成：已发送 1，收到回应 1。
 
 - 本机可能不是全局空闲；有 turn、审批、待输入、登录流程或镜像写入时会排队。
 - usage 验证失败会拒绝写盘。
-- 同名候选属于不同 account id 时会拒绝覆盖。
+- 同名候选属于不同 account id，或属于同一 account 下不同的可识别 ChatGPT 用户/邮箱时会拒绝覆盖。
 - 执行 `/auth sync events <候选名>` 或 `/auth sync trace <requestId>`，查看 FoxClaw 记录的接收、验证、跳过或失败流水。
 
 **要不要定期 `/auth refresh all confirm` 保活**

package/docs/zh/release.md

@@ -0,0 +1,102 @@
+# FoxClaw 发布 runbook
+
+本文件给维护者使用。用户侧升级由 `/update` 或 `foxclaw update` 完成，但它们只会安装 npm registry 上的 `@foxden-app/foxclaw@latest`。推 PR、推普通分支或本地提交都不会让已安装节点收到新版。
+
+## 发布规则
+
+- npm `latest` 是 `/update` 的事实来源。
+- GitHub `Publish` workflow 由 `v*` tag 触发，也支持手动 dispatch；正常发布只使用 tag。
+- tag 名必须等于 `v<package.json version>`，例如 `package.json` 是 `0.5.10` 时只能推 `v0.5.10`。
+- npm 上已经存在的版本不会再次发布。重新安装同版本时，Telegram 可能显示 `0.5.10 -> 0.5.10`，这表示 registry latest 没有前进。
+- `CHANGELOG.md` 必须包含目标版本条目。`/update` 完成回报会从已安装包读取这个条目展示“更新内容”。
+
+## 发布前检查
+
+确认工作区和远端状态：
+
+```bash
+git status --short --branch
+npm pkg get name version
+npm 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
+git ls-remote --tags origin refs/tags/v0.5.10
+```
+
+运行与发布 workflow 对齐的本地校验：
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm pack --dry-run
+git diff --check
+```
+
+`npm pack --dry-run` 会执行 `prepack` 构建，并列出 npm 包内容。确认输出里有 `CHANGELOG.md`。
+
+## 准备版本
+
+1. 更新 `package.json` 和 `package-lock.json` 的版本号。
+2. 在 `CHANGELOG.md` 顶部新增版本条目，包含 `### 中文` 和 `### English` 小节。
+3. 提交发布 commit，推荐格式：
+
+```bash
+git add package.json package-lock.json CHANGELOG.md
+git commit -m "发布 0.5.10：一句话说明"
+```
+
+## 推送并触发发布
+
+当前仓库使用 lightweight tag：
+
+```bash
+git tag v0.5.10
+git push origin <branch>
+git push origin v0.5.10
+```
+
+观察发布 workflow：
+
+```bash
+gh run list --repo foxden-app/foxclaw --workflow Publish --limit 5
+gh run watch <run-id> --repo foxden-app/foxclaw --exit-status
+```
+
+成功后确认 npm 和 GitHub Release：
+
+```bash
+npm view @foxden-app/foxclaw version
+gh release view v0.5.10 --repo foxden-app/foxclaw --json tagName,name,url,publishedAt,isDraft,isPrerelease
+```
+
+## 验收 `/update`
+
+在仍安装旧版本的节点上发送 `/update`，期望看到：
+
+```text
+FoxClaw 已升级并重启：0.5.9 -> 0.5.10。
+
+更新内容：
+- ...
+```
+
+如果节点已经是最新版本，再次 `/update` 可能显示：
+
+```text
+FoxClaw 已升级并重启：0.5.10 -> 0.5.10。
+```
+
+这只表示重新安装了当前 npm latest，并不代表有新版本。
+
+## 发布失败处理
+
+- 如果 workflow 在版本校验失败，先检查 tag 和 `package.json` 是否一致。
+- 如果 npm 显示版本已存在，不要复用同一个版本号；修正后发布下一个 patch 版本。
+- 如果 npm publish 成功但 GitHub Release 创建失败，可以重新运行 workflow 或手动修复 release notes。
+- 已发布到 npm 的版本不要删除重发。需要撤回线上 latest 时，优先发布修复版；只有紧急情况下才考虑调整 npm dist-tag。

package/docs/zh/user-manual.md

@@ -359,7 +359,7 @@ FoxClaw 识别这些候选文件名：
 - `auth.json.<name>`
 - `auth.json-<name>`
 
-`auth.json` 是 Codex 当前使用的文件。切换账号时，FoxClaw 会把 `auth.json` 指向某个候选文件。候选文件内容是 Codex CLI 生成的 JSON，不建议手写这些字段。多 bot 镜像只在账号标识一致、刷新时间更新，并且由当前 app-server 通过 ChatGPT 用量接口在线验证时复制候选，避免同名候选意外覆盖成另一个账号。切换或重载 auth 之前，FoxClaw 还会在其他 Codex home 中查找同账号 ID 的较新凭据，先恢复到发起操作的 runtime，再在重启后验证并镜像。
+`auth.json` 是 Codex 当前使用的文件。切换账号时，FoxClaw 会把 `auth.json` 指向某个候选文件。候选文件内容是 Codex CLI 生成的 JSON，不建议手写这些字段。多 bot 镜像只在账号标识和可识别的 ChatGPT 用户/邮箱身份兼容、刷新时间更新，并且由当前 app-server 通过 ChatGPT 用量接口在线验证时复制候选，避免同名候选意外覆盖成另一个账号或同一 Team 下的另一个 seat。切换或重载 auth 之前，FoxClaw 还会在其他 Codex home 中查找兼容的较新凭据，先恢复到发起操作的 runtime，再在重启后验证并镜像。
 
 如果你已经有一个可用的 `auth.json`，可以先备份成候选：
 
@@ -395,7 +395,7 @@ cp -L ~/.codex/auth.json ~/.codex/auth.json_personal
 
 `/auth` 会列出候选账号、当前账号和 auth 目录，并提供按钮切换、禁用、登录和重载。多 bot 模式中，面板顶部还会显示当前正在管理的 `@botname`，因为该 bot 内的私聊、群聊和话题共享同一个当前 auth。面板每页显示 8 个候选，支持翻页、`全部 / 已启用 / 需关注` 筛选和 `/auth list <关键词>` 文件名搜索，适合管理较大的本地候选清单。面板文本和按钮会省略标准候选文件名中重复的 `auth.json_` 前缀，例如磁盘上的 `auth.json_personal` 显示为 `personal`；文件本身不会重命名，搜索和命令仍按原候选工作。命令 `/auth use <n>` 的编号始终对应完整候选列表，不会因为分页变化。
 
-文本列表中每个候选名前的 `窗口:剩余百分比` 来自最近一次观察到的真实额度窗口，例如 Plus 账号可能显示 `5h:20|7d:25`，只有一个月度窗口的账号可能显示 `30d:97`。按钮为了适配窄屏，只显示两个剩余百分比数字，例如 `20|25`；未知值显示为 `—`。当前 auth 会在打开面板时刷新额度；其他候选不会为了查询额度被自动切换。如果多个 bot runtime 最近使用过同一个 ChatGPT 账号，FoxClaw 会按已验证的账号 ID 合并它们缓存到的额度快照，因此一个 bot 的 `/auth` 面板可以显示另一个 bot 掌握到的额度信息，同时不会把不同账号混在一起。
+文本列表中每个候选名前的 `窗口:剩余百分比` 来自最近一次观察到的真实额度窗口，例如 Plus 账号可能显示 `5h:20|7d:25`，只有一个月度窗口的账号可能显示 `30d:97`。按钮为了适配窄屏，只显示两个剩余百分比数字，例如 `20|25`；未知值显示为 `—`。当前 auth 会在打开面板时刷新额度；其他候选不会为了查询额度被自动切换。如果多个 bot runtime 最近使用过同一个 ChatGPT 额度身份，FoxClaw 会按账号下已验证的用户/邮箱身份合并缓存到的额度快照，因此一个 bot 的 `/auth` 面板可以显示另一个 bot 掌握到的额度信息，同时不会把同一个 Team account 里的不同 seat 混在一起。
 
 示意：
 
@@ -453,7 +453,7 @@ AUTH_SYNC_NODE_ID=workstation-a
 - Telegram 只承载密文；auth 文件内容、候选名、account id、`last_refresh` 都在 AES-256-GCM 加密 payload 内。
 - 只接收 `AUTH_SYNC_PEERS` 中 peer bot 发来的同步文件；密钥、cluster、nonce 或 payload 校验失败时不会写盘。
 - 远端导入必须等本机全局空闲，再临时切换到待验证 auth、重启 app-server、读取 usage 验证成功后才写入候选。
-- 同名候选如果已知属于不同 account id，永远拒绝覆盖。
+- 同名候选如果已知属于不同 account id，或属于同一 account 下不同的可识别 ChatGPT 用户/邮箱，永远拒绝覆盖。
 - 跨节点恢复只拉取 peer 已持有的有效副本，不会在恢复过程中直接轮换 refresh token；找不到有效副本时会停止，提示你人工维护授权。后台 9 天主动刷新会单独申请跨节点刷新锁，拿不到锁就跳过本轮。
 
 双主动流程：

package/package.json

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