pi-async 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+本文件记录用户可见变更。格式参考 Keep a Changelog，版本遵循 SemVer。
+
+## 0.2.0 — 2026-10-16
+
+自 0.1.0 起的 16 个提交，主体是 Wave1/Wave2 缺陷修复，附带少量新能力与若干
+**用户可见的行为变更**。升级前请看「Breaking / 行为变更」一节。
+
+### Breaking / 行为变更
+
+- **`async_status` 默认不再返回历史任务**（#22）。0.1.0 默认 `includeHistory !== false`
+  （含历史），现在默认**仅活跃**（running/pending）；需要历史要显式传
+  `includeHistory: true`，且最多返回最近 50 条。不传参的调用方会看到列表变短。
+- **`output_matches` 的正则现在以 `m` 编译**（REV-10）。`^` / `$` 从「整段锚点」变成
+  「行锚点」，多行输出下匹配结果可能变化。
+- **per-task activity id 形状变更**：`pi-async/<taskId>` → `plugin/pi-async/<taskId>`
+  （REV-8）。OSC 7501 / legion viz 侧可见。
+- **`async_logs` 输出文本清洗范围扩大**：从 `stripAnsi` 改为同时剥离裸 C0 控制字符，
+  并用 `truncateUtf8Bytes` 替代按字节 `subarray` 截断 —— 含 BEL/BS/FF 或多字节字符时
+  返回文本与 0.1.0 不同。
+- **新增校验会拒绝原先被接受的调用**：
+  - `json_path_exists.path` 必须以 `$` 开头（新增 `pattern: "^\\$"`）
+  - `async_run` 在非 sync 模式传 `timeoutMs`、非 delayed 模式传 `delayMs` 会被拒（#42/#45）
+  - `output_matches` 拒绝嵌套量词（ReDoS 防护），匹配窗口限制 64 KiB
+
+### Added
+
+- 新增环境变量 `PI_ASYNC_RETENTION_MS`（默认 7 天）与 `PI_ASYNC_RETENTION_COUNT`
+  （默认 100），用于按「时间 ∪ 数量」并集保留终态任务产物（#25）。
+- `async_kill` 返回新增 `killKind`、`alreadyTerminal`、`warning`；`isError` 改为条件值（#33/#6）。
+- 通知 XML 新增 `kill-kind` / `failure-kind` / `summary-truncated` 属性（#37）。
+- `async_wait` 结果项新增可选 `killKind` / `failureKind`；`WaitOutcome` 增加混合超时态。
+- 内部新增 `src/core/duration.ts`、`src/tui/width.ts`、`src/core/env.ts` 收敛重复实现。
+
+### Fixed
+
+- TUI：`displayWidth` / `truncateToWidth` 按显示单元截断（#7）；Esc 层级、elapsed、
+  pending、footer、border、theme.fg 修复（Wave1）；`PI_ASYNC_DOCK_SHORTCUT=off`
+  现在真正生效（#30）。
+- 核心：watch ReDoS 与匹配窗口、reload 前代 registry 关停、UTF-8 截断、C0/XML 非法字符
+  （Wave2）；sidecar/zombie 进程组清理、`wait` 消费（Wave1）；空 env 不再被解析成 0（#21）。
+- 通知：killKind / failureKind / summaryTruncated 接线补全（#37）。
+- 仓库：移除误提交的 62MB `docs/core` ELF dump（#50），`.gitignore` 收紧为 `/core`
+  以免误伤 `src/core/`。
+
+### 未变更
+
+- 5 个工具（`async_run` / `async_wait` / `async_logs` / `async_status` / `async_kill`）
+  的注册面与参数名集合不变；没有删除任何工具、参数或环境变量。
+
+## 0.1.0 — 2026-10-15
+
+首个发布版本。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-async contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# pi-async
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pi extension for running shell commands asynchronously with bounded output capture, completion notifications, and a task panel.
+
+## Install
+
+Install the package from a local path with Pi's package manager:
+
+```text
+pi install /path/to/pi-async
+```
+
+For development, load the extension directly (for example from this checkout):
+
+```sh
+pi -e ./extensions/index.ts
+```
+
+The extension uses the Pi host's project working directory to store task metadata and captured output in `.pi/async/<session-id>-<pid>/`.
+
+## Tools and commands
+
+The extension registers five tools:
+
+| Tool | Purpose |
+|---|---|
+| `async_run` | Start a background, delayed, or synchronous shell command. |
+| `async_wait` | Wait for task completion or return a `notReady` result on timeout. |
+| `async_logs` | Read bounded, ANSI-stripped captured output. |
+| `async_status` | List tasks and their current state. |
+| `async_kill` | Terminate a task and its process group. |
+
+| Command / key | Action |
+|---|---|
+| `/async` | Open the task panel. |
+| `/async-clear` | Clear completed-task history badges. |
+| `Ctrl+Alt+A` | Open the task panel (when the host allows the shortcut; `/async` remains available as fallback). |
+| `↑` / `↓` / `j` / `k` | Select tasks; in task details, scroll output. |
+| `Enter` | Open selected task details. |
+| `h` | Toggle history in the task list. |
+| `k` | Kill a running task (press again to confirm). |
+| `R` | Rerun the selected task command. |
+| `c` | Copy the captured output file path. |
+| `Esc` / `q` | Return from details / close the panel. |
+
+The panel and rail are only enabled in the main Pi TUI session; RPC, print, and child contexts retain the tool surface without TUI entrypoints.
+
+## Configuration
+
+| Environment variable | Default | Description |
+|---|---:|---|
+| `PI_ASYNC_MAX_OUTPUT_BYTES` | `20971520` (20 MiB) | Maximum captured output per task; exceeding it terminates the task with `output_cap`. |
+| `PI_ASYNC_MAX_TASKS` | `32` | Maximum concurrent running and pending tasks. |
+| `PI_ASYNC_HEARTBEAT_MS` | `60000` | Settle-guard heartbeat interval in milliseconds. |
+| `PI_ASYNC_DOCK_SHORTCUT` | `ctrl+alt+a` | Configured panel shortcut; the command remains available as fallback. |
+| `PI_ASYNC_RETENTION_MS` | `604800000` (7 days) | How long terminal-task artifacts are retained; union with `RETENTION_COUNT`. |
+| `PI_ASYNC_RETENTION_COUNT` | `100` | Max newest terminal tasks kept per dataDir; union with `RETENTION_MS`. |
+| `PI_ASYNC_RAIL_LINGER_MS` | `30000` | How long completed/failed/killed tasks stay on the rail before disappearing. |
+
+## Legion child sessions
+
+In a legion child session, collect task results with `async_wait` before returning a verdict. The settle guard reminds the agent about uncollected tasks, but the completion notification may not be delivered across turns until the upstream busy-hold contract lands. See [CONTRACT.md §6](docs/CONTRACT.md#6-唤醒链路与-legion-兼容冻结) for the frozen notification and collection requirements.
+
+## Known limitations
+
+- Crash-durability is not guaranteed: metadata is atomically replaced, but captured output is not fsynced. After a crash, orphaned tasks and delayed tasks are not automatically restored; recovery is limited to `/reload` in the same running process.
+- Busy-hold behavior depends on upstream pi-legion issue [#156](https://github.com/zzjcool/pi-legion/issues/156); the extension does not patch Pi or legion.
+- TUI rail and panel are available only in the main TUI session, not in RPC/print/child contexts.
+- `pi --print` notification delivery requires an available configured provider. If no provider is available, end-to-end print-mode verification remains pending a user run.
+
+## Development checks
+
+```sh
+npm run typecheck
+npm test
+```
+
+## Container QA
+
+Run the plugin inside a clean container against the local model endpoint:
+
+```sh
+cd test/docker
+make run     # start container + drop into pi (default: workbuddy/hy4-preview-ioa)
+make smoke   # L1 model reachable -> L2 tools advertised -> L3 a tool really runs
+make qa-up && make qa-tui SCENARIO=s1   # deterministic TUI scenario
+```
+
+`make run` reuses an already-running container, so it never tears down your session.
+
+The container QA setup itself lives in `test/docker/` (not shipped in the npm
+package). See its README in the repository for the two containers, the required
+mounts, and why L3 must not be skipped.
+
+## Known upstream issue (print mode)
+
+`pi --print` + background task completing **after** the agent settles: the wake happens but the woken
+run's `turn_end` boundary fails with `Extension error (<boundary>): turn_end could not resolve the
+persisted assistant entry ID` (pi 1.2.0 core, reproduced identically with pi-background-tasks —
+upstream issue https://github.com/earendil-works/pi/issues/11001). **RPC mode (legion subagents) and
+turn-internal waits are unaffected.**

package/docs/CONTRACT.md

@@ -0,0 +1,308 @@
+# pi-async 冻结契约 v1
+
+状态：**FROZEN**（2026-10-15） | 仓库：/root/code/pi-async | Node ≥ 22.19, pi ≥ 1.2.0（TUI）
+修订规则：任何字段/语义变更必须走 REV 条目登记原因，worker 不得自行解释矛盾。
+
+## 0. 定位与范围
+
+pi-async 是 pi 的异步任务运行时扩展：任务注册表 + 四种任务模式 + 完成唤醒 +
+主会话 TUI（轨道图 + 全屏面板）+ OSC 7501 busy 契约对齐（zzjcool/pi-legion#156）。
+
+**刻意不做**（禁止 worker 越界）：
+- 不做 delegate/attested/Fusion 子 agent（pi-background-tasks 已覆盖，我们只管 shell 任务）
+- 不改 pi-legion / pi 本体（busy-hold 走上游 issue #156 + 补充评论，我们不 fork）
+- 不做 SSH/remote 执行、不做 tmux/PTY attach（后续版本）
+- 不做 MCP server 化
+
+## 1. 目录与文件布局
+
+```
+pi-async/
+├── package.json            # name: pi-async, type: module, keywords 含 pi-package/pi-extension
+├── tsconfig.json
+├── extensions/index.ts     # 唯一扩展入口（package.json "pi".extensions 指向）
+├── src/
+│   ├── core/
+│   │   ├── registry.ts     # TaskRegistry：任务生命周期、终态、通知
+│   │   ├── task.ts         # Task 类型、状态机、snapshot
+│   │   ├── spawn.ts        # detached spawn + 进程组 kill 升级链
+│   │   ├── output.ts       # 输出捕获、tail 读取、ANSI 剥离
+│   │   ├── watch.ts        # 轮询 + 条件匹配引擎
+│   │   ├── notify.ts       # 完成通知/唤醒、抑制闩（每任务一条，不合并）
+│   │   └── bus.ts          # 预留 eventbus + OSC activity 上报
+│   ├── tools/
+│   │   └── index.ts        # 5 个工具的注册与 schema
+│   ├── tui/
+│   │   ├── rail.ts         # 任务轨道图 widget（≤10 行）
+│   │   ├── panel.ts        # 全屏面板（列表+详情）
+│   │   └── status.ts       # footer setStatus + setActivity
+│   └── guard/
+│       └── settle-guard.ts # agent_before_settle 守卫 + 心跳
+├── vendor/reference/       # 已就位（只读参考，不编译）
+└── docs/
+```
+
+运行时数据（不进仓库）：`.pi/async/<session-id>-<pid>/<task-id>.output` + `<task-id>.json`（atomic write）。
+
+## 2. 任务状态机（冻结）
+
+```
+pending --(delay 到期/spawn 成功)--> running --┬-- exit 0 --> completed
+                                             ├-- exit ≠0 --> failed
+                                             ├-- timeout/output_cap --> failed (kind 标注)
+                                             └-- kill --> killed
+```
+
+- 状态词汇：`pending | running | completed | failed | killed`；terminal = 后三者。
+- KillKind：`user | timeout | output_cap | shutdown | watch_failure`（进程被主动杀掉的原因）。
+- FailureKind：`lost | blind_exhausted | watch_timeout`（非「退出码失败」、需与 KillKind 并列区分的失败原因）。
+  - `lost`：reload 发现 pid 已死（§10）。
+  - `blind_exhausted`：watch blind_checks 耗尽。
+  - `watch_timeout`：watch `timeoutMs` 到期。
+- **双字段、不统一 reason（REV-11）**：KillKind 答「谁杀的/为何杀进程」；FailureKind 答「任务为何 failed」。
+  禁止发明第三套 `reason` 枚举把两者揉扁——通知与投影字段各自透传已有字段即可。
+- delayed 任务在 pending 期可 cancel（→ killed, kind=user）。
+- `notified` 持久闩（写进 metadata，reload 不重置），单次投递；发送失败回滚重试 ≤3 次。
+
+## 3. 任务模式与启动参数（async_run 工具，冻结）
+
+```ts
+async_run({
+  command: string,                    // 必填
+  name?: string,                      // 展示名；缺省从 command 派生（≤48 chars）
+  mode: "background" | "sync" | "delayed",   // 默认 background
+  // ── delayed ──
+  delayMs?: number,                   // mode=delayed 必填；pending 到期启动
+  // ── sync ──
+  timeoutMs: number,                  // mode=sync 必填（schema enforce）；
+                                      // 到点：onTimeout="promote" → 转 background 继续；
+                                      // onTimeout="abort" → Esc 语义，等待中断任务保留
+  onTimeout?: "promote" | "abort",    // 默认 promote
+  // ── 通用 ──
+  taskTimeoutMs?: number,             // 任务自身寿命；缺省 = 无限（watch 必填除外，见 §4）
+  notifyOnCompletion?: boolean,       // 默认 true
+  triggerOnCompletion?: boolean,      // 默认 true：完成 sendMessage({triggerTurn:true}) 唤醒
+  env?: Record<string, string>,       // 追加到 spawn env
+  watch?: WatchSpec,                  // 见 §4；模式仅 background/delayed
+})
+```
+
+**返回（receipt）**：`{ taskId, name, status, mode, outputHint }`；sync 模式返回
+`{ ...receipt, exitCode, outputTail }`。所有任务**同步启动**：spawn 成功即返回 `running`；
+spawn 失败立即抛错，无重试等待。admission 检查为 closed / maxTasks / 空命令，均同步完成。
+shutdown 先 drain 再退出。
+（**REV-6 裁决**：原「≤30s admission 预检」从未实现且与同步 spawn 设计冲突，改为描述现状；见 #29。）
+
+**工具集（5 个）**：`async_run` / `async_wait` / `async_logs` / `async_status` / `async_kill`。
+命令面：`/async`（开面板）、`/async-clear`（清历史徽章）。
+
+## 4. WatchSpec（照抄 better-bg 条件系统，冻结）
+
+```ts
+interface WatchSpec {
+  intervalMs: number;                 // 默认 30_000，min 1_000
+  timeoutMs: number;                  // watch 必填：watch 期限（schema enforce）
+  success_when: Condition[];          // 任一命中 → 任务完成语义（不干预进程，见下）
+  failure_when: Condition[];          // 任一命中 → kill(kind=watch_failure)
+  blind_checks?: number;              // 默认 3：连续 N 次「检查基础设施失败」(readOutput 抛错等)
+                                      // → failed；「尚未可判定」为 pending，不累计（见下方 REV-2）
+}
+type Condition =
+  | { type: "exit_code"; equals: number }
+  | { type: "stdout_contains"; value: string }
+  | { type: "stderr_contains"; value: string }
+  | { type: "json_path_exists"; path: string }        // 必须以 $ 开头，如 $.a.b[0]；启动前校验；tool schema 含 pattern/description（#12）
+  | { type: "output_matches"; regex: string }         // 合并输出流匹配（设备码等）；编译带 m（^/$ 按行）
+```
+
+- `success_when` 命中 → **不杀进程**：任务标 completed，通知带命中详情；进程按 taskTimeoutMs/kill 自然管理。
+  （区别于 better-bg 的 check 命令模式：我们 watch 的是**已存在任务**的输出/退出。）
+- 条件在 async_run 时**启动前校验**，非法 regex/JSON path 直接拒绝（不产生 pending 任务）。
+- **blind_checks 语义（REV-2 澄清）**：仅计「检查基础设施失败」（readOutput 抛错等）；
+  「尚未可判定」（exit_code 未退出 / json_path 输出尚非 JSON）为 **pending 态，不累计 blind、照常
+  继续轮询**。两者是不同语义，禁止合并。条件持续 pending 时**不**触发 blind 兜底，仅由
+  `timeoutMs` 结束 watch（WatchSpec 字段注释已与本条对齐，见 #27）。
+- promptGuidelines（写进工具 description）：check 不要 `|| true` 自吞错误；未知态映射失败；
+  结构化输出优先 jq -e；`output_matches` 的 regex 须加锚定防止过早匹配（编译固定带 `m`，
+  `^`/`$` 按行边界，故 `^READY$` 可命中多行输出中的某一行）。
+- **watch 失败性终态的进程处置（REV-4 裁决）**：`failure_when` 命中、blind 耗尽、watch timeout
+  三条 watch 失败路径在 finalize 任务的同时**必须 kill 进程组**（与 `failure_when → killed(watch_failure)`
+  同语义）；仅 `success_when`（D4）不干预进程。杀失败时响亮上报（kill 链已有 catch），
+  绝不允许「终态任务 + 活进程」残留导致 async_kill 静默不杀或 shutdown 挂起。
+  - **终态标注（REV-11）**：`failure_when` → `killed` + `killKind=watch_failure`；blind 耗尽 /
+    watch timeout → `failed` + `killKind=watch_failure` + 对应 `failureKind`
+    （`blind_exhausted` / `watch_timeout`）。三条都杀进程，用 status+failureKind 区分语义。
+- **REV-10 裁决（#48）**：`output_matches` 以 `new RegExp(regex, "m")` 编译（validate 与求值同）。
+  契约原先要求锚定（`^READY$`）防止过早匹配，但无 `m` 时 `^`/`$` 只锚整段输出，多行流上锚定
+  永不相交。加 `m` 使锚定与意图一致；整段匹配请用不含 `^`/`$` 的模式或显式 `\A`/`\z` 等价写法。
+
+## 5. async_wait（唤醒原语，冻结）
+
+```ts
+async_wait({ taskIds: string[], timeoutMs: number })   // timeoutMs 必填（schema enforce）
+// 返回三态（REV-7）：
+// → 全终态：{ results: Array<{taskId, status, exitCode?, outputTail}> }
+// → 超时且无已完成：{ notReady: Array<{taskId, status: "running"|"pending", elapsedMs}> }（不杀任务）
+// → 混合超时：{ results, notReady }（已完成走 waitResult/consume，抑制通知 chatter；未就绪不杀）
+```
+
+- 事件驱动：await 内部 waiter（任务 finalize 时 resolve），**禁止 sleep 轮询**（patty 教训）。
+- 支持 AbortSignal（Esc）；中断等待不中断任务。
+- 消费即抑制：async_wait 取回结果的任务，完成通知被 `outputConsumed` 闩抑制（防 chatter）。
+- **REV-7 裁决（#43）**：原契约只写「全终态 → results」与「超时 → notReady」两极，导致混合超时
+  路径丢弃已完成结果、且无法对已完成侧置 `outputConsumed`（通知抑制失效）。正式登记超集三态：
+  判据仍是「有 notReady ⇒ 超时分支」；`results` 可选并存。实现见 #56，本 REV 只改契约。
+
+## 6. 唤醒链路与 legion 兼容（冻结）
+
+| 环境 | triggerOnCompletion 行为 |
+|---|---|
+| 主会话（TUI/RPC/print） | `pi.sendMessage({customType:"async-task-notification"}, {deliverAs:"followUp", triggerTurn:true})`；idle → 立即新 turn；busy → followUp 队列 |
+| legion child，turn 内 | 同上 |
+| legion child，跨 turn | **hold 模式**：settle 前守卫上报 busy（见 §7）；上游 #156 busy-hold 落地前，通知可能无法送达——**契约要求 agent 在 legion 环境用 async_wait 收割后再报 verdict**（守卫强制提醒，最多 3 次） |
+
+- 环境检测：`PI_LEGION_NODE_ID` 存在 → legion child 环境，settle 守卫默认开启。
+- 通知 XML：`<async-task-notification>` + task-id/name/status/exit-code/**kill-kind**/**failure-kind**/output-file/summary/**summary-truncated**/guidance
+  （guidance 仅 failed 带，completed 纯信息——patty chatter 教训）。
+  - `kill-kind` / `failure-kind`：有值才输出（与 snapshot 同名语义）；模型据此区分非零退出 / output_cap / watch 失败 / lost，无需先 round-trip `async_status`（#37）。
+  - `summary-truncated`：summary 因 output_cap 或通知 tail 上限被截断时输出 `true`，避免把截断前缀误读为完整输出。
+  - **失败原因矩阵（REV-11）**：
+
+    | 原因 | status | killKind | failureKind | 通知要点 |
+    |---|---|---|---|---|
+    | 非零退出 | failed | — | — | exit-code |
+    | output cap | failed | output_cap | — | kill-kind + 常带 summary-truncated |
+    | failure_when 命中 | killed | watch_failure | — | kill-kind（status=killed 已区分） |
+    | blind 耗尽 | failed | watch_failure | blind_exhausted | kill-kind + failure-kind |
+    | watch timeout | failed | watch_failure | watch_timeout | kill-kind + failure-kind |
+    | reload lost | failed | — | lost | failure-kind |
+- **REV-9 裁决（#47）**：v1 **每任务一条**完成通知（各带己方 summary/output-file）；**不合并**。
+  模块图原先写「合并」为假承诺——同时完成会各发一条并各可能 `triggerTurn`。防 chatter 靠
+  `outputConsumed` 闩与 failed-only guidance（D5），不靠跨任务 debounce。真合并需改多任务 XML
+  schema + 窗宽策略，另开后续 REV（可派 Drift）。
+- 心跳：有 running/pending 任务期间，每 60s `pi.appendEntry` 一条 heartbeat（触发 legion
+  `collectArtifactGrowing` 宽限续期）；session jsonl 增长由守卫的提醒消息自然产生，心跳为兜底。
+
+## 7. Settle 守卫 + OSC busy 上报（冻结，对齐 #156 插件契约）
+
+- `agent_before_settle` 时存在未终态任务 → append 一条「N 个异步任务未收割（taskId 列表），先
+  async_wait/async_status 处理再报 verdict」+ `continue: true`；**每 run 重新武装，累计 ≤3 次**，
+  超过后放行但 verdict 提示里保留未决清单。
+- OSC busy 上报（feature-detect，无 API 则跳过）：
+  - `ui.setActivity("pi-async", { message: "N async tasks" })`，全清时 `undefined`
+  - 每任务 `id=plugin/pi-async/<task-id>`，raise/clear 与任务状态同步
+  - **REV-8 裁决（#26）**：实现必须带 `plugin/` 前缀（对齐 legion
+    `docs/contracts/osc-busy-plugin.md` 的 `plugin/<name>/…`）；聚合源仍为 `pi-async`（§7 冻结）。
+    此前实现漏前缀会导致宿主按 `plugin/` 路由时 per-task activity 静默无效。
+  - **禁止 printf OSC**；尊重 `PI_PROGRAM_STATUS`
+  - 上报时机：任务启动、终态、以及 `agent_before_settle`（闭合 retire 竞态窗口的关键，见 #156 补充评论）
+- RPC（legion child）内：setActivity 依赖 legion `extension_activity` 转发（#156 落地后生效），
+  未落地时静默降级，不影响工具面。
+
+## 8. TUI（冻结，仅主会话）
+
+- guard：所有 TUI 路径 `ctx.mode === "tui"`（hasUI 陷阱）；widget/面板/shortcut 全部跳过 rpc/json/print。
+- **轨道图 widget**（`setWidget("pi-async-rail", factory, {placement:"aboveEditor"})`）：
+  ≤10 行；每行一个 live 任务 `▶ name · state · elapsed`（running=类型色 / completed=settled 色 /
+  failed=error / killed=dim；配色走 legion palette 延迟解析 + OKLab 撞色检测）；wheel 滚动；
+  press→latch→click 命中任务 → 打开详情。空闲无任务时不渲染。
+- **footer**：`setStatus("pi-async", " N running · M done ")`。
+- **全屏面板**（`/async` 或 `Ctrl+Alt+A`）：`ctx.ui.custom({overlay:true, overlayOptions:
+  {width:"100%", maxHeight:"100%", anchor:"top-left", row:0, col:0}})` 自绘 mask+frame
+  （legion live-overlay 模式）；左列任务列表（含历史，`h` 切换），点击/Enter 进详情：
+  identity/status/elapsed/command/metadata + 输出 tail（128KiB UI 缓冲，12 行跟随滚动，上滚暂停）；
+  键位 `k` kill（二次确认）/`R` rerun/`c` 复制输出路径/`Esc q` 关闭。
+- **running 任务在列表直接显示最新输出行**（footer pill 模式，ANSI 剥离）——设备码场景用户无需
+  agent 中转即可看到输出。
+- shortcut 注册冲突处理：被保留键位占用则回退 `/async` 命令，不硬抢。
+- **早期输出 peek**：`async_logs` 对 running 任务即时可读；`async_run` 返回的 receipt 带
+  `outputHint` 提示 agent 设备码等早期输出可直接 peek。
+
+## 9. 输出与预算（冻结）
+
+- 写盘 cap：默认 20 MiB（`PI_ASYNC_MAX_OUTPUT_BYTES`），超限 → kill(kind=output_cap) → failed。
+- 模型读取：`async_logs { taskId, maxBytes≤50KiB, tail=true }`，truncated 带全量路径提示（`fullPath` 有效至被 §10 retention prune）。
+- ANSI/CSI/OSC 剥离：`async_logs` 返回与 TUI 显示前必须剥离（安全项，防输出注入转义序列）。
+- sync 返回 outputTail ≤ 8 KiB / 200 行（whichever first）。
+
+## 10. 杀伤与清理（冻结）
+
+- detached 进程组 spawn（POSIX）；kill：SIGTERM → 3s grace → 组 SIGKILL → 有界探测；
+  无法证明死亡 → 响亮报错「Descendant processes may have leaked」。
+- `session_shutdown`：幂等清理（admission close + drain + 全任务 kill(kind=shutdown)）；
+  **不承诺 crash-durability**（metadata 原子写，output 不 fsync）。
+- reload：registry 重建后扫描 `.pi/async/<session-id>-*`，running 且 pid 已死 → 标 failed(lost)；
+  delayed pending → 恢复计时（reload 保留）；**切换 session 不迁移**（旧目录只读留档）。
+  **REV-5 裁决（F3）**：reload 恢复仅限同进程存活期内的 /reload（dataDir 按进程固定
+  `<session-id>-<pid>`）；跨 pid 崩溃遗留目录只读留档、不恢复，崩溃后遗留的 pending 延迟任务
+  不会自动续跑。理由：跨 pid 收养需处理写入归属与幂等重建，与 v1 不承诺 crash-durability 的
+  定位一致。README 已知限制同步标注。
+- **磁盘产物 retention（#25）**：每个 dataDir 内，终态任务的 `.json` / `.output` 按 age+count
+  并集策略 prune（启动 `reloadFromDisk` 末尾跑一次；每次 finalize 后再轻量触发）。
+  - 保留并集：按 `finishedAt ?? createdAt` 降序的最新 `PI_ASYNC_RETENTION_COUNT` 个终态任务，
+    **或** 年龄仍小于 `PI_ASYNC_RETENTION_MS` 的终态任务；其余终态任务删除产物并从内存移除。
+  - 非终态（running/pending）永不 prune。
+  - `async_logs` 返回的 `fullPath` **有效至被 prune**（过期后文件可能已删；缺文件时
+    `logs()` 仍安全返回空文本，不抛错）。措辞待 Loom 确认是否需在工具面增加 `missing` 标志。
+  - 跨 session 目录（`<session-id>-<pid>`）的整目录回收不在本条范围（仍只读留档）。
+
+## 11. 配置与环境变量
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `PI_ASYNC_MAX_OUTPUT_BYTES` | 20 MiB | 写盘 cap |
+| `PI_ASYNC_MAX_TASKS` | 32 | 注册表上限，超了拒绝新任务 |
+| `PI_ASYNC_HEARTBEAT_MS` | 60_000 | settle 守卫心跳 |
+| `PI_ASYNC_DOCK_SHORTCUT` | "ctrl+alt+a" | 可 off |
+| `PI_ASYNC_RETENTION_MS` | 604_800_000（7 天） | 终态任务产物保留时长；与 COUNT 取并集 |
+| `PI_ASYNC_RETENTION_COUNT` | 100 | 每个 dataDir 最多保留的「最新」终态任务数；与 MS 取并集 |
+
+## 12. 工程约束
+
+- peerDependencies：`@earendil-works/pi-coding-agent`、`@earendil-works/pi-tui`（**不进 dependencies**，
+  jiti 虚拟模块映射要求）。
+- 语言 TS + node:test；验证命令：`npm run typecheck` && `npm test`（worker verify 门禁用）。
+- vendor/reference 不编译不 import，只作参考。
+- MIT License；legion viz 整块复用处保留 attribution 注释。
+
+## 13. D 编号决策（已定，reviewer 对照用）
+
+| # | 决策 |
+|---|---|
+| D1 | 不做子 agent 委派（delegate/attested/Fusion），只做 shell 任务运行时 |
+| D2 | sync 模式 timeout 必填，默认 promote 而非报错（逃生口，对齐社区惯例） |
+| D3 | async_wait timeout 必填；返回 notReady 不杀任务 |
+| D4 | success_when 命中不杀进程（completed 是观察结论，进程归 taskTimeout/kill 管理） |
+| D5 | 通知 completed 纯信息、failed 才带 guidance；outputConsumed 闩防 chatter |
+| D6 | TUI 仅主会话；subagent 自动退化纯工具面（mode guard） |
+| D7 | OSC busy 上报 feature-detect + settle 前上报闭合竞态（#156 契约）；未落地静默降级 |
+| D8 | 不改 legion/pi 本体；busy-hold 走上游（#156 + 补充评论已发） |
+| D9 | delayed：reload 恢复计时，切 session 不迁移 |
+| D10 | settle 守卫每 run 重武装、累计 ≤3 次，超限放行但保留未决清单提示 |
+
+## 14. 验收清单（verify 门禁）
+
+1. `npm run typecheck` && `npm test` 全绿
+2. background 任务：启动→立即 receipt→完成通知唤醒（print/RPC 模式实测：`pi --print` 会话收到
+   `<async-task-notification>` 并继续 turn）
+3. sync：短命令阻塞返回 exitCode；长命令 timeoutMs 到点 promote 转 background，任务不死
+4. delayed：delayMs 后启动；pending 期 cancel；reload 后恢复
+5. watch：stdout_contains/output_matches 命中 completed（含多行上 `^READY$` 因 m 命中）；
+   failure_when 命中 killed(watch_failure)；非法 regex 启动前拒绝
+6. async_wait：多任务等待全部终态；timeout 返回 notReady 且任务存活；混合超时同时含 results+notReady（已完成侧已 consume）；Esc 中断不杀任务
+7. 输出安全：注入 ANSI 转义的任务输出，async_logs 返回已剥离
+8. kill：进程组全灭（子进程不残留）；20MiB 超限 kill(output_cap)
+9. settle 守卫：有未决任务时 agent_before_settle 注入提醒并 continue；3 次后放行
+10. TUI（人工）：widget 轨道图渲染 + 点击进面板详情 + 输出 tail 跟随；RPC 下无 TUI 路径执行
+
+## 15. 加固层（2026-10-15 事故后追加）
+
+- **factory API 契约测试**：pi 1.2.0 的 factory-time ExtensionAPI **没有** `mode`/`ui`/`cwd`（探针实测，
+  仅 registerTool/on/sendMessage/appendEntry/sessionManager 等）。TUI 绑定只能从事件 ctx
+  （`pi.on(event, (event, ctx) => ...)`）获取。`tests/i-factory-contract.test.ts` 固化该形状：
+  mock 的 factory pi **禁止**发明真实宿主没有的字段（此前两起生产事故均源于 mock 幻觉字段）。
+- **工具返回值契约**：pi 不自动包装扩展工具返回值；全部 execute 必须经 `toolResult()` 包装成
+  `{content:[{type:"text"}], details, isError}`（TUI getTextOutput 直接 `result.content.filter`）。
+  `tests/a-tool-result-contract.test.ts` 逐工具断言。
+- **rail 终态滞留**：completed/failed/killed 任务在轨道图上保留 `PI_ASYNC_RAIL_LINGER_MS`
+  （默认 30s）供用户看到结果，之后自动消失；running/pending 恒显示；全空闲渲染空（§8）。

package/extensions/index.ts

@@ -0,0 +1,138 @@
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { clearTaskActivity, raiseTaskActivity, reportActivity } from "../src/core/bus.ts";
+import { sendCompletionNotification } from "../src/core/notify.ts";
+import { TaskRegistry } from "../src/core/registry.ts";
+import { SettleGuard } from "../src/guard/settle-guard.ts";
+import { registerTools } from "../src/tools/index.ts";
+import { registerRail } from "../src/tui/rail.ts";
+import { disposeStatus, initStatus } from "../src/tui/status.ts";
+import { registerPanelCommands } from "../src/tui/panel.ts";
+import { bindTuiHost } from "../src/tui/host.ts";
+import { isTerminal } from "../src/core/task.ts";
+
+export type PiCtx = ExtensionAPI;
+
+type RuntimeContext = PiCtx & {
+  cwd?: string;
+  pid?: number;
+  sessionId?: string;
+  getSessionId?: () => string | undefined;
+  sessionManager?: { getSessionId?: () => string | undefined };
+  mode?: string;
+  on?: (event: string, handler: (...args: unknown[]) => unknown) => unknown;
+  registerTool?: (...args: unknown[]) => unknown;
+};
+
+function registryDataDir(pi: PiCtx): string {
+  const context = pi as RuntimeContext;
+  const pid = Number.isInteger(context.pid) && (context.pid ?? 0) > 0 ? context.pid ?? process.pid : process.pid;
+  const sessionId = context.sessionManager?.getSessionId?.() ?? context.getSessionId?.() ?? context.sessionId;
+  const safeSessionId = (sessionId || String(process.pid)).replace(/[^\w.-]/g, "_");
+  const cwd = typeof context.cwd === "string" && context.cwd.length > 0 ? context.cwd : process.cwd();
+  return join(cwd, ".pi", "async", `${safeSessionId}-${pid}`);
+}
+
+/** Previous init generation; /reload re-runs init without session_shutdown (#44). */
+let activeRegistry: TaskRegistry | undefined;
+let activeDisposeTui: (() => void) | undefined;
+
+/** Wire the task runtime to the host API, degrading optional Pi features gracefully. */
+export async function init(pi: PiCtx): Promise<void> {
+  // Reload replaces the extension runtime; retire the previous generation first so
+  // its processes, watch loops, and timers are released (pi docs: cleanup must be
+  // idempotent across reload / session replacement / exit).
+  if (activeRegistry) {
+    try {
+      activeDisposeTui?.();
+    } catch { /* best effort */ }
+    activeDisposeTui = undefined;
+    try {
+      await activeRegistry.shutdown();
+    } catch (error) {
+      console.error("pi-async: previous registry shutdown during reload failed", error);
+    }
+    activeRegistry = undefined;
+  }
+  const registry = new TaskRegistry({ dataDir: registryDataDir(pi) });
+  activeRegistry = registry;
+  // NOTE: pi's factory-time ExtensionAPI exposes no `mode`/`ui` — those live on
+  // event-handler contexts (pi.on("session_start", (event, ctx) => ...)). TUI
+  // registration must therefore bind lazily from the first event context.
+  let tui = false;
+  const bindTui = (ctx: unknown): void => {
+    if (!bindTuiHost(ctx)) return;
+    tui = true;
+    initStatus(pi, registry);
+    registerRail(pi, registry);
+    registerPanelCommands(pi, registry);
+  };
+
+  registry.setEvents({
+    onFinalize: (snapshot) => {
+      clearTaskActivity(pi, snapshot.taskId);
+      reportActivity(pi, registry.activeCount());
+      if (tui) initStatus(pi, registry);
+      if (snapshot.metadata.notifyOnCompletion === false) return;
+      const outputFile = String(snapshot.metadata.outputFile ?? "");
+      const logSlice = registry.logs(snapshot.taskId, { maxBytes: 8192, tail: true });
+      const outputTail = logSlice.text;
+      const guidance = snapshot.status === "failed" ? `Inspect task output with async_logs (taskId: ${snapshot.taskId}).` : undefined;
+      const summaryTruncated = snapshot.metadata.capped === true || logSlice.truncated;
+      void sendCompletionNotification(pi, registry, {
+        taskId: snapshot.taskId,
+        name: snapshot.name,
+        status: snapshot.status,
+        ...(snapshot.exitCode === undefined ? {} : { exitCode: snapshot.exitCode }),
+        outputFile,
+        ...(outputTail ? { summary: outputTail } : {}),
+        ...(guidance ? { guidance } : {}),
+        ...(snapshot.killKind ? { killKind: snapshot.killKind } : {}),
+        ...(snapshot.failureKind ? { failureKind: snapshot.failureKind } : {}),
+        ...(summaryTruncated ? { summaryTruncated: true } : {}),
+      }, { triggerTurn: snapshot.metadata.triggerOnCompletion !== false })
+        .catch((error: unknown) => console.error(`pi-async: completion notification failed for ${snapshot.taskId}`, error));
+    },
+    onStateChange: (snapshot) => {
+      const active = registry.activeCount();
+      reportActivity(pi, active);
+      if (isTerminal(snapshot.status)) clearTaskActivity(pi, snapshot.taskId);
+      else raiseTaskActivity(pi, snapshot.taskId);
+      if (tui) initStatus(pi, registry);
+    },
+  });
+
+  try {
+    await registry.reloadFromDisk();
+  } catch (error) {
+    console.error("pi-async: failed to reload task state; continuing with an empty registry", error);
+  }
+
+  const context = pi as RuntimeContext;
+  if (typeof context.registerTool === "function") registerTools(pi, registry);
+  // Bind TUI surfaces from the first event context (factory API has no mode/ui).
+  if (typeof context.on === "function") {
+    context.on("session_start", (_event: unknown, ctx: unknown) => bindTui(ctx));
+    context.on("message_start", (_event: unknown, ctx: unknown) => bindTui(ctx));
+  }
+  if (typeof context.on === "function") new SettleGuard(pi, registry).register();
+
+  activeDisposeTui = () => {
+    if (tui) disposeStatus();
+  };
+
+  let shutdownPromise: Promise<void> | undefined;
+  if (typeof context.on === "function") {
+    context.on("session_shutdown", async () => {
+      if (!shutdownPromise) shutdownPromise = (async () => {
+        activeDisposeTui?.();
+        activeDisposeTui = undefined;
+        if (activeRegistry === registry) activeRegistry = undefined;
+        await registry.shutdown();
+      })();
+      await shutdownPromise;
+    });
+  }
+}
+
+export default init;