@matthewfl/pi-jtodo 0.0.2 → 0.0.3

package/README.md

@@ -41,6 +41,7 @@ Deliberately **not** ported from jcode: the `/overnight` mission mode (presumes
 - **Write-time gate**: a write that closes a group (or the implicit ungrouped list) without an honest `end_to_end_ownership` claim is **rejected whole** — stored state is returned unchanged with an actionable message naming the failing groups. A first plan write with severely low intent gets an immediate in-band continuation.
 - **Turn-end gates** (when the agent settles): incomplete todos → auto-poke ("You have N incomplete todos. Continue working, or update the todo tool."). Fully settled → the deferred quality digest (intent/feedback-loop weak points), then the completion-confidence and confidence-spike gates — each naming the flagged `#id`s — with an attempt budget, an unchanged-signature early stop, and a done notice when validation passes.
 - **Follow-ups are attributed**: pokes, digests, and gate challenges travel as custom messages (LLM-visible as user-role text, transcript-visible as `pi-jtodo/followup`), so reload/resume never re-renders them as user prompts.
+- **The poke waits `pokeDelayMs` before firing** (default 20s, pi-simple-goal's restart-countdown pattern): when the agent stops with open todos the settle schedules the poke instead of sending it, and the widget shows `· poke in Ns` counting down. **If the user starts typing during the window, the poke is canceled and poking pauses** until the next agent run, so a user who is about to take over is never fought by the machine. The completion/spike gates, the deferred digest, the watchdog re-fire, and manual `/todos poke on|trigger` stay immediate — gates respond to the agent's own claims, manual pokes are explicit.
 - **Escape pauses, it does not silence** (pi-simple-goal pattern): a raw `\x1b` keypress within 5s of an aborted run marks it as the user's stop — the settle is quiet and the poke pauses until the user re-engages; the next agent run lifts the pause and re-arms. Aborts with no recent Escape behind them are machinery (compaction, `ctx.abort()`, transport, provider stacks mislabeling the interrupt as an error): their settle is quiet but the cycle stays armed and the starvation watchdog covers a lost continuation. The only sticky off is `/todos poke off`.
 
 ## Display
@@ -56,6 +57,7 @@ Deliberately **not** ported from jcode: the `/overnight` mission mode (presumes
 {
 	"enabled": true,
 	"autoPoke": true,
+	"pokeDelayMs": 20000,
 	"completionGateMaxAttempts": 5,
 	"maxGateObservations": 256,
 	"maxConsecutivePokesWithoutProgress": 0,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@matthewfl/pi-jtodo",
-	"version": "0.0.2",
+	"version": "0.0.3",
 	"description": "Quality-gated todo tool for Pi: confidence scores with tool-owned histories, plan and per-goal assessments, write-time ownership rejection, turn-end completion/spike gates, deferred quality digests, auto-poke continuation, starvation watchdog, and a live todo strip.",
 	"type": "module",
 	"scripts": {

package/src/config.ts

@@ -2,6 +2,7 @@
  * Optional per-user configuration: ~/.pi/agent/state/pi-jtodo/config.json
  * Missing or unreadable config falls back to defaults. Gate thresholds are
  * calibration constants (see constants.ts) and deliberately NOT configurable.
+ * PI_JTODO_STATE_DIR overrides the state directory (embedding/tests).
  */
 
 import * as fs from "node:fs";
@@ -13,6 +14,13 @@ export interface TodoConfig {
 	enabled: boolean;
 	/** Arm the auto-poke cycle when each session starts (TUI/RPC only). */
 	autoPoke: boolean;
+	/**
+	 * Delay before the settle poke fires when the agent stops with open
+	 * todos (pi-simple-goal restartDelayMs pattern). While the poke waits,
+	 * any terminal input (the user starts typing) cancels it and pauses
+	 * poking until the next agent run. 0 = immediate (pure jcode).
+	 */
+	pokeDelayMs: number;
 	/** Turn-end re-validation budget before the gate stalls and disarms. */
 	completionGateMaxAttempts: number;
 	/** Cap on the turn-scoped observation log; oldest dropped first. */
@@ -38,6 +46,7 @@ export interface TodoConfig {
 export const DEFAULT_CONFIG: TodoConfig = {
 	enabled: true,
 	autoPoke: true,
+	pokeDelayMs: 20_000,
 	completionGateMaxAttempts: TODO_COMPLETION_GATE_MAX_ATTEMPTS,
 	maxGateObservations: MAX_GATE_OBSERVATIONS,
 	maxConsecutivePokesWithoutProgress: 0,
@@ -52,14 +61,10 @@ export const DEFAULT_CONFIG: TodoConfig = {
 
 export function loadConfig(): TodoConfig {
 	try {
-		const p = path.join(
-			os.homedir(),
-			".pi",
-			"agent",
-			"state",
-			"pi-jtodo",
-			"config.json",
-		);
+		const stateDir =
+			process.env.PI_JTODO_STATE_DIR ??
+			path.join(os.homedir(), ".pi", "agent", "state", "pi-jtodo");
+		const p = path.join(stateDir, "config.json");
 		const parsed = JSON.parse(fs.readFileSync(p, "utf8"));
 		if (typeof parsed === "object" && parsed !== null) {
 			return { ...DEFAULT_CONFIG, ...parsed };

package/src/index.ts

@@ -90,6 +90,7 @@ import { normalizeTodoInput } from "./normalize.js";
 import { TodoParams, type TodoParamsInput } from "./schema.js";
 import { TodoListComponent } from "./viewer.js";
 import { TODO_WIDGET_ID, makeTodoWidget } from "./widget.js";
+import { createPokeScheduler } from "./poke-scheduler.js";
 import { createWatchdog } from "./watchdog.js";
 
 // ============================================================================
@@ -167,6 +168,15 @@ export default function (pi: ExtensionAPI) {
 	// re-arms, per the user's "stop the poke for the next while" rule.
 	let escPokePaused = false;
 	let unsubscribeTerminalInput: (() => void) | undefined;
+	// pi-simple-goal restartDelayMs pattern (see sendSettlePoke): the settle
+	// poke can wait pokeDelayMs before firing; any terminal input during the
+	// window cancels it and pauses poking until the next agent run.
+	// 0 = immediate (pure jcode).
+	const pokeScheduler = createPokeScheduler(config.pokeDelayMs);
+	let pokeTickTimer: NodeJS.Timeout | undefined;
+	// Whether the raw-input listener is subscribed (TUI only). A delayed
+	// poke is only safe when typing can cancel it; otherwise fire immediately.
+	let terminalInputActive = false;
 	// Whether poking is allowed at all. session_start (when emitted — the
 	// SDK harness and some embedders never emit it) re-derives this from
 	// its ctx.hasUI; elsewhere starts optimistic, matching the module-level
@@ -181,6 +191,7 @@ export default function (pi: ExtensionAPI) {
 	let idleNudgeSent = false;
 
 	function disarm() {
+		cancelPendingPoke();
 		autoPokeArmed = false;
 		lastPokeTargets = undefined;
 		cycle = freshCycleFlags();
@@ -255,6 +266,7 @@ export default function (pi: ExtensionAPI) {
 						() => ({
 							armed: autoPokeArmed,
 							escPaused: escPokePaused,
+							pokePendingAt: pokeScheduler.deadlineAt(),
 							gateAttempts: cycle.gateAttempts,
 							gateMaxAttempts: config.completionGateMaxAttempts,
 							pokeTargets: lastPokeTargets,
@@ -268,6 +280,55 @@ export default function (pi: ExtensionAPI) {
 		}
 	}
 
+	/** Cancel a pending delayed poke (if any) and stop its countdown tick. */
+	function cancelPendingPoke(): void {
+		pokeScheduler.cancel();
+		if (pokeTickTimer !== undefined) {
+			clearInterval(pokeTickTimer);
+			pokeTickTimer = undefined;
+		}
+	}
+
+	/**
+	 * Send the settle poke, honoring pokeDelayMs (pi-simple-goal's restart
+	 * countdown pattern): schedule it so the user can take over during the
+	 * window — any typing cancels the poke and pauses the cycle — or fire
+	 * immediately when no delay is configured, the raw-input listener is not
+	 * subscribed (nothing could cancel it), or this is a manual trigger.
+	 */
+	function sendSettlePoke(ctx: ExtensionContext, immediate: boolean): void {
+		const fire = (): void => {
+			cancelPendingPoke();
+			const todos = incompleteTodos();
+			if (!config.enabled || !autoPokeArmed || escPokePaused || todos.length === 0) {
+				return; // state changed while the poke waited
+			}
+			if (watchdogCtx && !watchdogCtx.isIdle()) {
+				return; // something already restarted the agent
+			}
+			watchdog.notifyActivity();
+			lastPokeTargets = new Set(todos.map((t) => t.id));
+			notify(
+				ctx,
+				`👉 ${todos.length} incomplete todo${todos.length === 1 ? "" : "s"}. We poked it for you. ${NOTICE_POKE_OFF_HINT}`,
+			);
+			void sendGateFollowUp(buildAutoPokeMessage(todos.length));
+			refreshWidget(ctx);
+		};
+		if (!immediate && config.pokeDelayMs > 0 && terminalInputActive) {
+			pokeScheduler.schedule(fire);
+			if (pokeTickTimer === undefined) {
+				pokeTickTimer = setInterval(() => {
+					if (watchdogCtx) refreshWidget(watchdogCtx);
+				}, 1000);
+				if (typeof pokeTickTimer.unref === "function") pokeTickTimer.unref();
+			}
+			refreshWidget(ctx); // surface "poke in Ns" immediately
+		} else {
+			fire();
+		}
+	}
+
 	// ------------------------------------------------------------------------
 	// Branch-aware state (replaces jcode's per-session JSON files)
 	// ------------------------------------------------------------------------
@@ -481,7 +542,7 @@ export default function (pi: ExtensionAPI) {
 	 * completion-confidence and spike gates (budgeted), then disarm with a
 	 * done notice.
 	 */
-	async function runTurnEndCheck(ctx: ExtensionContext): Promise<void> {
+	async function runTurnEndCheck(ctx: ExtensionContext, immediatePoke = false): Promise<void> {
 		const todos = state.todos;
 		if (todos.length === 0) {
 			// jcode: a settle with no todos at all silently disarms the poke.
@@ -492,6 +553,12 @@ export default function (pi: ExtensionAPI) {
 
 		const incomplete = incompleteTodos();
 		if (incomplete.length > 0) {
+			if (escPokePaused) {
+				// The user paused poking (Escape, or typing during the poke
+				// window): quiet until the next agent run lifts the pause.
+				refreshWidget(ctx);
+				return;
+			}
 			cycle.gateAttempts = 0;
 			if (config.maxConsecutivePokesWithoutProgress > 0) {
 				const signature = JSON.stringify(
@@ -509,12 +576,10 @@ export default function (pi: ExtensionAPI) {
 					return;
 				}
 			}
-			notify(
-				ctx,
-				`👉 ${incomplete.length} incomplete todo${incomplete.length === 1 ? "" : "s"}. We poked it for you. ${NOTICE_POKE_OFF_HINT}`,
-			);
-			lastPokeTargets = new Set(incomplete.map((t) => t.id));
-			await sendGateFollowUp(buildAutoPokeMessage(incomplete.length));
+			// The poke itself may be delayed (pokeDelayMs): sendSettlePoke
+			// schedules it so the user can take over by typing, or fires
+			// immediately for manual /todos poke triggers.
+			sendSettlePoke(ctx, immediatePoke);
 			return;
 		}
 
@@ -603,6 +668,8 @@ export default function (pi: ExtensionAPI) {
 		isIdle: () => watchdogCtx?.isIdle() ?? false,
 		incompleteCount: () => incompleteTodos().length,
 		wasAborted: () => lastRunAborted,
+		// The watchdog must not inject through an Esc- or typing-pause either.
+		isPaused: () => escPokePaused,
 		idleMs: config.watchdogIdleMs,
 		maxRePokes: config.watchdogMaxRePokes,
 		onFire: () => {
@@ -798,7 +865,7 @@ export default function (pi: ExtensionAPI) {
 				ctx.ui.notify("Poke queued. We'll re-check for unfinished todos after this turn.", "info");
 				return;
 			}
-			await runTurnEndCheck(ctx);
+			await runTurnEndCheck(ctx, true);
 			refreshWidget(ctx);
 			return;
 		}
@@ -827,6 +894,9 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("agent_start", (_event, ctx) => {
+		// A pending delayed poke is moot once a new run starts: this run's
+		// settle will schedule a fresh one if todos remain open.
+		cancelPendingPoke();
 		// A new run means the user (or machinery) re-engaged: an Esc pause
 		// lifts outside the abort-correlation window where the just-triggered
 		// teardown is still settling (pi-simple-goal's maybeResumeOnActivity).
@@ -854,6 +924,7 @@ export default function (pi: ExtensionAPI) {
 	pi.on("session_start", (_event, ctx) => {
 		watchdogCtx = ctx;
 		watchdog.notifyActivity();
+		cancelPendingPoke(); // a stale delayed poke never crosses sessions
 		idleNudgeSent = false;
 		pendingObservations.length = 0;
 		cycle = freshCycleFlags();
@@ -875,14 +946,32 @@ export default function (pi: ExtensionAPI) {
 			const uictx = ctx as { mode?: string; ui: { onTerminalInput?: (cb: (data: string) => unknown) => () => void } };
 			if (uictx.mode === "tui" && typeof uictx.ui.onTerminalInput === "function") {
 				unsubscribeTerminalInput = uictx.ui.onTerminalInput((data) => {
+					watchdog.notifyActivity(); // any keystroke is user activity
 					if (data === "\x1b" || data === "\x1b\x1b" || data === "\x1b[27u") {
 						lastEscapeAt = Date.now();
+						// Escape = manual control (goal-plugin pattern): cancel any
+						// pending delayed poke and hold poking until the next run.
+						cancelPendingPoke();
+						if (!escPokePaused) {
+							escPokePaused = true;
+							refreshWidget(ctx);
+						}
+						return undefined;
+					}
+					if (pokeScheduler.isPending()) {
+						// Typing during the poke window cancels the poke and pauses
+						// the cycle (pi-simple-goal restart-countdown behavior).
+						cancelPendingPoke();
+						escPokePaused = true;
+						refreshWidget(ctx);
 					}
 					return undefined;
 				});
+				terminalInputActive = true;
 			}
 		} catch {
 			// Non-TUI or older pi: aborts fall back to machinery classification.
+			terminalInputActive = false;
 		}
 		reconstructState(ctx);
 		refreshWidget(ctx);
@@ -917,6 +1006,12 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("session_shutdown", () => {
 		clearInterval(watchdogTimer);
+		cancelPendingPoke();
+		if (unsubscribeTerminalInput) {
+			unsubscribeTerminalInput();
+			unsubscribeTerminalInput = undefined;
+		}
+		terminalInputActive = false;
 		watchdogCtx = undefined;
 	});
 

package/src/poke-scheduler.ts

@@ -0,0 +1,54 @@
+/**
+ * Pure delayed-poke scheduler (pi-simple-goal restartDelayMs pattern).
+ *
+ * The settle poke can be delayed (config.pokeDelayMs): while a poke is
+ * pending, any terminal input cancels it and pauses poking until the next
+ * agent run (see index.ts). This module owns only the timer lifecycle so it
+ * can be unit-tested without pi. A delayMs of 0 fires synchronously, which
+ * preserves the immediate (pure jcode) behavior with no branching at the
+ * call sites.
+ */
+
+export interface PokeScheduler {
+	/** Schedule a delayed poke, replacing any pending one. */
+	schedule(fire: () => void): void;
+	/** Cancel the pending poke (if any). */
+	cancel(): void;
+	/** Whether a poke is currently scheduled and waiting. */
+	isPending(): boolean;
+	/** Epoch ms when the pending poke fires; 0 when none pending. */
+	deadlineAt(): number;
+}
+
+export function createPokeScheduler(delayMs: number): PokeScheduler {
+	let timer: NodeJS.Timeout | undefined;
+	let deadline = 0;
+
+	const clear = (): void => {
+		if (timer !== undefined) {
+			clearTimeout(timer);
+			timer = undefined;
+		}
+		deadline = 0;
+	};
+
+	return {
+		schedule(fire: () => void): void {
+			if (delayMs <= 0) {
+				fire();
+				return;
+			}
+			clear();
+			deadline = Date.now() + delayMs;
+			timer = setTimeout(() => {
+				timer = undefined;
+				deadline = 0;
+				fire();
+			}, delayMs);
+			if (typeof timer.unref === "function") timer.unref();
+		},
+		cancel: clear,
+		isPending: (): boolean => timer !== undefined,
+		deadlineAt: (): number => deadline,
+	};
+}

package/src/watchdog.ts

@@ -19,6 +19,8 @@ export interface WatchdogDeps {
 	isIdle: () => boolean;
 	incompleteCount: () => number;
 	wasAborted: () => boolean;
+	/** Esc- or typing-paused cycle: the watchdog must not inject either. */
+	isPaused: () => boolean;
 	idleMs: number;
 	maxRePokes: number;
 	/** Re-send the auto-poke follow-up (fire-and-forget is fine). */
@@ -49,6 +51,13 @@ export function createWatchdog(deps: WatchdogDeps): Watchdog {
 				lastActivity = now;
 				return;
 			}
+			if (deps.isPaused()) {
+				// A paused cycle (Escape, or typing during the poke window) means
+				// the user took control; the watchdog stays quiet and the window
+				// restarts so unpausing (next agent run) gets a fresh idle period.
+				lastActivity = now;
+				return;
+			}
 			if (deps.incompleteCount() === 0) {
 				lastActivity = now;
 				rePokes = 0;

package/src/widget.ts

@@ -32,6 +32,8 @@ export interface WidgetRuntime {
 	armed: boolean;
 	/** An Escape-paused cycle: suppressed until the user re-engages */
 	escPaused?: boolean;
+	/** Epoch ms when a delayed poke fires; 0 = none pending (pokeDelayMs). */
+	pokePendingAt?: number;
 	gateAttempts: number;
 	gateMaxAttempts: number;
 	/** Ids of the todos that caused the most recent poke/gate challenge */
@@ -107,11 +109,20 @@ function buildLeftColumn(
 	// user has been seeing.
 	let status: string;
 	if (!allSettled) {
-		status = runtime.armed
-			? "· auto-poke"
-			: runtime.escPaused
+		const pendingIn =
+			runtime.pokePendingAt && runtime.pokePendingAt > 0
+				? Math.max(1, Math.ceil((runtime.pokePendingAt - Date.now()) / 1000))
+				: 0;
+		// A pause (Escape, or typing during the poke window) outranks the armed
+		// state: the cycle stays armed underneath but is held, so the user must
+		// see "poke paused", not a misleading "auto-poke".
+		status = runtime.escPaused
 				? "· poke paused"
-				: "· poke off";
+				: runtime.armed
+					? pendingIn > 0
+						? `· poke in ${pendingIn}s`
+						: "· auto-poke"
+					: "· poke off";
 	} else if (summary.needs_validation) {
 		status =
 			runtime.gateAttempts > 0

package/tests/test-todo.cjs

@@ -17,6 +17,13 @@ const os = require("node:os");
 const path = require("node:path");
 const fs = require("node:fs");
 
+// Point the extension's config at a scratch state dir BEFORE its module
+// loads: the e2e suite runs with a fast pokeDelayMs (400ms) so delayed-poke
+// scenarios exercise the real scheduler without waiting the real 20s.
+const TEST_STATE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "pi-jtodo-cfg-"));
+fs.writeFileSync(path.join(TEST_STATE_DIR, "config.json"), JSON.stringify({ pokeDelayMs: 400 }));
+process.env.PI_JTODO_STATE_DIR = TEST_STATE_DIR;
+
 let PI_PKG;
 try {
 	PI_PKG = path.dirname(require.resolve("@earendil-works/pi-coding-agent/package.json"));
@@ -39,6 +46,31 @@ function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
 
 async function freshSession(extraLoaderOptions) {
 	const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "pi-jtodo-test-"));
+	// Recording UI context: bindExtensions() fires session_start (arming +
+	// branch replay + raw-input listener), widgets/notices are recorded, and
+	// tests can inject synthetic keystrokes (the Esc/typing paths are
+	// TUI-only otherwise — this closes the harness blind spot).
+	const rec = { inputHandler: undefined, widgets: [], notifies: [] };
+	const uiContext = {
+		select: async () => undefined,
+		confirm: async () => false,
+		input: async () => undefined,
+		editor: async () => undefined,
+		notify: (message, type) => { rec.notifies.push({ message, type }); },
+		onTerminalInput: (handler) => {
+			rec.inputHandler = handler;
+			return () => { if (rec.inputHandler === handler) rec.inputHandler = undefined; };
+		},
+		setStatus: () => {},
+		setWorkingMessage: () => {},
+		setWorkingVisible: () => {},
+		setWorkingIndicator: () => {},
+		setWidget: (key, content) => {
+			const i = rec.widgets.findIndex((w) => w.key === key);
+			if (i >= 0) rec.widgets.splice(i, 1);
+			if (content !== undefined) rec.widgets.push({ key, content });
+		},
+	};
 	const loader = new pi.DefaultResourceLoader({
 		cwd,
 		agentDir: pi.getAgentDir(),
@@ -53,7 +85,10 @@ async function freshSession(extraLoaderOptions) {
 		resourceLoader: loader,
 		tools: ["todo"],
 	});
+	await session.bindExtensions({ uiContext, mode: "tui" });
 	return {
+		rec,
+		sendKeys: (data) => { if (rec.inputHandler) rec.inputHandler(data); },
 		session,
 		exec: (params, signal) =>
 			session
@@ -389,7 +424,7 @@ async function suiteA() {
 			alias: { "@earendil-works/pi-tui": `${PI_PKG}/node_modules/@earendil-works/pi-tui/dist/index.js` },
 		});
 		const { createWatchdog } = await jiti.import(path.join(EXT_DIR, "watchdog.ts"));
-		let t = 0, armed = true, idle = true, open = 3, aborted = false;
+		let t = 0, armed = true, idle = true, open = 3, aborted = false, paused = false;
 		const fires = [], starves = [];
 		const wd = createWatchdog({
 			now: () => t,
@@ -397,6 +432,7 @@ async function suiteA() {
 			isIdle: () => idle,
 			incompleteCount: () => open,
 			wasAborted: () => aborted,
+			isPaused: () => paused,
 			idleMs: 90_000,
 			maxRePokes: 3,
 			onFire: (n) => fires.push(n),
@@ -428,10 +464,47 @@ async function suiteA() {
 		// unarmed never fires
 		armed = false; aborted = false; t += 400_000; wd.tick();
 		const unarmedQuiet = fires.length === 4;
-		if (fires[0] === 1 && fires[1] === 2 && postponed && capped && resetWorks && settledQuiet && abortWins && unarmedQuiet) {
-			ok("T14 watchdog", "fire/postpone/cap/reset/settled-quiet/abort/unarmed all correct");
+		// paused cycle (Esc or typing took over): watchdog stays quiet and the
+		// idle window restarts each paused tick, so unpausing gets a fresh window
+		armed = true; paused = true; t += 400_000; wd.tick();
+		const pausedQuiet = fires.length === 4;
+		paused = false; t += 50_000; wd.tick(); // window restarted by the paused tick
+		const pausedWindowRestarted = fires.length === 4;
+		t += 91_000; wd.tick(); // fresh full window after unpausing -> 5th fire
+		const resumedAfterPause = fires.length === 5 && fires.at(-1) === 1;
+		if (fires[0] === 1 && fires[1] === 2 && postponed && capped && resetWorks && settledQuiet && abortWins && unarmedQuiet && pausedQuiet && pausedWindowRestarted && resumedAfterPause) {
+			ok("T14 watchdog", "fire/postpone/cap/reset/settled-quiet/abort/unarmed/paused-quiet all correct");
 		} else {
-			bad("T14 watchdog", JSON.stringify({ fires, starves, postponed, capped, resetWorks, settledQuiet, abortWins, unarmedQuiet }));
+			bad("T14 watchdog", JSON.stringify({ fires, starves, postponed, capped, resetWorks, settledQuiet, abortWins, unarmedQuiet, pausedQuiet, pausedWindowRestarted, resumedAfterPause }));
+		}
+	});
+
+	// T20: delayed-poke scheduler (pure timer module, real clock).
+	await run("T20 poke scheduler", async () => {
+		const { createJiti } = require(`${PI_PKG}/node_modules/jiti/lib/jiti.cjs`);
+		const jiti = createJiti(__filename, {
+			alias: { "@earendil-works/pi-tui": `${PI_PKG}/node_modules/@earendil-works/pi-tui/dist/index.js` },
+		});
+		const { createPokeScheduler } = await jiti.import(path.join(EXT_DIR, "poke-scheduler.ts"));
+		const fired = [];
+		const s = createPokeScheduler(80);
+		const idleStart = !s.isPending() && s.deadlineAt() === 0;
+		s.schedule(() => fired.push("a"));
+		const pending = s.isPending() && s.deadlineAt() > Date.now();
+		s.cancel();
+		const cancelWorks = !s.isPending() && fired.length === 0 && s.deadlineAt() === 0;
+		s.schedule(() => fired.push("a"));
+		s.schedule(() => fired.push("b")); // replaces the pending poke
+		await sleep(200);
+		const firedOnceLatest = fired.join(",") === "b" && !s.isPending();
+		const zeroDelay = createPokeScheduler(0);
+		const syncFired = [];
+		zeroDelay.schedule(() => syncFired.push("now"));
+		const immediate = syncFired.join(",") === "now" && !zeroDelay.isPending();
+		if (idleStart && pending && cancelWorks && firedOnceLatest && immediate) {
+			ok("T20 poke scheduler", "schedule/cancel/deadline/replacement/zero-delay all correct");
+		} else {
+			bad("T20 poke scheduler", JSON.stringify({ idleStart, pending, cancelWorks, firedOnceLatest, immediate, fired }));
 		}
 	});
 
@@ -954,7 +1027,7 @@ async function runScenario(name, script, assertions) {
 			});
 		},
 	};
-	await run(name, async ({ session }) => {
+	await run(name, async ({ session, rec }) => {
 		await session.setModel(MOCK_MODEL);
 		let abortTimerFired = false;
 		if (script.abortAtCall) {
@@ -965,6 +1038,17 @@ async function runScenario(name, script, assertions) {
 			const abortWhenStarted = () => {
 				if (calls.length >= script.abortAtCall) {
 					abortTimerFired = true;
+					// Raw Escape first (TUI Esc = user stop): this is exactly what the
+					// real terminal delivers to the listener before pi aborts the run.
+					if (script.escBeforeAbort && rec.inputHandler) {
+						rec.inputHandler("\x1b");
+						try {
+							const w = rec.widgets.find((x) => x.key === "pi-jtodo");
+							const th = { fg: (_c, s) => String(s), bold: (s) => String(s) };
+							const component = typeof w?.content === "function" ? w.content(null, th) : w?.content;
+							script.escPaint = (component?.render?.(120) ?? []).map(String);
+						} catch { script.escPaint = []; }
+					}
 					if (script.compactInsteadOfAbort) session.compact();
 					else session.abort();
 					// Safety net: if the abort somehow never reaches the mock, release
@@ -982,11 +1066,35 @@ async function runScenario(name, script, assertions) {
 		let prompted = false;
 		let aborted = false;
 		let resumed = false;
+		let inputArmed = false;
+		let inputSent = false;
 		while (Date.now() < deadline) {
 			if (!prompted && script.promptAfter && calls.length >= script.promptAfter) {
 				prompted = true;
 				void session.prompt(script.promptText ?? "continue");
 			}
+			if (!inputArmed && script.inputAfter && calls.length >= script.inputAfter.call) {
+				inputArmed = true;
+				// Synthetic keystroke lands while the session is idle with a poke
+				// pending (the typing/Esc paths are TUI-only otherwise).
+				setTimeout(() => {
+					inputSent = true;
+					if (rec.inputHandler) rec.inputHandler(script.inputAfter.data);
+					// Snapshot the paint synchronously: the widget is a live thunk
+					// factory, so building + rendering it later would show the final
+					// state instead of the paused moment.
+					try {
+						const w = rec.widgets.find((x) => x.key === "pi-jtodo");
+						const th = { fg: (_c, s) => String(s), bold: (s) => String(s) };
+						const component = typeof w?.content === "function" ? w.content(null, th) : w?.content;
+						script.inputAfter.paint = (component?.render?.(120) ?? []).map(String);
+					} catch { script.inputAfter.paint = []; }
+				}, script.inputAfter.atMs);
+			}
+			if (inputSent && script.promptAfterInput && !prompted) {
+				prompted = true;
+				void session.prompt(script.promptText ?? "resume");
+			}
 			if (!aborted && script.abortAtCall && calls.length >= script.abortAtCall) {
 				aborted = true; // bookkeeping only; the timer above fired the Esc
 				if (!abortTimerFired) session.abort();
@@ -1016,7 +1124,7 @@ async function runScenario(name, script, assertions) {
 			(e) => e.type === "message" && e.message?.role === "toolResult" && e.message?.toolName === "todo",
 		);
 		const lastDetails = todoResults.at(-1)?.message?.details;
-		await assertions({ calls, customs, lastDetails, entries });
+		await assertions({ calls, customs, lastDetails, entries, widgets: rec.widgets });
 	}, { extensionFactories: [mockFactory] });
 }
 
@@ -1266,6 +1374,127 @@ async function suiteB() {
 		if (stopReasons.includes("aborted")) ok("B6 compaction abort recorded", `stopReasons=${JSON.stringify(stopReasons)}`);
 		else bad("B6 compaction abort recorded", `no aborted stopReason; stopReasons=${JSON.stringify(stopReasons)}`);
 	});
+
+	// B7: typing during the pokeDelayMs window cancels the pending poke and
+	// pauses the cycle; the pause lifts at the next agent run (goal-plugin
+	// pattern) and the resumed run finishes cleanly.
+	const SCRIPT_B7 = {
+		call(step) {
+			if (step === 1) {
+				return {
+					type: "toolCall", id: "call-open", name: "todo",
+					arguments: {
+						todos: [{ content: "typing-cancel guard", status: "in_progress", priority: "high", id: "t1", group: "tc", confidence: 96 }],
+						plan: { user_intention: "typing cancel e2e", understands_user_intent: 97 },
+						goals: [{ group: "tc", closed_feedback_loop: 97, feedback_loop: "typing cancels the pending poke" }],
+					},
+				};
+			}
+			if (step === 3) {
+				return {
+					type: "toolCall", id: "call-done", name: "todo",
+					arguments: {
+						todos: [{ content: "typing-cancel guard", status: "completed", priority: "high", id: "t1", group: "tc", confidence: 96, completion_confidence: 96 }],
+						goals: [{ group: "tc", closed_feedback_loop: 97, feedback_loop: "typing cancels the pending poke", end_to_end_ownership: 96 }],
+					},
+				};
+			}
+			return null;
+		},
+		text(step) {
+			if (step === 2) return "Todos written.";
+			return "Done after the resume.";
+		},
+		inputAfter: { call: 2, atMs: 150, data: "x" },
+		promptAfterInput: true,
+		promptText: "resume working on the todos",
+		calls: 4,
+	};
+	await runScenario("B7 typing cancels the pending poke", SCRIPT_B7, async ({ customs, widgets, lastDetails }) => {
+		if (customs.length === 0) ok("B7 typing cancel + pause", "the user keystroke canceled the pending poke; the resume run lifted the pause and finished quietly");
+		else bad("B7 typing cancel + pause", `customs=${JSON.stringify(customs.map((t) => t.slice(0, 60)))}`);
+		const pausedPaint = SCRIPT_B7.inputAfter.paint?.some((l) => l.includes("poke paused"));
+		if (pausedPaint) ok("B7 widget pause paint", "the widget bottom line rendered 'poke paused' while held");
+		else bad("B7 widget pause paint", JSON.stringify(SCRIPT_B7.inputAfter.paint ?? null, (k, v) => (typeof v === "string" ? v.replace(/\x1b\[[0-9;]*m/g, "") : v)));
+		const done = lastDetails?.todos?.[0]?.status === "completed";
+		if (done) ok("B7 resume completed the todo", "the resumed run closed the item and the cycle ended clean");
+		else bad("B7 resume completed the todo", JSON.stringify(lastDetails?.todos));
+	});
+
+	// B8: Escape during the poke window cancels the pending poke and holds the
+	// pause for the Esc window; a resume inside that window stays quiet.
+	const SCRIPT_B8 = {
+		call(step) {
+			if (step === 1) {
+				return {
+					type: "toolCall", id: "call-open", name: "todo",
+					arguments: {
+						todos: [{ content: "esc-window guard", status: "in_progress", priority: "high", id: "e1", group: "ew", confidence: 96 }],
+						plan: { user_intention: "esc window e2e", understands_user_intent: 97 },
+						goals: [{ group: "ew", closed_feedback_loop: 97, feedback_loop: "esc holds the pause inside the window" }],
+					},
+				};
+			}
+			return null;
+		},
+		text(step) {
+			if (step === 2) return "Todos written.";
+			return "Resumed inside the Esc window, still working.";
+		},
+		inputAfter: { call: 2, atMs: 150, data: "\x1b" },
+		promptAfterInput: true,
+		promptText: "resume while the Esc window is open",
+		calls: 3,
+	};
+	await runScenario("B8 Esc during poke window holds the pause", SCRIPT_B8, async ({ customs, widgets }) => {
+		if (customs.length === 0) ok("B8 esc cancel + held pause", "Escape canceled the pending poke and the in-window resume settle stayed quiet");
+		else bad("B8 esc cancel + held pause", `customs=${JSON.stringify(customs.map((t) => t.slice(0, 60)))}`);
+		const pausedPaint = SCRIPT_B8.inputAfter.paint?.some((l) => l.includes("poke paused"));
+		if (pausedPaint) ok("B8 widget pause paint", "'poke paused' rendered during the held pause");
+		else bad("B8 widget pause paint", JSON.stringify(SCRIPT_B8.inputAfter.paint ?? null, (k, v) => (typeof v === "string" ? v.replace(/\x1b\[[0-9;]*m/g, "") : v)));
+	});
+
+	// B9: a raw Escape observed right before an abort classifies the run as the
+	// user's stop — the settle disarms and pauses instead of re-poking. This is
+	// the regression pin for the missing-constant crash the old suite missed
+	// (the Esc path only runs when terminal input has been seen).
+	const SCRIPT_B9 = {
+		call(step) {
+			if (step === 1) {
+				return {
+					type: "toolCall", id: "call-open", name: "todo",
+					arguments: {
+						todos: [{ content: "user-esc guard", status: "in_progress", priority: "high", id: "u1", group: "ue", confidence: 96 }],
+						plan: { user_intention: "user esc e2e", understands_user_intent: 97 },
+						goals: [{ group: "ue", closed_feedback_loop: 97, feedback_loop: "user Esc pauses the poke" }],
+					},
+				};
+			}
+			return null;
+		},
+		text(step) {
+			if (step === 2) return "Todos written.";
+			if (step === 3) return "Poked: working on it, mid-stream.";
+			return "Resumed inside the Esc window.";
+		},
+		abortAtCall: 3,
+		escBeforeAbort: true,
+		resumeText: "resume after the user interrupt",
+		calls: 4,
+	};
+	await runScenario("B9 user Esc abort pauses the poke", SCRIPT_B9, async ({ customs, entries, widgets }) => {
+		const pokes = customs.filter((t) => t.includes("You have 1 incomplete todo."));
+		if (pokes.length === 1) ok("B9 user-Esc settle quiet", "poke #1 at the write settle; the Esc-aborted settle and the in-window resume settle injected nothing");
+		else bad("B9 user-Esc settle quiet", `pokes=${pokes.length} customs=${JSON.stringify(customs.map((t) => t.slice(0, 60)))}`);
+		const stopReasons = entries
+			.filter((e) => e.type === "message" && e.message?.role === "assistant")
+			.map((e) => e.message.stopReason);
+		if (stopReasons.includes("aborted")) ok("B9 aborted run recorded", `stopReasons=${JSON.stringify(stopReasons)}`);
+		else bad("B9 aborted run recorded", `stopReasons=${JSON.stringify(stopReasons)}`);
+		const pausedPaint = SCRIPT_B9.escPaint?.some((l) => l.includes("poke paused"));
+		if (pausedPaint) ok("B9 widget pause paint", "'poke paused' rendered right after the user Esc");
+		else bad("B9 widget pause paint", JSON.stringify(SCRIPT_B9.escPaint ?? null, (k, v) => (typeof v === "string" ? v.replace(/\x1b\[[0-9;]*m/g, "") : v)));
+	});
 }
 
 // ============================================================================