apphx 1.1.0 → 2.0.0

package/README.md

@@ -1,227 +1,95 @@
 # apphx
 
-给现有 AI agent 接入 Flutter / iOS 开发、验收与交付流程。复用宿主的模型、会话和工具，不启动另一套 coding agent。
+给现有 AI agent 接入应用开发、验收与交付流程。支持 **Java Android、Swift、Flutter、React Native、Expo、uni-app、MyGo macOS**，可新建项目或接管已有工程；复用宿主模型和工具，不启动另一套 coding agent。
 
-## 1. 安装 CLI
+## 快速开始
 
-需要 Node.js **22.18+**。从 **1.1.0** 起，npm 包、命令和 Skill 统一为 **`apphx`**。已有 1.0 安装时，先按第 4 节迁移，**不要先升级 CLI**。
+需要 Node.js **22.18+**。先安装 CLI，再在控制项目中安装宿主工作流：
 
-| 包管理器 | 安装 CLI | 运行命令 | 卸载 CLI |
-| --- | --- | --- | --- |
-| npm | `npm install -g apphx` | `apphx` | `npm uninstall -g apphx` |
-| pnpm | `pnpm add -g apphx` | `apphx` | `pnpm remove -g apphx` |
-| Yarn Classic 1.x | `yarn global add apphx` | `apphx` | `yarn global remove apphx` |
-| Yarn 2+ | 在目标项目中 `yarn add -D apphx` | `yarn exec apphx` | `yarn remove apphx` |
-
-先确认目标版本已在 npm 发布；本地试用或发布前，将表格中的包名换成安装包的绝对路径，例如 `$PWD/apphx-1.1.0.tgz`。Yarn Classic 全局安装不能使用相对 tarball 路径。
-
-pnpm 提示缺少全局 bin 目录时，先运行 `pnpm setup` 并重新打开终端。Yarn 2+ 没有 `yarn global`：后文的 `apphx ...` 全部改用 `yarn exec apphx ...`，并从安装了依赖的控制项目目录执行。
-
-npm / pnpm 也可先在控制项目中执行 `npm install -D apphx` / `pnpm add -D apphx`，之后分别用 `npm exec --offline --package=apphx -- apphx ...` / `pnpm exec apphx ...`。Skill 只使用已安装的依赖，不会代为下载 CLI。
-
-## 2. 接入你的 agent
+```sh
+npm install -g apphx
+apphx install codex
+apphx init --framework android-java --platform android --package-target apk
+```
 
-在要开发应用的项目目录执行对应命令，再重新打开该目录的 agent 会话。
+`init` 只创建 `factory.json`，不覆盖已有文件，也不生成应用代码。按项目校准构建、设备验收和签名配置后，重新打开 agent 会话，交给它继续：
 
-| Agent | 安装工作流 | 在 agent 中启动 |
-| --- | --- | --- |
-| Codex App / CLI | `apphx install codex` | `$apphx <需求>` |
-| Claude Code | `apphx install claude` | `/apphx <需求>` |
-| Cursor | `apphx install cursor` | `/apphx <需求>` |
-| Pi | `apphx install pi` | `/skill:apphx <需求>` |
-| Gemini CLI | `apphx install gemini` | `请启用 apphx skill，<需求>` |
-| OpenCode | `apphx install opencode` | `请加载 apphx skill，<需求>` |
-| DeepSeek Harness | `apphx install deepseek` | `请加载 apphx skill，<需求>` |
-| Hermes | `apphx install hermes --global` | `/apphx <需求>` |
+```text
+$apphx 接管我的 Java Android 项目，完成真实验收，只做本地构建，不上传。
+```
 
-其他项目加 `--project /path/to/project`；用户级安装加 `--global`。Hermes 的全局目录跟随 `HERMES_HOME`，默认 `~/.hermes/skills`。也可在 Git 项目内使用 `apphx install hermes`，然后由你执行 `hermes skills trust` 授予项目信任；安装器不会代为授权。见 [Hermes Skills](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)。
+其他宿主先用 `apphx hosts` 查看安装方式；通常为 `apphx install <host>`：
 
-例如在 Codex 中输入：
+| 宿主 | 启动工作流 |
+| --- | --- |
+| Codex | `$apphx <需求>` |
+| Claude Code / Cursor | `/apphx <需求>` |
+| Pi | `/skill:apphx <需求>` |
+| Gemini / OpenCode / DeepSeek | 请加载 apphx skill，随后描述需求 |
+| Hermes | `apphx install hermes --global` 后使用 `/apphx <需求>` |
 
-```text
-$apphx 开发行李配重应用：离线记录物品重量、检查超重、支持备份恢复；完成模拟器验收，只做本地构建，不上传。
-```
+项目本地安装 CLI 时，使用原包管理器的 `pnpm exec apphx`、`yarn exec apphx` 或 `npm exec --offline --package=apphx -- apphx`；Skill 不会替你下载 CLI。
 
-## 3. 准备环境并确认接入
+## 选择项目与交付方式
 
-实际 iOS 验收需要 **macOS、完整 Xcode、Flutter 和模拟器**。仅在允许本机执行构建与验收命令时运行：
+- `--framework`：`android-java`、`swift`、`flutter`、`react-native`、`expo`、`uni-app`、`mygo`。
+- `--platform`：`android`、`ios` 或 `macos`；Java Android 仅 Android，Swift 仅 iOS，MyGo 仅 macOS。
+- `--package-target`：Android 用 `apk` / `aab`，iOS 用 `simulator` / `ipa`，MyGo macOS 用 `app` / `dmg`。
+- 已有工程在需求中设置 `project.sourceDir`，嵌套应用再设置 `project.directory`。只修改固定快照，不重写原工程或强制迁移技术栈。
 
-```sh
-apphx init --allow-local-execution
-```
+各技术栈及已有工程的成对需求/配置见 [examples](https://github.com/daguanren21/apple-app-factory/tree/main/packages/apple-app-factory/examples)（含 MyGo 原生 UI / Web）。复制到控制目录后按真实项目编辑，不要修改安装包资产或添加空验收脚本。
 
-用 `flutter devices` 查询目标并设置真实的 `IOS_DEVICE_ID`；按 `factory.json` 配置验收命令，指定 SDK 时设置 `toolchain.flutterSdk`。然后检查：
+需求文件就绪后，可直接检查环境和任务状态：
 
 ```sh
-apphx doctor --build-only
+apphx doctor requirement.json --build-only
 apphx doctor --host codex
 apphx status
 ```
 
-宿主 ID、`--project` / `--global` 与安装时保持一致。宿主检查只证明安装文件完整，实际加载看宿主的技能列表；Hermes 可用 `hermes skills list`。
+后续由 agent 按 `next` 返回的 action 研究、开发、审查，再通过 `step` 执行验收和打包。中断后继续原 `JOB_ID`，不要重复入队。全部命令见 `apphx --help`。
 
-无需配置另一份模型 API key 或 builder/reviewer。agent 负责研究、开发和独立审查，CLI 执行验收与交付门禁。`status` 返回任务 ID、阶段、错误和产物路径；中断后继续同一任务 ID，不重复入队。
+### 商店提交由人工完成
 
-## 4. 更新与卸载
+apphx 只负责在本地产出并验证 iOS/Android/macOS 包；App Store / Google Play 的上传、提交与审核都是工具之外的人工工作。内部关卡是真实验证证明 + 新鲜独立复核，附带诚实差异与质量清单：真实价值、视觉身份、开发者与应用元数据、已运行功能与代码身份——绝不伪造身份/IP、篡改哈希、隐藏敏感功能或脚本化回复，也不承诺过审。`apple` 元数据块是可选的所有者文档，不是提交要求。详见安装的 apphx Skill。
 
-以下适用于已经使用 `apphx` 命令和 Skill 的安装；1.0 用户先完成下方迁移。先升级 CLI（本地试用则安装新的 tarball），再显式更新宿主工作流：
+## 注意事项
 
-| 包管理器 | 升级 CLI |
-| --- | --- |
-| npm | `npm install -g apphx@latest` |
-| pnpm | `pnpm add -g apphx@latest` |
-| Yarn Classic 1.x | `yarn global add apphx@latest` |
-| Yarn 2+ | 在控制项目中 `yarn add -D apphx@latest` |
+- **执行权限**：默认不开启本地执行或云构建。确认命令可信后，才加 `--allow-local-execution` 或开启 `allowLocalExecution`。工作区不是安全沙箱；检查与真实运行验收都不能省略。
+- **子进程隔离**：可显式配置 `isolation: { "mode": "macos-sandbox", "readOnlyPaths": [], "network": "deny" }`。macOS 检查/打包子进程默认只能访问自己的工作区、临时目录和批准的工具；后端不可用会阻塞，不回退。它不隔离宿主 agent，不提供 VM/资源配额，也不保证 GUI/设备工具兼容；未配置时仍是可信执行。详见 Skill。
+- **工具链**：iOS 本地构建需要 macOS、完整 Xcode 和设备/模拟器；Android 需要匹配的 JDK、Android SDK 和设备/模拟器。配置外部 Flutter SDK 隔离克隆时，文件系统须支持写时复制。模块名、scheme、产物路径与签名按实际工程校准；`doctor` 通过不代表应用已运行。
+- **Expo / uni-app**：Expo 使用 EAS local 时仍需认证和签名配置，且不保证完全离线；不要求 prebuild/eject。经典 HBuilderX uni-app 不要求添加 package.json 或 npm 工程，保留原有构建与设备验收命令；WGT/H5 产物不能冒充 APK/IPA。
+- **MyGo macOS**：`apphx init --framework mygo` 默认 macOS/app；固定 MyGo v0.3.0 需 Go 1.27.1。仅本地 ad-hoc 签名、不公证/上传；原生 UI 不要求 Bun。`doctor` 在导入源的应用目录检查项目工具；新项目尚无源码时明确报告无法检查，不借用控制目录模块。真实桌面验收、名称/版本/架构和输出路径须按 Skill 与示例校准。
+- **源码与产物**：控制配置、状态目录和导入源必须分离。应用目录不能放在被排除的 build/cache 路径下；产物必须新生成，拒绝符号链接别名和旧产物。Gradle `files` / `dirs` 集合只支持可证明归属的字面量路径，不接受未计入快照的外部可变依赖。
+- **渠道**：默认 `channel: "local"`。`app-store` / `google-play` 只标记交付去向，产出仍是本地包；商店上传、提交与审核都是工具之外的人工工作。`built` 不等于上架或过审。
+- **IPA 导出**：内置 Flutter 导出及配置中可识别的 `xcodebuild -exportArchive` 使用检查后的本地导出配置快照，拒绝 `destination=upload`。任意自定义脚本仍须信任审查；这不是脚本沙箱。
+- **默认值与云构建**：不传技术栈时，`init` 默认 Flutter/iOS/simulator；`android-java` 默认 Android/APK，Expo 默认 iOS/IPA。远程云编译另需 `allowCloudBuild`；不确定的远程结果先对账，不自动重放。
+- **升级旧数据**：先结束活跃任务，保留 `.factory`、配置和迁移备份。新需求显式带 `platform`，配置带 `packageTarget`；`version`、`screenshotsDir` 放在需求顶层。队列 v3 保留历史与回执、清除旧证明；重新验收后再继续。1.0 用户须在升级 CLI 前用原 `app-factory uninstall` 安全卸载未修改的旧 Skill，再安装新 `apphx` Skill；不要覆盖修改过的安装。
+- **宿主与调度**：更新、卸载时保持原 `--project` / `--global` 作用域。Hermes 项目级安装还需你手动授予信任；定时任务应唤醒宿主、续跑同一任务并避免重叠，不能只定时执行 `next`。详见 [Hermes 调度文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)。
 
-npm / pnpm 项目本地依赖分别用 `npm install -D apphx@latest` / `pnpm add -D apphx@latest`。升级后执行：
+已安装的工作流需显式更新或卸载；这些操作不会删除应用代码、配置或任务数据：
 
 ```sh
 apphx update codex
-apphx update hermes --global
-```
-
-`install` 只安装；重复安装相同内容不做改动，已有不同版本会提示使用 `update`。`update` 不创建缺失的安装，也不会覆盖你修改过的文件。更新使用原来的 `--project` / `--global` 作用域。
-
-卸载时先移除工作流，再按安装表卸载 CLI：
-
-```sh
 apphx uninstall codex
-apphx uninstall hermes --global
-```
-
-不会删除应用代码、`factory.json`、`remote.json` 或 `.factory` 任务数据。
-
-<details>
-<summary>已有 1.0 安装：迁移到统一的 apphx 入口</summary>
-
-1.0 的 npm 包已经叫 `apphx`，但可执行文件是 `app-factory`，Skill 是 `apple-app-factory`。1.1 只支持新的 `apphx` 入口；新版不会识别、接管或自动改名旧 Skill。
-
-1. **暂停所有定时工作**，例如 `hermes cron pause CRON_ID`。保存原 `JOB_ID`、配置绝对路径、每个宿主的安装作用域与 profile；确认先前执行已结束，状态不明时停止，不抢占任务。
-2. **升级 npm 包之前**，用仍已安装的 **1.0 CLI** 卸载每一个未修改的旧 Skill。下面是项目级和全局示例；将宿主、路径换成原安装值，对所有安装逐一执行，保持原 `--project` / `--global` 及 `HERMES_HOME` 等环境：
-
-   ```sh
-   app-factory uninstall codex --project /absolute/project
-   app-factory uninstall hermes --global
-   ```
-
-   若旧 CLI 是控制项目的本地依赖，使用原项目的 `pnpm exec app-factory`、`yarn exec app-factory` 或 `npm exec --offline --package=apphx -- app-factory` 前缀执行同样的卸载。
-
-   **如果 CLI 已升级**，由你明确手动调用精确的旧版本作为卸载工具（可能需要下载并确认），而不是让新版兼容或让 Skill 自动获取旧 CLI：
-
-   ```sh
-   npm exec --package=apphx@1.0.0 -- app-factory uninstall codex --project /absolute/project
-   npm exec --package=apphx@1.0.0 -- app-factory uninstall hermes --global
-   ```
-
-   旧卸载器只移除归其所有且未修改的安装。若发现编辑过、添加或缺失的文件而拒绝，**停止自动迁移**：由你备份、审阅并决定如何保留；如需退出旧 Skill，由你明确将完整目录归档到宿主发现范围之外。不要覆盖、自动删除或篡改所有权标记来绕过拒绝。更早的本地预览包 `apple-app-factory` 也应先用其原 CLI 安全卸载 Skill，再用原包管理器卸载旧包。
-3. 确认 1.1.0 可获取后，按上表升级 `apphx`（或安装已验证的 1.1.0 tarball），运行 `apphx --version` 确认版本，再用 **`install`，不是 `update`** 安装新 Skill：
-
-   ```sh
-   apphx install codex --project /absolute/project
-   apphx install hermes --global
-   apphx status JOB_ID --config /absolute/project/factory.json
-   ```
-
-   保留原 `factory.json`、`remote.json`、`.factory` 及其任务数据，不重新 `init` 或 `enqueue`。使用 SSH 时，也在 Mac 主机升级 CLI，并将 `remote.json` 的 `executable` 改为该主机 `apphx` 的绝对路径，其他字段保持不变。重新打开宿主，确认加载的是 `apphx`；按第 2 节的新名称调用，继续同一个 `JOB_ID`。
-4. 在恢复调度前，编辑**原定时任务**的命令、Skill 和名称为 `apphx` / `apphx` / `apphx-continue`，保留原任务 ID、配置、工作目录和防重叠设置，不另建并行调度。Hermes 可先替换所附 Skill（保留其他 Skill）：
-
-   ```sh
-   hermes cron edit CRON_ID --remove-skill apple-app-factory --add-skill apphx
-   hermes cron list
-   ```
-
-   同时按第 5 节修改原任务提示词与名称；核对配置和任务状态后，才执行 `hermes cron resume CRON_ID` 或恢复原调度器。不要用恢复调度替代人工授权。
-
-</details>
-
-
-## 5. Hermes 与定时任务
-
-先在 Hermes 中完成一次正常接入，取得 `apphx status` 中的任务 ID。定时任务**唤醒 Hermes 并续跑这个任务**，不是重复 `enqueue`，也不是只运行 `apphx next`。
-
-将 `JOB_ID`、`/absolute/project` 换成真实值，使用相同的 Hermes profile：
-
-```sh
-hermes cron create "every 30m" \
-  "继续 apphx 任务 JOB_ID，配置 /absolute/project/factory.json。先检查 status；若 running 且原执行是否结束不明，则报告并停止。否则读取 next，只处理一个返回 action；wait/done 或需要人工授权时停止。所有 apphx 操作使用 --build-only，不重复 enqueue，不上传。" \
-  --skill apphx \
-  --workdir /absolute/project \
-  --name apphx-continue \
-  --paused
-hermes cron list
 ```
 
-核对后，将 `CRON_ID` 换成 Hermes 返回的定时任务 ID，再启用：
+## 开发与发布
 
-```sh
-hermes cron resume CRON_ID
-hermes cron status
-```
-
-- **Hermes gateway 必须运行**：可前台运行 `hermes gateway`，或按官方方式安装服务。`hermes cron tick` 不会替你启动 gateway。
-- gateway 的执行环境必须能访问 CLI、同一配置/工作目录和 Mac 工具链；使用本地 Yarn 依赖时还需在控制项目中使用 `yarn exec apphx`。
-- 同一 apphx 任务只交给一个调度入口；不要同时手工编辑。Hermes 的定时任务去重不是 apphx 跨宿主的文件编辑锁。需要人工处理时先 `hermes cron pause CRON_ID`。
-- 系统 cron / launchd / CI 也遵循相同边界：只查询状态可直接运行 CLI；需要模型工作时必须唤醒已有 agent 宿主，保留任务 ID、工作目录、环境和防重叠设置。
-
-创建为暂停状态不会自动执行。具体调度、恢复和服务安装见 [Hermes 定时任务文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)。
-
-默认只构建、不上传；`built` 不代表 App Store 批准。Skill 不接管宿主所有工具权限，CLI 只对本项目的任务推进和交付执行门禁。
-
-<details>
-<summary>开发、打包与版本发布（Turborepo + tsdown + repoctl）</summary>
-
-维护者使用 `.nvmrc` 指定的 **Node.js 24.22.1** 和 **pnpm 12.15.0**。根目录是私有工具 workspace，唯一发布包为 `apphx`；内部源码目录保留 `packages/apple-app-factory`，以兼容 repoctl 对已发布版本的历史路径校验。Turbo 编排构建、类型检查和测试，tsdown 生成发布产物，repoctl 管理版本和发布。
+维护者使用 `.nvmrc` 指定的 Node.js 和仓库声明的 pnpm 版本：
 
 ```sh
 pnpm install
-pnpm exec repoctl config validate --json
 pnpm test
 pnpm run package:check
 pnpm run package:pack
 ```
 
-构建缓存包含 `dist`、README 与两份 MIT 许可证，并将根目录 README/LICENSE 纳入缓存输入；测试不缓存结果。只使用本地 Turbo 缓存，没有启用远程缓存。安装包输出到仓库根目录。
-
-### Trusted Publisher 与原始源码恢复
-
-1.0.0 的手动首发及原生元数据补齐已完成；后续使用 repoctl，不重复手动 `npm publish`。npm Trusted Publisher 保持以下身份：
-
-| npm 字段 | 值 |
-| --- | --- |
-| Organization or user | `daguanren21` |
-| Repository | `apple-app-factory` |
-| Workflow filename | `release.yml`（只填文件名） |
-| Environment name | `npm` |
-| Allowed actions | 必须允许 `npm publish`；只有默认的 `npm stage publish` 不够 |
-
-GitHub 的 `npm` environment 应受保护，发布 job 保留 `id-token: write`；源码仓库必须公开以生成 provenance。CI 使用 OIDC，不保存长期 npm token。`npm dist-tag` 是独立权限，不能替代 `npm publish`。可在 **Release** 工作流运行 `oidc-audit` 核对身份。
-
-新建 Trusted Publisher 后，须在 **2 天内**通过它完成首次成功发布，否则配置过期，必须删除重建；审计或已发布版本的元数据恢复不算首次发布。首次成功发布后，该初始 2 天限制不再适用。见 [npm Trusted Publisher 配置规则](https://docs.npmjs.com/trusted-publishers/)。
-
-发布中断时，从 `main` 手动分发 **Release**，选择 `publish`，`source-sha` 填引入该版本 changelog/ledger 的完整版本提交 SHA，先勾选 `dry-run`。它不能是任意后续文档提交。核对目标版本、源码与已发布包后，以同一输入取消 dry-run；repoctl 补齐缺失步骤，已存在的 npm 版本不重复上传。
-
-不要拿后续 `main` 冒充原始源码、重写历史 manifest/changelog/ledger，或覆盖 `GITHUB_SHA`。repoctl 会隔离所选版本提交；来源不明、内容冲突或完整性不符时停止调查，不移动已有 tag，也不绕过校验。保留 `repoctl-release-state` 和发布诊断产物。
-
-### 原生版本发布
-
-按实际变更选择 `patch`、`minor` 或 `major`；每项变更只记录一次意图，再检查原生计划：
-
-```sh
-pnpm change apphx --bump patch --summary "描述本次用户可见改动"
-pnpm run release:plan
-```
-
-确认目标版本，审查并提交实现及意图，推送到 `main`；不能在脏工作树上跳过门禁。随后在 GitHub Actions 的 **Release** 中依次运行 `plan`、`prepare`，审查原生版本 PR 和 changelog/ledger，检查通过后合并，再运行 `publish`（先勾选 `dry-run`）。`prepare` 会创建并推送版本 PR；repoctl 负责质量门禁、版本、npm 上传、tag、GitHub Release 与检查点。
-
-使用默认 `GITHUB_TOKEN` 准备 PR 时，需要允许 Actions 创建 PR，并在生成的版本分支手动运行 **Check**；该 token 创建的 PR 不会自动触发普通 PR 工作流。已有 GitHub App 时，可配置 `REPOCTL_APP_CLIENT_ID` 变量和 `REPOCTL_APP_PRIVATE_KEY` secret。
-
-Release 仅手动触发，不会因普通 push 自动上传。保留 `repoctl-release-state` 检查点；恢复细节见 [repoctl 发布文档](https://repo.icebreaker.top/tasks/release)。不要对私有根包直接执行 `npm publish`。
-
-本项目不安装本地提交钩子，Release 是自有的手动工作流；`repo doctor` 对这两项的提示会保留，不应为清除提示而自动覆盖发布流程。
+未发布的源码改动请使用本地打包产物验证，不要假定 npm 上的旧版本已经包含它们。Yarn 2+ 使用项目依赖；pnpm 全局安装缺少 bin 目录时先运行 `pnpm setup`。
 
-配置与需求示例见 [factory.json](https://github.com/daguanren21/apple-app-factory/blob/main/packages/apple-app-factory/examples/factory.json) 和 [luggage.json](https://github.com/daguanren21/apple-app-factory/blob/main/packages/apple-app-factory/examples/luggage.json)。全部命令见 `apphx --help`；不要删除 `.factory`。
+维护入口：`pnpm smoke:apps --help` 驱动真实 Android Java / MyGo 应用与重启持久化；`pnpm eval:prepare /absolute/fresh-run` 生成原生 agent 审核案例，再用 `pnpm eval:score /absolute/fresh-run --manifest-sha256 PREPARE_HASH` 检查实际结果；未运行不能算通过。`pnpm bench:peers` 提供固定十应用比较基准。工具链须已安装；评估案例不是 iOS 真机或商店过审证明，详情见各命令帮助。
 
-</details>
+版本变更通过 `pnpm change apphx --bump patch --summary "变更说明"` 记录，再运行 `pnpm run release:plan`。发布只走已有的手动 Release 工作流；恢复时绑定原版本提交，不改写历史、tag 或 ledger。详见 [repoctl 发布文档](https://repo.icebreaker.top/tasks/release)。
 
 ## License
 

package/benchmarks/peer-context-worker.mjs

@@ -0,0 +1,186 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { syncBuiltinESMExports } from 'node:module';
+import { Session } from 'node:inspector';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const [root, label, output, mode] = process.argv.slice(2);
+const manifest = JSON.parse(fs.readFileSync(join(root, 'manifest.json'), 'utf8'));
+const dist = manifest[label].dist;
+const sha = value => createHash('sha256').update(value).digest('hex');
+const report = { label, mode: mode ?? 'timing', wallMs: null, operations: 0, errors: [], claims: 0, resumes: 0, outputBytes: 0, expectedRejections: 0, work: {} };
+const { Store } = await import(pathToFileURL(join(dist, 'store.js')));
+const { nextTurn, completeTurn } = await import(pathToFileURL(join(dist, 'runner.js')));
+const store = new Store(join(root, 'state'));
+const jobs = store.list();
+assert.equal(jobs.length, manifest.apps);
+// Independent oracle over the deliberately simple fixture: no production fingerprint helper.
+function sourceHash(directory) {
+  const hash = createHash('sha256');
+  function visit(path) {
+    for (const name of fs.readdirSync(path).sort()) {
+      if (path === directory && name === '.dart_tool') continue;
+      const file = join(path, name), stat = fs.lstatSync(file);
+      assert(!stat.isSymbolicLink());
+      if (stat.isDirectory()) visit(file);
+      else hash.update(relative(directory, file)).update('\0').update(`${stat.size}:${stat.mode & 0o777}\0`).update(fs.readFileSync(file));
+    }
+  }
+  visit(directory);
+  return hash.digest('hex');
+}
+const expected = new Map(jobs.map(job => {
+  const peers = jobs.filter(peer => peer.spec.id !== job.spec.id).sort((a, b) => a.id.localeCompare(b.id)).map(peer => ({ jobId: peer.id, spec: peer.spec, source: peer.workspace, importedSource: peer.sourceDirectory, directory: '.', revision: { source: sourceHash(peer.workspace), dependencies: sha('factory-dependency-resolution-v1\0missing') } }));
+  return [job.id, { peers: JSON.parse(JSON.stringify(peers)), digest: sha(JSON.stringify(peers)) }];
+}));
+const prompts = {};
+const goldenPath = join(root, 'expected-prompts.json');
+const golden = fs.existsSync(goldenPath) ? JSON.parse(fs.readFileSync(goldenPath, 'utf8')) : null;
+let instrumentation = false;
+let session;
+const post = (method, parameters = {}) => new Promise((resolve, reject) => session.post(method, parameters, (error, result) => error ? reject(error) : resolve(result)));
+if (mode === '--instrument') {
+  for (const name of ['readFileSync', 'readdirSync', 'lstatSync', 'realpathSync', 'existsSync']) {
+    const original = fs[name];
+    fs[name] = function (...args) {
+      if (!instrumentation) return Reflect.apply(original, this, args);
+      const entry = report.work[name] ??= { calls: 0, bytes: 0, microseconds: 0 };
+      const start = process.hrtime.bigint();
+      try {
+        const value = Reflect.apply(original, this, args);
+        entry.calls++;
+        if (name === 'readFileSync') {
+          entry.bytes += Buffer.byteLength(value);
+          const path = String(args[0]);
+          if (path.includes('/workspaces/') && /\/(?:source-\d+\.dart|pubspec\.yaml)$/.test(path)) {
+            const key = path.endsWith('pubspec.yaml') ? 'manifestReads' : 'payloadReads';
+            const count = report.work[key] ??= { calls: 0, bytes: 0 };
+            count.calls++;
+            count.bytes += Buffer.byteLength(value);
+          }
+        }
+        return value;
+      } finally { entry.microseconds += Number(process.hrtime.bigint() - start) / 1000; }
+    };
+  }
+  syncBuiltinESMExports();
+  const list = Store.prototype.list;
+  Store.prototype.list = function (...args) {
+    if (instrumentation) report.work.storeListCalls = (report.work.storeListCalls ?? 0) + 1;
+    return Reflect.apply(list, this, args);
+  };
+  session = new Session();
+  session.connect();
+  await post('Profiler.enable');
+  await post('Profiler.start');
+}
+function consume(action, job, resumed) {
+  const serialized = JSON.stringify(action);
+  report.outputBytes += Buffer.byteLength(serialized);
+  const result = JSON.parse(serialized);
+  assert.equal(result.action, 'host');
+  assert.equal(result.job.id, job.id);
+  assert.equal(result.job.stage, 'research');
+  assert.equal(result.job.status, 'running');
+  assert.equal(result.job.hostTurns, 1);
+  assert.deepEqual(result.job.attempts, { research: 1 });
+  assert.equal(result.turn.id, result.job.turn.id);
+  assert.match(result.turn.id, /^[a-f0-9-]{36}$/);
+  assert.equal(result.turn.cwd, job.workspace);
+  assert.equal(result.turn.stage, 'research');
+  assert.deepEqual(result.turn.environment, { CI: '1' });
+  assert.equal(result.job.turn.policyContextDigest, expected.get(job.id).digest);
+  const marker = 'Other same-channel products, including pending batch packages (read-only comparison): ';
+  const start = result.turn.prompt.indexOf(marker);
+  assert(start >= 0);
+  const peerLine = result.turn.prompt.slice(start + marker.length).split('\n')[0];
+  assert.deepEqual(JSON.parse(peerLine), expected.get(job.id).peers);
+  if (resumed) assert.deepEqual(result.turn, prompts[job.id].turn);
+  else prompts[job.id] = { hash: sha(result.turn.prompt), turn: result.turn };
+  if (golden) assert.equal(sha(result.turn.prompt), golden[job.id], 'Full prompt differs from frozen baseline');
+  return result;
+}
+const cpuStart = process.cpuUsage();
+const started = process.hrtime.bigint();
+instrumentation = mode === '--instrument';
+try {
+  for (const resumed of [false, true]) {
+    for (const job of jobs) {
+      report.operations++;
+      try {
+        consume(await nextTurn(store, job.id), job, resumed);
+        report[resumed ? 'resumes' : 'claims']++;
+      } catch (error) { report.errors.push({ operation: resumed ? 'resume' : 'claim', job: job.id, message: error.stack }); }
+    }
+  }
+} finally {
+  report.wallMs = Number(process.hrtime.bigint() - started) / 1e6;
+  report.cpu = process.cpuUsage(cpuStart);
+  instrumentation = false;
+}
+if (session) {
+  const { profile } = await post('Profiler.stop');
+  fs.writeFileSync(output.replace(/\.json$/, '.cpuprofile'), JSON.stringify(profile));
+  session.disconnect();
+  const hits = new Map();
+  const nodes = new Map(profile.nodes.map(node => [node.id, node]));
+  for (const id of profile.samples ?? []) {
+    const frame = nodes.get(id).callFrame;
+    const key = `${frame.functionName || '(anonymous)'} ${frame.url}:${frame.lineNumber + 1}`;
+    hits.set(key, (hits.get(key) ?? 0) + 1);
+  }
+  report.profile = { samples: profile.samples?.length ?? 0, top: [...hits].sort((a, b) => b[1] - a[1]).slice(0, 25) };
+}
+if (!golden && !report.errors.length) {
+  assert.equal(label, 'baseline');
+  fs.writeFileSync(goldenPath, JSON.stringify(Object.fromEntries(Object.entries(prompts).map(([id, value]) => [id, value.hash])), null, 2), { flag: 'wx', mode: 0o600 });
+}
+if (mode === '--correctness' && !report.errors.length) {
+  async function rejectsPeerChange(name, mutate, restore) {
+    const target = jobs[0], before = store.get(target.id);
+    try {
+      mutate();
+      await assert.rejects(nextTurn(store, target.id), /peer comparison context changed/);
+      report.expectedRejections++;
+      assert.throws(() => completeTurn(store, target.id, before.turn.id, {}), /peer comparison context changed/);
+      report.expectedRejections++;
+      assert.deepEqual(store.get(target.id), before, `${name} stale rejection mutated the claimed task`);
+    } catch (error) { report.errors.push({ operation: name, message: error.stack }); }
+    finally { restore(); }
+    consume(await nextTurn(store, target.id), target, true);
+  }
+  try {
+    // Exercise the native CLI boundary, consume all output, and preserve the exact claim.
+    for (const job of jobs) {
+      const child = spawnSync(process.execPath, [join(dist, 'cli.js'), 'next', job.id, '--config', join(root, 'factory.json')], { encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024 });
+      assert.equal(child.status, 0, child.stderr);
+      consume(JSON.parse(child.stdout), job, true);
+      report.cliResumes = (report.cliResumes ?? 0) + 1;
+    }
+    const peer = jobs[1], file = join(peer.workspace, 'lib', 'source-00000.dart');
+    const bytes = fs.readFileSync(file), stat = fs.statSync(file);
+    await rejectsPeerChange('same-size peer source with restored mtime', () => {
+      const changed = Buffer.from(bytes); changed[changed.length - 1] ^= 1;
+      fs.writeFileSync(file, changed); fs.utimesSync(file, stat.atime, stat.mtime);
+    }, () => { fs.writeFileSync(file, bytes); fs.utimesSync(file, stat.atime, stat.mtime); });
+    const dependencyDirectory = join(peer.workspace, '.dart_tool');
+    await rejectsPeerChange('generated dependency resolution', () => {
+      fs.mkdirSync(dependencyDirectory);
+      fs.writeFileSync(join(dependencyDirectory, 'package_config.json'), JSON.stringify({ configVersion: 2, packages: [] }));
+    }, () => fs.rmSync(dependencyDirectory, { recursive: true, force: true }));
+    const originalSpec = store.get(peer.id).spec;
+    await rejectsPeerChange('peer metadata', () => store.update(peer.id, { spec: { ...originalSpec, purpose: `${originalSpec.purpose} changed` } }), () => store.update(peer.id, { spec: originalSpec }));
+    // Scheduler bookkeeping must not invalidate peer comparison inputs.
+    store.update(peer.id, { feedback: 'Scheduling-only marker', nextAt: peer.nextAt + 1 });
+    consume(await nextTurn(store, jobs[0].id), jobs[0], true);
+    report.schedulingOnlyStable = true;
+  } catch (error) { report.errors.push({ operation: 'correctness', message: error.stack }); }
+}
+report.promptHashes = Object.fromEntries(Object.entries(prompts).map(([id, value]) => [id, value.hash]));
+report.memory = process.memoryUsage();
+store.close();
+fs.writeFileSync(output, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
+if (report.errors.length) process.exitCode = 1;

package/benchmarks/peer-context.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// Run `node benchmarks/peer-context.mjs prepare /absolute/fresh-directory`, then
+// `... baseline /absolute/directory` and, after rebuilding externally,
+// `... compare /absolute/directory /absolute/candidate/dist`.
+// No build, test runner, publisher, SDK, or external service is invoked.
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { cpus, loadavg, platform, release, arch } from 'node:os';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = dirname(here);
+const worker = join(here, 'peer-context-worker.mjs');
+const sha = value => createHash('sha256').update(value).digest('hex');
+const json = path => JSON.parse(fs.readFileSync(path, 'utf8'));
+const save = (path, value) => fs.writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+function treeHash(root) {
+  const hash = createHash('sha256');
+  function walk(directory, prefix = '') {
+    for (const name of fs.readdirSync(directory).sort()) {
+      const path = join(directory, name), relative = `${prefix}${name}`;
+      if (fs.statSync(path).isDirectory()) walk(path, `${relative}/`);
+      else hash.update(relative).update('\0').update(fs.readFileSync(path));
+    }
+  }
+  walk(root);
+  return hash.digest('hex');
+}
+function snapshot(root, name, dist) {
+  const target = join(root, name);
+  fs.mkdirSync(target, { mode: 0o700 });
+  fs.cpSync(dist, join(target, 'dist'), { recursive: true });
+  save(join(target, 'package.json'), { type: 'module' });
+  for (const dependency of ['yaml', 'zod']) {
+    fs.cpSync(fs.realpathSync(join(packageRoot, 'node_modules', dependency)), join(target, 'node_modules', dependency), { recursive: true });
+  }
+  return { dist: join(target, 'dist'), digest: treeHash(target), dependencies: Object.fromEntries(['yaml', 'zod'].map(name => [name, json(join(target, 'node_modules', name, 'package.json')).version])) };
+}
+function number(value, fallback, minimum) {
+  const result = value === undefined ? fallback : Number(value);
+  assert(Number.isSafeInteger(result) && result >= minimum, `Expected integer >= ${minimum}`);
+  return result;
+}
+function reset(root) {
+  const manifest = json(join(root, 'manifest.json'));
+  assert.equal(manifest.owner, 'apphx-peer-context-benchmark-v1');
+  const state = join(root, 'state');
+  fs.rmSync(state, { recursive: true, force: true });
+  fs.cpSync(join(root, 'seed-state'), state, { recursive: true });
+}
+export function runWorker(command, args, path, stderrPath, timeout = 300000) {
+  fs.rmSync(path, { force: true });
+  const result = spawnSync(command, args, { encoding: 'utf8', timeout, maxBuffer: 16 * 1024 * 1024 });
+  fs.writeFileSync(stderrPath, result.stderr ?? '');
+  let data;
+  try {
+    data = json(path);
+    assert(data && typeof data === 'object' && !Array.isArray(data), 'Expected a report object');
+    assert(Array.isArray(data.errors) && data.errors.every(error => error && typeof error.message === 'string'), 'Expected structured errors');
+    assert(Number.isFinite(data.wallMs) && data.wallMs >= 0, 'Expected a finite nonnegative wallMs');
+    assert(Number.isSafeInteger(data.operations) && data.operations >= 0, 'Expected a nonnegative operation count');
+  } catch (error) {
+    data = { errors: [{ operation: 'worker-report', message: `Missing or malformed fresh worker report: ${error.message}` }], wallMs: null, operations: 0 };
+  }
+  if (result.error) data.errors.push({ operation: 'worker-process', message: `Worker spawn failed: ${result.error.message}` });
+  if (result.signal) data.errors.push({ operation: 'worker-process', message: `Worker terminated by signal ${result.signal}` });
+  if (result.status !== 0) data.errors.push({ operation: 'worker-process', message: `Worker exited with status ${result.status}` });
+  data.exitStatus = result.status;
+  data.signal = result.signal;
+  save(path, data);
+  return data;
+}
+function sample(root, label, name, options = []) {
+  reset(root);
+  const path = join(root, `${name}.json`);
+  return runWorker(process.execPath, [worker, root, label, path, ...options], path, join(root, `${name}.stderr`));
+}
+function summarize(samples) {
+  const times = samples.map(value => value.wallMs).filter(value => value !== null).sort((a, b) => a - b);
+  return { samples: samples.length, measuredSamples: times.length, medianMs: times.length ? (times[Math.floor((times.length - 1) / 2)] + times[Math.ceil((times.length - 1) / 2)]) / 2 : null,
+    rangeMs: times.length ? [times[0], times.at(-1)] : null,
+    operations: samples.reduce((sum, value) => sum + (value.operations ?? 0), 0), errors: samples.reduce((sum, value) => sum + value.errors.length, 0),
+    rawMs: samples.map(value => value.wallMs) };
+}
+async function prepare(root, args) {
+  const apps = number(args[0], 10, 2), files = number(args[1], 128, 1), bytes = number(args[2], 4096, 128), samples = number(args[3], 5, 5);
+  fs.mkdirSync(root, { mode: 0o700 }); // Refuse an existing directory, including somebody else's fixture.
+  const baseline = snapshot(root, 'baseline', join(packageRoot, 'dist'));
+  const { ConfigSchema } = await import(pathToFileURL(join(baseline.dist, 'schemas.js')));
+  const { Store } = await import(pathToFileURL(join(baseline.dist, 'store.js')));
+  const config = ConfigSchema.parse({ stateDir: join(root, 'state'), workspaceRoot: join(root, 'workspaces'), packageTarget: 'simulator', maxJobHours: 87600, verification: { checks: [[process.execPath, '--version']], runtime: [[process.execPath, '--version']] } });
+  save(join(root, 'factory.json'), config);
+  const store = new Store(config.stateDir);
+  const jobs = [];
+  try {
+    for (let app = 0; app < apps; app++) {
+      const spec = { id: `peer-benchmark-${app}`, name: `Peer workload ${app}`, framework: 'flutter', platform: 'ios', channel: 'app-store', version: '1.0.0', purpose: `Record collection ${app}`, audience: `Collection keepers ${app}`, differentiators: [`Collection workflow ${app}`], acceptance: [`Preserve collection ${app}`], apple: { appId: `${100000 + app}`, bundleId: `invalid.benchmark.peer${app}`, buildNumber: '1', locale: 'en-US', description: `Deterministic workload ${app}; not a submitted app`, keywords: 'records', supportUrl: 'https://example.invalid/support', privacyPolicyUrl: 'https://example.invalid/privacy', reviewNotes: 'Performance fixture, not App Review evidence', copyright: 'Fixture', manualSetupConfirmed: true, contact: { firstName: 'Test', lastName: 'Only', email: 'test@example.invalid', phone: '+12025550123' } } };
+      const job = store.enqueue(spec, config);
+      fs.mkdirSync(join(job.workspace, 'lib'), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(join(job.workspace, 'pubspec.yaml'), `name: peer_benchmark_${app}\ndependencies:\n  flutter: {sdk: flutter}\n`, { mode: 0o600 });
+      for (let file = 0; file < files; file++) {
+        const seed = sha(`peer-context-fixed-seed-v1:${app}:${file}`);
+        fs.writeFileSync(join(job.workspace, 'lib', `source-${String(file).padStart(5, '0')}.dart`), `// ${seed.repeat(Math.ceil(bytes / seed.length))}`.slice(0, bytes), { mode: 0o600 });
+      }
+      jobs.push(job);
+    }
+  } finally { store.close(); }
+  fs.cpSync(config.stateDir, join(root, 'seed-state'), { recursive: true });
+  const manifest = { owner: 'apphx-peer-context-benchmark-v1', baseline, node: process.version, executable: process.execPath, platform: platform(), release: release(), arch: arch(), cpu: cpus()[0]?.model, seed: 'peer-context-fixed-seed-v1', apps, files, bytes, samples, jobs, workspaceDigest: treeHash(config.workspaceRoot), seedDigest: treeHash(join(root, 'seed-state')), timing: 'Fresh process; warm OS file cache; imports, fixture reset and oracle creation excluded. Timed 10 claims + 10 resumes include JSON serialization, consumption and exact output assertions. Separate CLI correctness and CPU/instrumented runs.' };
+  save(join(root, 'manifest.json'), manifest);
+  console.log(JSON.stringify({ root, apps, sourceFiles: apps * (files + 1), payloadBytes: apps * files * bytes, baseline: baseline.digest }));
+}
+async function main() {
+  const [command, input, ...args] = process.argv.slice(2);
+  assert(input && ['prepare', 'baseline', 'compare'].includes(command), 'Usage: peer-context.mjs prepare ROOT [apps=10 files=128 bytes=4096 samples=5] | baseline ROOT | compare ROOT CANDIDATE_DIST');
+  const root = resolve(input);
+  if (command === 'prepare') return prepare(root, args);
+  const manifest = json(join(root, 'manifest.json'));
+  assert.equal(manifest.node, process.version, 'Node version changed');
+  assert.equal(treeHash(join(root, 'baseline')), manifest.baseline.digest, 'Frozen baseline changed');
+  assert.equal(treeHash(join(root, 'workspaces')), manifest.workspaceDigest, 'Fixture source changed');
+  assert.equal(treeHash(join(root, 'seed-state')), manifest.seedDigest, 'Fixture initial state changed');
+  const report = { command, loadBefore: loadavg(), machine: { node: process.version, cpu: cpus()[0]?.model, platform: platform(), release: release(), arch: arch() }, samples: {} };
+  if (command === 'compare') {
+    assert(args[0], 'Candidate dist directory required');
+    manifest.candidate = snapshot(root, 'candidate', resolve(args[0]));
+    assert.deepEqual(manifest.candidate.dependencies, manifest.baseline.dependencies, 'Dependency versions differ');
+    save(join(root, 'manifest.json'), manifest);
+  }
+  const labels = command === 'compare' ? ['baseline', 'candidate'] : ['baseline'];
+  report.warmups = Object.fromEntries(labels.map(label => [label, sample(root, label, `${command}-${label}-warmup`)]));
+  for (let index = 0; index < manifest.samples; index++) {
+    for (const label of index % 2 ? [...labels].reverse() : labels) {
+      (report.samples[label] ??= []).push(sample(root, label, `${command}-${label}-${index}`));
+    }
+  }
+  report.summary = Object.fromEntries(labels.map(label => [label, summarize(report.samples[label])]));
+  report.correctness = Object.fromEntries(labels.map(label => [label, sample(root, label, `${command}-${label}-correctness`, ['--correctness'])]));
+  report.profiles = Object.fromEntries(labels.map(label => [label, sample(root, label, `${command}-${label}-profile`, ['--instrument'])]));
+  report.loadAfter = loadavg();
+  save(join(root, `${command}-report.json`), report);
+  console.log(JSON.stringify({ summary: report.summary, correctness: Object.fromEntries(labels.map(label => [label, report.correctness[label].errors])), profiles: Object.fromEntries(labels.map(label => [label, report.profiles[label].work])) }, null, 2));
+  if (Object.values(report.summary).some(value => value.errors || value.measuredSamples !== manifest.samples) || [...Object.values(report.warmups), ...Object.values(report.correctness), ...Object.values(report.profiles)].some(value => value.errors.length)) process.exitCode = 1;
+}
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  main().catch(error => { console.error(error); process.exitCode = 1; });
+}