@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/acp/qoderStartup.js

@@ -35,7 +35,7 @@ export async function prepareQoderStartup(launch, lease, cwd, env, agentEnv) {
                     '--setting-sources', '', '--settings', '{"autoMemoryEnabled":false}',
                     '--disallowed-tools', 'Agent', '--cwd', cwd,
                     '--append-system-prompt', 'Use the axom-delegation MCP tools for delegation. Native Agent execution is disabled in this session.'] },
-            secrets: [authorization, authorization.slice('Bearer '.length)], dispose,
+            secrets: [authorization, authorization.slice('Bearer '.length)], dir, dispose,
         };
     }
     catch (error) {

package/dist/workstation/acp/registry/catalog.js

@@ -6,7 +6,7 @@
  * 一个 agent 在本清单里，就是我们真机验证过（roster 的 `curated`），设置页把它放进展开区；其余官方
  * 条目进折叠的 "Unverified Agents"。本清单能做的事，各有一节在下面：
  *
- * - **推荐**：`recommended` 是静态的，只给愿意向任何一台新机器推荐的（claude、codex、pi）。
+ * - **推荐**：`recommended` 是静态的，只给愿意向任何一台新机器推荐的（pi）。
  * - **本地检测**（`detect`，见 `detect.ts`）：PATH 上的命令或固定文件位置，只看文件在不在、不起进程。
  *   检测到 = 这台机器的用户自己在用它，于是它也进推荐位，原因写"本机在用"。
  * - **前置依赖**（`prerequisite`）：适配器之外、它起得来所必需的本体（Pi 的 CLI、ZCode 桌面应用），
@@ -15,7 +15,7 @@
  *
  * ## 托管与检测是两件事
  *
- * Axom 启动的**一律是 Axom 托管的那份**——npx 缓存、`uv tool dir`、`<config dir>/acp-adapters` 里我们
+ * Axom 启动的**一律是 Axom 托管的那份**——`<config dir>/acp-adapters` 里我们（npm、uv、binary 各按版本）
  * 自己装的、钉了版本的副本，与用户自己的安装隔离、独立升级。`adapterInstalled` 只回答这一份在不在。
  * 用户 PATH 上的 `kimi`、`command-code` **不算** Axom 已安装，也从不被拿来启动：它只是 `detect` 的
  * 推荐信号。两份共用数据目录（`~/.kimi-code`、`~/.commandcode`），所以登录是共享的。
@@ -44,7 +44,7 @@
  *
  * 这里写下的来源**整个替换** registry 的 `version` 与 `distribution`，id 与展示名仍是 registry 的，
  * 于是已有的配置条目、roster、安装、启动、更新都不用知道发生过替换（见 {@link withCatalogOverrides}）。
- * 本文件里的是长期的（Qoder：registry 落后于验证过的原生版本）；临时的钉版本放在
+ * 本文件的 distribution 用于长期策略；Qoder 等临时的钉版本放在
  * axom-patch/cli/runtime.json，按 registry 版本挑选（`when_registry_version` / `until_registry_version`，
  * 见 `patchAssets.ts`），registry 一到就自己让位。两者与上面的 `install` 是同一条安全边界：只能是
  * 随 CLI 发布、钉死版本、由真机验证过的可信配置。
@@ -85,19 +85,47 @@ export const AXOM_AGENT_CATALOG = [
         registryAgent: 'claude-acp',
         defaultName: 'claude-agent',
         defaultLabel: 'Claude Agent',
-        recommended: true,
         detect: { commands: ['claude'] },
+        // 钉版本的唯一理由是补丁：claude-account-limits 的配方只核验过 0.90.0（runtime.json 的
+        // package_patches）。不钉的话 registry 一发新版，Install/Update 就装上一个配方不覆盖的包，
+        // 账号配额扩展静默消失——2026-10-14 的 antigravity（registry 已到 1.4.0、native extension
+        // 只认 1.3.0）就是这个缺口的实例。钉住后 scan 的 Update 比对（installedVersion vs 本清单的
+        // version）只在落后于钉住版本时才成立，上游新版要等 nightly 核验移植配方后再 bump。
+        // 周期核验步骤见 axom-patch/cli/nightly-task.md。
+        distribution: { version: '0.90.0', npx: { package: '@agentclientprotocol/claude-agent-acp@0.90.0' } },
+        launchEnv: {
+            // Axom 拉起的 Claude Code——会话进程、配额读的 /usage、auth status 探针、terminalLogin 代跑的
+            // `--cli auth login`——一律使用独立的 OAuth 凭据槽，与用户终端 `claude login` 写进默认槽
+            // （macOS keychain `Claude Code-credentials`）的那份互不轮换。Claude 的 refresh token 单次
+            // 轮换，多进程共享一份凭据时并发刷新会互相作废、进而被 Claude Code 清除（全员登出；
+            // anthropics/claude-code#54443，2026-10 本机实测每日复现）。
+            //
+            // CLAUDE_SECURESTORAGE_CONFIG_DIR 只改槽位命名，不把存储切到目录：macOS 上 keychain 条目变为
+            // `Claude Code-credentials-<sha256(路径)前8位>`，明文回退文件在 <路径>/.credentials.json（仅当
+            // keychain 写入失败时才落）。前导 `~` 由 `registry/launch.ts` 在 launch env 边界展开为绝对路径——
+            // Claude 把这个值按字面路径使用，不展开 `~`。
+            //
+            // **共享/独立凭据的开关收敛在这一个键上**：删除它（或将来的用户开关通过 workstation 配置的
+            // 同名变量覆盖）即回到与终端 CLI 共享默认槽的旧行为，判定点只此一处。路径一旦发布永不改名——
+            // 换字符串等于强制所有人重新登录。
+            CLAUDE_SECURESTORAGE_CONFIG_DIR: '~/.axom/auth/secures/claude',
+        },
+    },
+    {
+        registryAgent: 'codex-acp',
+        defaultName: 'codex',
+        defaultLabel: 'Codex',
+        detect: { commands: ['codex'] },
+        // 与 claude-acp 同一条规则：codex-account-limits 只核验过 2.2.2，钉住直到配方随新版本移植。
+        distribution: { version: '2.2.2', npx: { package: '@agentclientprotocol/codex-acp@2.2.2' } },
     },
-    { registryAgent: 'codex-acp', defaultName: 'codex', defaultLabel: 'Codex', recommended: true, detect: { commands: ['codex'] } },
     {
         registryAgent: 'qoder',
         defaultName: 'qoder',
         defaultLabel: 'Qoder',
         detect: { commands: ['qodercli'] },
-        // The registry still launches 0.2.14, which only reports legacy `models`. The tested native
-        // release reports ACP configOptions for model/mode and accepts session/set_config_option.
-        // Keep registry installs on the same verified runtime as the native production baseline.
-        distribution: { version: '1.1.61', npx: { package: '@qoder-ai/qodercli@1.1.61', args: ['--acp'] } },
+        // The temporary registry catch-up pin lives in axom-patch/cli/runtime.json so a newer
+        // upstream release can take over without another Axom release.
     },
     // `gemini` was here and is deliberately gone. `@google/gemini-cli --acp` now refuses `session/new`
     // outright ("This client is no longer supported for Gemini Code Assist for individuals … migrate
@@ -145,19 +173,21 @@ export const AXOM_AGENT_CATALOG = [
         registryAgent: 'command-code',
         defaultName: 'command-code',
         defaultLabel: 'Command Code',
-        // registry 没有它。1.66.0 还没有 `acp` 子命令，1.74.3 起有、真机试跑通过。包里有 `cmd`、`cmdc`、
+        // registry 没有它。1.66.0 还没有 `acp` 子命令，1.74.3 起有、真机试跑通过；2026-10-14 nightly
+        // 升到 1.82.1：`acp` 子命令仍在（四个 bin 不变），commandcode-account-limits 配方已随
+        // generate.py 移植（handler map 换了名字 u/dn→m/hn，锚点已跟）。包里有 `cmd`、`cmdc`、
         // `commandcode`、`command-code` 四个 bin，npx 挑与包名同名的那个。没有 ACP 登录方法，只有一句
         // 说明（终端里跑 `cmd login`）；凭据在 `~/.commandcode`，与用户自己装的那份共用。npm 上的许可证
         // 写的是 UNLICENSED（专有）。
         supplement: {
             name: 'Command Code',
-            version: '1.74.3',
+            version: '1.82.1',
             description: 'Command Code, coding agent that continuously learns your coding taste.',
             website: 'https://commandcode.ai',
             authors: ['Command Code'],
             license: 'UNLICENSED',
             icon: 'https://commandcode.ai/favicon.ico',
-            distribution: { npx: { package: 'command-code@1.74.3', args: ['acp'] } },
+            distribution: { npx: { package: 'command-code@1.82.1', args: ['acp'] } },
         },
         detect: { commands: ['command-code', 'commandcode'] },
     },
@@ -165,21 +195,27 @@ export const AXOM_AGENT_CATALOG = [
         registryAgent: 'zcode-acp',
         defaultName: 'zcode',
         defaultLabel: 'ZCode',
-        unverified: 'zcode-acp 0.63/0.64 与 ZCode 桌面 3.14.x 不兼容：3.14 不写 ~/.zcode/v2/config.json，模型只剩无授权的 ' +
-            'builtin:bigmodel-coding-plan\\GLM-5.3，首轮 CONFIGURATION_ERROR "Model creation failed"（2026-10-06 两台机器复现）。',
-        // 社区适配器（registry#566、#650 都还没合），驱动的是 ZCode 桌面应用自带的 `zcode app-server`，
+        // 社区适配器（registry#566、#650 都还没合），驱动的是 ZCode 桌面应用自带的 `zcode app-server`,
         // 所以 ZCode 本体是前置依赖，而且没有一条我们能替用户跑的安装命令 —— 只能告诉他去装。
-        // 凭据在 `~/.zcode/v2/config.json`，由 ZCode 自己登录写下。Linux 上本体没有固定路径，只认 PATH。
+        // 凭据：legacy `~/.zcode/v2/config.json`，但 ZCode 桌面 3.14.x 起不再写它；适配器 0.68.1+（上游
+        // #320）在 config.json 缺席时改读加密凭据库 `~/.zcode/v2/credentials.json`（桌面登录时写下）取
+        // individual coding-plan 的 api-key。Linux 上本体没有固定路径，只认 PATH。
+        // 2026-10-13 真机验证（ZCode 桌面 3.14.5 + 0.69.3）：initialize → session/new → 首轮 prompt 通过，
+        // 日志 "serving the coding-plan API key (config.json or store)"。0.63/0.64 那轮不兼容（模型只剩
+        // 无授权的 builtin:bigmodel-coding-plan\GLM-5.3，首轮 CONFIGURATION_ERROR "Model creation failed"，
+        // 2026-10-06 两台机器复现）自 0.68.1 起修复。2026-10-14 nightly 升到 0.69.4：三份配方的目标文件
+        // 与 0.69.3 字节一致（配方 versions 同时覆盖两版），subagent 探针在 0.69.4 补丁副本上通过、
+        // pristine 证实上游仍未原生发出 subagent/async 变体。
         supplement: {
             name: 'ZCode',
-            version: '0.63.0',
+            version: '0.69.4',
             description: 'Community bridge that drives the real ZCode app-server (GLM) over ACP.',
             repository: 'https://github.com/william0wang/zcode-acp',
             website: 'https://github.com/william0wang/zcode-acp',
             authors: ['William Wang'],
             license: 'Apache-2.0',
             icon: 'https://raw.githubusercontent.com/william0wang/zcode-acp/main/registry/zcode-acp/icon.svg',
-            distribution: { npx: { package: 'zcode-acp-server@0.63.0' } },
+            distribution: { npx: { package: 'zcode-acp-server@0.69.4' } },
         },
         prerequisite: {
             label: 'ZCode',
@@ -200,6 +236,10 @@ export const AXOM_AGENT_CATALOG = [
         defaultName: 'pi',
         defaultLabel: 'Pi',
         recommended: true,
+        // pi-steering 与 pi-subagent-subwork 两份配方只核验过 0.0.34。registry 今天也在 0.0.34，
+        // 但那是巧合而不是保护：上游一发 0.0.35，未钉版本的 Install 就会装上一个 steering/子代理
+        // 归一都不生效的包。钉住后版本只随配方移植走（nightly-task.md）。
+        distribution: { version: '0.0.34', npx: { package: 'pi-acp@0.0.34' } },
         prerequisite: {
             label: 'Pi',
             detect: { commands: ['pi'] },
@@ -212,8 +252,62 @@ export const AXOM_AGENT_CATALOG = [
             requiresNode: '>=22.19.0',
         },
     },
+    {
+        // 推荐位第二名（pi 之后的第一个）：真机验证记录见 2026-10-13 genius 站验证（scan/verify/会话/审批
+        // 全链路）。hermes 不在公开 ACP registry（41 个 agent 里没有），本条同时是 supplement —— registry
+        // 一旦收录这个 id 就整体让位。PyPI 上的 `hermes-agent`（0.19.0，requires_python <3.14）是过时的
+        // 次要通道，官方分发是 `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash`（git
+        // clone + pm bootstrap，写 ~/.local/bin/{hermes,hermes-acp}），所以走 pathLaunch 而不是 uvx：
+        // 启动用户自己装的那份，本机只有一份，与 pi 的本体同款哲学。`hermes-acp` 是官方 wheel/git 都
+        // 声明的 ACP console script；不要用 `hermes-agent`（那是 demo runner）或裸 `hermes`（CLI 主入口，
+        // acp 只是它的子命令 —— 两者都不带 ACP 语义的入口保障）。
+        registryAgent: 'hermes-acp',
+        defaultName: 'hermes',
+        defaultLabel: 'Hermes',
+        recommended: true,
+        detect: {
+            commands: ['hermes'],
+            locations: everyPlatform(['~/.local/bin/hermes-acp'], ['~/.local/bin/hermes-acp.exe']),
+        },
+        pathLaunch: { command: 'hermes-acp', hint: 'Install Hermes Agent with the official installer (curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash), then scan again.' },
+        supplement: {
+            name: 'Hermes',
+            version: '0.21.7',
+            description: "Nous Research's self-improving coding agent — native ACP server (hermes acp).",
+            repository: 'https://github.com/NousResearch/hermes-agent',
+            website: 'https://hermes-agent.nousresearch.com',
+            authors: ['Nous Research'],
+            license: 'Apache-2.0',
+            icon: 'https://hermes-agent.nousresearch.com/favicon.ico',
+            // supplement 必须给一条 distribution 才能在 registry 类型里站得住；hermes 没有任何可安装产物，
+            // 留空 distribution 由 pathLaunch 接管 available（见 acpAgents.ts 的 roster）。
+            distribution: {},
+        },
+    },
     // registry 自己的条目（binary .par），我们只补名字与本机检测；`agy` 是 Antigravity 装好后放进 PATH 的命令。
-    { registryAgent: 'antigravity-acp', defaultName: 'google-antigravity', defaultLabel: 'Google Antigravity', detect: { commands: ['agy'] } },
+    // distribution 钉住：antigravity 的账号配额靠 native extension（runtime.json
+    // native_extensions，account-limits/antigravity-proxy.mjs），proxy 是 stdio sidecar，只在核验过的
+    // 版本上声明能力。2026-10-14 nightly 升到 1.4.0：真实 1.4.0 .par 经 proxy 拉起，initialize 透传无损、
+    // `axom/accountRateLimits` 能力注入成功（本地实测；配额 READ 属于用户凭据路径，留给真机冒烟）。
+    // 归档 URL 抄自 registry 的 1.4.0 条目；registry 本身不给这个条目发 sha256，这里同样不发，校验语义与
+    // registry 直装一致（binaryInstall：无 sha256 即不校验）。上游发新版时按 nightly-task.md 核验后同升。
+    {
+        registryAgent: 'antigravity-acp',
+        defaultName: 'google-antigravity',
+        defaultLabel: 'Google Antigravity',
+        detect: { commands: ['agy'] },
+        distribution: {
+            version: '1.4.0',
+            binary: {
+                'darwin-aarch64': { archive: 'https://dl.google.com/agy-extensions/releases/macos/agy-acp-server-1.4.0-darwin-arm64.zip', cmd: './agy_acp_server.par' },
+                'darwin-x86_64': { archive: 'https://dl.google.com/agy-extensions/releases/macos/agy-acp-server-1.4.0-darwin-x86_64.zip', cmd: './agy_acp_server.par' },
+                'linux-x86_64': { archive: 'https://dl.google.com/agy-extensions/releases/linux/agy-acp-server-1.4.0-linux-x86_64.zip', cmd: './agy_acp_server.par', args: ['--uid='] },
+                'linux-aarch64': { archive: 'https://dl.google.com/agy-extensions/releases/linux/agy-acp-server-1.4.0-linux-arm64.zip', cmd: './agy_acp_server.par', args: ['--uid='] },
+                'windows-x86_64': { archive: 'https://dl.google.com/agy-extensions/releases/windows/agy-acp-server-1.4.0-windows-x86_64.zip', cmd: './agy_acp_server.exe' },
+                'windows-aarch64': { archive: 'https://dl.google.com/agy-extensions/releases/windows/agy-acp-server-1.4.0-windows-arm64.zip', cmd: './agy_acp_server.exe' },
+            },
+        },
+    },
 ];
 /**
  * Kimi Code 的六个平台归档：GitHub release `@moonshot-ai/kimi-code@<version>` 下的
@@ -236,30 +330,58 @@ function everyPlatform(unix, windows) {
     };
 }
 const BY_ID = new Map(AXOM_AGENT_CATALOG.map((entry) => [entry.registryAgent, entry]));
+/**
+ * 静态推荐条目的展示序（目录数组序）：推荐层的排序依据，用户可指定（2026-10-13：pi 第一、hermes
+ * 第二）。名册序做不到这件事 —— supplement 追加在 registry 之后，字母序又与本意相反（H < P），
+ * 所以显式带一个序号，roster 经 `recommendedRank` 下发、推荐层按它排。非静态推荐的 detected 卡
+ * （"本机在用"）没有序号，排在静态推荐之后、按 label 字母序。
+ */
+export const RECOMMENDED_RANK = new Map(AXOM_AGENT_CATALOG
+    .map((entry, index) => [entry.registryAgent, index])
+    .filter(([id]) => catalogEntryFor(id)?.recommended === true)
+    .map(([id], rank) => [id, rank]));
 export function catalogEntryFor(registryAgent) {
     return BY_ID.get(registryAgent);
 }
-/**
- * The registry entry as Axom will actually install and launch it: unchanged unless something
- * overrides it. A distribution replaces the registry's `version` and `distribution` — a runtime.json
- * override that applies at this registry version first, else this catalog's own. Launch env is merged
- * under every distribution's own `env` (the registry's declared variables win over ours). Identity
- * and the registry's own words never move (see the file header).
- */
-export function applyCatalogOverrides(agent) {
+/** The CLI-owned launch environment for one agent at one registry version: catalog `launchEnv`, then runtime.json `env`. */
+export function catalogLaunchEnv(agentId, registryVersion) {
+    return { ...catalogEntryFor(agentId)?.launchEnv, ...patchOverridesFor(agentId, registryVersion).env };
+}
+export function effectiveEntry(agent, supplemented = false) {
     const entry = catalogEntryFor(agent.id);
     const patch = patchOverridesFor(agent.id, agent.version);
     const pinned = patch.distribution ?? entry?.distribution;
-    const launchEnv = { ...entry?.launchEnv, ...patch.env };
+    const pinnedBy = patch.distribution ? 'runtime-override'
+        : entry?.distribution || supplemented ? 'catalog' : undefined;
     let effective = agent;
     if (pinned) {
         const { version, ...distribution } = pinned;
         effective = { ...effective, version, distribution };
     }
-    if (Object.keys(launchEnv).length) {
-        effective = { ...effective, distribution: withLaunchEnv(effective.distribution, launchEnv) };
-    }
-    return effective;
+    return {
+        agent: effective,
+        registryVersion: agent.version,
+        launchEnv: { ...entry?.launchEnv, ...patch.env },
+        ...(pinnedBy ? { pinnedBy } : {}),
+    };
+}
+/** {@link withCatalogEntries} then {@link effectiveEntry} over a whole registry document, supplements marked as catalog pins. */
+export function effectiveEntries(agents) {
+    const published = new Set(agents.map((agent) => agent.id));
+    return withCatalogEntries(agents).map((agent) => effectiveEntry(agent, !published.has(agent.id)));
+}
+/**
+ * The registry entry as Axom will actually install and launch it: unchanged unless something
+ * overrides it. A distribution replaces the registry's `version` and `distribution` — a runtime.json
+ * override that applies at this registry version first, else this catalog's own. Launch env is merged
+ * under every distribution's own `env` (the registry's declared variables win over ours). Identity
+ * and the registry's own words never move (see the file header).
+ */
+export function applyCatalogOverrides(agent) {
+    const { agent: effective, launchEnv } = effectiveEntry(agent);
+    if (!Object.keys(launchEnv).length)
+        return effective;
+    return { ...effective, distribution: withLaunchEnv(effective.distribution, launchEnv) };
 }
 /** The registry's list with this catalog's supplements added where the registry lacks them and superseded ids removed. */
 export function withCatalogEntries(agents) {

package/dist/workstation/acp/registry/launch.js

@@ -1,128 +1,70 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
-import { binaryTargetFor, installedBinaryVersion, platformTriple } from '../binaryInstall.js';
-import { npmPackageName } from '../installProbe.js';
-import { uvPackageName, uvToolEntrypoint, uvToolEntrypointFrom } from '../uvxInstall.js';
-export class UnsupportedDistributionError extends Error {
-}
-/** `npx --yes <specifier> [dist args]`,两个调用方共用的一处构造:钉版本的和不钉版本的。 */
-function npxLaunch(specifier, npx, platform) {
-    return {
-        command: platform === 'win32' ? 'npx.cmd' : 'npx',
-        // `--yes` 让首次拉包不停在交互确认上。
-        args: ['--yes', specifier, ...(npx.args ?? [])],
-        env: { ...(npx.env ?? {}) },
-    };
-}
+import { fileURLToPath } from 'node:url';
+import { nativeExtensionFor } from '../patchAssets.js';
+import { verifyPatchedFiles } from '../managedPatches.js';
+import { AdapterNotInstalledError, inside, labelFor } from '../builds/model.js';
+import { assertBuildRunsOn } from '../builds/nodeGate.js';
 /**
- * registry 只给原料,不给命令行 —— 没有 `command` 字段,启动方式要从 `distribution` 推导。
- *
- * 三种分发方式现在都支持:`npx`/`uvx` 走各自安装侧维护的缓存/工具目录(见 `installProbe.ts`、
- * `uvxInstall.ts`),`binary` 走 `binaryInstall.ts`(Task 8)—— 按六个平台三元组挑一个目标、
- * 从 `adapterRoot` 找已经装好的版本。三条路径共同的规则是:**从不猜**,找不到就抛
- * `UnsupportedDistributionError`,理由写清楚是"这个平台没有发行版"还是"这台机器还没装",而不是
- * 笼统的一句"不支持"。
+ * `env` with `prefix` first on its `PATH` — unless `PATH` already starts with exactly that prefix (the
+ * spec's own env survived the merge), so applying it twice is harmless.
  */
-export async function resolveLaunch(agent, platform, 
-// 六个平台三元组里的一半;只有 binary 分支用到。
-arch, 
-// `<workstation config dir>/acp-adapters` —— `binaryInstall.ts` 解包落地的根目录,只有 binary
-// 分支用到。npx 走 npm 自己的 `_npx` 缓存,uvx 走 `uv tool dir`,都不需要这个根目录。
-adapterRoot, 
-// 仅测试注入:真实调用永远走 `uvxInstall.ts` 的默认 `uv` 实现。签名上留成可选,两个真实调用点
-// (`acpAgents.ts`)不用跟着改。下面的 `uvTools` 给出时,这个参数被忽略 —— 见它的说明。
-run, 
-// 已经读好的 `uv tool list` 快照(`listUvTools`)。给了就直接查表,不再自己起 `uv` 子进程 ——
-// `AcpAgents.roster` 为整份 39 条 registry 只读一次,把结果传进这里,而不是让每个 uvx agent
-// 在这条路径上各自再起一次 `uv`。真正的启动路径(`resolveLaunchFor`)不传这个参数,继续用
-// `run`/默认实现现读一次,这里的现读对它而言正是期望行为。
-//
-// 这个函数整体是 async 的唯一原因:`uv` 现在是非阻塞调用(`RunUv` 返回 `Promise`,见
-// `uvxInstall.ts`),没有预取快照时这里必须 `await` 它。给了 `uvTools` 的那条路径
-// (`AcpAgents.resolvable`)完全同步、不等待任何东西,包成 `async` 只是让两条路径共用同一个
-// 签名——`Promise.resolve` 包一层同步返回值的开销,跟每次 roster 扫描本来就要付的成本比可以
-// 忽略不计。
-uvTools) {
-    const { npx, uvx, binary } = agent.distribution;
-    // specifier 里已内联精确版本,不会追 latest —— 除非 registry 钉的那个版本 npm 根本没有,
-    // 见 {@link unpinnedFallbackFor}。
-    if (npx)
-        return npxLaunch(npx.package, npx, platform);
-    if (uvx) {
-        // 不走 `uvx <pkg>`:那条路用 uv 自己的临时环境缓存,目录名带哈希,"装没装"读不可靠。
-        // 改成我们自己 `uv tool install`、启动时直接跑装出来的入口点 —— 与 binary 一样,
-        // 落到"我们装的、我们知道装在哪"这一条统一规则上。
-        const outcome = uvTools
-            ? uvToolEntrypointFrom(uvPackageName(uvx.package), uvTools)
-            : await uvToolEntrypoint(uvPackageName(uvx.package), run);
-        if (outcome.ok) {
-            return { command: outcome.path, args: [...(uvx.args ?? [])], env: { ...(uvx.env ?? {}) } };
-        }
-        if (outcome.reason === 'ambiguous') {
-            // 装了,但不敢猜:多个可执行文件里没有一个跟包名同名,uv 的列出顺序又不是文档化契约——
-            // 静默启动错的那个,换来的是一次没人能追回这里的 ACP 握手挂死或失败,比拒绝启动更糟。
-            throw new UnsupportedDistributionError(`Agent '${agent.id}' is distributed through uvx and its tool is installed, but this build ` +
-                `cannot tell which of its executables is the ACP adapter: ${outcome.candidates.join(', ')}.`);
-        }
-        throw new UnsupportedDistributionError(`Agent '${agent.id}' is distributed through uvx but its tool is not installed on this machine.`);
-    }
-    if (binary) {
-        // 六个平台三元组里挑一个;`windows-aarch64` 在实测的 registry 快照上只有 9/18 的覆盖,
-        // "这个平台没有发行版"是常态,不是异常——`installBinary`（`binaryInstall.ts`）在下载前就
-        // 用同一个函数做同一个判断,这里只是启动路径上再问一次同一件事,答案必须一致。
-        const triple = platformTriple(platform, arch);
-        const target = triple ? binaryTargetFor(agent, triple) : undefined;
-        if (!target) {
-            throw new UnsupportedDistributionError(`Agent '${agent.id}' publishes no archive for ${triple ?? `${platform}-${arch}`}.`);
-        }
-        // 装没装是这台机器磁盘上的事实,不是 registry 条目的属性 —— 跟 npx/uvx 分支一样,没装就说
-        // "没装",不是"不支持"。
-        //
-        // `agent.version` 必须传:同一个 agent 的多个版本可以并存(`<root>/<agent>/<version>/`,
-        // 就是为此设计的),`pickInstalledVersion` 的规则是"钉的版本在就取它,否则取最大"。
-        // `AcpAgents.roster` 报告 `adapterVersion` 时传了它,这里不传就会在两个版本并存时报告一个、
-        // 启动另一个 —— 名册说 0.75.0、跑起来是 0.74.0,而且没有任何一处会说出这件事。
-        const version = installedBinaryVersion(agent.id, adapterRoot, agent.version);
-        if (!version) {
-            throw new UnsupportedDistributionError(`Agent '${agent.id}' has no installed adapter on this machine.`);
-        }
-        return {
-            command: path.join(adapterRoot, agent.id, version, target.cmd),
-            args: [...(target.args ?? [])],
-            env: { ...(target.env ?? {}) },
-        };
-    }
-    throw new UnsupportedDistributionError(`Agent '${agent.id}' declares no launchable distribution.`);
+export function withPathPrefix(env, prefix) {
+    if (!prefix?.length)
+        return env;
+    const head = prefix.join(path.delimiter);
+    const current = env.PATH ?? '';
+    if (current === head || current.startsWith(head + path.delimiter))
+        return env;
+    return { ...env, PATH: current ? head + path.delimiter + current : head };
 }
 /**
- * 同一个 agent,但把 registry 钉的版本从 specifier 上剥掉 —— 上游钉了一个 npm 上并不存在的版本时,
- * 唯一还能把这个 agent 救回来的启动方式。
- *
- * ## 为什么需要它
- *
- * 2026-09-04 实测:registry 的 `codex-acp` 条目声明
- * `@agentclientprotocol/codex-acp@1.10.0`,而 npm 上这个包的版本停在 `1.9.0`
- * (`dist-tags.latest` 也是 `1.9.0`)。于是每一次 codex 启动都是 `npm error code ETARGET`,npx 退出,
- * 子进程死掉 —— 两台真实工作站同时失去了 codex。这是上游的缺陷;这里能做的是不让它把 agent 砖掉。
- *
- * ## 代价,以及为什么仍然值得
+ * The spawn spec for an installed build — **no npx, no registry read, no network**: the build's own
+ * entry, run with a fixed absolute Node (`nodePath`, the daemon's `process.execPath`) when it is
+ * JavaScript, or executed directly when it is native.
  *
- * 不钉版本装回来的,是 npm 此刻叫 `latest` 的那一个 —— **registry 从来没有指定过它**。它可能比钉的
- * 版本新(常见,上游多半正是发版发歪了),也可能是一个协议行为不同、甚至跟这个客户端谈不拢
- * `initialize` 的版本。所以这条路只在 ETARGET 上走(见 `acpClient.ts` 的 `isMissingPackageVersion`),
- * 只走一次,而且两条 warn 日志会把「跑的不是 registry 要的那个版本」说穿。
- *
- * ## 三种「没有回退可言」的情况,都返回 undefined
+ * `launchEnv` is the running CLI's catalog/runtime.json launch environment for this agent, evaluated
+ * at the registry version the build was installed from. It goes underneath the build's own
+ * (distribution-declared) env, the same order `registry/catalog.ts`'s `withLaunchEnv` always used.
+ * A patched build's files are re-hashed first (the tamper check that used to run on every launch), and
+ * a JavaScript build must pass the Node gate (`builds/nodeGate.ts`) against `nodePath`.
+ */
+/**
+ * Expand a leading `~` / `~/` in every env value against the user's home directory.
  *
- * 没有 npx 分发(`uvx` 走的是 uv 自己的缓存,`binary` 这个版本压根不支持)、specifier 本来就不带版本
- * (剥无可剥,npm 已经在追 latest 了)。剥版本用 `npmPackageName`,它按最后一个 `@` 切,所以
- * `@scope/name@1.10.0` → `@scope/name`,而前导的 `@` 不会被当成版本分隔符。
+ * Why here and nowhere else: the CLI-owned `launchEnv` (catalog / runtime.json) ships as a static
+ * file, so it cannot spell the per-machine absolute path some consumers need — Claude's
+ * `CLAUDE_SECURESTORAGE_CONFIG_DIR` is used as a literal path and never expands `~` itself. And the
+ * final merged env is the only point that covers both sources: a build's own distribution env
+ * overwrites same-key `launchEnv` values, so expanding the `launchEnv` alone would let an unexpanded
+ * build value win. Only a leading `~` is touched; a `~` elsewhere in a value is data, not a path.
  */
-export function unpinnedFallbackFor(agent, platform) {
-    const npx = agent.distribution.npx;
-    if (!npx)
-        return undefined;
-    const unpinned = npmPackageName(npx.package);
-    if (unpinned === npx.package)
-        return undefined;
-    return { pinned: npx.package, unpinned, launch: npxLaunch(unpinned, npx, platform) };
+function expandHomeInEnv(env) {
+    const home = homedir();
+    return Object.fromEntries(Object.entries(env).map(([key, value]) => [key, value === '~' ? home : value.startsWith('~/') ? path.join(home, value.slice(2)) : value]));
+}
+export async function launchForBuild(build, root, options) {
+    const dir = inside(root, build.dir);
+    const entry = inside(dir, build.launch.entry);
+    if (build.kind === 'npm-patched' && build.package && build.patchedFiles) {
+        await verifyPatchedFiles(inside(path.join(dir, 'node_modules'), build.package), build.patchedFiles);
+    }
+    if (!existsSync(entry))
+        throw new AdapterNotInstalledError(build.agentId, `build ${build.buildId} is missing its executable`);
+    // Every build launch passes the Node gate — patched and pristine alike, whatever the args look like.
+    await assertBuildRunsOn(build, root, options.nodePath);
+    const env = expandHomeInEnv({ ...options.launchEnv, ...build.launch.env });
+    const pathPrefix = build.launch.pathDirs?.map((relative) => inside(dir, relative));
+    if (pathPrefix?.length) {
+        env.PATH = pathPrefix.join(path.delimiter) + path.delimiter + (env.PATH ?? options.basePath ?? process.env.PATH ?? '');
+    }
+    const extra = pathPrefix?.length ? { pathPrefix } : {};
+    const extension = build.launch.runtime !== 'node' ? nativeExtensionFor(build.agentId, build.version) : undefined;
+    if (extension) {
+        return { command: options.nodePath, args: [fileURLToPath(extension), entry, ...build.launch.args], env, label: labelFor(build), ...extra };
+    }
+    return build.launch.runtime === 'node'
+        ? { command: options.nodePath, args: [entry, ...build.launch.args], env, label: labelFor(build), ...extra }
+        : { command: entry, args: [...build.launch.args], env, label: labelFor(build), ...extra };
 }

package/dist/workstation/acp/sessionUpdateMapper.js

@@ -1,4 +1,7 @@
 import { codexActivityRaw } from './activityReporting.js';
+export function newMapperScopeData() {
+    return { byId: {}, lastReportedQueueDepth: 0 };
+}
 /**
  * One session's memory, and the reason this file is no longer stateless: **what this session has
  * already been told**, for the two branches that cannot answer a frame from the frame alone.
@@ -32,7 +35,7 @@ import { codexActivityRaw } from './activityReporting.js';
  */
 export class SessionMapperState {
     onActivityReported;
-    byId = new Map();
+    data;
     /**
      * Where an agent-reported activity-state push (today, only `codexActivityRaw`'s extraction of
      * `session_info_update._meta.codex.threadStatus`) actually goes once {@link reportActivity} is
@@ -44,8 +47,11 @@ export class SessionMapperState {
      * replay path, which has no live connection to report anything on — keeps compiling and keeps
      * doing nothing, exactly as it always has.
      */
-    constructor(onActivityReported = () => { }) {
+    constructor(onActivityReported = () => { }, 
+    /** The memory itself, mutated in place — the processor passes the checkpointed copy it owns. */
+    data = newMapperScopeData()) {
         this.onActivityReported = onActivityReported;
+        this.data = data;
     }
     /**
      * The agent queue depth this session has already reported to the server.
@@ -55,7 +61,9 @@ export class SessionMapperState {
      * reader already assumes. Seeding it to `-1` (or `null`) would let the very first frame through,
      * which on `pi-acp` is `startTurn`'s, i.e. the defect this field exists to prevent.
      */
-    lastReportedQueueDepth = 0;
+    get lastReportedQueueDepth() {
+        return this.data.lastReportedQueueDepth;
+    }
     /**
      * Is `depth` news? Records it if so. **This is the whole fix for a defect that shipped in the
      * previous commit**, so the reasoning is written out rather than summarised.
@@ -110,7 +118,7 @@ export class SessionMapperState {
     reportsQueueDepth(depth) {
         if (depth === this.lastReportedQueueDepth)
             return false;
-        this.lastReportedQueueDepth = depth;
+        this.data.lastReportedQueueDepth = depth;
         return true;
     }
     /**
@@ -126,7 +134,10 @@ export class SessionMapperState {
     /** Remember what this call is called. Later updates that carry no `name` fall back to it. */
     record(toolCallId, name) {
         if (name)
-            this.byId.set(toolCallId, name);
+            this.remember(toolCallId, name);
+    }
+    remember(toolCallId, name) {
+        Object.defineProperty(this.data.byId, toolCallId, { value: name, enumerable: true, writable: true, configurable: true });
     }
     /**
      * The name to report for one update, in ACP's own order of authority: an explicit `name` on the
@@ -138,10 +149,10 @@ export class SessionMapperState {
      */
     resolve(toolCallId, name, title) {
         if (name) {
-            this.byId.set(toolCallId, name);
+            this.remember(toolCallId, name);
             return name;
         }
-        return this.byId.get(toolCallId) ?? title ?? 'unknown';
+        return (Object.hasOwn(this.data.byId, toolCallId) ? this.data.byId[toolCallId] : undefined) ?? title ?? 'unknown';
     }
 }
 /**

package/dist/workstation/acp/steering.js

@@ -0,0 +1,58 @@
+/**
+ * The `_session/steering` and `_session/async_task/stop` extension vocabulary of the deterministic processor
+ * (`processor/control.ts`; the old live session that also used it was deleted in Task 29). Pure: no I/O,
+ * no clock — the processor's import guard walks this file.
+ */
+/**
+ * The steering extension's JSON-RPC method. **Not an ACP method** — `grep steer` over the pinned
+ * SDK's `dist/schema/types.gen.d.ts` returns nothing. It is implemented by `claude-agent-acp`
+ * (`acp-agent.js@0.76.0:164`), whose own comment calls it a *"Custom (extension) request method ...
+ * Named `_session/steering` per the agreed ACP steering wire protocol"*; the leading underscore is
+ * ACP's extension namespace. It is therefore reached through the untyped `request<Response, Params>
+ * (method: string, …)` overload rather than `methods.agent.*`, and every caller must check
+ * {@link AcpConnection.supportsSteering} first.
+ */
+export const STEER_METHOD = '_session/steering';
+/**
+ * The adapter's *stop one background task* extension method. **Not an ACP method** either — it is
+ * `claude-agent-acp`'s own `ASYNC_TASK_STOP_METHOD` (`acp-agent.js@0.79.0:165`), whose own comment
+ * reads *"Stops one Claude background task without cancelling the parent prompt turn."*
+ * `codex-acp@1.12.0` registers the same literal name with the same params
+ * (`dist/index.js:31608`, `:35126-35129`, `:32395-32406`). Reached through the untyped `request`
+ * overload, for the reason {@link STEER_METHOD} documents.
+ */
+export const ASYNC_TASK_STOP_METHOD = '_session/async_task/stop';
+/**
+ * Narrow a `_session/steering` response onto {@link SteerOutcome}, or throw.
+ *
+ * The extension answers with one of three outcomes (`acp-agent.js@0.76.0:1737`, `:1751`, `:1779`):
+ *
+ * - `injected` — a turn was running and the message went into it.
+ * - `promptRequired` (with `reason: "noRunningTurn"`) — no turn was running and we opted in, so the
+ *   agent did nothing at all and the content stays host-owned.
+ * - `startedNewTurn` — no turn was running and the client did *not* opt in, so the agent detached a
+ *   `prompt()` of its own.
+ *
+ * **`startedNewTurn` throws rather than mapping to anything** (decision D13). We always send
+ * `idleBehavior: "promptRequired"` ({@link AcpSession.steer}), so receiving it means the agent
+ * ignored the opt-in — and what it handed back is a turn nobody awaits: it never enters our queue,
+ * never lands an item, and never produces a `turn_done`, in a system that accounts by turn.
+ * Absorbing it as "injected" would mark a message delivered to a turn we are not tracking;
+ * absorbing it as "promptRequired" would submit the same message a second time. Neither is a
+ * recovery, so this fails where the contract broke, loudly enough to name.
+ *
+ * An outcome nobody recognises throws for the same reason: silently reading it as `injected` would
+ * record a delivery that may never have happened.
+ */
+export function mapSteerOutcome(result) {
+    const outcome = result?.outcome;
+    if (outcome === 'injected')
+        return 'injected';
+    if (outcome === 'promptRequired')
+        return 'promptRequired';
+    if (outcome === 'startedNewTurn') {
+        throw new Error(`[acp] the agent answered ${STEER_METHOD} with 'startedNewTurn', a turn this client never ` +
+            "opted into and does not track: we always send _meta.steering.idleBehavior = 'promptRequired'.");
+    }
+    throw new Error(`[acp] unrecognised ${STEER_METHOD} outcome: ${JSON.stringify(outcome)}`);
+}