pi-legion 5.0.0 → 5.0.1

package/CHANGELOG.md

@@ -11,6 +11,86 @@ summary so you can see **2.x vs 0.16** without leaving the tree.
 
 ## [Unreleased]
 
+## [5.0.1] — 2026-10-27
+
+Patch release. **This is the release where 5.0.0's extension-inheritance policy
+starts actually taking effect** — upgrading changes what a child loads, so read
+the first entry before rolling it out to a fleet.
+
+### Fixed
+
+- **Host extensions are inherited again (#280).** 5.0.0 declared "children inherit
+  every host extension by default" and documented the narrowing knobs, but the
+  policy never reached the spawn path: `discoverHostExtensions()` had no callers,
+  the sync getter it fed therefore returned `undefined`, and
+  `inheritedExtensions` was always handed an empty host list. Children kept
+  getting exactly the card's own `extensions` plus the child-guard — the
+  `--no-extensions` behaviour #280 set out to remove, under a new description.
+
+  Discovery is now warmed once per process before a child is spawned. The cache
+  lives on `globalThis` under `Symbol.for` rather than in a module-level `let`,
+  because pi re-evaluates an extension module with `moduleCache: false` for a
+  child's `--extension` load: a module-level variable is invisible across those
+  instances, so a child spawned from a re-loaded instance would have inherited
+  nothing. The same escape hatch already backs `child-context.ts`,
+  `inprocess-depth.ts` and `admission-queue.ts`.
+
+  The warm-up sits in each backend's `spawnChild` (and in `RoutingSupervisor`,
+  which sees both). It is deliberately not in `Orchestrator.launch`: that fast
+  path may not gain an await before the synchronous admission block
+  (`launch-admission-queue-v1` §13.7).
+
+- **`PI_LEGION_CHILD_INHERIT_EXTENSIONS=0` works on the inherited half (#280).**
+  `collectChildExtensions` accepted an `env` argument and then did not forward it
+  to `inheritedExtensions`, so the operator kill-switch applied everywhere except
+  the set it was meant to disable. Harmless while that set was always empty;
+  wrong the moment it is not.
+
+- **A manifest that names a directory no longer breaks rpc children (#280).**
+  `pi.extensions: ["./extensions"]` (what `pi-diff-review` ships) resolved to the
+  directory itself, and `pi -e <dir>` exits 1 with `Failed to load extension:
+  Cannot find module` — so wiring inheritance up would have failed every rpc
+  child of a session with that package installed. Declared entries now resolve the
+  way pi's own loader does: a file as-is, a directory through its own
+  `pi.extensions`, else its `index.ts` / `index.js`, else its `*.ts` / `*.js`
+  files. An entry that expands to nothing is dropped instead of leaving an
+  unloadable path.
+
+- **`extensions/<name>/index.ts` is discovered (#280).** The first sweep collected
+  only files directly inside a declared directory, so pi's documented
+  subdirectory layout resolved to nothing and the package silently contributed
+  zero extensions. The sweep now matches pi's `collectAutoExtensionEntries`:
+  `.`-prefixed names and `node_modules` are skipped, `*.ts` / `*.js` files are
+  collected, and a subdirectory is resolved as a package of its own (one level,
+  as pi does).
+
+- **A failing `pi list` is retried, and costs one probe per spawn (#280).** The
+  old shape cached the failure as `[]` permanently, so one transient error
+  disabled inheritance until the process restarted. Failures now stamp
+  `failedAt` and short-circuit for `FAILURE_TTL_MS` (5 s), which keeps a
+  three-point warm-up from probing twice on the same spawn while still retrying
+  once the window passes.
+
+- **A direct `RpcSupervisor` gets the same warm-up (#280).** `api.ts` documents
+  `new Orchestrator({ supervisor: new RpcSupervisor(), … })`, which never touches
+  `RoutingSupervisor`; warming only there left that path inheriting nothing.
+
+### Notes
+
+- **Cost now matches what 5.0.0 promised.** Inheriting everything includes
+  pi-lens (a ~5.7 MB bundle that starts an LSP stack) on every child. In-process
+  children share the host process, so this is host memory, not a new process.
+  Add `excludeExtensions: [pi-lens]` to a card (or
+  `PI_LEGION_CHILD_INHERIT_EXTENSIONS=0` globally) if a fleet does not need it —
+  before this release those knobs were inert.
+- **This package is never inherited into its own children.** In the source-tree
+  layout `pi list` and the child-guard name different files for the same code, so
+  dedupe could not collapse them and a child loaded two legion factories
+  (`Tool "subagent" conflicts with …`). The guard is still appended
+  unconditionally at the end.
+- Doctor output and the README described the intended behaviour, which is now the
+  actual behaviour; they were not rewritten for this release.
+
 ## [5.0.0] — 2026-10-26
 
 Major because upgrading **can break an existing role card**: unknown frontmatter

package/docs/contracts/extension-inheritance-wiring-v1.md

@@ -0,0 +1,428 @@
+# 冻结契约：extension inheritance 接线（#280 的漏接线修复）
+
+状态：**FROZEN** — 实施中禁止偏离。发现矛盾立刻停下报告，不要自圆其说。
+范围：implementation-ready。本文件冻结接口、落点、禁令与验收。
+
+## 0. 目标与不做的事
+
+**目标**：让 5.0.0 已声明的策略「children inherit every host extension by default
+(#280)」在运行时真正生效。当前 `discoverHostExtensions()` 全仓零调用，
+`discoveredHostExtensions()` 恒为 `undefined`，`inheritedExtensions` 恒收到空 host
+列表，策略层存在但等于空转。
+
+**顺带修掉两个独立缺陷**（它们被空 discovery 掩盖，接线后会立刻显形）：
+
+- `collectChildExtensions(agent, env)` 丢弃 `env`，导致 `PI_LEGION_CHILD_INHERIT_EXTENSIONS=0`
+  对继承集无效（实测：`inheritedExtensions(agent, HOST, envOff)` → 0 条，但
+  `collectChildExtensions(agent, envOff)` → 7 条）
+- legion 自身可能被当作「宿主扩展」注入子会话，与 child-guard 形成双份加载
+
+**non-goals（本契约明确不做）**：
+
+- 不改 `role-tool-gates.ts:79` 的「inheritsExtensions 为 true 时静音」策略。接线成功后该策略
+  才真正成立；若宿主确实缺某扩展，静音仍是既有独立缺陷，另立 issue。
+- 不改 doctor 的 `!inheritGlobal` 模型探测短路（`legion-doctor.ts:569/597/607`）。接线后
+  `inheritGlobal=true` 与「真的继承了」重新一致。
+- 不修 `playbook.ts:14` / `docs/headless-child-contract.md` 等文案。文案与代码再次一致后
+  这些描述自动成立。
+- 不动 `--no-extensions` + 显式 `--extension` 的既有形状。rpc/inprocess 字节级对齐是
+  冻结契约（`args.ts:249-255`、`inprocess-supervisor.ts:151-159`）。
+
+## 1. 已确认事实（父会话已核对，**禁止重新侦察**）
+
+| # | 事实 | 证据 |
+| --- | --- | --- |
+| F1 | `discoverHostExtensions()` 全仓零调用；`resetExtensionDiscoveryCache()` 同样零调用 | `src/runs/extension-inheritance.ts:128`、`:70`（唯一定义处） |
+| F2 | `discovered` 唯一赋值点在 `discoverHostExtensions` 内部 | `extension-inheritance.ts:144` |
+| F3 | `discoveredHostExtensions()` 是纯 sync getter，返回模块级 `discovered` | `extension-inheritance.ts:156-158` |
+| F4 | `collectChildExtensions` 把 `discoveredHostExtensions() ?? []` 传给 `inheritedExtensions`，**未传 env** | `src/runs/args.ts:217` |
+| F5 | `childInheritsExtensions` 默认返回 `true`；env 只能降不能升（`=1` 是 no-op） | `extension-inheritance.ts:51-61`（实测三种卡片形态下 env=1 与默认完全相同） |
+| F6 | 实测 `moduleCache:false` 下模块级 `let` **跨 jiti 实例不可见**，且**同实例重复 import 也重执行**（executions: 2） | jiti 探针 P1/P1h（见侦察报告） |
+| F7 | 默认缓存下同一模块实例可跨 jiti 实例共享（`B 看到 A 的 6 条`） | jiti 探针 P1-default-cache |
+| F8 | 本仓另三处**故意**用 `globalThis+Symbol.for` 对抗 jiti 重载 | `src/supervisor/child-context.ts:11-24`、`src/supervisor/inprocess-depth.ts:6-26`、`src/supervisor/admission-queue.ts:25-31` |
+| F9 | `/reload` → `clearExtensionCache()` → 入口模块重新 import → `discovered` 归零 | `agent-session.js:3010` → `resource-loader.js:352-359` → `loader.js:89-93`、`:461-490`（实测每次 reload 重新 transpile） |
+| F10 | 同 cwd 下新建子 loader **复用**父模块实例；cwd 变化才 `clearExtensionCache` | 探针 P3m（`A==B same cwd -> shared: true`、`A==C diff cwd -> re-imported`） |
+| F11 | 安装副本形态下 guard 路径 === discovered legion 条目（`path.resolve` 后相等），dedupe 合并成 1 条 | 探针 P2（`dedupeKeys equal? true`、`collectChildExtensions count: 1`） |
+| F12 | 源码树自举形态下两者不等，出现**两个 legion factory**并报 tool 冲突 | 探针 P2h（`legion factories: 2`、`Tool "subagent" conflicts with /root/code/...`） |
+| F13 | `extensionDedupeKey` 只做 `path.resolve`（builtin 除外） | `src/runs/args.ts:181-183` |
+| F14 | `matchesExcludedExtension` 支持包名形式，`pi-legion` 匹配安装副本与源码树两种路径 | `extension-inheritance.ts:170-195` |
+| F15 | `launch()` 774→1072 只有 2 个 await（`:1005`、`:1072`），均在同步准入块 `:938-955` 之后 | 探针 P4 + 源码 |
+| F16 | 契约禁令：禁止让 `launch()` 的快路径多出任何 await | `docs/contracts/launch-admission-queue-v1.md:829` |
+| F17 | `LaunchInput` 无 `signal`/`abort` 字段；`launch()` 内无 abort 读取 | `orchestrator.ts:180-196`；P4 |
+| F18 | `RoutingSupervisor.spawnChild` 是唯一分派到两个后端的点，且**本身 async** | `src/supervisor/routing-supervisor.ts:128-160` |
+| F19 | 唯一 spawn 漏斗是 `Orchestrator.launch` → `supervisor.spawnChild`（`:1072`） | `orchestrator.ts:774`、`:1072` |
+| F20 | 存在 3 类不在 tool execute 帧内的 spawn 出口：postman 定时器、启动期团队恢复 microtask、launch 队列泵 | `legion-tools.ts:106-110`→`:184`→`index.ts:544`；`index.ts:642-649`→`:683`；`orchestrator.ts:1488`/`:1449-1452` |
+| F21 | `pi list` 实测 320–920 ms；有 project 资源时内部会加载全部扩展（309 条 jiti 记录） | 探针 P4-timing |
+| F22 | `discoverHostExtensions` 只 `execFile("pi",["list"])`，不 spawn 子 agent、不写 legion.db | `extension-inheritance.ts:128-152` |
+| F23 | 失败也会被缓存成 `[]`，且 `if (discovered)` 对空数组为真 → 永不重试 | `extension-inheritance.ts:129`、`:143-151` |
+| F24 | 会因 discovery 接上而变红的现有测试 | `test/unit/args.test.ts:43,40,128,185`；`test/unit/legion-doctor.test.ts:261`（详见 §6） |
+| F25 | 脚本：`npm run typecheck` / `npm test` / `npm run test:integration` | `package.json:52-54` |
+
+## 2. 决策（D 编号，reviewer 必读）
+
+### D1 — 缓存迁到 `globalThis[Symbol.for]`
+
+**判定**：`discovered` / `discovery` 从模块级 `let` 迁到
+`globalThis[Symbol.for("pi-legion.extension-discovery")]` 上的一个 holder 对象。
+
+**理由**：F6 实测证明模块级 `let` 在 pi 的真实 loader 配置（`moduleCache:false`）下跨 jiti
+实例不可见、同实例重 import 也归零。若继续用模块级变量，子会话（cwd 不同时触发
+`clearExtensionCache`，F10）内的 spawn 会读到空的 `discovered`，「父预热一次惠及全树」不成立。
+F8 是本仓库已验证的同因先例。
+
+**失败模式**：不做迁移 → 探针 P1-noCache 的形态（`B.discovered: undefined`）在生产复现，
+修复只对「第一次 spawn」有效。
+
+**验收**：A1、A2。
+
+#### D1-a — holder 形状与复位语义
+
+```ts
+const STORE_KEY = Symbol.for("pi-legion.extension-discovery");
+
+interface DiscoveryStore {
+	/** Resolved list, or undefined until discovery completes. */
+	discovered?: string[];
+	/** In-flight promise, so concurrent launches share one `pi list`. */
+	inFlight?: Promise<string[]>;
+}
+
+type StoreHolder = { [key: symbol]: DiscoveryStore | undefined };
+const store = ((globalThis as unknown as StoreHolder)[STORE_KEY] ??= {});
+```
+
+`resetExtensionDiscoveryCache()` 必须 **清空同一个 holder 的字段**（`delete store.discovered;
+delete store.inFlight;`），不得重新赋值 holder —— 否则父会话与子会话会指向两个不同对象
+（F6 的直接后果），`reset` 在测试外的语义也会静默失效。
+
+### D2 — 预热落点：`RoutingSupervisor.spawnChild`，不是 `Orchestrator.launch`
+
+**判定**：在 `RoutingSupervisor.spawnChild` 顶部（`resolveSpawnMode` 之后、分派之前）
+`await ensureHostExtensions()`。**不得**在 `Orchestrator.launch` 顶部预热。
+
+**理由**：
+
+- F16 是**已冻结契约的禁令**：`launch()` 快路径不得多出 await。F15 显示这段只有 2 个
+  await 且都在同步准入块之后，插到准入块之前会破坏 A21（同 tick 8 步 fanout 的槽位预留）。
+- F18：`RoutingSupervisor.spawnChild` 本身 async、已在 await 链上、且是唯一同时看见两后端的点。
+- F19 + F20：`Orchestrator.launch` 是唯一 spawn 漏斗，`RoutingSupervisor.spawnChild` 是它唯一
+  的下游分派点 —— 三类后台出口（postman 定时器 / 团队恢复 microtask / 队列泵）全部经过它，
+  因此预热覆盖全部 spawn 路径。
+- F21：预热最坏 920 ms 且只在**首次**发生（之后 holder 命中）。放在分派点不影响准入判定。
+
+**失败模式**：放到 `launch()` → 违反 F16，A21 测试变红；放到 `index.ts` 的 tool execute →
+漏掉 F20 的三类后台出口。
+
+**验收**：A3、A4。
+
+#### D2-a — `ensureHostExtensions` 契约
+
+```ts
+/**
+ * Resolve the host's extension set once, for the whole process.
+ *
+ * Never throws and never rejects: discovery failure must not fail a launch
+ * (F22/F23). Returns the resolved list, or `[]` when discovery failed.
+ */
+export async function ensureHostExtensions(env?: NodeJS.ProcessEnv): Promise<string[]>;
+```
+
+- 幂等：并发调用共享同一个 in-flight promise（与既有 `discovery ??=` 语义一致）。
+- 已缓存则立即返回缓存（不跑 `pi list`）。
+- **失败缓存策略变更**：`pi list` 失败时**不缓存空数组**，只清 in-flight，让下一次 spawn 重试。
+  理由 F23：既有实现把 `[]` 永久缓存，一次瞬时失败会静默关闭继承直到进程重启。
+- `env` 透传给 `execFile`（既有行为），但**缓存键不区分 env** —— 保持"进程内一份主机扩展集"语义。
+
+**验收**：A5。
+
+### D3 — env 透传修复
+
+**判定**：`collectChildExtensions` 把 `env` 传给 `inheritedExtensions`。
+
+```ts
+...inheritedExtensions(agent, discoveredHostExtensions() ?? [], env),
+```
+
+**理由**：F4 实测 `PI_LEGION_CHILD_INHERIT_EXTENSIONS=0` 目前对继承集无效。接线后 doctor 里
+按 env 构造的场景（`legion-doctor.test.ts` 多处）会连锁失败。
+
+**失败模式**：不修 → opt-out 在生产无效，用户设 `=0` 却仍拿到全部宿主扩展（接线后）。
+
+**验收**：A6。
+
+### D4 — legion 自身从继承集排除
+
+**判定**：`collectChildExtensions` 在合并前把 legion 自身从 inherited 集合里滤掉：
+
+```ts
+const inherited = inheritedExtensions(agent, discoveredHostExtensions() ?? [], env)
+	.filter((ext) => !matchesExcludedExtension(ext, SELF_EXTENSION_NAME));
+```
+
+其中 `SELF_EXTENSION_NAME` 是包名常量（`"pi-legion"`）。child-guard 仍在
+函数末尾**无条件**追加，因此本判定不影响 guard 的必然存在。
+
+**理由**：F11 显示安装副本形态本来就会 dedupe 成 1 条；F12 显示自举形态会出现两个 factory
+并报 tool 冲突（`Tool "subagent" conflicts with ...`）。自排除让两种形态都收敛到 1 条。
+
+**不做的事**：不依赖 `extensionDedupeKey` 做路径归一化。F13 显示它只做 `path.resolve`，
+无法识别"同一份代码的两个副本"（F12 实测 inode 不同）。
+
+**验收**：A7。
+
+### D5 — 不新增 await 到 `launch()`，不碰 doctor 策略
+
+见 non-goals 与 F16。`legion-doctor.ts` 的 `extensionsForRole` 占位串
+`"(all host-discovered extensions)"` 接线后重新成立，**不改**。
+
+**验收**：A8（`launch()` 的 await 数量与位置不变）。
+
+## 3. 文件归属（单 writer，禁止越界）
+
+| 文件 | 允许的改动 |
+| --- | --- |
+| `src/runs/extension-inheritance.ts` | D1（holder 迁移）、D2-a（新增 `ensureHostExtensions`）；`discoverHostExtensions` 失败不缓存空数组 |
+| `src/runs/args.ts` | D3（第 217 行补 env）、D4（自排除 + 常量） |
+| `src/supervisor/routing-supervisor.ts` | D2（`spawnChild` 顶部 `await ensureHostExtensions()`） |
+| `test/unit/extension-inheritance.test.ts` | A1、A2、A5 新增用例 |
+| `test/unit/args.test.ts` | A6、A7 新增用例；修 F24 的 4 条 |
+| `test/unit/legion-doctor.test.ts` | 修 F24 的 1 条（`:261`） |
+
+**禁止改动**：`src/runs/orchestrator.ts`、`src/supervisor/inprocess-supervisor.ts`、
+`src/supervisor/rpc-supervisor.ts`、`src/extension/legion-doctor.ts`（生产代码）、
+`src/runs/role-tool-gates.ts`、`docs/contracts/launch-admission-queue-v1.md`。
+
+## 4. 验收清单
+
+| # | 断言 | 方式 |
+| --- | --- | --- |
+| A1 | 迁移后 `discoveredHostExtensions()` 仍能读到 `ensureHostExtensions()` 的结果 | 单测：`await ensureHostExtensions()` 后 `discoveredHostExtensions()` 非 undefined |
+| A2 | `resetExtensionDiscoveryCache()` 清空的是**同一个** holder（不是换新对象） | 单测：reset 前拿到 holder 引用，reset 后 `discoveredHostExtensions()` 为 undefined 且引用不变 |
+| A3 | `RoutingSupervisor.spawnChild` 在分派前 await 预热 | 单测：stub `ensureHostExtensions`，断言调用发生在 backend.spawnChild 之前 |
+| A4 | 预热幂等：连续 2 次 spawn 只跑一次 `pi list` | 单测：计数 stub，断言恰好 1 次 |
+| A5 | 预热失败不抛、不缓存空结果（第二次会重试） | 单测：stub execFile 先失败后成功，断言第 2 次调用拿到结果 |
+| A6 | `collectChildExtensions(agent, {PI_LEGION_CHILD_INHERIT_EXTENSIONS:"0"})` 不含 inherited 条目 | 单测：primed discovery 后断言 |
+| A7 | inherited 集合不含 legion 自身，但 child-guard 仍在末尾 | 单测：断言 `!list.includes(selfPath) && list.includes(childGuardExtensionPath())` |
+| A8 | `orchestrator.ts` 的 774→1072 区间 await 仍只有 `:1005`（内容可漂）与 `spawnChild` 那一处 | `grep -c await` 对照 + 契约禁令 5 复核 |
+| A9 | 全量单测绿 | `npm run typecheck && npm test && npm run test:integration` |
+| A10 | 真实端到端：primed 后 `collectChildExtensions` 含宿主扩展（pi-lens 等） | 内联 `node -e` 探针，输出与 F11 形状一致 |
+
+## 5. 实施顺序
+
+1. D1 holder 迁移（不改变行为，先让缓存可跨实例）
+2. D2-a `ensureHostExtensions`（含失败不缓存）
+3. D3 env 透传 → D4 自排除（两处都在 `args.ts`，一次改完）
+4. D2 预热点接入
+5. 修 F24 的 5 条测试 + 新增 A1–A7
+
+第 1 步之后跑一次 `npm test` 确认零红，再继续 —— 否则后续失败无法归因。
+
+## 6. 已知会变红的测试（F24，必须一并处理）
+
+| 测试 | 位置 | 变红原因 |
+| --- | --- | --- |
+| `buildPiArgs injects the child-guard extension` | `args.test.ts:30`，断言 `:43-45` | `--extension` 计数从 1 变 7；第一个值不再是 guard |
+| 同上 `:39-41` | 取第一个 `--extension` 值 | 同上 |
+| `#43 children get --no-extensions by default` | `args.test.ts:124`，`deepEqual` `:128` | 全量数组顺序敏感 |
+| `#89 collectChildExtensions dedupes explicit builtin:codemode` | `args.test.ts:178`，`deepEqual` `:185-188` | 同上 |
+| `#70 bundled worker does not promise lens tools` | `legion-doctor.test.ts:230`，断言 `:261` | discovered 含 `pi-lens/dist/index.js` |
+
+**修复方式**：这些测试断言的是「discovery 为空时」的列表形状。改为**显式控制 discovery
+状态**：在 `withEnv` 里额外 `resetExtensionDiscoveryCache()`，并对需要完整列表的用例断言
+「inherited 条目存在 + guard 在末尾」而不是全量 `deepEqual`。
+
+**禁止**：用 `excludeExtensions: ["*"]` 或伪造空 host 来让旧断言继续通过 —— 那是把 F24
+的假设重新固化成契约。
+
+---
+
+## 7. 修订 R1（review 后追加，2026-10-26）
+
+本节由 reviewer 审查 `fix/280-extension-inheritance-wiring` 后追加。**修订原因是实施中发现了
+F1–F25 未能预见的两条真实缺陷**；F 事实表保持不变，A 清单在其后增量。
+
+### R1-a — 目录形态的 `pi.extensions` 条目必须展开成可加载文件（critical）
+
+**新事实**：
+
+| # | 事实 | 证据 |
+| --- | --- | --- |
+| F26 | `pi-diff-review` 的 `package.json` 声明 `pi.extensions: ["./extensions"]`，该目录内只有 `review.ts`、无 `package.json`/`index.ts` | `node -e require('.../pi-diff-review/package.json').pi` + `ls` |
+| F27 | `resolveExtensionEntries` 对声明条目只做 `existsSync` 过滤，**不过滤目录** | `extension-inheritance.ts:130-134`（接线后实测 `非文件条目: [".../pi-diff-review/extensions"]`） |
+| F28 | 真实 `pi -e <该目录> --print` → **exit 1**（`Failed to load extension: Cannot find module`）；换成 `-e <该目录>/review.ts` → **exit 0** | 实测两次退出码 |
+| F29 | in-process 后端不致命但静默丢弃：`DefaultResourceLoader({additionalExtensionPaths:[该目录]})` → `errors: 1, loaded: 0`，且 `inprocess-supervisor.ts` 只 warn `pendingProviderRegistrations`，读不到 `getExtensions().errors` | SDK 探针 |
+
+**判定**：`resolveExtensionEntries` 必须把目录条目展开成其内可加载的 `*.ts|*.js`，
+镜像 pi 自己的 loader 行为；展开为空则丢弃该条目。
+
+**为什么这不违反 non-goal 5**：non-goal 5 指「不修 `pi.extensions` 写成目录而非文件」这个
+**拼写选择**。本节不改变那个选择，只保证交给 `-e` 的东西可加载。接线前该缺陷不可达（F3），
+接线后它变成「每个用 pi-diff-review 的 rpc 子会话启动失败」，属改动自身引入的回归。
+
+**新增验收**：
+
+| # | 断言 |
+| --- | --- |
+| A11 | `pi.extensions: ["./extensions"]` 且目录内只有 `review.ts`（无 index/package.json）→ 解析结果是 `.../extensions/review.ts`，不是目录 |
+| A12 | `pi.extensions` 指向空目录 → 该条目被丢弃，不出现在 argv |
+| A13 | `collectChildExtensions` 返回值中**不存在**非文件路径（用 `statSync().isFile()` 全量断言） |
+
+### R1-b — 预热点必须覆盖直连 `RpcSupervisor` 的公开路径（major）
+
+**新事实**：
+
+| # | 事实 | 证据 |
+| --- | --- | --- |
+| F30 | `api.ts:13` 的文档示例是 `new Orchestrator({ supervisor: new RpcSupervisor(), ... })`，绕过 `RoutingSupervisor` | 读 `src/api.ts:8-20` |
+| F31 | `Orchestrator` 构造函数的 supervisor 默认值也是裸 `RpcSupervisor` | `orchestrator.ts:453` |
+| F32 | `index.ts` 的 5 处 `new Orchestrator` **全部**传 `input.supervisor`（来自 `RoutingSupervisor`），故自举形态覆盖正常 | `grep -A6 "new Orchestrator" index.ts`（736/1832/1930/2422/3116） |
+
+**判定**：预热点从 `RoutingSupervisor.spawnChild` **下沉**到两个后端各自的
+`spawnChild` 顶部（`InProcessSupervisor.spawnChild`、`RpcSupervisor.spawnChild`）。
+理由：这是无论调用方走 router 还是直连后端都必须经过的点，且两者本身都是 async。
+`RoutingSupervisor.spawnChild` 的预热**保留**——它能在参数校验失败前就暖好缓存，
+且 router 路径下第一次调用会命中已暖的 holder（幂等，无额外 `pi list`）。
+
+**为什么不放 `Orchestrator.launch`**：F16 禁令不变，`launch()` 快路径不得新增 await。
+
+**新增验收**：
+
+| # | 断言 |
+| --- | --- |
+| A14 | 直接 `new RpcSupervisor()` + `new Orchestrator({supervisor})` 后 `launch()`，`discoveredHostExtensions()` 非 undefined |
+| A15 | 同上，in-process 后端 |
+| A16 | 幂等不变：router 路径下连续 2 次 spawn 仍只 1 次 `pi list` |
+
+### R1-c — 驳回的 finding（记录以免重复争议）
+
+reviewer 报的 minor「自排除会误吃 `acme/src/legion/index.ts`」**不成立**：
+自排除常量是 `"pi-legion"`，`matchesExcludedExtension` 的 `dir === target` /
+`file === target.ts` 兜底只在目录/文件名恰为 `pi-legion` 时触发。实测 5 条路径，
+仅真正的 `node_modules/pi-legion/index.ts` 被丢：
+
+```
+kept    /host/node_modules/acme/src/legion/index.ts
+kept    /host/node_modules/acme/extensions/legion.ts
+kept    /host/node_modules/acme-legion/index.ts
+kept    /host/node_modules/acme/legion-ext/index.ts
+DROPPED /host/node_modules/pi-legion/index.ts
+```
+
+reviewer 用错了包名（拿 `legion` 当 target）。**不修。**
+
+### R1-d — 修订后的文件归属
+
+在 §3 基础上**新增允许改动**：
+
+| 文件 | 允许的改动 |
+| --- | --- |
+| `src/runs/extension-inheritance.ts` | R1-a 的目录展开（`resolveExtensionEntries`） |
+| `src/supervisor/inprocess-supervisor.ts` | **仅** R1-b：`spawnChild` 顶部 `await ensureHostExtensions()` |
+| `src/supervisor/rpc-supervisor.ts` | **仅** R1-b：`spawnChild` 顶部 `await ensureHostExtensions()` |
+| `test/unit/extension-inheritance.test.ts` | A11–A13 |
+| `test/unit/routing-supervisor*.test.ts` 或 `test/unit/orchestrator*` 就近文件 | A14–A16 |
+
+§3 的其余禁区不变（`orchestrator.ts` 仍禁止改，含 `launch()`）。
+
+---
+
+## 8. 修订 R2（第二次 review 后追加，2026-10-26）
+
+由 `rev-r1` 复审 `8cf2aba` 后追加。R1 的两条修复方向正确，但**镜像 pi loader 的目标未达到**，
+且三处预热点在失败路径上互相叠加。以下为增量事实与决策。
+
+### R2-a — 目录展开必须镜像 `collectAutoExtensionEntries`（major）
+
+| # | 事实 | 证据 |
+| --- | --- | --- |
+| F33 | pi 处理 manifest 声明的目录走 `collectAutoExtensionEntries`，对每个**子目录**再调 `resolveExtensionEntries`，因此 `extensions/<name>/index.ts` 是官方文档化布局 | `package-manager.js:407-462`；`loader.js:623-631` 注释「规则 2: Subdirectory with index」 |
+| F34 | 本实现在同一 fixture 上返回 `[]`：`extensions/alpha/index.ts` + `extensions/beta/index.ts` 全部静默丢失 | 实测 `resolveExtensionEntries("/tmp/extprobe/pkg")` → `[]` |
+| F35 | `discoverExtensionFiles` 的注释自称「Deliberately one level」，理由是「嵌套包不需要，递归会把错拼路径变成无界遍历」 | `extension-inheritance.ts:160-168` |
+| F36 | 同一实现把 `extensions/.eslintrc.js` **收进**结果；pi 的 `collectAutoExtensionEntries` 显式跳过 `.` 开头与 `node_modules` | `extension-inheritance.ts:176`；`package-manager.js:407-462` |
+| F37 | 但 `pi -e <点文件>` 实测 **exit 0**（不是 exit 1），故 F36 的后果是「多传一条无用条目」而非启动失败 | 实测 `.eslintrc.js` → EXIT=0；`alpha/index.ts` → EXIT=0 |
+
+**判定（R2-a）**：`discoverExtensionFiles` 改为与 pi 同形：
+
+- 跳过 `.` 开头的条目与 `node_modules`
+- 文件且 `*.ts|*.js` → 收
+- **子目录** → 调 `resolveExtensionEntries(child, false)`，收到结果就收，收不到就跳过
+
+F35 的「无界遍历」担忧用**深度上限**解决：`resolveExtensionEntries(dir, allowNestedManifest)` 的
+第二个参数（已存在）作为递归闸门，嵌套层只允许一层子目录解析，子目录内部不再继续递归。
+这与 pi 的行为一致（pi 也只递归一层：`collectAutoExtensionEntries` → `resolveExtensionEntries`
+→ 不再往下）。
+
+**新增验收**：
+
+| # | 断言 |
+| --- | --- |
+| A17 | `extensions/alpha/index.ts` + `extensions/beta/index.ts`（无 manifest/index 于 extensions 根）→ 两条结果都出现 |
+| A18 | `extensions/.eslintrc.js` 不被收进结果 |
+| A19 | 子目录内还是目录（`extensions/x/y/index.ts`）→ 不递归收，结果为空（或只收 `x` 层能解析到的） |
+
+### R2-b — 预热点在失败路径上必须幂等（major）
+
+| # | 事实 | 证据 |
+| --- | --- | --- |
+| F38 | `ensureHostExtensions` 失败时不缓存（F23 的刻意设计，保留），故每次调用都会重跑 `pi list` | `extension-inheritance.ts:292-313` |
+| F39 | 三处预热点（router + rpc 后端 + inprocess 后端）叠加后，router 路径一次 spawn 会 warm 两次：router 一次（失败）+ 后端一次（再失败） | 实测三次连续 `ensureHostExtensions` → `[[],[],[]]` |
+| F40 | 失败时每个 spawn 恒付 2× 探测成本（真实 0.3–1.8s；`pi list` 超时时最坏 +30s），且发生在内存门之前 | `rev-r1` 实测（fake `pi` 500ms → spawn#1 1035ms / spawn#2 1026ms） |
+| F41 | A16 的字面断言「router 路径连续 2 次 spawn 仍只 1 次 `pi list`」只在成功路径成立 | 同上 |
+
+**判定（R2-b）**：引入**同 spawn 短路标记**，不动「失败不缓存跨 spawn 可重试」的语义：
+
+```ts
+/**
+ * Mark the current spawn attempt as already-warmed, so the backend's warm call
+ * does not repeat a FAILED `pi list` that the router just paid for.
+ *
+ * Scope: one spawn attempt. Reset when the outermost warm returns.
+ */
+```
+
+实现方式（选一，实施者择简）：
+
+- **(a) 传入标记**：`ensureHostExtensions(env, { spawnScoped?: boolean })`；`RoutingSupervisor`
+  调用后设置一个同步可见的 `recentlyWarmed` 时间戳/布尔，两个后端在**同一 tick 内**看到就短路。
+- **(b) 失败短 TTL**：失败时把 `failedAt = Date.now()` 记进 holder，`ensureHostExtensions` 在
+  `FAILURE_TTL_MS`（如 5s）内直接返回 `[]` 而不重跑。跨 spawn 的最坏情况变成「首次失败后 5s 内的
+  spawn 都不重试」，比现状好，且仍满足 F23「不是永久关闭」。
+
+**倾向 (b)**：实现最小（holder 加一个字段），无需在 router 与后端之间传状态，也不改变
+`ensureHostExtensions` 的签名（A14/A15 的测试不用重写）。TTL 值必须是命名常量并注释理由。
+
+**新增验收**：
+
+| # | 断言 |
+| --- | --- |
+| A20 | `pi list` 失败下，router 路径一次 spawn 只跑 **1** 次 `pi list`（不是 2） |
+| A21 | 失败后超过 `FAILURE_TTL_MS`，下一次 spawn 会**重试**（可恢复性未被永久关闭） |
+| A22 | 成功路径行为不变：连续 2 次 spawn 仍只 1 次 `pi list`（既有 A16 保持绿） |
+
+### R2-c — 测试注释必须如实（minor）
+
+`test/unit/extension-inheritance.test.ts:601-604` 的注释声称断言集合是「fake host **PLUS the
+live `pi list`**」，但 `withPathEnv` 执行的是 `process.env.PATH = pathValue`（**完全替换**，
+`test/unit/extension-inheritance.test.ts:235`），真实 `pi list` 从未运行。
+
+**判定**：删掉「PLUS the live `pi list`」这半句。**不得**为此新增不做 PATH 遮蔽的用例 ——
+那会让测试依赖本机安装的包，不可移植。
+
+### R2-d — 修订后的文件归属增量
+
+在 §7 R1-d 基础上，**新增允许改动**：
+
+| 文件 | 允许的改动 |
+| --- | --- |
+| `src/runs/extension-inheritance.ts` | R2-a 的 sweep 重写、R2-b 的失败 TTL |
+| `test/unit/extension-inheritance.test.ts` | A17–A21、R2-c 的注释删除 |
+| `test/unit/routing-supervisor*.test.ts` 或就近文件 | A20 |
+
+`src/runs/orchestrator.ts`、`src/extension/legion-doctor.ts`、`src/runs/role-tool-gates.ts`、
+`docs/contracts/launch-admission-queue-v1.md` 仍为禁区。
+
+### R2-e — 降级与驳回记录
+
+- **降级**：`rev-r1` 的 minor「点文件导致 `pi -e` exit 1」论据不成立（实测 EXIT=0）。
+  但「点文件不该被收」仍成立（pi 自己会跳过，多传一条无用条目）→ 并入 R2-a 的 A18。
+- **保持驳回**：§7 R1-c 的「自排除误吃 `acme/src/legion/index.ts`」仍不成立，勿再报。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-legion",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "Pi Legion v2: recursive centurion teams on Pi. Children run in-process by default (rpc only for a worktree-owning centurion); shared SQLite WAL legion.db. Declarative per-team phase machine (built-in default: planning/implementing/reviewing/verifying), parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume.",
   "type": "module",
   "license": "MIT",

package/src/runs/args.ts

@@ -14,7 +14,7 @@ import {
 	isThinkingLevel,
 } from "../shared/types.ts";
 import { formatChildTask } from "../extension/child-guard.ts";
-import { childInheritsExtensions, discoveredHostExtensions, inheritedExtensions } from "./extension-inheritance.ts";
+import { discoveredHostExtensions, inheritedExtensions, matchesExcludedExtension } from "./extension-inheritance.ts";
 
 /** Re-exported for callers that only need the level list. */
 export { THINKING_LEVELS };
@@ -191,6 +191,9 @@ export function isCodemodeExtension(ext: string): boolean {
 	return t === BUILTIN_CODEMODE || t.endsWith("/" + BUILTIN_CODEMODE);
 }
 
+/** This package's name — its extension is never inherited, only guarded explicitly. */
+export const SELF_EXTENSION_NAME = "pi-legion";
+
 /**
  * Effective `--extension` values for a child.
  *
@@ -213,8 +216,22 @@ export function collectChildExtensions(
 	>,
 	env: NodeJS.ProcessEnv = process.env,
 ): string[] {
+	// `env` MUST be forwarded: `PI_LEGION_CHILD_INHERIT_EXTENSIONS=0` is the
+	// operator kill-switch, and dropping it here made the opt-out a no-op for the
+	// inherited half of the list while still applying to everything else.
+	//
+	// Legion's own extension is filtered out of the inherited set. In the
+	// installed-copy layout `pi list` reports the same package the child-guard
+	// already names, and dedupe collapses them; in the source-tree layout the two
+	// paths differ, so the child would load TWO legion factories and die on
+	// `Tool "subagent" conflicts with ...`. Self-exclusion makes both layouts
+	// converge on exactly one, and the guard below still appends it
+	// unconditionally — so a hermetic card does not lose the guard either.
+	const inherited = inheritedExtensions(agent, discoveredHostExtensions() ?? [], env).filter(
+		(ext) => !matchesExcludedExtension(ext, SELF_EXTENSION_NAME),
+	);
 	const list = [
-		...inheritedExtensions(agent, discoveredHostExtensions() ?? []),
+		...inherited,
 		...(agent.extensions ?? []),
 		...(agent.subagentOnlyExtensions ?? []),
 		...childExtraExtensions(env),

package/src/runs/extension-inheritance.ts

@@ -61,25 +61,187 @@ export function childInheritsExtensions(
 
 const execFileAsync = promisify(execFile);
 
-/** Host-discovered package extension paths, resolved once per process. */
-let discovered: string[] | undefined;
-/** In-flight discovery, so concurrent launches share one `pi list`. */
-let discovery: Promise<string[]> | undefined;
+/**
+ * Where the discovery cache lives: `globalThis` under `Symbol.for(...)`.
+ *
+ * A module-level `let` would be invisible to the other module *instances* in
+ * this process. A child's `--extension` load re-evaluates this module with
+ * `moduleCache: false`, and `/reload` plus a cwd change clear pi's extension
+ * cache, so each re-evaluation would start from an empty cache and throw away
+ * the parent's warm result — "discover once per process" would degrade to
+ * "discover once per module instance", and a child spawned from a re-loaded
+ * instance would silently inherit nothing.
+ *
+ * `Symbol.for` is registry-backed and `globalThis` survives re-evaluation; the
+ * same escape hatch is used by `supervisor/child-context.ts`,
+ * `supervisor/inprocess-depth.ts` and `supervisor/admission-queue.ts` for the
+ * same reason.
+ *
+ * Do NOT turn this back into a module-level variable, and do not re-assign the
+ * holder in `resetExtensionDiscoveryCache` — two module instances would then
+ * point at two different holders and the reset would silently stop working.
+ */
+const STORE_KEY = Symbol.for("pi-legion.extension-discovery");
 
-/** Reset the cache. Test seam only. */
+interface DiscoveryStore {
+	/** Resolved extension list, or undefined until a discovery succeeds. */
+	discovered?: string[];
+	/** In-flight discovery, so concurrent launches share one `pi list`. */
+	inFlight?: Promise<string[]>;
+	/**
+	 * When the last discovery FAILED, in `Date.now()` terms.
+	 *
+	 * A failure is still not cached as `[]` (F23: one blip must not disable
+	 * inheritance until restart), but every caller is not allowed to re-probe
+	 * either: three warm-up points (router, rpc backend, in-process backend) turn
+	 * one spawn into two `pi list` calls when each of them retries. This stamp is
+	 * the short memory that makes the retry storm impossible while keeping the
+	 * failure recoverable — see `FAILURE_TTL_MS`.
+	 */
+	failedAt?: number;
+}
+
+/** Symbol-indexed view of globalThis so the cache survives module re-evaluation. */
+type StoreHolder = { [key: symbol]: DiscoveryStore | undefined };
+
+// SAFETY: `globalThis` is an object, so a `Symbol.for`-keyed property on it is
+// readable; the only invariant TypeScript cannot check is that whoever wrote
+// that slot first stored a `DiscoveryStore`. Both sides of that contract live in
+// this file, so the declared slot type is authoritative.
+const store = ((globalThis as unknown as StoreHolder)[STORE_KEY] ??= {});
+
+/**
+ * Reset the cache. Test seam only.
+ *
+ * Clears the holder's FIELDS rather than replacing the holder: a replacement
+ * would be invisible to every other module instance still pointing at the old
+ * object (the exact failure mode the shared holder exists to prevent).
+ */
 export function resetExtensionDiscoveryCache(): void {
-	discovered = undefined;
-	discovery = undefined;
+	delete store.discovered;
+	delete store.inFlight;
+	// The failure stamp is part of the cache: leaving it behind would make the
+	// next case inherit this one's backoff and silently skip its `pi list`.
+	delete store.failedAt;
+}
+
+/**
+ * Expand one declared `pi.extensions` entry into loadable files (#280 R1-a).
+ *
+ * A manifest may name a DIRECTORY (`pi.extensions: ["./extensions"]` — that is
+ * what `pi-diff-review` ships). Handing that path to `pi -e` is fatal: pi's
+ * loader requires an entry point and exits 1 with `Failed to load extension:
+ * Cannot find module`. So a directory is resolved the way pi's own
+ * `discoverAndLoadExtensions` resolves an explicitly configured path: the
+ * directory's own `pi.extensions`, else its `index.ts`/`index.js`, else the
+ * `*.ts`/`*.js` files sitting directly in it.
+ *
+ * `allowNestedManifest` bounds the walk to one extra level: a nested package's
+ * manifest is read, but the directories IT declares expand to their files
+ * instead of recursing again. Without that bound a manifest declaring `"./"`
+ * would re-enter itself forever.
+ *
+ * Returns `[]` when nothing loadable is inside, so the caller can DROP the entry
+ * rather than emit a path that cannot be loaded.
+ */
+function expandDeclaredEntry(entry: string, allowNestedManifest: boolean): string[] {
+	let stat: fs.Stats;
+	try {
+		stat = fs.statSync(entry);
+	} catch {
+		return [];
+	}
+	if (stat.isFile()) return [entry];
+	if (!stat.isDirectory()) return [];
+	if (allowNestedManifest) {
+		const nested = resolveExtensionEntries(entry, false);
+		if (nested.length > 0) return nested;
+	}
+	const index = indexEntryIn(entry);
+	if (index) return [index];
+	// The sweep inherits the same depth budget: a declared directory reached from
+	// inside a nested resolution may list its own files, but must not descend into
+	// subdirectories again (otherwise a manifest declaring `"./"` deep in the tree
+	// would walk without a bound).
+	return discoverExtensionFiles(entry, allowNestedManifest);
+}
+
+/** `<dir>/index.ts`, else `<dir>/index.js`, else undefined. */
+function indexEntryIn(dir: string): string | undefined {
+	for (const candidate of ["index.ts", "index.js"]) {
+		const entry = path.join(dir, candidate);
+		if (fs.existsSync(entry)) return entry;
+	}
+	return undefined;
+}
+
+/**
+ * Sweep a declared directory the way pi's `collectAutoExtensionEntries` does.
+ *
+ * Same shape as pi, because anything less silently loses extensions:
+ *
+ *   - `.`-prefixed entries and `node_modules` are skipped (pi skips both; a
+ *     dotfile such as `.eslintrc.js` is never an entry point)
+ *   - a `*.ts`/`*.js` file is collected as-is
+ *   - a subdirectory is resolved as a package of its own, which is what makes
+ *     the documented `extensions/<name>/index.ts` layout loadable at all; a
+ *     subdirectory that resolves to nothing contributes nothing
+ *
+ * `allowNestedDirs` is the depth bound. pi stops after one level
+ * (`collectAutoExtensionEntries` → `resolveExtensionEntries` → no further), and
+ * so do we: the top-level sweep may resolve subdirectories, but a directory
+ * reached from inside a nested resolution sweeps files only. That keeps a
+ * mistyped or self-declaring path from becoming an unbounded walk.
+ *
+ * Sorted, so the child's argv is stable between runs and platforms.
+ */
+function discoverExtensionFiles(dir: string, allowNestedDirs: boolean): string[] {
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const files: string[] = [];
+	for (const entry of entries) {
+		if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+		const full = path.join(dir, entry.name);
+		let isFile = entry.isFile();
+		let isDir = entry.isDirectory();
+		if (entry.isSymbolicLink()) {
+			try {
+				const stats = fs.statSync(full);
+				isFile = stats.isFile();
+				isDir = stats.isDirectory();
+			} catch {
+				continue;
+			}
+		}
+		if (isFile) {
+			if (/\.(ts|js)$/.test(entry.name)) files.push(full);
+			continue;
+		}
+		if (isDir && allowNestedDirs) {
+			// `allowNestedManifest: false` is the gate: the nested resolution sweeps
+			// files but never descends into subdirectories itself.
+			files.push(...resolveExtensionEntries(full, false));
+		}
+	}
+	return files.sort();
 }
 
 /**
  * Resolve a package directory to its extension entry points, exactly like pi's
  * own loader: `package.json`'s `pi.extensions` first, then `index.ts`/`index.js`.
  *
+ * Declared entries may themselves be directories (R1-a); those expand into
+ * loadable files, and an entry that expands to nothing is dropped so the caller
+ * never sees a path `pi -e` would refuse. Every returned path is a file.
+ *
  * A directory with neither is not an extension package (a theme pack, a skill
  * bundle) and contributes nothing.
  */
-export function resolveExtensionEntries(dir: string): string[] {
+export function resolveExtensionEntries(dir: string, allowNestedManifest = true): string[] {
 	const manifestPath = path.join(dir, "package.json");
 	try {
 		if (fs.existsSync(manifestPath)) {
@@ -88,21 +250,27 @@ export function resolveExtensionEntries(dir: string): string[] {
 			};
 			const declared = manifest.pi?.extensions;
 			if (Array.isArray(declared)) {
-				const resolved = declared
-					.filter((entry): entry is string => typeof entry === "string" && entry.length > 0)
-					.map((entry) => path.resolve(dir, entry))
-					.filter((entry) => fs.existsSync(entry));
+				// R1-a: directories expand; empty expansions are dropped. Only files
+				// reach the caller, because that is all `-e` can load. Deduped because a
+				// manifest may name both a directory and a file inside it.
+				const resolved: string[] = [];
+				const seen = new Set<string>();
+				for (const entry of declared) {
+					if (typeof entry !== "string" || entry.length === 0) continue;
+					for (const file of expandDeclaredEntry(path.resolve(dir, entry), allowNestedManifest)) {
+						if (seen.has(file)) continue;
+						seen.add(file);
+						resolved.push(file);
+					}
+				}
 				if (resolved.length > 0) return resolved;
 			}
 		}
 	} catch {
 		// Unreadable/invalid manifest: fall through to the index-file convention.
 	}
-	for (const candidate of ["index.ts", "index.js"]) {
-		const entry = path.join(dir, candidate);
-		if (fs.existsSync(entry)) return [entry];
-	}
-	return [];
+	const index = indexEntryIn(dir);
+	return index ? [index] : [];
 }
 
 /** Parse `pi list` output into the package directories it reports. */
@@ -119,42 +287,117 @@ export function parsePiList(output: string): string[] {
 }
 
 /**
- * Ask pi which packages are installed and resolve them to extension files.
+ * Run one `pi list` and resolve it to extension entry paths.
  *
- * Never throws: a host without `pi` on PATH, or a `pi list` failure, degrades to
- * "no discovered extensions" (children still get their explicit list plus the
- * child-guard). Failure to discover must not fail a launch.
+ * Returns `undefined` when discovery itself failed (no `pi` on PATH, non-zero
+ * exit, timeout) so the caller can distinguish "nothing installed" from "could
+ * not ask" — only the latter must stay retryable.
  */
-export async function discoverHostExtensions(env: NodeJS.ProcessEnv = process.env): Promise<string[]> {
-	if (discovered) return discovered;
-	discovery ??= (async () => {
-		let dirs: string[] = [];
-		try {
-			const { stdout } = await execFileAsync("pi", ["list"], {
-				env,
-				timeout: 15_000,
-				maxBuffer: 4 * 1024 * 1024,
-			});
-			dirs = parsePiList(stdout);
-		} catch {
-			dirs = [];
-		}
-		const entries = dirs.flatMap((dir) => resolveExtensionEntries(dir));
-		const seen = new Set<string>();
-		discovered = entries.filter((entry) => {
-			const key = path.resolve(entry);
-			if (seen.has(key)) return false;
-			seen.add(key);
-			return true;
+async function resolveHostExtensions(env: NodeJS.ProcessEnv): Promise<string[] | undefined> {
+	let dirs: string[];
+	try {
+		const { stdout } = await execFileAsync("pi", ["list"], {
+			env,
+			timeout: 15_000,
+			maxBuffer: 4 * 1024 * 1024,
 		});
-		return discovered;
-	})();
-	return discovery;
+		dirs = parsePiList(stdout);
+	} catch {
+		return undefined;
+	}
+	const entries = dirs.flatMap((dir) => resolveExtensionEntries(dir));
+	const seen = new Set<string>();
+	return entries.filter((entry) => {
+		const key = path.resolve(entry);
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+
+/**
+ * How long a FAILED discovery is remembered, in milliseconds.
+ *
+ * A failure cannot be cached as `[]` (F23), but it cannot be re-probed by every
+ * caller either: three warm-up points sit on one spawn (router + rpc backend +
+ * in-process backend), so an always-failing host pays twice per spawn today, and
+ * `pi list` costs 0.3–0.9 s measured (up to its 15 s timeout in the worst case) —
+ * before the memory gate even runs.
+ *
+ * 5 s covers every warm call of the same spawn with a wide margin (they are
+ * tens of milliseconds apart at most) while staying short enough that a
+ * transient failure costs a bounded window, not the process lifetime. Measured
+ * `pi list` latency (0.3–0.9 s) makes 5 s roughly one order of magnitude above a
+ * single probe, i.e. a retry is never more than a few spawns away.
+ */
+export const FAILURE_TTL_MS = 5_000;
+
+/**
+ * Discover the host's extensions once per process and return them.
+ *
+ * Idempotent and concurrency-safe: the first caller runs `pi list`, concurrent
+ * callers await the same in-flight promise, and once resolved every later call
+ * returns the cache without spawning anything.
+ *
+ * Never throws and never rejects: a host without `pi`, or a failing `pi list`,
+ * degrades to `[]` (children still get their explicit list plus the
+ * child-guard). Failure to discover must not fail a launch.
+ *
+ * A FAILED discovery is deliberately not cached as `[]`. The previous shape
+ * cached `[]` permanently, so one transient `pi list` error disabled inheritance
+ * until the process restarted. Instead the failure stamps `failedAt` and calls
+ * inside `FAILURE_TTL_MS` short-circuit to `[]` without a probe — the backoff
+ * that keeps the three warm-up points idempotent (R2-b). Once the stamp ages out,
+ * the next call probes again, so a failure is never a permanent off switch (F23).
+ *
+ * `env` is handed to `execFile` (a caller can point discovery at a specific
+ * PATH); the cache itself is process-wide and does not vary by env.
+ */
+export async function ensureHostExtensions(env: NodeJS.ProcessEnv = process.env): Promise<string[]> {
+	if (store.discovered) return store.discovered;
+	if (store.failedAt !== undefined && Date.now() - store.failedAt < FAILURE_TTL_MS) return [];
+	if (!store.inFlight) {
+		store.inFlight = (async () => {
+			try {
+				const resolved = await resolveHostExtensions(env);
+				if (!resolved) {
+					store.failedAt = Date.now();
+					return [];
+				}
+				store.discovered = resolved;
+				// A success supersedes any earlier failure, so the backoff stamp must not
+				// outlive it — otherwise a later re-probe (after a reset) would inherit an
+				// unrelated window.
+				delete store.failedAt;
+				return resolved;
+			} catch {
+				// Belt and braces: the contract is "never rejects", and a launch must
+				// never fail because the host could not be asked about packages.
+				store.failedAt = Date.now();
+				return [];
+			} finally {
+				// Success caches through `discovered`; failure leaves the `failedAt`
+				// stamp behind (the backoff) plus a cleared in-flight slot, or the
+				// retry could never start.
+				delete store.inFlight;
+			}
+		})();
+	}
+	return store.inFlight;
 }
 
+/**
+ * Historical name for the same resolver; kept for callers that still use it.
+ *
+ * Aliased rather than wrapped so both names are literally one function: a
+ * second `async` wrapper would only add a promise layer and a second identity
+ * for the same cache.
+ */
+export const discoverHostExtensions = ensureHostExtensions;
+
 /** Synchronous read of whatever discovery has already produced. */
 export function discoveredHostExtensions(): string[] | undefined {
-	return discovered;
+	return store.discovered;
 }
 
 /**

package/src/supervisor/inprocess-supervisor.ts

@@ -17,6 +17,7 @@ import {
 	childInheritsExtensions,
 	collectChildExtensions,
 } from "../runs/args.ts";
+import { ensureHostExtensions } from "../runs/extension-inheritance.ts";
 import {
 	ErrorCodes,
 	unknownChildError,
@@ -705,6 +706,20 @@ export class InProcessSupervisor implements LegionSupervisor {
 	}
 
 	async spawnChild(input: SpawnInput): Promise<ChildHandle> {
+		// #280 R1-b: warm host-extension discovery HERE, not only in
+		// `RoutingSupervisor`, because a caller may construct this backend
+		// directly (`new Orchestrator({ supervisor: new RpcSupervisor() })` is the
+		// documented public shape in `api.ts`, and it is `Orchestrator`'s default).
+		// That path bypasses the router entirely, and without this the child's
+		// argv builder would read an empty sync cache and inherit nothing.
+		//
+		// It cannot live in `Orchestrator.launch`: that fast path must not gain an
+		// await before the synchronous admission block
+		// (launch-admission-queue-v1 §13.7 ban 5 / F16).
+		//
+		// Idempotent and never rejects, so the router's own warm call makes this a
+		// map lookup, and a failed `pi list` still leaves a working launch.
+		await ensureHostExtensions();
 		if (input.agent.kind !== "pi") {
 			throw new SubagentError(
 				`InProcessSupervisor only supports pi children (received kind '${input.agent.kind}')`,

package/src/supervisor/routing-supervisor.ts

@@ -16,6 +16,7 @@ import {
 import { InProcessSupervisor, type InProcessSlotEvent } from "./inprocess-supervisor.ts";
 import { RpcSupervisor } from "./rpc-supervisor.ts";
 import { resolveSpawnMode } from "./spawn-mode.ts";
+import { ensureHostExtensions } from "../runs/extension-inheritance.ts";
 import type { UIProxy } from "./ui-proxy.ts";
 import type {
 	ChildHandle,
@@ -127,6 +128,19 @@ export class RoutingSupervisor implements LegionSupervisor {
 
 	async spawnChild(input: SpawnInput): Promise<ChildHandle> {
 		const mode = resolveSpawnMode(input.agent);
+		// #280: warm host-extension discovery before anything is spawned.
+		//
+		// This is the one place that sees BOTH backends and sits on an await chain
+		// already, so every spawn path is covered — the tool execute frame, the
+		// postman timer, the team-restore microtask and the launch-queue pump all
+		// funnel through `Orchestrator.launch` → here. It deliberately does NOT live
+		// in `launch()`: that fast path must not gain an await before the
+		// synchronous admission block (launch-admission-queue-v1 §13.7 ban 5).
+		//
+		// `ensureHostExtensions` is idempotent and never rejects, so a warm cache is
+		// a map lookup and a failed `pi list` leaves the child with the explicit
+		// list plus the guard instead of failing the launch.
+		await ensureHostExtensions();
 		if (mode === "inprocess") {
 			if (input.agent.kind !== "pi") {
 				throw new SubagentError(

package/src/supervisor/rpc-supervisor.ts

@@ -11,6 +11,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { formatChildTask } from "../extension/child-guard.ts";
 import { buildPiArgs, LEGION_IDENTITY_ENV_KEYS } from "../runs/args.ts";
+import { ensureHostExtensions } from "../runs/extension-inheritance.ts";
 import { TEMP_OWNER_FILE, writeOwnerFile } from "../runs/owner.ts";
 import { checkMemoryGate, childMemoryEnv } from "./child-memory.ts";
 import { enrichFailureWithAutoDoctor } from "../extension/auto-doctor.ts";
@@ -228,6 +229,19 @@ export class RpcSupervisor implements LegionSupervisor {
 	}
 
 	async spawnChild(input: SpawnInput): Promise<ChildHandle> {
+		// #280 R1-b: warm host-extension discovery HERE, not only in
+		// `RoutingSupervisor`. `api.ts` documents `new Orchestrator({ supervisor:
+		// new RpcSupervisor(), ... })` and that is also `Orchestrator`'s default,
+		// so this backend is reachable without ever passing through the router —
+		// without this warm-up the child's argv builder reads an empty sync cache
+		// and the whole of #280 stays broken on that public path.
+		//
+		// It deliberately precedes the memory gate: warming is cheap, idempotent
+		// and never rejects, and doing it first keeps the ordering identical for
+		// admitted and refused spawns. It must NOT move into `Orchestrator.launch`
+		// (launch-admission-queue-v1 §13.7 ban 5 / F16: that fast path may not gain
+		// an await before the synchronous admission block).
+		await ensureHostExtensions();
 		// Memory gate (program level): refuse before any process/temp dir exists.
 		const inFlight = [...this.children.values()].filter((child) => child.state === "starting").length;
 		const gate = checkMemoryGate({ name: input.name, inFlight, ...(this.memoryAvailable ? { available: this.memoryAvailable } : {}) });