pi-quiver 3.3.2 → 3.4.1

package/CHANGELOG.md

@@ -8,6 +8,20 @@ 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.4.1 - 2026-08-04
+
+- **`fast-mode` now corrects reported `usage.cost` to true 2x fast pricing for Opus 4.8/5** (statusline, persisted cost, and pi-cohort `Σ$` per load order) (#6).
+- **Documented Anthropic stall-retry activation.** A session trace confirmed Pi's existing 2/4/8-second exponential backoff was active and that the watchdog retained the retry budget resolved when its extension instance started. Local `retry.maxRetries: 5` now takes effect after a fresh session or explicit reload, with no watchdog cooldown, resubmission path, or runtime code change.
+
+## v3.4.0 - 2026-07-30
+
+- **`provider-stall-watchdog`: new `firstEventMs` tier (default 20s) fast-fails a request that never streams.** A pre-first-event deadline is armed at every provider request and cleared by the first assistant `message_start`; on expiry the request is aborted and converted to a retryable error, cutting recovery for an unresponsive request from ~240s to ~22s (detection + Pi's 2s backoff). Previously only the 240s mid-stream `recoveryMs` timer caught this case.
+- **Widened activation.** The `firstEventMs` tier arms in every mode (`tui`, `print`, `json`, `rpc`) and from every origin, including extension-triggered turns that never emit `before_agent_start`; activation is now lazy inside `before_provider_request`, so the `input` and `before_agent_start` handlers are gone. The mid-stream `warningMs`/`recoveryMs` tier stays TUI-only - an unattended abort discards billed output tokens with nobody reading the warning. Headless runs report on stderr via `console.warn` (never stdout, which `json` mode uses for its protocol).
+- **Behaviour change: `maxStallRetries: 0` is now valid** and means "detect and stop, never auto-retry" - it previously failed validation and disabled the extension. When unset, `maxStallRetries` inherits the layered `retry.maxRetries` including an explicit `0`, matching Pi's own `?? 3` instead of silently resolving 0 to 3. Both tiers share the one budget.
+- **Abort-hang escalation.** After any watchdog abort a fixed 10s deadline announces that the provider connection is unresponsive if the request never terminates; any post-abort stream event re-arms it, so a straggler followed by a wedge still escalates. It reduces the hang, it cannot force the provider to stop - undici's `headersTimeout`/`bodyTimeout` (pi's `httpIdleTimeoutMs`, default 300s) stay the backstop.
+- **Config is read once per session,** on the first provider request, instead of per prompt. Editing `settings.json` mid-session - including repairing an invalid block that disabled the extension - now requires a session restart.
+- **`"providerStallWatchdog": false` now works.** The boolean shorthand the README already documented was rejected as "must be an object"; it is now accepted as `{ "enabled": <bool> }`, matching `swordHeader`, `fastMode`, and `sessionAutoName`. Previously harmless (the warning was TUI-only), the widened activation above would otherwise have printed a config error to stderr on every headless run.
+
 ## v3.3.2 - 2026-07-30
 
 - **`fast-mode` supports Claude Opus 5.** Added `claude-opus-5` to the model prefix allowlist (fast mode API mechanics are identical to Opus 4.8: `speed: "fast"` + `fast-mode-2026-02-01` beta; compat verified identical in pi-ai 0.82.1, so `buildBetaHeader`'s OAuth-only preservation still holds).

package/README.md

@@ -67,7 +67,7 @@ A 300 KB changelog page never touches your context window - you get a preview an
 | `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 / Opus 5 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 each stall to Pi's retry loop until the stall retry budget (`maxStallRetries`, default = `retry.maxRetries`) is exhausted. OFF by default. |
+| `provider-stall-watchdog.ts` | - | Opt-in provider-stall recovery, in two tiers: a pre-first-event deadline (`firstEventMs`, 20s) on every provider request in every mode, and the mid-stream pair (warn at 2 min, recover at 4 min) in TUI runs only. Policy D offers each stall to Pi's retry loop until the stall retry budget (`maxStallRetries`, default = `retry.maxRetries`) is exhausted. 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).
 
@@ -79,20 +79,20 @@ Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md
 | 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 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. |
+| Provider stall recovery | The watchdog detects a missing first stream event and missing parsed semantic progress, not network liveness. The pre-first-event tier covers every mode and origin; the mid-stream tier is TUI-only. |
 
 ## 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.
+- A Pi run needs an opt-in guard against provider requests that never produce a first stream event, plus mid-stream silence recovery in interactive TUI sessions.
 
 ## 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, 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.
+- You need *mid-stream* stall recovery in JSON, RPC, or print runs - only the pre-first-event tier arms there; mid-stream silence falls through to pi's transport timeout.
 
 ## Install
 
@@ -150,6 +150,8 @@ These extensions are opt-in via `settings.json` (project `.pi/settings.json` ove
 
 `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` and `claude-opus-5` 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.
 
+`pi-ai` prices every fast request at standard rates - it has no `usage.speed` support and no request-level pricing modifier - so `fastMode` corrects the reported cost itself: a `message_end` handler scales all four `usage.cost` components by `FAST_MODE_COST_MULTIPLIER` (2x) and returns the corrected message. Persisted session JSONL and pi's own native cost display are always exact, since they're written from this corrected message. pi-cohort's live `Σ$` reflects the correction only when pi-quiver's `message_end` handler runs before pi-cohort's - best-effort, depending on extension load order - and is reconciled on pi-cohort's next `session_start` regardless. The upstream fix (teaching `pi-ai`'s `Usage`/`calculateCost` about `usage.speed`) is the better long-term path and is tracked separately.
+
 Recommended explicit retry and watchdog settings:
 
 ```json
@@ -161,6 +163,7 @@ Recommended explicit retry and watchdog settings:
   },
   "providerStallWatchdog": {
     "enabled": true,
+    "firstEventMs": 20000,
     "warningMs": 120000,
     "recoveryMs": 240000,
     "maxStallRetries": 3
@@ -168,7 +171,30 @@ Recommended explicit retry and watchdog settings:
 }
 ```
 
-`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: each semantic stall is aborted and offered to Pi retry until `maxStallRetries` conversions are used; further stalls stop for manual resubmission. `maxStallRetries` defaults to the layered `retry.maxRetries` (Pi default 3); consecutive stall conversions consume Pi retry attempts without a success reset in between, so keep `maxStallRetries <= retry.maxRetries`. A successful assistant turn resets the stall counter (mirroring Pi's own retry counter). The silence warning and all watchdog notices render as main-window notifications, not the bottom status line. 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.
+| Key | Default | Where it arms | What it measures |
+| --- | --- | --- | --- |
+| `enabled` | `false` | - | Master switch. OFF means the extension does nothing. |
+| `firstEventMs` | `20000` | every provider request, every mode (`tui`/`print`/`json`/`rpc`), every origin | Silence between the request and the first assistant `message_start`. |
+| `warningMs` | `120000` | mid-stream, `ctx.mode === "tui"` only | Silence since the last non-empty text/thinking/toolcall delta; notifies. |
+| `recoveryMs` | `240000` | mid-stream, `ctx.mode === "tui"` only | Same clock; aborts and converts. Must be `> warningMs`. |
+| `maxStallRetries` | layered `retry.maxRetries`, else `3` | shared by both tiers | Watchdog aborts that may convert to a retryable error before stopping. |
+
+`providerStallWatchdog` is OFF by default. Once enabled it arms in two tiers per provider request:
+
+- **Pre-first-event (`firstEventMs`).** Armed at every provider request, in every mode and from every origin - including extension-triggered turns that never emit `before_agent_start` - and cleared by the first assistant `message_start`. On expiry the request is aborted and, budget permitting, converted to a retryable error, so an unresponsive request recovers in ~22s (20s detection + Pi's 2s backoff) instead of the ~240s it took when only the mid-stream tier existed.
+- **Mid-stream (`warningMs` / `recoveryMs`).** Armed from the first assistant `message_start` onward, and only when `ctx.mode === "tui"`. Aborting mid-generation discards billed output tokens and an unattended run has nobody to read the warning, so headless mid-stream silence deliberately falls through to the transport timeout instead.
+
+**Raise `firstEventMs` if your provider is legitimately slow to first event.** Queueing gateways, throttled endpoints, and busy single-slot local model servers can hold the connection for well over 20s before their first stream event; every false abort re-uploads the whole context and spends one stall retry.
+
+**Leave pi's own `httpIdleTimeoutMs` (default `300000`) at its default.** It is the transport backstop, and a single value drives undici's `headersTimeout` *and* `bodyTimeout` - lowering it to get fast pre-stream failure also truncates legitimate mid-stream gaps. `firstEventMs` is the knob for pre-stream silence.
+
+Verified with Pi 0.80.10: each stall is aborted and offered to Pi retry until `maxStallRetries` conversions are used; further stalls stop for manual resubmission. Both tiers draw on that one budget. `maxStallRetries` defaults to the layered `retry.maxRetries` (Pi default 3, an explicit `0` honoured); `0` is valid and means "detect and stop, never auto-retry". Consecutive stall conversions consume Pi retry attempts without a success reset in between, so keep `maxStallRetries <= retry.maxRetries`. A successful assistant turn resets the stall counter (mirroring Pi's own retry counter). 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.
+
+Operational notes:
+
+- **Settings are read once per session,** on the first provider request. Editing `settings.json` mid-session changes nothing until you restart the session - that includes repairing an invalid block that already disabled the extension.
+- **A watchdog abort that the provider ignores escalates after a fixed 10s.** Any post-abort stream event re-arms that deadline (bytes prove only that the connection was alive at that instant), so a stream that emits a straggler and then wedges still escalates 10s after its last event. This reduces the hang; it cannot force the provider to stop, and undici's timeouts remain the final backstop.
+- **Headless runs report on stderr.** In `print`/`json` mode pi binds a no-op UI, so watchdog notices go out via `console.warn`. Nothing is ever written to stdout, which `json` mode uses for its protocol. In TUI and RPC the notices render as main-window notifications, not the bottom status line.
 
 ## Development
 

package/fast-mode.ts

@@ -22,6 +22,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Usage } from "@earendil-works/pi-ai";
 import { resolveConfig } from "./extension-config.ts";
 
 export const FAST_MODE_BETA = "fast-mode-2026-02-01";
@@ -29,6 +30,21 @@ export const FAST_SPEED = "fast";
 // Loose prefixes: match dated snapshots (claude-opus-4-8-*, claude-opus-5-*).
 // Opus 4.7 is out of scope (D1); a future model needs a one-line addition here.
 export const FAST_MODE_MODEL_PREFIXES = ["claude-opus-4-8", "claude-opus-5"];
+
+// Anthropic bills Opus 4.8/5 fast mode at exactly 2x standard rates; input,
+// output, and cache read/write all scale by the same factor because caching
+// multipliers "apply on top of fast mode pricing". Rate card:
+// https://docs.claude.com/en/docs/build-with-claude/fast-mode (retrieved 2026-08-04).
+export const FAST_MODE_COST_MULTIPLIER = 2;
+
+export function scaleCost(cost: Usage["cost"], multiplier: number): Usage["cost"] {
+	const input = cost.input * multiplier;
+	const output = cost.output * multiplier;
+	const cacheRead = cost.cacheRead * multiplier;
+	const cacheWrite = cost.cacheWrite * multiplier;
+	return { input, output, cacheRead, cacheWrite, total: input + output + cacheRead + cacheWrite };
+}
+
 export const OAUTH_IDENTITY_BETAS = ["claude-code-20250219", "oauth-2025-04-20"];
 const STATUS_KEY = "fast-mode";
 const BETA_HEADER = "anthropic-beta";
@@ -92,6 +108,10 @@ export function resolveEnabled(s: State): boolean {
 export default function (pi: ExtensionAPI) {
 	let liveOverride: boolean | null = null;
 	let enabled = false;
+	// Per-request snapshot. Safe as plain booleans because pi serializes provider
+	// requests per session (headers -> request -> message_end, awaited in order).
+	let pendingFastSpeed = false;
+	let pendingFastHeader = false;
 
 	const readFlag = (): boolean => pi.getFlag("fast") === true;
 
@@ -135,16 +155,43 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("before_provider_request", (event, ctx) => {
-		if (!shouldInject(enabled, ctx.model)) return;
-		return injectSpeed(event.payload);
+		if (!shouldInject(enabled, ctx.model)) {
+			pendingFastSpeed = false;
+			return;
+		}
+		const next = injectSpeed(event.payload);
+		pendingFastSpeed =
+			typeof next === "object" && next !== null && (next as Record<string, unknown>).speed === FAST_SPEED;
+		return next;
 	});
 
 	pi.on("before_provider_headers", async (event, ctx) => {
-		if (!shouldInject(enabled, ctx.model)) return;
-		if (!event.headers) return;
+		if (!shouldInject(enabled, ctx.model) || !event.headers) {
+			pendingFastHeader = false;
+			return;
+		}
 		const isOAuth = await detectOAuth(ctx);
-		if (isOAuth === null) return;
+		if (isOAuth === null) {
+			pendingFastHeader = false;
+			return;
+		}
 		event.headers[BETA_HEADER] = buildBetaHeader(event.headers[BETA_HEADER], isOAuth);
+		pendingFastHeader = true;
+	});
+
+	pi.on("message_end", (event) => {
+		const msg = event.message;
+		if (msg.role !== "assistant") return;
+		const corrected = pendingFastSpeed && pendingFastHeader && !!msg.usage?.cost;
+		pendingFastSpeed = false;
+		pendingFastHeader = false;
+		if (!corrected) return;
+		return {
+			message: {
+				...msg,
+				usage: { ...msg.usage, cost: scaleCost(msg.usage.cost, FAST_MODE_COST_MULTIPLIER) },
+			},
+		};
 	});
 
 	pi.registerCommand("fast", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "3.3.2",
+  "version": "3.4.1",
   "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",

package/provider-stall-watchdog.ts

@@ -4,12 +4,14 @@ import { readSettings, resolveConfig, settingsPaths } from "./extension-config.t
 export const MAX_TIMER_MS = 2_147_483_647;
 export const DEFAULT_CONFIG = {
 	enabled: false,
+	firstEventMs: 20_000,
 	warningMs: 120_000,
 	recoveryMs: 240_000,
 } as const;
 
 export type WatchdogConfig = {
 	enabled: boolean;
+	firstEventMs: number;
 	warningMs: number;
 	recoveryMs: number;
 	maxStallRetries: number;
@@ -24,6 +26,7 @@ export type WatchdogRuntime = {
 export type ConfigCandidate = {
 	blockIsObject?: unknown;
 	enabled?: unknown;
+	firstEventMs?: unknown;
 	warningMs?: unknown;
 	recoveryMs?: unknown;
 	maxStallRetries?: unknown;
@@ -37,11 +40,12 @@ const DEFAULT_CANDIDATE: ConfigCandidate = { blockIsObject: true, ...DEFAULT_CON
 
 export function coerce(raw: unknown): ConfigCandidate | undefined {
 	if (raw === undefined) return undefined;
+	if (typeof raw === "boolean") return { blockIsObject: true, enabled: raw };
 	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", "maxStallRetries"] as const) {
+	for (const key of ["enabled", "firstEventMs", "warningMs", "recoveryMs", "maxStallRetries"] as const) {
 		if (Object.hasOwn(source, key)) candidate[key] = source[key];
 	}
 	return candidate;
@@ -50,14 +54,16 @@ export function coerce(raw: unknown): ConfigCandidate | undefined {
 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.firstEventMs)) return { ok: false, error: "firstEventMs must be a positive timer delay" };
 	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" };
-	if (!isPositiveInteger(candidate.maxStallRetries)) return { ok: false, error: "maxStallRetries must be a positive integer" };
+	if (!isNonNegativeInteger(candidate.maxStallRetries)) return { ok: false, error: "maxStallRetries must be a non-negative integer" };
 	return {
 		ok: true,
 		config: {
 			enabled: candidate.enabled,
+			firstEventMs: candidate.firstEventMs,
 			warningMs: candidate.warningMs,
 			recoveryMs: candidate.recoveryMs,
 			maxStallRetries: candidate.maxStallRetries,
@@ -69,8 +75,8 @@ function isTimerDelay(value: unknown): value is number {
 	return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value > 0 && value <= MAX_TIMER_MS;
 }
 
-function isPositiveInteger(value: unknown): value is number {
-	return typeof value === "number" && Number.isInteger(value) && value > 0;
+function isNonNegativeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0;
 }
 
 /** Pi's own resolution is `settings.retry?.maxRetries ?? 3` over the same layered settings.json files. */
@@ -80,7 +86,7 @@ export function resolveRetryMaxRetries(cwd: string): number {
 		const retry = readSettings(path)?.retry;
 		if (retry === null || typeof retry !== "object" || Array.isArray(retry)) continue;
 		const value = (retry as Record<string, unknown>).maxRetries;
-		if (isPositiveInteger(value)) maxRetries = value;
+		if (isNonNegativeInteger(value)) maxRetries = value;
 	}
 	return maxRetries;
 }
@@ -100,8 +106,11 @@ const defaultRuntime: WatchdogRuntime = {
 };
 
 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.";
+// Reduces, but cannot eliminate, the hang when an aborted provider operation never terminates;
+// undici's headersTimeout/bodyTimeout stay the backstop past this point.
+const ABORT_GRACE_MS = 10_000;
 
-type Timer = { warning?: unknown; recovery?: unknown };
+type Timer = { firstEvent?: unknown; warning?: unknown; recovery?: unknown; abortGuard?: unknown };
 
 function formatElapsed(ms: number): string {
 	if (ms % 60_000 === 0) return `${ms / 60_000}m`;
@@ -109,6 +118,8 @@ function formatElapsed(ms: number): string {
 	return `${ms}ms`;
 }
 
+const ABORT_STUCK_NOTICE = `The stalled request did not stop within ${formatElapsed(ABORT_GRACE_MS)} of being aborted; the provider connection is unresponsive. No automatic retry will run - the turn will not end until the HTTP idle timeout expires.`;
+
 function warningNotice(config: WatchdogConfig): string {
 	return `No model progress for ${formatElapsed(config.warningMs)}; aborting and asking Pi to retry in ${formatElapsed(config.recoveryMs - config.warningMs)} (Esc aborts now)`;
 }
@@ -117,9 +128,20 @@ function exhaustedNotice(config: WatchdogConfig): string {
 	return `Stall retry budget (${config.maxStallRetries}) exhausted; aborting without another automatic retry. Submit the message again manually.`;
 }
 
+function firstEventRetryNotice(config: WatchdogConfig): string {
+	return `Provider sent no response for ${formatElapsed(config.firstEventMs)}; stopping and retrying the request.`;
+}
+
+function firstEventExhaustedNotice(config: WatchdogConfig): string {
+	return `Provider sent no response for ${formatElapsed(config.firstEventMs)} and the stall-retry budget is spent; the request was stopped.`;
+}
+
 export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRuntime): (pi: ExtensionAPI) => void {
 	return (pi) => {
-		let pendingInteractive = false;
+		let midStreamEnabled = false;
+		let firstEventSeen = false;
+		let hasUI = false;
+		let pendingTimeoutReason: string | undefined;
 		let activeRun = false;
 		let disabled = false;
 		let config: WatchdogConfig | undefined;
@@ -127,22 +149,25 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 		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: { notify(text: string, type?: string): void } | undefined;
 		let watchdogAbortedGeneration: number | undefined;
-		let timeoutConversionPending = false;
 		let stallRetriesUsed = 0;
 		let continuationStarted = false;
 		let convertedTimeout = false;
 
 		const clearTimers = () => {
-			if (timers.warning !== undefined) runtime.clearTimeout(timers.warning);
-			if (timers.recovery !== undefined) runtime.clearTimeout(timers.recovery);
+			for (const key of ["firstEvent", "warning", "recovery", "abortGuard"] as const) {
+				if (timers[key] !== undefined) runtime.clearTimeout(timers[key]);
+			}
 			timers = {};
 		};
+		const announce = (text: string, type?: string) => {
+			ui?.notify(text, type);
+			if (!hasUI) console.warn(text);
+		};
 		const clear = () => {
 			clearTimers();
 			removeSignalListener?.();
@@ -153,20 +178,81 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 		const resetRunState = () => {
 			disarm();
 			activeRun = false;
-			pendingInteractive = false;
 			stallRetriesUsed = 0;
 			continuationStarted = false;
 			convertedTimeout = false;
 			watchdogAbortedGeneration = undefined;
-			timeoutConversionPending = false;
+			pendingTimeoutReason = undefined;
+			firstEventSeen = false;
+		};
+		const armAbortGuard = (capturedGeneration: number) => {
+			if (timers.abortGuard !== undefined) runtime.clearTimeout(timers.abortGuard);
+			timers.abortGuard = runtime.setTimeout(() => {
+				if (capturedGeneration !== activeGeneration || !activeRun) return;
+				announce(ABORT_STUCK_NOTICE, "error");
+				// Only the timers go: the generation stays armed so a message_end arriving after the grace
+				// period still converts the abort the stall retry already paid for.
+				clearTimers();
+			}, ABORT_GRACE_MS);
 		};
-		const schedule = (ctx: { ui: typeof ui; abort(): void }) => {
+		// A stream event on a generation the watchdog already aborted: the stall cycle is over for this
+		// request, so nothing re-enters it. The bytes only prove the connection was alive at this instant,
+		// so the guard is re-armed rather than cleared - a wedge right after a straggler still escalates.
+		const postAbortStreamEvent = () => {
+			if (activeGeneration === undefined || watchdogAbortedGeneration !== activeGeneration) return false;
+			armAbortGuard(activeGeneration);
+			return true;
+		};
+		const abortStall = (
+			ctx: { abort(): void },
+			capturedGeneration: number,
+			notices: { retry: () => string; exhausted: () => string },
+			reason: string,
+		) => {
+			if (!config) return;
+			clearTimers();
+			warned = false;
+			watchdogAbortedGeneration = capturedGeneration;
+			// Armed before ctx.abort() so a synchronous teardown inside it cannot orphan the timer;
+			// the generation check makes the callback a no-op if that teardown disarmed the watchdog.
+			armAbortGuard(capturedGeneration);
+			if (stallRetriesUsed >= config.maxStallRetries) {
+				announce(notices.exhausted());
+				ctx.abort();
+				return;
+			}
+			pendingTimeoutReason = reason;
+			stallRetriesUsed += 1;
+			announce(notices.retry());
+			ctx.abort();
+		};
+		const armFirstEvent = (ctx: { abort(): void }) => {
 			if (activeGeneration === undefined || !config) return;
+			const cfg = config;
+			const capturedGeneration = activeGeneration;
+			const capturedDeadlineEpoch = ++deadlineEpoch;
+			const threshold = cfg.firstEventMs;
+			const run = () => {
+				if (capturedGeneration !== activeGeneration || capturedDeadlineEpoch !== deadlineEpoch || !activeRun || firstEventSeen) return;
+				const elapsed = runtime.now() - lastSemanticAt;
+				if (elapsed < threshold) {
+					timers.firstEvent = runtime.setTimeout(run, threshold - elapsed);
+					return;
+				}
+				abortStall(ctx, capturedGeneration, {
+					retry: () => firstEventRetryNotice(cfg),
+					exhausted: () => firstEventExhaustedNotice(cfg),
+				}, `Provider first-event timeout after ${cfg.firstEventMs} ms without a stream event`);
+			};
+			timers.firstEvent = runtime.setTimeout(run, threshold);
+		};
+		const schedule = (ctx: { abort(): void }) => {
+			if (activeGeneration === undefined || !config) return;
+			const cfg = config;
 			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;
+				if (capturedGeneration !== activeGeneration || capturedDeadlineEpoch !== deadlineEpoch || !activeRun) return;
 				const elapsed = runtime.now() - lastSemanticAt;
 				if (elapsed < threshold) {
 					timers[kind] = runtime.setTimeout(run(kind, threshold), threshold - elapsed);
@@ -174,51 +260,38 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 				}
 				if (kind === "warning" && !warned) {
 					warned = true;
-					ctx.ui?.notify(warningNotice(config), "warning");
+					announce(warningNotice(cfg), "warning");
 				}
 				if (kind === "recovery") {
-					clearTimers();
-					warned = false;
-					if (stallRetriesUsed >= config.maxStallRetries) {
-						ui?.notify(exhaustedNotice(config));
-						ctx.abort();
-						return;
-					}
-					watchdogAbortedGeneration = capturedGeneration;
-					timeoutConversionPending = true;
-					stallRetriesUsed += 1;
-					ui?.notify(`No model progress for ${formatElapsed(elapsed)}; aborting now. Pi will retry (${stallRetriesUsed}/${config.maxStallRetries}) if retry is enabled and capacity remains. Pending follow-ups are returned to the editor.`);
-					ctx.abort();
+					abortStall(ctx, capturedGeneration, {
+						retry: () => `No model progress for ${formatElapsed(elapsed)}; aborting now. Pi will retry (${stallRetriesUsed}/${cfg.maxStallRetries}) if retry is enabled and capacity remains. Pending follow-ups are returned to the editor.`,
+						exhausted: () => exhaustedNotice(cfg),
+					}, `Provider semantic timeout after ${cfg.recoveryMs} ms without progress`);
 				}
 			};
-			timers.warning = runtime.setTimeout(run("warning", config.warningMs), config.warningMs);
-			timers.recovery = runtime.setTimeout(run("recovery", config.recoveryMs), config.recoveryMs);
+			timers.warning = runtime.setTimeout(run("warning", cfg.warningMs), cfg.warningMs);
+			timers.recovery = runtime.setTimeout(run("recovery", cfg.recoveryMs), cfg.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;
+		pi.on("before_provider_request", (_event, ctx) => {
+			if (disabled) return;
+			ui = ctx.ui;
+			hasUI = ctx.hasUI;
+			if (!config) {
+				const resolved = resolveWatchdogConfig(ctx.cwd);
+				if (!resolved.ok) {
+					disabled = true;
+					announce(`providerStallWatchdog disabled: ${resolved.error}`, "warning");
+					return;
+				}
+				config = resolved.config;
 			}
-			config = resolved.config;
 			activeRun = config.enabled;
-		});
-		pi.on("before_provider_request", (_event, ctx) => {
-			if (!activeRun || ctx.mode !== "tui" || !config) return;
+			if (!activeRun) return;
 			disarm();
 			if (convertedTimeout) continuationStarted = true;
 			activeGeneration = ++generation;
 			lastSemanticAt = runtime.now();
-			ui = ctx.ui;
 			const target = ctx.signal;
 			if (target) {
 				const listener = () => {
@@ -227,11 +300,30 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 				target.addEventListener("abort", listener, { once: true });
 				removeSignalListener = () => target.removeEventListener("abort", listener);
 			}
+			midStreamEnabled = ctx.mode === "tui";
+			firstEventSeen = false;
+			armFirstEvent(ctx);
+		});
+		pi.on("message_start", (event, ctx) => {
+			// Pi fires message_start for user and toolResult messages too; only an assistant one is
+			// provider traffic, so the role check must stay ahead of the liveness re-arm below.
+			if (event.message.role !== "assistant") return;
+			if (postAbortStreamEvent()) return;
+			if (!activeRun || activeGeneration === undefined || firstEventSeen) return;
+			firstEventSeen = true;
+			if (timers.firstEvent !== undefined) {
+				runtime.clearTimeout(timers.firstEvent);
+				timers.firstEvent = undefined;
+			}
+			if (!midStreamEnabled || !config) return;
+			lastSemanticAt = runtime.now();
+			warned = false;
 			schedule(ctx);
 		});
 		pi.on("message_update", (event, ctx) => {
+			if (postAbortStreamEvent()) return;
 			const update = event.assistantMessageEvent;
-			if (activeGeneration === undefined || !(update.type === "text_delta" || update.type === "thinking_delta" || update.type === "toolcall_delta") || update.delta.length === 0) return;
+			if (!midStreamEnabled || !firstEventSeen || activeGeneration === undefined || !(update.type === "text_delta" || update.type === "thinking_delta" || update.type === "toolcall_delta") || update.delta.length === 0) return;
 			lastSemanticAt = runtime.now();
 			warned = false;
 			clearTimers();
@@ -239,25 +331,25 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 		});
 		pi.on("message_end", (event) => {
 			if (event.message.role !== "assistant") return;
-			const matchesWatchdogAbort = event.message.stopReason === "aborted"
-				&& activeGeneration === watchdogAbortedGeneration
-				&& timeoutConversionPending;
+			const errorMessage = pendingTimeoutReason;
+			pendingTimeoutReason = undefined;
+			const matchesWatchdogAbort = errorMessage !== undefined
+				&& event.message.stopReason === "aborted"
+				&& activeGeneration === watchdogAbortedGeneration;
 			disarm();
 			// Mirror Pi's retry loop, which resets its attempt counter on any successful assistant turn.
 			if (event.message.stopReason !== "aborted" && event.message.stopReason !== "error") stallRetriesUsed = 0;
-			if (!matchesWatchdogAbort || !config) return;
-			timeoutConversionPending = false;
+			if (!matchesWatchdogAbort) return;
 			convertedTimeout = true;
 			continuationStarted = false;
-			return { message: { ...event.message, stopReason: "error", errorMessage: `Provider semantic timeout after ${config.recoveryMs} ms without progress` } };
+			return { message: { ...event.message, stopReason: "error", errorMessage } };
 		});
 		pi.on("agent_end", () => disarm());
 		pi.on("agent_settled", () => {
-			if (convertedTimeout && !continuationStarted) ui?.notify(DEGRADATION_NOTICE);
+			if (convertedTimeout && !continuationStarted) announce(DEGRADATION_NOTICE);
 			resetRunState();
 		});
 		pi.on("session_shutdown", () => {
-			epoch += 1;
 			resetRunState();
 			config = undefined;
 			disabled = false;