pi-quiver 3.1.2 → 3.3.0

package/CHANGELOG.md

@@ -8,6 +8,16 @@ Published to npm as `pi-quiver` (`pi install npm:pi-quiver`). Pushing a
 via OIDC trusted publishing. The release helper at
 `.agents/skills/release/scripts/release.sh` cuts the tag; CI publishes.
 
+## v3.3.0 - 2026-07-17
+
+- **`provider-stall-watchdog`: opt-in semantic-silence recovery.** Policy D warns after configured silence, aborts the first semantic stall, and offers it once to Pi's existing retry loop; a second stall stops without another watchdog retry. OFF by default.
+- **Human-TUI boundary.** Arms only for confirmed human interactive TUI runs; JSON, RPC, print, and subagent runs are excluded by activation rather than environment or session lineage.
+- **Compatibility and fallback.** Verified against Pi 0.80.10. Automatic continuation requires enabled Pi retry with remaining capacity; disabled, exhausted, or incompatible retry leaves the request stopped for manual resubmission. Pending steering and follow-ups return to the editor and are excluded from automatic continuation; invalid merged watchdog configuration fails closed.
+
+## v3.2.0 - 2026-07-12
+
+- Add `fast-mode` extension: opt-in Anthropic fast mode for Claude Opus 4.8 (`speed: "fast"` payload + `fast-mode-2026-02-01` beta header), controlled via `fastMode` settings key, `--fast` flag, and `/fast [on|off|status]`. OFF by default. Preserves OAuth identity betas. Requires pi bundling `@earendil-works/pi-coding-agent` >= 0.80.5 (the `before_provider_headers` hook).
+
 ## v3.1.2 - 2026-07-07
 
 - **`fetch` routes GitHub Actions run URLs through `gh`.** `github.com/{owner}/{repo}/actions/runs/{id}` URLs are served by `gh run view {id} --repo {owner}/{repo}` and returned through the existing size gate with a `Source: gh run view ...` header, alongside the existing issue/PR/repo routing. Only the bare run URL routes; deeper paths (`.../runs/{id}/jobs/{jobId}`, `.../actions/workflows/{file}`) fall back to HTTP. Falls back silently when `gh` is absent/unauthenticated/errors; `raw=true` forces the rendered page.

package/README.md

@@ -18,7 +18,7 @@ But the moment an agent does that, one `fetch` or PDF read can dump hundreds of
 
 `fetch` and `doc_to_md` bring real web pages, GitHub issues/PRs, and local PDF/DOCX/PPTX files into context - and every result is size-gated by construction: over 32 KB or 1000 lines spills to a temp file with a preview and a grep/read hint, so a single call can never flood the window. Ingestion is what makes data-driven work possible; the gate is what keeps it safe.
 
-`session-name` and `sword-header` are smaller, opt-in ergonomics on top - session labeling and a themed startup header.
+`session-name`, `sword-header`, `fast-mode`, and `provider-stall-watchdog` are opt-in ergonomics and recovery controls: session labeling, a themed startup header, Anthropic fast mode, and semantic-stall recovery.
 
 ## Part of the pi agent toolkit
 
@@ -33,7 +33,7 @@ No code dependency between them. pi-quiver is call-level: it gates the size of w
 
 ## Mental model
 
-Every extension here is context-safe by construction, not by convention: the size check runs on every call, there's no flag to forget. Two tools bring real sources in (`fetch`, `doc_to_md`); two are opt-in ergonomics (`session-name`, `sword-header`).
+Every ingestion extension here is context-safe by construction, not by convention: the size check runs on every call, there's no flag to forget. `fetch` and `doc_to_md` bring real sources in; `session-name`, `sword-header`, `fast-mode`, and `provider-stall-watchdog` are opt-in.
 
 ```mermaid
 flowchart LR
@@ -66,6 +66,8 @@ A 300 KB changelog page never touches your context window - you get a preview an
 | `doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/PPTX to Markdown. High-fidelity via `pymupdf4llm` (run through `uv`); degraded pure-JS fallback (`unpdf`) when `uv`/Python is unavailable or conversion times out. DOCX/PPTX convert via LibreOffice first. |
 | `session-name.ts` | `/session-name` | Manual + opt-in automatic session naming, with Ghostty tab rename. OFF by default. |
 | `sword-header.ts` | `/builtin-header` | Themed ASCII startup header replacing pi's default logo. OFF by default. |
+| `fast-mode.ts` | `/fast` | Inject Anthropic fast-mode (`speed: "fast"` + `anthropic-beta: fast-mode-2026-02-01`) into every Claude Opus 4.8 request, any thinking level. `--fast` flag + `/fast [on\|off\|status]`. OFF by default. |
+| `provider-stall-watchdog.ts` | - | Opt-in semantic-silence watchdog for human interactive TUI runs. Warns after 2 minutes and recovers after 4 minutes; policy D offers the first stall once to Pi's retry loop, then stops a second stall. OFF by default. |
 
 Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md), [doc/doc-to-md.md](doc/doc-to-md.md).
 
@@ -76,18 +78,21 @@ Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md
 | Size gate | Text/Markdown/JSON output over 32 KB or 1000 lines spills to a temp file with a 60-line preview instead of inlining. |
 | Content routing | HTML -> Markdown, binary -> untouched file, GitHub URLs -> `gh` CLI, everything else -> the size gate. |
 | Graceful degradation | Optional binaries (`gh`, `uv`, LibreOffice) are never hard install-time deps; each has a defined, documented fallback or failure mode. |
-| Opt-in ergonomics | `session-name` and `sword-header` do nothing until explicitly enabled in `settings.json`. |
+| Opt-in extensions | `session-name`, `sword-header`, `fast-mode`, and `provider-stall-watchdog` do nothing until explicitly enabled in `settings.json`. |
+| Provider stall recovery | The watchdog detects missing parsed semantic progress, not network liveness. It is limited to confirmed human interactive TUI runs. |
 
 ## When to use
 
 - An agent needs to reason from a real web page, GitHub issue/PR, or local PDF/DOCX/PPTX instead of memory.
 - You want that ingestion to be safe by default, with no risk of a single call blowing the context budget.
+- A human interactive Pi session needs an opt-in guard against providers that stop making semantic progress.
 
 ## When NOT to use
 
 - You need a general-purpose web scraper (JS-rendered pages, pagination, auth flows) - `fetch` does plain HTTP + Readability extraction, nothing more.
 - You need spreadsheet conversion - `doc_to_md` explicitly excludes spreadsheets (they paginate badly via PDF).
-- You want automatic session naming or a custom header without opting in - both stay off until you flip the config.
+- You want automatic session naming, a custom header, fast mode, or stall recovery without opting in - all stay off until you flip the config.
+- You need watchdog behavior in JSON, RPC, print, or subagent runs - activation excludes them by input origin and mode, not environment or session lineage.
 
 ## Install
 
@@ -130,18 +135,39 @@ The npm package's bundled JS deps install automatically on `pi install`. A few *
 
 None is a hard install-time dependency of the package; they are tools you provide in the environment where pi runs.
 
-### session-name and sword-header config
+### Opt-in extension config
 
-Both are opt-in via `settings.json` (project `.pi/settings.json` overrides the global agent-dir layer):
+These extensions are opt-in via `settings.json` (project `.pi/settings.json` overrides the global agent-dir layer):
 
 ```jsonc
 {
   "sessionAutoName": { "enabled": false, "ghosttyTab": true }, // or boolean shorthand
-  "swordHeader": false                                         // or { "enabled": true }
+  "swordHeader": false,                                        // or { "enabled": true }
+  "fastMode": false,                                           // or { "enabled": true }
+  "providerStallWatchdog": false                               // or { "enabled": true }
 }
 ```
 
-`sessionAutoName.enabled` makes one extra short LLM call per session (once, after the first turn) to title it; `false` (default) makes no model calls. See [doc/fetch.md](doc/fetch.md) and [doc/doc-to-md.md](doc/doc-to-md.md) for the ingestion tools' full reference; session-name/sword-header behavior above is complete.
+`sessionAutoName.enabled` makes one extra short LLM call per session (once, after the first turn) to title it; `false` (default) makes no model calls. `fastMode` only affects `claude-opus-4-8` requests on Anthropic's `anthropic-messages` API; enabling it opts into premium fast-mode pricing. `--fast` forces it on for one launch; `/fast on|off` toggles live. Proxy providers (opencode, cloudflare-ai-gateway) are excluded. `fastMode`'s header injection needs the `before_provider_headers` hook (pi bundling `@earendil-works/pi-coding-agent` >= 0.80.5); on older pi the beta header is silently not sent. See [doc/fetch.md](doc/fetch.md) and [doc/doc-to-md.md](doc/doc-to-md.md) for the ingestion tools' full reference; session-name/sword-header behavior above is complete.
+
+Recommended explicit retry and watchdog settings:
+
+```json
+{
+  "retry": {
+    "enabled": true,
+    "maxRetries": 3,
+    "baseDelayMs": 2000
+  },
+  "providerStallWatchdog": {
+    "enabled": true,
+    "warningMs": 120000,
+    "recoveryMs": 240000
+  }
+}
+```
+
+`providerStallWatchdog` is OFF by default and runs only for confirmed human interactive TUI runs. JSON, RPC, print, and subagent runs are excluded by activation, not environment or session lineage. Verified with Pi 0.80.10: the first semantic stall is aborted and offered once to Pi retry; a second stall stops. Automatic continuation needs enabled Pi retry with remaining capacity. Disabled, exhausted, or incompatible retry degrades to manual resubmission. Pending steering or follow-ups return to the editor and are excluded from automatic continuation. Invalid merged watchdog config fails closed.
 
 ## Development
 

package/fast-mode.ts

@@ -0,0 +1,182 @@
+/**
+ * Fast mode for Claude Opus 4.8.
+ *
+ * When enabled, injects Anthropic's fast-mode signals into every qualifying
+ * Opus 4.8 request on the anthropic-messages API, regardless of thinking level:
+ *   - payload: { ...payload, speed: "fast" }        (before_provider_request)
+ *   - header:  anthropic-beta: ...,fast-mode-2026-02-01  (before_provider_headers)
+ *
+ * OFF BY DEFAULT. Three control surfaces, lowest precedence first:
+ *   1. settings.json  "fastMode": true | { "enabled": true }  (default false)
+ *   2. --fast launch flag                                      (force-on only)
+ *   3. /fast [on|off|status] live toggle                       (wins for session)
+ *
+ * Header coupling to pi-ai internals: pi assembles `anthropic-beta` AFTER this
+ * hook and merges the hook's headers LAST, so setting the header here REPLACES
+ * pi's list. For opus-4-8 pi's conditional betas (fine-grained tool streaming,
+ * interleaved thinking) are never applied (eager tool streaming defaults on +
+ * forceAdaptiveThinking), so the only betas to preserve are the OAuth identity
+ * betas. We detect OAuth via the same token marker pi uses and rebuild the
+ * exact list. If pi later adds betas for opus-4-8, revisit buildBetaHeader.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveConfig } from "./extension-config.ts";
+
+export const FAST_MODE_BETA = "fast-mode-2026-02-01";
+export const FAST_SPEED = "fast";
+// Loose prefix: matches dated snapshots (claude-opus-4-8-*). Opus 4.7 is out of
+// scope (D1); a future 4.9 needs a one-line addition here.
+export const FAST_MODE_MODEL_PREFIXES = ["claude-opus-4-8"];
+export const OAUTH_IDENTITY_BETAS = ["claude-code-20250219", "oauth-2025-04-20"];
+const STATUS_KEY = "fast-mode";
+const BETA_HEADER = "anthropic-beta";
+
+type Config = { enabled: boolean };
+const DEFAULT_CONFIG: Config = { enabled: false };
+
+export function coerce(raw: unknown): Partial<Config> | undefined {
+	if (raw === undefined) return undefined;
+	if (typeof raw === "boolean") return { enabled: raw };
+	if (raw && typeof raw === "object") {
+		const o = raw as Record<string, unknown>;
+		const out: Partial<Config> = {};
+		if (typeof o.enabled === "boolean") out.enabled = o.enabled;
+		return out;
+	}
+	return undefined;
+}
+
+type ModelLike = { id?: string; api?: string; provider?: string } | undefined;
+
+export function shouldInject(enabled: boolean, model: ModelLike): boolean {
+	if (!enabled || !model) return false;
+	if (model.provider !== "anthropic") return false;
+	if (model.api !== "anthropic-messages") return false;
+	const id = model.id;
+	if (typeof id !== "string") return false;
+	return FAST_MODE_MODEL_PREFIXES.some((p) => id.startsWith(p));
+}
+
+export function injectSpeed(payload: unknown): unknown {
+	if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+		return payload;
+	}
+	return { ...(payload as Record<string, unknown>), speed: FAST_SPEED };
+}
+
+export function buildBetaHeader(existing: string | null | undefined, isOAuth: boolean): string {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	const add = (b: string): void => {
+		const t = b.trim();
+		if (t && !seen.has(t)) {
+			seen.add(t);
+			out.push(t);
+		}
+	};
+	if (isOAuth) OAUTH_IDENTITY_BETAS.forEach(add);
+	if (typeof existing === "string") existing.split(",").forEach(add);
+	add(FAST_MODE_BETA);
+	return out.join(",");
+}
+
+type State = { config: boolean; flag: boolean; live: boolean | null };
+
+export function resolveEnabled(s: State): boolean {
+	if (s.live !== null) return s.live;
+	return s.flag || s.config;
+}
+
+export default function (pi: ExtensionAPI) {
+	let liveOverride: boolean | null = null;
+	let enabled = false;
+
+	const readFlag = (): boolean => pi.getFlag("fast") === true;
+
+	const resolveState = (ctx: ExtensionContext): boolean => {
+		const config = resolveConfig(ctx.cwd, "fastMode", DEFAULT_CONFIG, coerce).enabled;
+		enabled = resolveEnabled({ config, flag: readFlag(), live: liveOverride });
+		return enabled;
+	};
+
+	const refreshStatus = (ctx: ExtensionContext): void => {
+		if (!enabled) {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			return;
+		}
+		ctx.ui.setStatus(STATUS_KEY, shouldInject(enabled, ctx.model) ? "\u26a1 fast" : "\u26a1 n/a");
+	};
+
+	const detectOAuth = async (ctx: ExtensionContext): Promise<boolean | null> => {
+		if (!ctx.model) return null;
+		try {
+			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+			if (!auth.ok) return null;
+			return typeof auth.apiKey === "string" && auth.apiKey.includes("sk-ant-oat");
+		} catch {
+			return null;
+		}
+	};
+
+	pi.registerFlag("fast", {
+		type: "boolean",
+		description: "Enable Anthropic fast mode for Opus 4.8 requests this launch",
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		resolveState(ctx);
+		refreshStatus(ctx);
+	});
+
+	pi.on("model_select", async (_event, ctx) => {
+		refreshStatus(ctx);
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		if (!shouldInject(enabled, ctx.model)) return;
+		return injectSpeed(event.payload);
+	});
+
+	pi.on("before_provider_headers", async (event, ctx) => {
+		if (!shouldInject(enabled, ctx.model)) return;
+		if (!event.headers) return;
+		const isOAuth = await detectOAuth(ctx);
+		if (isOAuth === null) return;
+		event.headers[BETA_HEADER] = buildBetaHeader(event.headers[BETA_HEADER], isOAuth);
+	});
+
+	pi.registerCommand("fast", {
+		description: "Manage Opus 4.8 fast mode: /fast [on|off|status]",
+		getArgumentCompletions: (prefix) => {
+			const p = prefix.trim().toLowerCase();
+			if (p.includes(" ")) return null;
+			const matches = ["on", "off", "status"].filter((v) => v.startsWith(p));
+			return matches.length ? matches.map((value) => ({ value, label: value })) : null;
+		},
+		handler: async (args, ctx) => {
+			const arg = args.trim().toLowerCase();
+			if (arg === "status") {
+				const eff = liveOverride !== null ? "live toggle" : readFlag() ? "--fast flag" : "settings.json";
+				const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "(no model selected)";
+				const applies = shouldInject(enabled, ctx.model) ? "applies to current model" : "does not apply to current model";
+				ctx.ui.notify(
+					`Fast mode is ${enabled ? "on" : "off"} (source: ${eff}). Model: ${model} - ${applies}.`,
+					"info",
+				);
+				return;
+			}
+			if (arg === "on" || arg === "off") {
+				liveOverride = arg === "on";
+			} else if (arg === "") {
+				liveOverride = !enabled;
+			} else {
+				ctx.ui.notify("Usage: /fast [on|off|status]", "warning");
+				return;
+			}
+			resolveState(ctx);
+			refreshStatus(ctx);
+			ctx.ui.notify(`Fast mode ${enabled ? "enabled" : "disabled"}`, "info");
+		},
+	});
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-quiver",
-  "version": "3.1.2",
-  "description": "Personal pack of Pi coding-agent extensions: context-safe fetch, doc_to_md PDF/DOCX/PPTX-to-Markdown conversion, session naming, and a themed ASCII startup header.",
+  "version": "3.3.0",
+  "description": "Personal pack of Pi coding-agent extensions: context-safe fetch, doc_to_md PDF/DOCX/PPTX-to-Markdown conversion, session naming, a themed ASCII startup header, Opus 4.8 fast mode, and a provider-stall watchdog.",
   "author": "Jacek Juraszek",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,8 @@
     "doc_to_md.ts",
     "session-name.ts",
     "sword-header.ts",
+    "fast-mode.ts",
+    "provider-stall-watchdog.ts",
     "extension-config.ts",
     "scripts/pdf_to_md.py",
     "types/**/*.d.ts",
@@ -41,7 +43,7 @@
   "scripts": {
     "check:agents-core": "node scripts/check-agents-core.mjs",
     "test": "node --test \"*.test.ts\"",
-    "typecheck": "npx -y tsc --noEmit --allowImportingTsExtensions --target es2022 --module nodenext --moduleResolution nodenext --strict --skipLibCheck --esModuleInterop --resolveJsonModule --lib es2022 --types node fetch.ts fetch.test.ts doc_to_md.ts doc_to_md.test.ts session-name.ts session-name.test.ts sword-header.ts sword-header.test.ts extension-config.ts types/turndown-plugin-gfm.d.ts",
+    "typecheck": "npx -y tsc --noEmit --allowImportingTsExtensions --target es2022 --module nodenext --moduleResolution nodenext --strict --skipLibCheck --esModuleInterop --resolveJsonModule --lib es2022 --types node fetch.ts fetch.test.ts doc_to_md.ts doc_to_md.test.ts session-name.ts session-name.test.ts sword-header.ts sword-header.test.ts fast-mode.ts fast-mode.test.ts provider-stall-watchdog.ts provider-stall-watchdog.test.ts extension-config.ts types/turndown-plugin-gfm.d.ts",
     "test:all": "npm run check:agents-core && npm run test && npm run typecheck"
   },
   "pi": {
@@ -49,7 +51,9 @@
       "./fetch.ts",
       "./doc_to_md.ts",
       "./session-name.ts",
-      "./sword-header.ts"
+      "./sword-header.ts",
+      "./fast-mode.ts",
+      "./provider-stall-watchdog.ts"
     ],
     "image": "https://raw.githubusercontent.com/jjuraszek/pi-quiver/main/pi-quiver.png"
   },
@@ -86,7 +90,7 @@
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.80.3",
-    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@earendil-works/pi-coding-agent": "^0.80.5",
     "@earendil-works/pi-tui": "^0.80.3",
     "@sinclair/typebox": "^0.34.49",
     "@types/jsdom": "^28.0.3",

package/provider-stall-watchdog.ts

@@ -0,0 +1,245 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolveConfig } from "./extension-config.ts";
+
+export const MAX_TIMER_MS = 2_147_483_647;
+export const DEFAULT_CONFIG = {
+	enabled: false,
+	warningMs: 120_000,
+	recoveryMs: 240_000,
+} as const;
+
+export type WatchdogConfig = {
+	enabled: boolean;
+	warningMs: number;
+	recoveryMs: number;
+};
+
+export type WatchdogRuntime = {
+	now(): number;
+	setTimeout(callback: () => void, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+};
+
+export type ConfigCandidate = {
+	blockIsObject?: unknown;
+	enabled?: unknown;
+	warningMs?: unknown;
+	recoveryMs?: unknown;
+};
+
+export type ConfigValidation =
+	| { ok: true; config: WatchdogConfig }
+	| { ok: false; error: string };
+
+const DEFAULT_CANDIDATE: ConfigCandidate = { blockIsObject: true, ...DEFAULT_CONFIG };
+
+export function coerce(raw: unknown): ConfigCandidate | undefined {
+	if (raw === undefined) return undefined;
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return { blockIsObject: false };
+
+	const source = raw as Record<string, unknown>;
+	const candidate: ConfigCandidate = { blockIsObject: true };
+	for (const key of ["enabled", "warningMs", "recoveryMs"] as const) {
+		if (Object.hasOwn(source, key)) candidate[key] = source[key];
+	}
+	return candidate;
+}
+
+export function validateConfig(candidate: ConfigCandidate): ConfigValidation {
+	if (candidate.blockIsObject !== true) return { ok: false, error: "providerStallWatchdog must be an object" };
+	if (typeof candidate.enabled !== "boolean") return { ok: false, error: "enabled must be a boolean" };
+	if (!isTimerDelay(candidate.warningMs)) return { ok: false, error: "warningMs must be a positive timer delay" };
+	if (!isTimerDelay(candidate.recoveryMs)) return { ok: false, error: "recoveryMs must be a positive timer delay" };
+	if (candidate.warningMs >= candidate.recoveryMs) return { ok: false, error: "warningMs must be less than recoveryMs" };
+	return {
+		ok: true,
+		config: {
+			enabled: candidate.enabled,
+			warningMs: candidate.warningMs,
+			recoveryMs: candidate.recoveryMs,
+		},
+	};
+}
+
+function isTimerDelay(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value > 0 && value <= MAX_TIMER_MS;
+}
+
+export function resolveWatchdogConfig(cwd: string): ConfigValidation {
+	return validateConfig(resolveConfig(cwd, "providerStallWatchdog", DEFAULT_CANDIDATE, coerce));
+}
+
+const defaultRuntime: WatchdogRuntime = {
+	now: () => Date.now(),
+	setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+const STATUS_KEY = "providerStallWatchdog";
+const SECOND_STALL_NOTICE = "The retry also stopped making progress; aborting without another automatic retry. Submit the message again manually.";
+const DEGRADATION_NOTICE = "The stalled request was stopped, but Pi did not start an automatic retry. Retry may be disabled, exhausted, or incompatible; submit the message again to retry manually.";
+
+type Timer = { warning?: unknown; recovery?: unknown };
+
+function formatElapsed(ms: number): string {
+	if (ms % 60_000 === 0) return `${ms / 60_000}m`;
+	if (ms % 1_000 === 0) return `${ms / 1_000}s`;
+	return `${ms}ms`;
+}
+
+function warningStatus(config: WatchdogConfig): string {
+	return `No model progress for ${formatElapsed(config.warningMs)}; aborting and asking Pi to retry once in ${formatElapsed(config.recoveryMs - config.warningMs)} (Esc aborts now)`;
+}
+
+export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRuntime): (pi: ExtensionAPI) => void {
+	return (pi) => {
+		let pendingInteractive = false;
+		let activeRun = false;
+		let disabled = false;
+		let config: WatchdogConfig | undefined;
+		let generation = 0;
+		let activeGeneration: number | undefined;
+		let lastSemanticAt = 0;
+		let warned = false;
+		let epoch = 0;
+		let deadlineEpoch = 0;
+		let timers: Timer = {};
+		let removeSignalListener: (() => void) | undefined;
+		let ui: { setStatus(key: string, text: string | undefined): void; notify(text: string, type?: string): void } | undefined;
+		let watchdogAbortedGeneration: number | undefined;
+		let timeoutConversionPending = false;
+		let stallRetryConsumed = false;
+		let continuationStarted = false;
+		let convertedTimeout = false;
+
+		const clearTimers = () => {
+			if (timers.warning !== undefined) runtime.clearTimeout(timers.warning);
+			if (timers.recovery !== undefined) runtime.clearTimeout(timers.recovery);
+			timers = {};
+		};
+		const clearDeadlines = () => {
+			clearTimers();
+			ui?.setStatus(STATUS_KEY, undefined);
+		};
+		const clear = () => {
+			clearDeadlines();
+			removeSignalListener?.();
+			removeSignalListener = undefined;
+			activeGeneration = undefined;
+		};
+		const disarm = () => { clear(); warned = false; };
+		const resetRunState = () => {
+			disarm();
+			activeRun = false;
+			pendingInteractive = false;
+			stallRetryConsumed = false;
+			continuationStarted = false;
+			convertedTimeout = false;
+			watchdogAbortedGeneration = undefined;
+			timeoutConversionPending = false;
+		};
+		const schedule = (ctx: { ui: typeof ui; abort(): void }) => {
+			if (activeGeneration === undefined || !config) return;
+			const capturedGeneration = activeGeneration;
+			const capturedEpoch = epoch;
+			const capturedDeadlineEpoch = ++deadlineEpoch;
+			const run = (kind: "warning" | "recovery", threshold: number) => () => {
+				if (capturedEpoch !== epoch || capturedGeneration !== activeGeneration || capturedDeadlineEpoch !== deadlineEpoch || !activeRun || !config) return;
+				const elapsed = runtime.now() - lastSemanticAt;
+				if (elapsed < threshold) {
+					timers[kind] = runtime.setTimeout(run(kind, threshold), threshold - elapsed);
+					return;
+				}
+				if (kind === "warning" && !warned) {
+					warned = true;
+					ctx.ui?.setStatus(STATUS_KEY, warningStatus(config));
+				}
+				if (kind === "recovery") {
+					clearDeadlines();
+					warned = false;
+					if (stallRetryConsumed) {
+						ui?.notify(SECOND_STALL_NOTICE);
+						ctx.abort();
+						return;
+					}
+					watchdogAbortedGeneration = capturedGeneration;
+					timeoutConversionPending = true;
+					stallRetryConsumed = true;
+					ui?.notify(`No model progress for ${formatElapsed(elapsed)}; aborting now. Pi will retry once if retry is enabled and capacity remains. Pending follow-ups are returned to the editor.`);
+					ctx.abort();
+				}
+			};
+			timers.warning = runtime.setTimeout(run("warning", config.warningMs), config.warningMs);
+			timers.recovery = runtime.setTimeout(run("recovery", config.recoveryMs), config.recoveryMs);
+		};
+
+		pi.on("input", (event) => {
+			if (!activeRun) pendingInteractive = event.source === "interactive";
+		});
+		pi.on("before_agent_start", (_event, ctx) => {
+			if (!pendingInteractive) return;
+			pendingInteractive = false;
+			if (ctx.mode !== "tui" || disabled) return;
+			const resolved = resolveWatchdogConfig(ctx.cwd);
+			if (!resolved.ok) {
+				disabled = true;
+				console.warn(`providerStallWatchdog disabled: ${resolved.error}`);
+				ctx.ui.notify(`providerStallWatchdog disabled: ${resolved.error}`, "warning");
+				return;
+			}
+			config = resolved.config;
+			activeRun = config.enabled;
+		});
+		pi.on("before_provider_request", (_event, ctx) => {
+			if (!activeRun || ctx.mode !== "tui" || !config) return;
+			disarm();
+			if (convertedTimeout) continuationStarted = true;
+			activeGeneration = ++generation;
+			lastSemanticAt = runtime.now();
+			ui = ctx.ui;
+			const target = ctx.signal;
+			if (target) {
+				const listener = () => {
+					if (watchdogAbortedGeneration !== activeGeneration) disarm();
+				};
+				target.addEventListener("abort", listener, { once: true });
+				removeSignalListener = () => target.removeEventListener("abort", listener);
+			}
+			schedule(ctx);
+		});
+		pi.on("message_update", (event, ctx) => {
+			const update = event.assistantMessageEvent;
+			if (activeGeneration === undefined || !(update.type === "text_delta" || update.type === "thinking_delta" || update.type === "toolcall_delta") || update.delta.length === 0) return;
+			lastSemanticAt = runtime.now();
+			warned = false;
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			clearTimers();
+			schedule(ctx);
+		});
+		pi.on("message_end", (event) => {
+			if (event.message.role !== "assistant") return;
+			const matchesWatchdogAbort = event.message.stopReason === "aborted"
+				&& activeGeneration === watchdogAbortedGeneration
+				&& timeoutConversionPending
+				&& stallRetryConsumed;
+			disarm();
+			if (!matchesWatchdogAbort || !config) return;
+			timeoutConversionPending = false;
+			convertedTimeout = true;
+			return { message: { ...event.message, stopReason: "error", errorMessage: `Provider semantic timeout after ${config.recoveryMs} ms without progress` } };
+		});
+		pi.on("agent_end", () => disarm());
+		pi.on("agent_settled", () => {
+			if (convertedTimeout && !continuationStarted) ui?.notify(DEGRADATION_NOTICE);
+			resetRunState();
+		});
+		pi.on("session_shutdown", () => {
+			epoch += 1;
+			resetRunState();
+			config = undefined;
+			disabled = false;
+		});
+	};
+}
+
+export default createProviderStallWatchdog();