@andares/pi-toolkits 0.11.2 → 0.12.0

package/README.md

@@ -13,7 +13,7 @@
 [![pi >= 0.99](https://img.shields.io/badge/pi-%3E%3D0.99.0-blueviolet)](https://github.com/earendil-works/pi)
 [![GitHub](https://img.shields.io/badge/github-andares%2Fpi--toolkits-181717?logo=github)](https://github.com/andares/pi-toolkits)
 
-In a nutshell: seven ready-to-use capabilities — **read-only consult mode** `ask`, **session-scoped boundary permission** `ask-perm`, **model favorites** `favorites`, **prompt stash** `stash`, **third-party code review** `third-review`, **dedicated compaction model** `compact-model` and **session startup automation** `autostart` — with more to come.
+In a nutshell: nine ready-to-use capabilities — **read-only consult mode** `ask`, **session-scoped boundary permission** `ask-perm`, **model favorites** `favorites`, **prompt stash** `stash`, **third-party code review** `third-review`, **dedicated compaction model** `compact-model`, **session startup automation** `autostart`, an **agent memory framework** `ask-init`, and a **quit watchdog** `quit-guard` — with more to come.
 
 **Requirements**: pi `>=0.99.0`. Every published pi release from 0.99.0 through 1.5.0 has been verified with the full gate (install → `tsc --noEmit` → full test suite → keybinding audit → hash compare of the host files this package patches), each in a sandbox with the whole `@earendil-works/*` family pinned to the version under test. Newer releases are verified as they ship and the floor moves only when the measurement says so; `pnpm check:compat` reproduces the result. Note: pi ≥ 0.99 hosts require host-provided packages to be declared in `peerDependencies` with a `"*"` range — `@earendil-works/pi-tui` and `typebox` (the `scratchpad` tool builds a TypeBox schema) are declared that way; an installed copy in `dependencies` would make pi warn.
 
@@ -57,6 +57,7 @@ After installing, verify in any pi session:
   - [🗜️ compact — dedicated compaction model](#compact)
   - [🚀 autostart — session startup automation](#autostart)
   - [🧠 init — agent memory framework](#init)
+  - [🧯 quit-guard — quit watchdog](#quit-guard)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -77,6 +78,7 @@ After installing, verify in any pi session:
 | 🗜️ **compact** dedicated compaction model | `/compact-model` | give `/compact` and auto-compact a cheap fast model to summarize with, leaving the main model free to focus on the conversation; zero overhead when unconfigured, falls back to pi's default on any failure |
 | 🚀 **autostart** session startup automation | `.pi/autostart.toml` | declare slash commands to run automatically at session start, per project (first use case: mounting multi-repo directories with `/add-dir`); never runs in untrusted directories, unregistered commands are skipped instead of being sent to the model |
 | 🧠 **init** agent memory framework | `/ask-init` | install or adopt a fixed memory layout (`AGENTS.md` + `specs/` + `.agents/memory` + `.agents/implementations`), migrate an existing one with a snapshot and a coverage table, and audit it later for drift, budgets and duplicated facts |
+| 🧯 **quit-guard** quit watchdog | `/quit-guard` | force-exit when pi's shutdown hangs after the TUI is gone (an extension `session_shutdown` that never settles), write a hang report, and give the shell prompt back; TUI restarts and Ctrl+Z resume disarm it |
 
 ---
 
@@ -451,6 +453,77 @@ published); text written *into* a project follows that project's language.
 > framework version lives in `.agents/framework/state.toml`; a project whose state
 > version is newer than the installed tool is never migrated.
 
+## 🧯 quit-guard — quit watchdog
+
+<a name="quit-guard"></a>
+
+**The problem.** pi's interactive `/quit` stops the TUI and then awaits every extension's
+`session_shutdown` handler, one after another, **with no timeout**
+(`runtimeHost.dispose()` → `emitSessionShutdownEvent()`; upstream
+[issue #9997](https://github.com/earendil-works/pi/issues/9997), still unbounded in 1.5.0 and on
+`main`). One handler that never settles leaves pi alive at 0% CPU *after* the terminal has
+already been restored and the final frame reprinted: the screen looks like a frozen "exit
+screen", and the shell prompt never comes back. Ctrl+C and SIGTERM did not end the hung process
+in our measurements (SIGKILL did); once that phase starts, the host has no way out of it.
+Measured with a 20-extension setup (2026-11-05): a healthy quit spends 0.1–3 s in that phase,
+`pi -ne` 0.12 s — and one of three quits with the same setup never finished at all.
+
+**What this does.** The guard watches the terminal instead of the event stream, so it still
+works when the handler that hangs was loaded *before* this package (in that case our own
+`session_shutdown` would never run). It arms on the TUI's teardown sequence
+(`\x1b[?2004l` / `\x1b[?1049l`); if the process is still alive `timeoutMs` later, it writes a
+hang report and forces the exit. A TUI that comes back disarms it — an interactive mode switch
+(`/settings` → TUI mode) and Ctrl+Z suspend/resume both re-enter the TUI, and a live session
+must never be killed.
+
+### Commands
+
+| Command | Effect |
+| --- | --- |
+| `/quit-guard` | status: on/off, timeout, report on/off, newest hang report |
+| `/quit-guard on` / `/quit-guard off` | enable/disable, persisted |
+| `/quit-guard <ms>` | set the deadline (clamped to 2000–60000 ms), persisted |
+
+**Configuration** — `<agent-dir>/pi-toolkits-quit-guard.json`, written by the commands; every
+field is optional:
+
+```json
+{
+  "enabled": true,
+  "timeoutMs": 10000,
+  "report": true
+}
+```
+
+`timeoutMs` counts **from the teardown write**, not from the moment you press Enter, so the time
+the TUI spends stopping is not charged against a slow-but-finishing shutdown. Keep it below your
+slowest healthy quit; 10 s leaves a wide margin (the slowest healthy quit measured above was 5 s
+end to end, of which ~2 s came after the teardown).
+
+**Hang reports** — `<agent-dir>/quit-guard/quit-hang-<timestamp>-<pid>.json` records the
+arm/fire timing, the teardown marker, and the process state at the deadline (`activeHandles`,
+`activeRequests`, and the host's libuv handle table). An empty `libuv` table next to a live
+process is the signature of a promise nobody will ever resolve, as opposed to a blocked socket
+or a lingering child process. The file is owner-only (0600 in an 0700 directory) and process
+arguments are redacted with the same rules as the approval log, so `pi --api-key …` does not
+leave the key on disk.
+
+`PI_QUIT_GUARD_DEBUG=<file>` appends one line per `arm` / `disarm` / `fire` (plus one per
+extension registration); once the TUI is gone it is the only channel left.
+
+### Boundaries
+
+- Interactive TUI only. Print (`-p`), JSON, and RPC sessions never write the teardown
+  sequences, so the guard stays inert there.
+- The deadline covers the **post-teardown** phase. A shutdown that hangs before the TUI stops
+  (not observed; `drainInput` is bounded at 1 s) is out of scope.
+- When it fires, the remaining extension cleanup is skipped **by design** — that cleanup is what
+  was hanging. Session entries are appended to the session JSONL as they happen, so the
+  transcript is intact up to the last written entry. The process exits 0; if `process.exit()`
+  itself is turned into a no-op by an `exit` listener, a 500 ms fallback sends `SIGKILL`.
+- This is a workaround for a host gap. If pi ever bounds `session_shutdown`, the guard becomes
+  a no-op safety net and can be removed.
+
 ---
 
 ## 🛠️ Development
@@ -493,6 +566,8 @@ src/
     ├── permission/       # session-scoped boundary permission: modes, panel,
     │                     #           bash units, policy, session grants, prompt,
     │                     #           audit payload, tests
+    ├── quit-guard/       # quit watchdog: terminal-teardown trigger, settings
+    │                     #           store, hang report, tests
     ├── review/           # third-party review: input/command triggers,
     │                     #           review-model config store, prompt, tests
     └── stash/            # prompt stash: hotkey state machine + tests

package/README.zh-CN.md

@@ -13,7 +13,7 @@
 [![pi >= 0.99](https://img.shields.io/badge/pi-%3E%3D0.99.0-blueviolet)](https://github.com/earendil-works/pi)
 [![GitHub](https://img.shields.io/badge/github-andares%2Fpi--toolkits-181717?logo=github)](https://github.com/andares/pi-toolkits)
 
-一句话介绍:目前包含七个开箱即用的功能——**只读咨询模式** `ask`、**会话级边界权限** `ask-perm`、**模型收藏** `favorites`、**提示词暂存** `stash`、**第三方代码评审** `third-review`、**独立压缩模型** `compact-model`、**会话启动自动化** `autostart`,后续持续追加。
+一句话介绍:目前包含九个开箱即用的功能——**只读咨询模式** `ask`、**会话级边界权限** `ask-perm`、**模型收藏** `favorites`、**提示词暂存** `stash`、**第三方代码评审** `third-review`、**独立压缩模型** `compact-model`、**会话启动自动化** `autostart`、**agent 记忆框架** `ask-init`、**退出看门狗** `quit-guard`,后续持续追加。
 
 **版本要求**:pi `>=0.99.0`。0.99.0 到 1.5.0 的每一个已发布版本都用完整门禁实测过(install → `tsc --noEmit` → 全量测试 → 键位审计 → 对 patch 目标宿主文件做哈希比对),每个版本都在沙箱中把整个 `@earendil-works/*` 家族钉在同一版本。更新的版本随发布逐个验证,下限只在实测结果允许时移动;`pnpm check:compat` 可复现该结论。注:pi ≥ 0.99 的宿主要求「宿主提供的包」一律声明为 peerDependencies `"*"` —— `@earendil-works/pi-tui` 与 `typebox`(ask 的 `scratchpad` 用它构造参数 schema)都按此声明;若放进 `dependencies`,pi 会告警。
 
@@ -57,6 +57,7 @@ pi -e ./src/index.ts
   - [🗜️ compact — 独立压缩模型](#compact)
   - [🚀 autostart — 会话启动自动化](#autostart)
   - [🧠 init — agent 记忆框架](#init)
+  - [🧯 quit-guard — 退出看门狗](#quit-guard)
 - [开发](#development)
 - [贡献](#contributing)
 - [许可](#license)
@@ -77,6 +78,7 @@ pi -e ./src/index.ts
 | 🗜️ **compact** 独立压缩模型 | `/compact-model` | 给 `/compact` 与 auto-compact 配一个便宜快模型做总结,主模型专注对话;未配置零开销、任何异常回落 pi 默认 |
 | 🚀 **autostart** 会话启动自动化 | `.pi/autostart.toml` | 项目内声明启动时自动执行的斜杠命令(首批用例:`/add-dir` 多仓库挂载);未信任不执行、未注册命令跳过不发给模型 |
 | 🧠 **init** agent 记忆框架 | `/ask-init` | 安装或接管一套固定的记忆结构(`AGENTS.md` + `specs/` + `.agents/memory` + `.agents/implementations`),带快照与覆盖表迁移旧文档,之后可随时审计漂移、预算与重复事实 |
+| 🧯 **quit-guard** 退出看门狗 | `/quit-guard` | TUI 已停、进程却卡在扩展 `session_shutdown` 上时，超时后写诊断报告并强制退出，把命令行提示符还给你；TUI 重启（切换显示模式）与 Ctrl+Z 恢复都会解除看守 |
 
 ---
 
@@ -435,6 +437,46 @@ run = [
 > **跑完记得 `/reload`**,让新的 `AGENTS.md` 进入提示词。框架版本记在
 > `.agents/framework/state.toml`;若项目的状态版本比当前工具新,则拒绝迁移。
 
+## 🧯 quit-guard — 退出看门狗
+
+<a name="quit-guard"></a>
+
+**要解决的问题**。pi 的 `/quit` 先停 TUI，然后**逐个 await** 每个扩展的 `session_shutdown` 处理器,且**没有任何超时**(`runtimeHost.dispose()` → `emitSessionShutdownEvent()`;上游
+[issue #9997](https://github.com/earendil-works/pi/issues/9997),1.5.0 与 `main` 至今未修)。只要有一个处理器永不 settle,pi 就会在终端已还原、最后一帧已重绘之后,以 0% CPU 永远挂着:画面看起来像「停在退出界面」,提示符再也不回来;实测 Ctrl+C 与 SIGTERM 都无法结束这个进程(只有 SIGKILL 有效)——进了这段收尾,宿主自己也没有出口。20 个扩展的环境实测(2026-11-05):健康退出在这段收尾上花 0.1–3 秒,`pi -ne` 0.12 秒;同一环境三次 `/quit` 就有一次**永远不结束**。
+
+**这个功能做什么**。看守盯的是**终端写出的收尾序列**,而不是事件流——所以即使卡死的处理器比本包**先**加载(那样我们自己的 `session_shutdown` 根本不会运行),它照样能触发。它在 TUI 收尾序列(`\x1b[?2004l` / `\x1b[?1049l`)出现时开始计时;若 `timeoutMs` 之后进程还活着,就写一份诊断报告并强制退出。TUI **回来**时自动解除:`/settings` 里切换 TUI 显示模式、Ctrl+Z 挂起后 `fg` 恢复,都会让 TUI 重新进入,绝不能误杀活着的会话。
+
+### 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `/quit-guard` | 查看状态:开关、超时、报告开关、最近一份诊断报告 |
+| `/quit-guard on` / `/quit-guard off` | 开启/关闭,并持久化 |
+| `/quit-guard <ms>` | 设置超时(钳制在 2000–60000 ms),并持久化 |
+
+**配置** —— `<agent-dir>/pi-toolkits-quit-guard.json`,由命令写入;所有字段都可省略:
+
+```json
+{
+  "enabled": true,
+  "timeoutMs": 10000,
+  "report": true
+}
+```
+
+`timeoutMs` 从**收尾序列写出**那一刻开始算,不是从你按下 Enter 开始算——TUI 自己停下来的时间不计入,所以「慢但能完成」的收尾(记忆库 flush、MCP 关闭)不会被误杀。把它设在「你最慢的健康退出」之上;10 秒余量很大(上例最慢的健康退出端到端 5 秒,其中约 2 秒发生在收尾之后)。
+
+**诊断报告** —— `<agent-dir>/quit-guard/quit-hang-<时间戳>-<pid>.json`,记录开始计时/触发的时间、触发用的收尾序列,以及截止时进程的状态(`activeHandles`、`activeRequests`、宿主 libuv 句柄表)。**进程还活着但 `libuv` 表是空的**,就是「有个 Promise 永远不会 settle」的特征,区别于阻塞的 socket 或残留子进程。报告文件**仅本人可读**(0700 目录下的 0600 文件),进程参数按审批日志同一套规则脱敏,所以 `pi --api-key …` 不会把密钥留在盘上。
+
+`PI_QUIT_GUARD_DEBUG=<文件>` 会把每次 `arm` / `disarm` / `fire`(以及每次扩展注册)追加一行;TUI 已经没了的时候,这是唯一还能观察的通道。
+
+### 边界
+
+- 只覆盖交互式 TUI。`-p`(print)、JSON、RPC 模式不会写这些收尾序列,看守在那里完全不生效。
+- 计时覆盖的是**收尾之后**的阶段;在 TUI 停下之前就卡住的情况(未观察到;`drainInput` 上限 1 秒)不在范围内。
+- 触发时**按设计跳过**剩余扩展清理——挂住的就是它。会话条目是随发生随写入 JSONL 的,所以最后一条已写入的记录不会丢。正常路径退出码 0;若 `process.exit()` 本身被 `exit` 监听器变成空操作,500 ms 后会补一记 `SIGKILL`。
+- 这是对宿主缺口的权宜之计:哪天 pi 给 `session_shutdown` 加上限时,看守就退化成无害的保险,可以直接删掉。
+
 ---
 
 ## 🛠️ 开发
@@ -476,6 +518,8 @@ src/
     ├── permission/       # 会话级边界权限:模式、面板、bash 拆解、
     │                     #           策略、会话授权、确认对话框、
     │                     #           审计 payload、测试
+    ├── quit-guard/       # 退出看门狗:终端收尾触发、配置存储、
+    │                     #           诊断报告、测试
     ├── review/           # 第三方评审:输入/指令触发、
     │                     #           评审模型配置存储、提示词、测试
     └── stash/            # 提示词暂存:热键状态机 + 测试

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andares/pi-toolkits",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Integrated toolkit extension for pi — ask mode (read-only Q&A), session-scoped permission checks, model favorites, prompt stash, third-party code review, session autostart, a dedicated compaction model, and an agent memory framework (/ask-init)",
   "type": "module",
   "license": "MIT",

package/src/features/compact/compact.test.ts

@@ -296,7 +296,7 @@ describe("pickCompactModel", () => {
 		const { ctx, notify } = fakeCtx({ models: [] });
 		await pickCompactModel(ctx, getCompactStore());
 		expect(notify).toHaveBeenCalledWith(
-			expect.stringContaining("没有可用模型"),
+			expect.stringContaining("No models are available"),
 			"error",
 		);
 	});
@@ -308,7 +308,7 @@ describe("pickCompactModel", () => {
 		expect(model).toBeUndefined();
 		expect(getCompactStore().getModel()).toBe("google/gemini-2.5-flash");
 		expect(notify).toHaveBeenCalledWith(
-			expect.stringContaining("置为 null"),
+			expect.stringContaining("set model to null"),
 			"info",
 		);
 	});
@@ -326,7 +326,7 @@ describe("pickCompactModel", () => {
 		await pickCompactModel(ctx, getCompactStore());
 		expect(getCompactStore().getModel()).toBe("google/gemini-2.5-flash");
 		expect(notify).toHaveBeenCalledWith(
-			expect.stringContaining("已取消"),
+			expect.stringContaining("cancelled"),
 			"info",
 		);
 	});
@@ -336,7 +336,7 @@ describe("pickCompactModel", () => {
 		const { ctx, notify } = fakeCtx({ customResult: MODELS[0] });
 		await pickCompactModel(ctx, getCompactStore());
 		expect(notify).toHaveBeenCalledWith(
-			expect.stringContaining("不存在或不可用"),
+			expect.stringContaining("does not exist or is unavailable"),
 			"warning",
 		);
 		expect(getCompactStore().getModel()).toBe("google/gemini-2.5-flash");
@@ -451,7 +451,7 @@ describe("session_before_compact handler", () => {
 		)) as SessionBeforeCompactResult | undefined;
 		expect(result).toBeUndefined();
 		expect(notify).toHaveBeenCalledWith(
-			expect.stringContaining("摘要为空"),
+			expect.stringContaining("came back empty"),
 			"warning",
 		);
 	});
@@ -525,6 +525,61 @@ describe("session_before_compact handler", () => {
 		expect(compaction.usage?.input).toBe(107);
 	});
 
+	it("keeps the cost provider-reported only when both split-turn parts report it", async () => {
+		// 1.5.0's combineUsage rule end-to-end: the merged compaction usage, not
+		// just the helper. A part that reports no provider cost is enough to make
+		// the sum "not provider-reported"; only both parts reporting it flips it
+		// to true (asserted below on a second run). The flag is cost provenance,
+		// not the token sum.
+		getCompactStore().setModel("google/gemini-2.5-flash");
+		const { handler } = registeredHandler();
+		const withFlag = (flag: boolean | undefined) => {
+			const usage = fakeUsage();
+			if (flag !== undefined) usage.cost.totalFromProvider = flag;
+			return usage;
+		};
+		const { ctx } = fakeCtx({
+			complete: vi.fn(async (_model, context) => {
+				const text = (context.messages[0]?.content as Array<{ text?: string }>)[0]
+					?.text;
+				return text?.includes("# Instructions")
+					? fakeResponse("TURN PREFIX", { usage: withFlag(true) })
+					: fakeResponse("HISTORY", { usage: withFlag(undefined) });
+			}),
+		});
+		const event = fakeEvent({
+			turnPrefixMessages: [userMessage("prefix msg")],
+			isSplitTurn: true,
+		});
+		const result = (await handler(
+			event as never,
+			ctx,
+		)) as SessionBeforeCompactResult | undefined;
+		// Read through the structural view, not the host's `CompleteUsage`:
+		// `cost.totalFromProvider` only exists on pi ≥ 1.5.0's types, so reading
+		// it directly from the host type breaks typecheck on the 1.2–1.4 window
+		// even though the runtime field we write is the same.
+		const mergedUsage = result!.compaction!.usage as unknown as UsageLike;
+		expect(mergedUsage.cost.totalFromProvider).toBe(false);
+
+		// Same split turn, but both summaries report the cost themselves → true.
+		const both = fakeCtx({
+			complete: vi.fn(async (_model, context) => {
+				const text = (context.messages[0]?.content as Array<{ text?: string }>)[0]
+					?.text;
+				return text?.includes("# Instructions")
+					? fakeResponse("TURN PREFIX", { usage: withFlag(true) })
+					: fakeResponse("HISTORY", { usage: withFlag(true) });
+			}),
+		});
+		const bothResult = (await handler(
+			event as never,
+			both.ctx,
+		)) as SessionBeforeCompactResult | undefined;
+		const bothUsage = bothResult!.compaction!.usage as unknown as UsageLike;
+		expect(bothUsage.cost.totalFromProvider).toBe(true);
+	});
+
 	it("keeps the previous summary as history text on split turns with no messages", async () => {
 		getCompactStore().setModel("google/gemini-2.5-flash");
 		const { handler } = registeredHandler();

package/src/features/compact/index.ts

@@ -217,7 +217,7 @@ async function runCompactModelCompaction(
 		if (!summaryText.trim()) {
 			if (!signal.aborted) {
 				ctx.ui.notify(
-					"compact-model: 压缩摘要为空，已回落 pi 默认压缩。",
+					"compact-model: the summary came back empty — falling back to pi's default compaction.",
 					"warning",
 				);
 			}
@@ -244,7 +244,7 @@ async function runCompactModelCompaction(
 		const message =
 			error instanceof Error ? error.message : String(error);
 		ctx.ui.notify(
-			`compact-model: 压缩摘要失败（${message}），已回落 pi 默认压缩。`,
+			`compact-model: summarization failed (${message}) — falling back to pi's default compaction.`,
 			"error",
 		);
 		return undefined;
@@ -261,7 +261,7 @@ export async function pickCompactModel(
 ): Promise<AvailableModel | undefined> {
 	if (!ctx.hasUI) {
 		ctx.ui.notify(
-			"compact-model: 当前环境不支持模型选择对话框，请编辑 <agent-dir>/pi-toolkits-compact.json 手动配置。",
+			"compact-model: this environment has no model picker dialog — edit <agent-dir>/pi-toolkits-compact.json to configure it manually.",
 			"error",
 		);
 		return undefined;
@@ -270,16 +270,17 @@ export async function pickCompactModel(
 	const configuredModel = resolveConfiguredModel(ctx, configured);
 	if (!configuredModel && configured) {
 		ctx.ui.notify(
-			`compact-model: 配置的压缩模型 ${configured} 不存在或不可用，请重新选择。`,
+			`compact-model: the configured compact model ${configured} does not exist or is unavailable — pick another one.`,
 			"warning",
 		);
 	}
 	const model = await openModelPicker(ctx, configuredModel, {
-		selectTitle: "选择压缩模型（首项为当前默认，回车使用）",
+		selectTitle:
+			"Select the compaction model (first entry is the current default; press Enter to use it)",
 	});
 	if (!model) {
 		ctx.ui.notify(
-			"compact-model: 已取消，压缩模型配置未变更。清除配置请编辑 <agent-dir>/pi-toolkits-compact.json（把 model 置为 null）。",
+			"compact-model: cancelled — the compact model is unchanged. To clear the setting, edit <agent-dir>/pi-toolkits-compact.json and set model to null.",
 			"info",
 		);
 		return undefined;
@@ -290,7 +291,7 @@ export async function pickCompactModel(
 		store.setModel(key);
 	}
 	ctx.ui.notify(
-		`compact-model: 压缩模型已设置为「${model.name}」，后续压缩总结将由它执行。`,
+		`compact-model: compact model set to "${model.name}" — it will run the next compaction summary.`,
 		"info",
 	);
 	return model;
@@ -310,7 +311,7 @@ export function registerCompact(pi: ExtensionAPI): void {
 			const model = resolveConfiguredModel(ctx, configured);
 			if (!model) {
 				ctx.ui.notify(
-					`compact-model: 配置的压缩模型 ${configured} 不存在或不可用，已回落 pi 默认压缩。`,
+					`compact-model: the configured compact model ${configured} does not exist or is unavailable — falling back to pi's default compaction.`,
 					"warning",
 				);
 				return undefined;

package/src/features/favorites/constants.ts

@@ -29,7 +29,8 @@ export const FAVORITES_FILE = "pi-toolkits-favorites.json";
  * (0.87–0.99 defaulted to `regular`, where the binding is inert). On
  * Windows/WSL `tui.altScreen.search` resolves to ctrl+f, and
  * `TuiAltScreen.handleViewportInput()` checks it before
- * `shouldDeferViewportInputToOverlay()`, so the keystroke opens transcript
+ * `shouldDeferViewportInput()` (named `shouldDeferViewportInputToOverlay()`
+ * through 1.4.0), so the keystroke opens transcript
  * search and the selector never sees it (verified in pi-tui 1.5.0
  * `dist/tui-alt-screen.js`: the search check is still the first key branch
  * and still returns `{ consume: true }` unconditionally; the 1.5.0 changes to

package/src/features/favorites/favorites.test.ts

@@ -39,6 +39,7 @@ import {
 	setSharedFavoritesStore,
 } from "./store.js";
 import { applyCyclePatch } from "./patch-cycle.js";
+import { styleFavorite } from "./constants.js";
 import {
 	applyModelSelectorPatches,
 	setSelectorThemeProvider,
@@ -505,5 +506,40 @@ describe("selector patches", () => {
 		expect(renamedLine).toContain(
 			"(MiniMax M3 [rasmus@openrouter, parasail])",
 		);
+		// The full line pins the 1.5.0 column order (id → name → provider badge)
+		// and the favorite highlight not leaking ANSI codes into the name. The
+		// two spaces after → are the (empty) current-marker column; the fake
+		// selector has no currentModel, so no ✓ is drawn.
+		expect(redundantLine).toBe("→   claude-sonnet-4 [anthropic]");
+		expect(renamedLine).toBe(
+			"    minimax/minimax-m3 (MiniMax M3 [rasmus@openrouter, parasail]) [openrouter]",
+		);
+	});
+
+	it("keeps the favorite highlight while appending the disambiguating name", () => {
+		// Regression guard: the 1.5.0 name text must land AFTER the styled id
+		// (and outside its ANSI reset), or favorited ids would lose their color.
+		const favoriteModel = {
+			provider: "anthropic",
+			id: "claude-opus-4",
+			name: "Claude Opus 4 (max)",
+		};
+		getFavoritesStore().toggle(favoriteModel);
+		const lines: string[] = [];
+		const selector = fakeSelector({
+			activeModels: [],
+			filteredModels: [
+				{ provider: favoriteModel.provider, id: favoriteModel.id, model: favoriteModel },
+			] as unknown as FakeSelector["filteredModels"],
+			listContainer: {
+				clear() {},
+				addChild: (child: unknown) =>
+					lines.push((child as { text?: string }).text ?? ""),
+			},
+		});
+		selector.updateList();
+		expect(lines[0]).toBe(
+			`→   ${styleFavorite("claude-opus-4")} (Claude Opus 4 (max)) [anthropic]`,
+		);
 	});
 });

package/src/features/favorites/patch-cycle.ts

@@ -59,7 +59,7 @@ interface CycleSessionInternals {
 		setDefaultModelAndProvider(provider: string, id: string): void;
 	};
 	/**
-	 * pi 1.0–1.3: keeps a persisted default usable when cycling inside a
+	 * pi 1.0–1.5: keeps a persisted default usable when cycling inside a
 	 * non-empty --models scope.
 	 */
 	_addPersistedDefaultToNonEmptyScope(model: unknown): void;
@@ -142,7 +142,7 @@ export function applyCyclePatch(): boolean {
 			return original.call(this, direction, options);
 		}
 
-		// Same source and availability filtering as pi's stock cycling (1.0–1.3).
+		// Same source and availability filtering as pi's stock cycling (1.0–1.5).
 		const scoped = this._scopedModels.length > 0;
 		let candidates: CycleCandidate[];
 		if (scoped) {
@@ -187,7 +187,7 @@ export function applyCyclePatch(): boolean {
 				: this._getThinkingLevelForModelSwitch();
 		this.agent.state.model = next.model;
 		this.sessionManager.appendModelChange(next.model.provider, next.model.id);
-		// pi 1.0–1.3: only persist the default model when the caller asked for it.
+		// pi 1.0–1.5: only persist the default model when the caller asked for it.
 		if (options.persist) {
 			this.settingsManager.setDefaultModelAndProvider(
 				next.model.provider,

package/src/features/favorites/patch-selector.ts

@@ -149,7 +149,7 @@ let patched = false;
 export function applyModelSelectorPatches(): boolean {
 	if (patched) return true;
 	// SAFETY: ModelSelectorComponent's members are TS-private (compile-time
-	// only); the structural view matches pi 1.0–1.3's prototype shape
+	// only); the structural view matches pi 1.0–1.5's prototype shape
 	// (byte-identical across that span) and every touched method is
 	// existence-checked below before any patching happens.
 	const proto =

package/src/features/quit-guard/constants.ts

@@ -0,0 +1,60 @@
+/**
+ * quit-guard feature — constants and the rationale behind them.
+ *
+ * WHY a terminal-sequence trigger instead of `session_shutdown`: pi runs
+ * extension shutdown handlers one after another without a timeout. If a
+ * handler loaded BEFORE ours never settles, our own `session_shutdown` never
+ * runs, so a watchdog armed from that event would miss exactly the hangs it
+ * is meant to catch. The teardown sequence below is written by the TUI
+ * before that phase starts, so it arms the guard regardless of extension
+ * load order (and even when the host's own writes are what hangs).
+ *
+ * Teardown markers (arm):
+ *  - `\x1b[?2004l` — bracketed paste off, written by `ProcessTerminal.stop()`
+ *    (both `regular` and `fullscreen` modes);
+ *  - `\x1b[?1049l` — alternate-screen exit, written by the fullscreen
+ *    renderer's `afterTerminalStop()`.
+ *
+ * Restart markers (disarm): a TUI that re-enters must never be killed by a
+ * timer meant for a process that is leaving:
+ *  - `\x1b[?2004h` — bracketed paste on, `ProcessTerminal.start()`;
+ *  - `\x1b[?1049h` — alternate-screen enter, fullscreen `beforeTerminalStart()`.
+ *
+ * These cover the two legitimate teardown-then-restart paths: an interactive
+ * TUI mode switch (`switchTuiMode()` stops the old renderer with
+ * `preserveScreen`, then starts the new one) and Ctrl+Z suspend/resume
+ * (`handleCtrlZ()` calls `ui.stop()`, then `ui.start()` on SIGCONT). The
+ * SIGCONT listener in index.ts disarms synchronously as well, so an expired
+ * timer cannot win a race against a resume.
+ *
+ * Scope: interactive TUI only. Print/JSON/RPC sessions never write these
+ * sequences, so the guard stays inert there (documented boundary).
+ */
+export const QUIT_GUARD_FILE = "pi-toolkits-quit-guard.json";
+
+/** Directory holding the JSON reports written when the guard fires. */
+export const QUIT_GUARD_REPORT_DIR = "quit-guard";
+
+/**
+ * Default watchdog deadline, measured from the terminal teardown write.
+ *
+ * Measured on a 20-extension setup (2026-11-05): a healthy `/quit` spends
+ * ~0.1–3 s between the teardown write and `process.exit(0)` (the whole
+ * `runtimeHost.dispose()` / extension-shutdown phase), and 0.12 s with
+ * `pi -ne`. 10 s leaves a wide margin for a slow-but-finishing shutdown
+ * (e.g. a memory flush or an MCP server close) while still returning the
+ * prompt quickly when something never settles.
+ */
+export const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** Floor for `/quit-guard <ms>`: below this, a healthy slow quit would be cut. */
+export const MIN_TIMEOUT_MS = 2_000;
+
+/** Ceiling for `/quit-guard <ms>`: beyond this the user is better off with `kill -9`. */
+export const MAX_TIMEOUT_MS = 60_000;
+
+/** Sequences after which the interactive TUI has begun tearing down. */
+export const TEARDOWN_MARKERS = ["\x1b[?2004l", "\x1b[?1049l"] as const;
+
+/** Sequences that mean a TUI is starting (mode switch or suspend/resume). */
+export const RESTART_MARKERS = ["\x1b[?2004h", "\x1b[?1049h"] as const;