@andares/pi-toolkits 0.11.3 → 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.3",
+  "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",
 		);
 	});

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/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;

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

@@ -0,0 +1,214 @@
+/**
+ * quit-guard feature — watchdog state machine.
+ *
+ * Deliberately dependency-free and side-effect free: it is fed stdout chunks
+ * and clock/scheduler callbacks, so every branch is unit-testable without a
+ * real TUI. The wiring to `process.stdout`, `SIGCONT`, the settings store and
+ * the actual `process.exit()` lives in index.ts.
+ *
+ * State machine:
+ *
+ *   idle ──teardown marker──▶ armed ──timer──▶ fired (onFire, then exit)
+ *     ▲                         │
+ *     └──restart marker / resume┘
+ *
+ * Invariants:
+ *  - arming is idempotent while armed (a teardown writes two markers);
+ *  - a TUI restart (mode switch, Ctrl+Z resume) always wins over the timer:
+ *    the fire callback is deferred one turn so a SIGCONT handler can disarm
+ *    first, and the token check drops a fire whose arm was superseded;
+ *  - disabled means inert: it never arms and disarms immediately.
+ */
+import { RESTART_MARKERS, TEARDOWN_MARKERS } from "./constants.js";
+
+/** A chunk as written to `process.stdout` (string, or Buffer/typed array). */
+export type GuardChunk = string | Uint8Array;
+
+export interface GuardFireInfo {
+	/** Clock value captured when the guard armed. */
+	startedAt: number;
+	/** Milliseconds spent armed (i.e. inside the shutdown phase). */
+	elapsedMs: number;
+	/** The teardown sequence that armed the guard. */
+	marker: string;
+}
+
+export interface QuitGuardDeps {
+	now?: () => number;
+	/** Start a timer; returns a handle handed back to `cancel`. */
+	schedule?: (run: () => void, ms: number) => unknown;
+	cancel?: (handle: unknown) => void;
+	/**
+	 * Defer one turn (setImmediate in production). Used so an expired timer
+	 * cannot beat a SIGCONT-driven disarm on the resume path.
+	 */
+	defer?: (run: () => void) => void;
+	/** Called exactly once per arm that reaches the deadline. */
+	onFire: (info: GuardFireInfo) => void;
+	/** Optional debug tap (PI_QUIT_GUARD_DEBUG); never affects behavior. */
+	onEvent?: (event: "arm" | "disarm" | "fire", detail: string) => void;
+	/**
+	 * Second, independent "is a TUI still running" signal, checked right before
+	 * firing. The teardown marker can also arrive inside rendered content (a
+	 * file or tool output that happens to contain the escape sequence); raw
+	 * mode cannot: the TUI leaves raw mode while tearing down. An active
+	 * session must never be killed by a stray marker.
+	 */
+	isTuiActive?: () => boolean;
+}
+
+/** First marker in `markers` that appears in the chunk, if any. */
+export function findMarker(
+	chunk: GuardChunk,
+	markers: readonly string[],
+): string | undefined {
+	if (typeof chunk === "string") {
+		if (chunk.length === 0) return undefined;
+		for (const marker of markers) {
+			if (chunk.includes(marker)) return marker;
+		}
+		return undefined;
+	}
+	if (!(chunk instanceof Uint8Array) || chunk.byteLength === 0) {
+		return undefined;
+	}
+	// Buffers are the normal case; other typed arrays are rare enough that a
+	// one-off copy is cheaper than a hand-rolled byte scan.
+	const buffer: Buffer = Buffer.isBuffer(chunk)
+		? chunk
+		: Buffer.from(chunk);
+	for (const marker of markers) {
+		if (buffer.includes(marker)) return marker;
+	}
+	return undefined;
+}
+
+export class QuitGuard {
+	private readonly now: () => number;
+	private readonly schedule: (run: () => void, ms: number) => unknown;
+	private readonly cancel: (handle: unknown) => void;
+	private readonly defer: (run: () => void) => void;
+	private readonly onFire: (info: GuardFireInfo) => void;
+	private readonly onEvent?: (event: "arm" | "disarm" | "fire", detail: string) => void;
+	private readonly isTuiActive?: () => boolean;
+
+	private enabled = true;
+	private timeoutMs: number;
+	private armed = false;
+	private handle: unknown;
+	private startedAt = 0;
+	private armedBy = "";
+	/** Incremented on every arm; a stale fire callback compares against it. */
+	private armToken = 0;
+
+	constructor(timeoutMs: number, deps: QuitGuardDeps) {
+		this.timeoutMs = timeoutMs;
+		// performance.now() is monotonic: a wall-clock jump (NTP, WSL VM
+		// resume, manual `date`) must not make a 10 s deadline look like 7 s,
+		// and `elapsedMs` in the hang report must measure real time spent.
+		this.now = deps.now ?? (() => performance.now());
+		this.schedule =
+			deps.schedule ??
+			((run, ms) => setTimeout(run, ms));
+		this.cancel =
+			deps.cancel ??
+			((handle) => clearTimeout(handle as ReturnType<typeof setTimeout>));
+		this.defer = deps.defer ?? ((run) => setImmediate(run));
+		this.onFire = deps.onFire;
+		this.onEvent = deps.onEvent;
+		this.isTuiActive = deps.isTuiActive;
+	}
+
+	/** Feed one stdout chunk. Converts markers into arm/disarm transitions. */
+	observeOutput(chunk: GuardChunk): void {
+		if (!this.enabled) return;
+		if (this.armed) {
+			// While armed the only meaningful signal is "the TUI came back".
+			if (findMarker(chunk, RESTART_MARKERS)) {
+				this.disarm();
+			}
+			return;
+		}
+		const marker = findMarker(chunk, TEARDOWN_MARKERS);
+		if (marker) this.arm(marker);
+	}
+
+	/** Process resumed from Ctrl+Z: the TUI is about to re-enter, never kill it. */
+	resume(): void {
+		this.disarm();
+	}
+
+	setEnabled(enabled: boolean): void {
+		this.enabled = enabled;
+		if (!enabled) this.disarm();
+	}
+
+	isEnabled(): boolean {
+		return this.enabled;
+	}
+
+	setTimeoutMs(timeoutMs: number): void {
+		this.timeoutMs = timeoutMs;
+	}
+
+	getTimeoutMs(): number {
+		return this.timeoutMs;
+	}
+
+	isArmed(): boolean {
+		return this.armed;
+	}
+
+	private arm(marker: string): void {
+		const token = (this.armToken += 1);
+		const startedAt = this.now();
+		this.armed = true;
+		this.startedAt = startedAt;
+		this.armedBy = marker;
+		this.onEvent?.("arm", `${marker} timeout=${this.timeoutMs}ms`);
+		this.handle = this.schedule(
+			() => this.onTimeout(token, startedAt),
+			this.timeoutMs,
+		);
+	}
+
+	private disarm(): void {
+		if (!this.armed) return;
+		this.armed = false;
+		this.onEvent?.("disarm", this.armedBy);
+		if (this.handle !== undefined) {
+			this.cancel(this.handle);
+			this.handle = undefined;
+		}
+	}
+
+	private onTimeout(token: number, startedAt: number): void {
+		this.handle = undefined;
+		// One turn later: a pending SIGCONT handler runs before this and can
+		// disarm, so resume always wins over an expired timer.
+		this.defer(() => {
+			if (!this.armed || this.armToken !== token || this.startedAt !== startedAt) {
+				return;
+			}
+			// The liveness probe is best-effort: if it throws (stdin already
+			// destroyed/replaced during teardown), treat the TUI as gone and
+			// still fire. A probe that can throw must not disable the watchdog.
+			let tuiActive = false;
+			try {
+				tuiActive = this.isTuiActive?.() === true;
+			} catch {
+				tuiActive = false;
+			}
+			if (tuiActive) {
+				// A live TUI means the marker was content, not a teardown.
+				this.armed = false;
+				this.onEvent?.("disarm", "tui-still-active");
+				return;
+			}
+			this.armed = false;
+			const elapsedMs = this.now() - startedAt;
+			this.onEvent?.("fire", `elapsed=${Math.round(elapsedMs)}ms`);
+			this.onFire({ startedAt, elapsedMs, marker: this.armedBy });
+		});
+	}
+}