@bachi/pi-coder 1.0.0

package/extensions/recap/subagents.ts

@@ -0,0 +1,128 @@
+/**
+ * subagents.ts — 探测「此刻有没有子代理在跑」。
+ *
+ * recap 是**闲置制**触发的：回合结束（`agent_settled`）后静止 30s 就生成摘要。
+ * 但异步子代理是**脱离回合**的：`subagent({ async: true })` 一发出去主回合就结束，
+ * 子代理还在后台跑几十秒甚至几分钟，结果稍后由被唤醒的回合带回来。这时 30s 到点，
+ * 摘要会把「刚把任务发出去、还在等」总结成「这轮干完了」。所以生成摘要前必须问一句
+ * 「还有子代理在跑吗」，有就只重查、不生成 —— 等它们都结束了再重新起 30s 定时。
+ *
+ * 为什么走 pi-subagents 的进程内 RPC，而不是自己数 `subagent` 工具调用：
+ *   - **数不出来**。异步调用立刻返回（`details.asyncId`），结果由后续回合带回，工具调用
+ *     本身看不出"还在跑"；状态只活在 pi-subagents 的进程内 state 里（`asyncJobs` /
+ *     `foregroundControls`），没有 session 条目、没有落盘文件可以读。
+ *   - **它的文档就给了这个口子**。`pi-subagents/docs/extension-api.md` 的
+ *     "In-process event-bus RPC" 一节是给「其他 Pi 扩展」用的公开接口：发
+ *     `subagents:rpc:v1:request`、在 `subagents:rpc:v1:reply:<requestId>` 上收回复；
+ *     `status` 方法（不带任何 target）的回包里带 `data.fleet`（Fleet status DTO v1），
+ *     `totalActive` 就是当前会话的活跃子代理数（前台 + 异步 + 排队都算）。
+ *   - **不 import pi-subagents 的任何文件**。它是独立安装的 npm 包，不是本扩展可解析的
+ *     依赖；而且它也可能没装（换台机器就没装）。协议是版本化的字符串频道 + JSON 回包，
+ *     按结构化最小接口对接即可。同理本文件**也不 import pi**（总线按下面的接口注入），
+ *     所以 `node --test` 能拿假总线直接跑：
+ *
+ *         node --test clients/pi/extensions/recap/subagents.test.ts
+ *
+ * 失败一律当「没有」：没装 pi-subagents、协议版本变了、回包格式不认识、超时/抛异常 ——
+ * 全部返回 false（fail-open）。宁可偶尔在子代理运行中生成一条摘要，也不能因为探测环节
+ * 把 recap 整个弄停摆。探测超时 1s：没有子代理时对端回的是内存快照，毫秒级就到。
+ */
+
+/** pi 事件总线的子集（真实的 pi `EventBus` 结构兼容）。 */
+export interface SubagentEventBus {
+	on(channel: string, handler: (data: unknown) => void): (() => void) | void;
+	emit(channel: string, data: unknown): void;
+}
+
+/** pi-subagents 的 RPC 频道（见其 docs/extension-api.md，协议版本 1）。 */
+export const SUBAGENT_RPC_REQUEST = "subagents:rpc:v1:request";
+export const SUBAGENT_RPC_REPLY_PREFIX = "subagents:rpc:v1:reply:";
+export const SUBAGENT_RPC_VERSION = 1;
+
+/** 探测超时：没有子代理时对端秒回，超时就当对端不在。 */
+export const SUBAGENT_RPC_TIMEOUT_MS = 1_000;
+
+let requestSeq = 0;
+
+/** 每个请求一个唯一 id —— 只认自己那条回复频道，不会吃到别人的回复。 */
+export function nextSubagentRequestId(now = Date.now()): string {
+	requestSeq += 1;
+	return `recap-${requestSeq}-${now.toString(36)}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * 从 `status` 的回复里判断「有子代理在跑」。
+ *
+ * 主判据是 `data.fleet.totalActive`（有界 entries 之外的**全量**活跃数，所以超过
+ * entries 窗口的也不会漏）。`asyncSnapshot.runs` 里的 `queued` / `running` 是兜底：
+ * fleet 是 v1 才有的能力（`ping.capabilities.fleetStatus` 没有就整个不出现），
+ * 快照在旧版本里也可能单独存在。两条都不认识就返回 false（fail-open）。
+ */
+export function isSubagentWorkActive(reply: unknown): boolean {
+	if (!isRecord(reply) || reply.success !== true) return false;
+	const data = reply.data;
+	if (!isRecord(data)) return false;
+
+	const fleet = data.fleet;
+	if (isRecord(fleet) && typeof fleet.totalActive === "number" && fleet.totalActive > 0) return true;
+
+	const snapshot = data.asyncSnapshot;
+	const runs = isRecord(snapshot) ? snapshot.runs : undefined;
+	if (!Array.isArray(runs)) return false;
+	return runs.some((run) => isRecord(run) && (run.state === "queued" || run.state === "running"));
+}
+
+/**
+ * 问一次 pi-subagents：现在有子代理在跑吗。
+ *
+ * 正常路径：先订阅回复频道 → 发 request → 收到回复（或超时）→ 退订 → 解析。
+ * 任何一步出错都当「没有」，本函数**不抛异常**。
+ */
+export async function hasActiveSubagentWork(
+	events: SubagentEventBus,
+	options: { timeoutMs?: number; requestId?: string } = {},
+): Promise<boolean> {
+	const timeoutMs = options.timeoutMs ?? SUBAGENT_RPC_TIMEOUT_MS;
+	const requestId = options.requestId ?? nextSubagentRequestId();
+
+	const reply = await new Promise<unknown>((resolve) => {
+		let settled = false;
+		let unsubscribe: (() => void) | undefined;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+
+		const finish = (value: unknown) => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			try {
+				unsubscribe?.();
+			} catch {
+				// 退订失败无所谓：handler 已经 settled，再来回复也直接忽略。
+			}
+			resolve(value);
+		};
+
+		try {
+			const off = events.on(`${SUBAGENT_RPC_REPLY_PREFIX}${requestId}`, finish);
+			if (typeof off === "function") unsubscribe = off;
+			timer = setTimeout(() => finish(undefined), timeoutMs);
+			timer.unref?.();
+			events.emit(SUBAGENT_RPC_REQUEST, {
+				version: SUBAGENT_RPC_VERSION,
+				requestId,
+				method: "status",
+				// 不带 target = 只要当前会话的舰队概要（对端走内存快照，秒回）。
+				params: {},
+				source: { extension: "recap" },
+			});
+		} catch {
+			finish(undefined);
+		}
+	});
+
+	return isSubagentWorkActive(reply);
+}

package/extensions/rewind/README.md

@@ -0,0 +1,229 @@
+# rewind — Claude Code style checkpointing and `/rewind` for pi
+
+Automatic working-tree checkpoints plus a Claude Code style rewind menu, and
+`Esc` + `Esc` bound to `/rewind` instead of pi's built-in tree navigator.
+
+## What it does
+
+- **Snapshots the working tree before every user prompt that starts a turn**
+  (Claude Code's checkpoint model), plus one at session start.
+- **Catches the files that snapshot cannot see.** A checkpoint only covers
+  tracked paths under the project root, so edits to `~/.pi/agent/themes/…`, an
+  ignored `.env` or anything else outside the worktree would leave no trace —
+  and a checkpoint with no visible change used to hide the code options
+  entirely. Right before an `edit`/`write` tool runs, the file's bytes are
+  copied into a pre-image blob, so those files come back too. See
+  [Files outside the project](#files-outside-the-project).
+- **`/rewind`** (or **`Esc` twice at an empty prompt**) opens the rewind menu:
+
+  ```
+   ────────────────────────────────────────────────────────────────────
+   Rewind to a checkpoint
+     #48  16:52  probe prompt 048 — …
+   → #41  16:45  probe prompt 041 — …
+     #40  16:44  probe prompt 040 — …
+     (21/62)
+     ↑↓ navigate  pageUp/pageDown page  enter select  escape/ctrl+c cancel
+   ────────────────────────────────────────────────────────────────────
+  ```
+
+  The list is a **window sized to the terminal** and scrolls with the cursor:
+  pi's built-in `ctx.ui.select()` renders one row per option and never scrolls,
+  so a session with enough checkpoints produced a dialog taller than the
+  viewport — and since pi-tui paints only the last `terminal.rows` lines of the
+  document, the title and the `→` cursor row were the first things to disappear.
+  The picker (`picker.ts` + `viewport.ts`) keeps the whole dialog inside the
+  viewport, centres the window on the selection and shows a `(12/37)` position
+  line, so the arrow is always visible. Rows still show the same
+  `#N  HH:MM  prompt` labels, numbered oldest → newest.
+
+  Keys: `↑`/`↓` (or `j`/`k`) move one row and clamp at both ends,
+  `PageUp`/`PageDown` move a window, `Home`/`End` jump to the ends,
+  `Enter` selects, `Esc` cancels (they follow the `tui.select.*` keybindings,
+  and the paging hint only appears when the list is actually longer than the
+  window). Hosts that cannot render extension components (RPC, print) fall back
+  to the plain `ctx.ui.select()` list.
+
+  then offers, for the selected checkpoint:
+
+  | Action | Effect |
+  | --- | --- |
+  | Restore code and conversation | files + session tree back to that point |
+  | Restore conversation (keep current files) | session tree only |
+  | Restore code (keep conversation) | files only |
+  | Summarize from here (frees context) | pi's native branch summary of everything after that point |
+  | Never mind | back out |
+
+  The two code options appear **only** when the checkpoint has file changes to
+  revert (Claude Code parity) — counted over the worktree *and* the pre-images —
+  and a confirmation dialog lists exactly which files will change before
+  anything is touched.
+- Conversation restore uses pi's native `navigateTree`, which drops the
+  selected user message and **puts its text back into the editor** — the same
+  behavior Claude Code documents.
+- Footer status: `◆ N checkpoints`.
+- An `↩ Undo last rewind` entry appears after a code restore, backed by an
+  automatic pre-restore snapshot, so a rewind can itself be undone.
+
+## Storage: a shadow git repository
+
+Snapshots live in a **separate git dir outside the project**, not in the
+project's own repository:
+
+```
+~/.pi/agent/rewind/<sha1(project path)[:16]>/
+├── git/               # shadow GIT_DIR (commits + refs/pi-rewind/<id>)
+├── files/             # pre-image blobs (content addressed) for outside files
+└── checkpoints.json   # per-session checkpoint metadata
+```
+
+Consequences worth knowing:
+
+- The project's **git history, index, HEAD, refs and `git status` are never
+  touched**. A restore cannot move HEAD or discard staged work.
+- Checkpointing also works when the directory is **not a git repo**.
+- `.gitignore` is respected, and the real repo's `.git/info/exclude` is copied
+  into the shadow repo, so ignored paths are never snapshotted and therefore
+  never deleted by a restore's `git clean` (which runs without `-x`).
+- Checkpoints are reachable through `refs/pi-rewind/<id>`, so `git gc --auto`
+  can never prune a live checkpoint.
+- Per session: 100 checkpoints max (Claude Code's number); oldest are pruned.
+  Sessions whose newest checkpoint is older than 30 days are swept at startup
+  (Claude Code's retention window), followed by a background `git gc`.
+- A snapshot of an unchanged worktree reuses the previous commit, so read-only
+  turns cost nothing but a metadata row.
+
+Measured on this repo (105 files): cold snapshot 137 ms, warm 48 ms.
+
+## Files outside the project
+
+The worktree snapshot cannot see two kinds of files, and both are exactly the
+kind the agent is asked to edit:
+
+- anything **outside the project root** — `~/.pi/agent/themes/*.json`,
+  `~/.claude/settings.json`, `~/.zshrc`, another checkout on the same machine;
+- anything inside the root that **`.gitignore` hides from `git add -A`** —
+  `.env`, `local.settings.json`, a scratch directory.
+
+The extension therefore also captures **pre-images**. The `tool_call` hook fires
+*after* `tool_execution_start` and *before* the tool runs — the last moment the
+old bytes still exist — and, for `edit` / `write` targets the worktree snapshot
+does not cover, copies the file into the project's blob store and records it on
+the session's newest checkpoint:
+
+- coverage is decided by path prefix plus `git check-ignore`, which applies
+exactly the rules `git add -A` uses (the project's `.gitignore` files and the
+  shadow repo's `info/exclude`), so a path is captured only when the snapshot
+  really cannot restore it;
+- blobs are content addressed (`files/<sha1>`), so the same content is stored
+  once no matter how many checkpoints reference it;
+- the **first touch inside a turn wins**, so the record is the file as it was
+  before that turn changed it; a path touched in later turns resolves to the
+  earliest checkpoint at or after the one you rewind to;
+- a file that did not exist yet is recorded as *missing*, so a restore deletes
+  it (the same thing `git clean -fd` does for new files inside the root);
+- blobs no live checkpoint references are dropped when checkpoints are pruned,
+  so the store stays bounded;
+- the `↩ Undo last rewind` safety checkpoint carries the current bytes of every
+  file the restore is about to touch, so an undo covers them too.
+
+Limits worth knowing: only `edit` and `write` calls are tracked — a `bash`
+command (`sed -i`, `cat >`) that writes **outside** the root is not parseable and
+therefore not captured (inside the root it is still covered by the worktree
+snapshot); files larger than 8 MB are skipped rather than copied.
+
+## Esc + Esc
+
+pi's own double-escape action is `doubleEscapeAction` in
+`~/.pi/agent/settings.json` (default `"tree"`). This extension replaces it:
+
+```json
+{ "doubleEscapeAction": "none" }
+```
+
+The extension counts two raw `Esc` presses within 500 ms while the agent is
+idle, the editor is empty and no dialog is open, then dispatches `/rewind`
+through pi's command path (so the handler gets a command context with
+`navigateTree`, which a raw-input handler never has).
+
+Details that matter:
+
+- The **second** press is consumed (`{ consume: true }`). Without that, the
+  escape would land on the selector that `/rewind` just focused synchronously
+  and instantly cancel it. Consuming also keeps the press from pi's built-in
+  double-escape action, so `/rewind` takes over even if `doubleEscapeAction`
+  is still `"tree"` or `"fork"`.
+- The **first** press is passed through untouched, so a lone `Esc` still aborts
+  streaming, aborts a running `!` bash command and cancels dialogs.
+- Presses are ignored while streaming (`isIdle()`), while the editor has text,
+  and while any extension dialog is open (tracked via `ui_prompt_start` /
+  `ui_prompt_end`), matching Claude Code's "double `Esc` at an empty prompt".
+
+To get pi's tree navigator back on `Esc` + `Esc`, remove this extension and
+set `doubleEscapeAction` back to `"tree"`; `/tree` always works regardless.
+
+## Differences from Claude Code (all deliberate)
+
+| Claude Code | Here |
+| --- | --- |
+| Tracks only its file-editing tools; **bash-made changes are not tracked** | Whole-worktree snapshots, so bash edits, subagent edits and any other edit inside the root are captured too; edits outside the root (or in ignored paths) are captured as pre-images by the same `edit`/`write` hook |
+| Snapshots the edited files themselves | Worktree snapshot for the project, pre-image blobs only for what it cannot see: no duplicate copies of tracked files |
+| No redo of a rewind | `↩ Undo last rewind`, backed by a pre-restore snapshot |
+| No confirmation before a code restore | One confirmation listing the changed files |
+| `Summarize up to here` | Not offered — pi can summarize an abandoned branch or compact the whole context, but not "everything before an entry while keeping later messages" |
+| Skips symlinked / hard-linked paths on restore | git materializes symlinks as symlinks, so no skip list is needed |
+| Checkpoints survive resume | Same — metadata is keyed by session id |
+
+Known gap: a follow-up message that pi delivers inside a running turn still
+gets its own checkpoint (it is a user message), unlike Claude Code's
+"messages sent mid-turn are not checkpointed".
+
+## Files
+
+```
+rewind/
+├── index.ts              # entry: session lifecycle, checkpoint + pre-image hooks, /rewind, Esc+Esc
+├── checkpoints.ts        # pure shadow-git core (no pi imports)
+├── flow.ts               # the /rewind menu flow
+├── picker.ts             # the scrollable checkpoint picker (pi-tui component)
+├── viewport.ts           # pure layout budget: how many list rows fit the terminal
+├── checkpoints.test.ts   # 23 tests for the core
+├── flow.test.ts          # 26 tests for the flow (scripted mock dialogs)
+└── viewport.test.ts      # 8 tests for the picker layout budget
+```
+
+pi auto-loads only `index.ts` from a subdirectory (`extensions/*/index.ts`);
+the other files are plain modules and tests.
+
+## Tests
+
+```bash
+node --test ~/.pi/agent/extensions/rewind/checkpoints.test.ts
+node --test ~/.pi/agent/extensions/rewind/flow.test.ts
+node --test ~/.pi/agent/extensions/rewind/viewport.test.ts
+```
+
+57 tests, no npm dependencies. The core tests create throwaway projects and
+agent dirs under the OS temp dir and assert the real repo's index/HEAD/status
+stay untouched; the flow tests drive the menu with a scripted mock command
+context, since TUI dialogs cannot be exercised headlessly (the picker is
+reached through the injectable `deps.pick`, with the `ctx.ui.select()` fallback
+covered separately); the viewport tests assert that the dialog — list, chrome
+and the rows pi paints below the editor — fits the terminal at every height.
+
+The picker itself was verified live in a tmux-driven TUI with 62 checkpoints:
+at 24 rows it shows 14 rows plus `(1/62)`, at 14 rows it shrinks to 4, in both
+cases with the title, the borders and the arrow on screen; `PageDown` jumps a
+window (`(1/62)` → `(29/63)`), `End` lands on `Never mind` with the arrow still
+visible, and picking `#4` of five checkpoints holding distinct file contents
+restored exactly that version (`v5` → `v4`), with `↩ Undo last rewind` putting
+`v5` back. `Esc` cancelling the picker and `Esc` + `Esc` opening it (a single
+`Esc` not) were re-checked there too.
+
+Earlier live checks (unchanged by the picker): `/rewind` restore, a lone `Esc`
+still aborting streaming, and `Esc` + `Esc` correctly doing nothing while the
+editor holds text. The outside-project path was verified the same way: a
+`write` to a file outside the root was captured as a pre-image, the menu then
+read `1 file: ~1` for a project whose worktree was untouched and offered the
+code options, the restore put the old bytes back, and `↩ Undo last rewind` put
+the new ones back again.