gentle-pi 3.2.1 → 3.4.0

package/tests/gentle-shell.test.ts

@@ -1,12 +1,13 @@
 import assert from "node:assert/strict";
 import { execFileSync, execFile } from "node:child_process";
-import { mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import { initTheme, type ExtensionAPI, type ExtensionContext, type SlashCommandInfo, type SourceInfo } from "@earendil-works/pi-coding-agent";
-import type { TUI } from "@earendil-works/pi-tui";
-import installGentleShell, { buildShellBarModel, createActiveProfileReader, changesShortcut, devBinaryCard, fetchCodexUsage, fetchNanUsage, loadFileDiff, shellGitRunner, openInExternalEditor, type GentlePromptEditor } from "../extensions/gentle-shell.ts";
+import type { TUI, TuiMouseEvent } from "@earendil-works/pi-tui";
+import installGentleShell, { buildShellBarModel, createActiveProfileReader, changesShortcut, devBinaryCard, extractQueuedText, fetchCodexUsage, fetchNanUsage, loadFileDiff, shellGitRunner, openInExternalEditor, usageShortcut, type GentlePromptEditor } from "../extensions/gentle-shell.ts";
+import { USAGE_SOURCE_EVENT, USAGE_SOURCE_SCHEMA } from "../lib/shell-usage.ts";
 import { CHANGE_STATUS } from "../lib/shell-changes.ts";
 import { sidebarState, type SidebarRail } from "../lib/shell-sidebar.ts";
 import type { ShellBarTheme } from "../lib/shell-bar.ts";
@@ -53,6 +54,7 @@ interface GitScript {
 }
 
 interface CommandRegistration {
+	description?: string;
 	handler: (args: string, ctx: ExtensionContext) => Promise<void>;
 }
 
@@ -128,7 +130,7 @@ async function fire(handlers: Map<string, Array<(event: unknown, ctx: ExtensionC
 	for (const handler of handlers.get(event) ?? []) await handler({}, ctx);
 }
 
-function fakeContext(options: { hasUI?: boolean; entries?: unknown[]; oauth?: boolean; pending?: boolean; editorFactory?: unknown; token?: string } = {}): { ctx: ExtensionContext; ui: FakeUi; overlayReady: Promise<void> } {
+function fakeContext(options: { hasUI?: boolean; entries?: unknown[]; oauth?: boolean; pending?: boolean; idle?: boolean; editorFactory?: unknown; token?: string; select?: (title: string, options: string[]) => Promise<string | undefined> } = {}): { ctx: ExtensionContext; ui: FakeUi; overlayReady: Promise<void> } {
 	const ui: FakeUi = { footerFactory: undefined, editorFactory: options.editorFactory, widgets: new Map(), widgetSets: 0, workingVisible: undefined, notices: [], overlay: undefined, overlayView: undefined, closeOverlay: undefined };
 	let resolveOverlay: () => void;
 	const overlayReady = new Promise<void>((resolve) => { resolveOverlay = resolve; });
@@ -136,6 +138,7 @@ function fakeContext(options: { hasUI?: boolean; entries?: unknown[]; oauth?: bo
 	const ctx = {
 		hasUI: options.hasUI ?? true,
 		hasPendingMessages: () => options.pending ?? false,
+		isIdle: () => options.idle ?? true,
 		cwd: "/repo",
 		model: { id: "gpt-5.5", provider: "openai-codex", reasoning: true, contextWindow: 272_000 },
 		sessionManager: {
@@ -148,6 +151,9 @@ function fakeContext(options: { hasUI?: boolean; entries?: unknown[]; oauth?: bo
 		getContextUsage: () => ({ tokens: 122_400, contextWindow: 272_000, percent: 45 }),
 		ui: {
 			theme: plainTheme,
+			// Added only when requested: an absent select keeps the no-menu fallback
+			// that every pre-existing test relies on.
+			...(options.select ? { select: options.select } : {}),
 			setFooter(factory: unknown) {
 				ui.footerFactory = factory;
 			},
@@ -253,12 +259,11 @@ test("gentleShell installs the footer on session_start when a UI exists", () =>
 	assert.match(lines[0], /main ⟡ gpt-5\.5 · medium/);
 });
 
-test("the fullscreen Status rail carries a live digest so a model switch refreshes it", async () => {
+test("the fullscreen Status rail carries a live digest so a profile switch refreshes it", async () => {
 	const { pi, handlers } = fakePi();
 	let profile: string | undefined = "team";
 	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { activeProfile: () => profile });
-	const entries: unknown[] = [];
-	const { ctx, ui } = fakeContext({ entries });
+	const { ctx, ui } = fakeContext();
 	await fire(handlers, "session_start", ctx);
 
 	const statuses = new Map<string, string>();
@@ -270,7 +275,7 @@ test("the fullscreen Status rail carries a live digest so a model switch refresh
 		const rail = sidebarState(tui as unknown as TUI).parts.get("footer") as SidebarRail;
 		const live = () => rail.digest?.();
 		assert.equal(typeof rail.digest, "function", "the Status card paints live state and must declare a digest");
-		assert.match(rail.render(46).join("\n"), /gpt-5\.5/);
+		assert.doesNotMatch(rail.render(46).join("\n"), /gpt-5\.5/, "model now lives in the header, not the Status card");
 
 		assert.match(rail.render(46).join("\n"), /Profile.*team/);
 		const beforeProfile = live();
@@ -280,26 +285,79 @@ test("the fullscreen Status rail carries a live digest so a model switch refresh
 		profile = undefined;
 		assert.doesNotMatch(rail.render(46).join("\n"), /Profile/);
 
+		const beforeStatus = live();
+		statuses.set("mcp", "MCP: 3 servers enabled");
+		assert.notEqual(live(), beforeStatus, "extension statuses have no event and must change the digest");
+		assert.match(rail.render(46).join("\n"), /MCP: 3 servers enabled/);
+		assert.equal(live(), live(), "an unchanged digest still reuses the prepared rail");
+	} finally {
+		component.dispose();
+	}
+});
+
+test("the fullscreen header rail carries a live digest so model, context, and cost changes refresh it", async () => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" });
+	const entries: unknown[] = [];
+	const { ctx, ui } = fakeContext({ entries });
+	await fire(handlers, "session_start", ctx);
+
+	const liveFooterData = { getGitBranch: () => "main", getExtensionStatuses: () => new Map([["mcp", "MCP: 3 servers enabled"]]), getAvailableProviderCount: () => 1, onBranchChange: () => () => {} };
+	const tui = { terminal: { rows: 40, columns: 160 }, requestRender() {} };
+	const factory = ui.footerFactory as (tui: unknown, theme: ShellBarTheme, footerData: unknown) => { render(width: number): string[]; dispose(): void };
+	const component = factory(tui, plainTheme, liveFooterData);
+	try {
+		const header = sidebarState(tui as unknown as TUI).parts.get("header") as SidebarRail;
+		assert.equal(typeof header.digest, "function", "the header paints live state every frame and must declare a digest");
+		const live = () => header.digest?.();
+		const text = () => header.render(160).join("\n");
+		assert.match(text(), /gpt-5\.5/);
+		assert.doesNotMatch(text(), /MCP: 3 servers/, "extension statuses never reach the header");
+		assert.doesNotMatch(text(), /working/i, "the working state never reaches the header");
+
 		const beforeModel = live();
 		(ctx.model as { id: string }).id = "gpt-5.6";
-		assert.notEqual(live(), beforeModel, "/model must change the digest");
-		assert.match(rail.render(46).join("\n"), /gpt-5\.6/);
+		assert.notEqual(live(), beforeModel, "/model must change the header digest");
+		assert.match(text(), /gpt-5\.6/);
 
 		const beforeUsage = live();
 		(ctx as unknown as { getContextUsage: () => unknown }).getContextUsage = () => ({ tokens: 200_000, contextWindow: 272_000, percent: 74 });
-		assert.notEqual(live(), beforeUsage, "context usage must change the digest");
-		assert.match(rail.render(46).join("\n"), /74%/);
+		assert.notEqual(live(), beforeUsage, "context usage must change the header digest");
+		assert.match(text(), /74%/);
 
 		const beforeCost = live();
 		entries.push(assistantEntry({ input: 100, output: 20, cost: 0.42 }));
-		assert.notEqual(live(), beforeCost, "session cost must change the digest");
-		assert.match(rail.render(46).join("\n"), /\$0\.420/);
+		assert.notEqual(live(), beforeCost, "session cost must change the header digest");
+		assert.match(text(), /\$0\.420/);
+		assert.equal(live(), live(), "an unchanged digest still reuses the prepared header");
+	} finally {
+		component.dispose();
+	}
+});
 
-		const beforeStatus = live();
-		statuses.set("mcp", "MCP: 3 servers enabled");
-		assert.notEqual(live(), beforeStatus, "extension statuses have no event and must change the digest");
-		assert.match(rail.render(46).join("\n"), /MCP: 3 servers enabled/);
-		assert.equal(live(), live(), "an unchanged digest still reuses the prepared rail");
+test("clicking the header's usage segment opens the usage panel; other header clicks are ignored", async () => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" });
+	const { ctx, ui } = fakeContext();
+	await fire(handlers, "session_start", ctx);
+
+	const liveFooterData = { getGitBranch: () => "main", getExtensionStatuses: () => new Map(), getAvailableProviderCount: () => 1, onBranchChange: () => () => {} };
+	const tui = { terminal: { rows: 40, columns: 160 }, requestRender() {} };
+	const factory = ui.footerFactory as (tui: unknown, theme: ShellBarTheme, footerData: unknown) => { render(width: number): string[]; dispose(): void };
+	const component = factory(tui, plainTheme, liveFooterData);
+	try {
+		const header = sidebarState(tui as unknown as TUI).parts.get("header") as SidebarRail;
+		const line = header.render(160).join("");
+		const usageAt = line.indexOf("usage");
+		assert.ok(usageAt >= 0, "the header shows a standing usage segment");
+
+		const click = (x: number) => header.handleMouse?.({ type: "click", button: "left", x, y: 0, screenX: x, screenY: 0, width: 160, height: 1, shift: false, alt: false, ctrl: false } as TuiMouseEvent);
+		assert.equal(click(0), undefined, "a click on the brand does not open the panel");
+		const hit = click(usageAt + 1);
+		assert.equal(hit?.handled, true);
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		assert.match(ui.overlayView!.render(90).join("\n"), /Subscriptions/);
+		ui.closeOverlay?.();
 	} finally {
 		component.dispose();
 	}
@@ -355,10 +413,15 @@ const fakeTui = { terminal: { rows: 40, columns: 120 }, requestRender() {} };
 const editorTheme = { borderColor: (text: string) => text, selectList: {} };
 const fakeKeybindings = { matches: () => false };
 
-function installedPrompt(ctx: ExtensionContext, ui: FakeUi, handlers: Map<string, Array<(event: unknown, ctx: ExtensionContext) => unknown>>): GentlePromptEditor {
+function installedPrompt(
+	ctx: ExtensionContext,
+	ui: FakeUi,
+	handlers: Map<string, Array<(event: unknown, ctx: ExtensionContext) => unknown>>,
+	keybindings: unknown = fakeKeybindings,
+): GentlePromptEditor {
 	for (const handler of handlers.get("session_start") ?? []) handler({}, ctx);
 	const factory = ui.editorFactory as (tui: unknown, theme: unknown, keybindings: unknown) => GentlePromptEditor;
-	return factory(fakeTui, editorTheme, fakeKeybindings);
+	return factory(fakeTui, editorTheme, keybindings);
 }
 
 test("gentleShell frames the editor with the petal prompt and a hint while empty", () => {
@@ -416,7 +479,122 @@ test("gentleShell shows working while the agent runs and queued when messages wa
 	editor.dispose();
 });
 
+test("animations command reports without writing and switches the live pulse", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const delays: number[] = [];
+	let active = 0;
+	t.mock.method(globalThis, "setInterval", (_callback: () => void, delay: number) => {
+		delays.push(delay); active++; return { unref() {} };
+	});
+	t.mock.method(globalThis, "clearInterval", () => { active--; });
+	const { pi, handlers, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers);
+	const command = commands.get("gentle:animations");
+	assert.ok(command);
+	await command.handler("", ctx);
+	assert.match(ui.notices.at(-1)!, /animations: quality/);
+	assert.equal(existsSync(join(configHome, "animations.json")), false);
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	assert.deepEqual(delays, [80]);
+	await command.handler("performance", ctx);
+	assert.deepEqual(delays, [80, 1000]);
+	assert.equal(active, 1);
+	await command.handler("potato", ctx);
+	assert.equal(active, 0);
+	assert.match(stripAnsi(editor.render(60)[0]), /working/);
+	assert.equal(JSON.parse(readFileSync(join(configHome, "animations.json"), "utf8")).policy, "potato");
+	await command.handler("invalid", ctx);
+	assert.equal(JSON.parse(readFileSync(join(configHome, "animations.json"), "utf8")).policy, "potato");
+	await command.handler("quality", ctx);
+	assert.deepEqual(delays, [80, 1000, 80]);
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.equal(active, 0);
+	editor.dispose();
+});
+
+test("potato repaints start/settle and shows queued state on the host's next render without intervals", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	writeFileSync(join(configHome, "animations.json"), '{"schema":"gentle-pi.animations/v1","policy":"potato"}');
+	const intervals = t.mock.method(globalThis, "setInterval", () => { throw new Error("potato must not animate"); });
+	const renders = t.mock.method(fakeTui, "requestRender", () => {});
+	const { pi, handlers, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	const pending = { value: false };
+	(ctx as unknown as { hasPendingMessages(): boolean }).hasPendingMessages = () => pending.value;
+	const editor = installedPrompt(ctx, ui, handlers);
+	let before = renders.mock.callCount();
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	assert.ok(renders.mock.callCount() > before);
+	assert.match(stripAnsi(editor.render(60)[0]), /✿ working/);
+	before = renders.mock.callCount();
+	pending.value = true;
+	assert.equal(renders.mock.callCount(), before, "changing the queue flag is not a Gentle repaint event");
+	// Pi owns enqueue and its repaint scheduling; this fake context exposes only
+	// hasPendingMessages, not Pi's enqueue path. Simulate the host's render request:
+	// this proves next-render visibility, not real Pi enqueue-to-paint latency.
+	fakeTui.requestRender();
+	assert.equal(renders.mock.callCount(), before + 1);
+	assert.match(stripAnsi(editor.render(60)[0]), /✿ queued/);
+	before = renders.mock.callCount();
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.ok(renders.mock.callCount() > before);
+	assert.doesNotMatch(stripAnsi(editor.render(60)[0]), /working|queued/);
+	await commands.get("gentle:animations")!.handler("status", ctx);
+	assert.match(ui.notices.at(-1)!, /animations: potato/);
+	for (const handler of handlers.get("session_shutdown") ?? []) handler({}, ctx);
+	assert.equal(intervals.mock.callCount(), 0);
+});
+
+test("animations status attributes malformed files and reports a failed write", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const path = join(configHome, "animations.json");
+	writeFileSync(path, "broken");
+	const { pi, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	await commands.get("gentle:animations")!.handler("", ctx);
+	assert.match(ui.notices.at(-1)!, /animations: quality.*global file.*malformed/);
+	assert.equal(readFileSync(path, "utf8"), "broken");
+	rmSync(path);
+	mkdirSync(path);
+	await commands.get("gentle:animations")!.handler("potato", ctx);
+	assert.match(ui.notices.at(-1)!, /EISDIR|ENOTEMPTY|EPERM/);
+});
+
+test("animations with no argument opens a selectable menu and applies the chosen policy", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const path = join(configHome, "animations.json");
+	const { pi, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	// No editor/prompt is installed: the handler's `prompt?.setAnimationPolicy`
+	// optional chain must tolerate the interactive menu without one.
+	const chosen = fakeContext({
+		select: async (title, options) => {
+			assert.match(title, /Gentle animations/);
+			assert.deepEqual(options, ["quality", "performance", "potato", "status"]);
+			return "potato";
+		},
+	});
+	await commands.get("gentle:animations")!.handler("", chosen.ctx);
+	assert.equal(JSON.parse(readFileSync(path, "utf8")).policy, "potato");
+	assert.match(chosen.ui.notices.at(-1)!, /animations: potato/);
+
+	// A dismissed menu (undefined selection) reports nothing and writes nothing.
+	const dismissHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi: dismissPi, commands: dismissCommands } = fakePi();
+	gentleShell(dismissPi, { GENTLE_PI_CONFIG_HOME: dismissHome });
+	const dismissed = fakeContext({ select: async () => undefined });
+	await dismissCommands.get("gentle:animations")!.handler("", dismissed.ctx);
+	assert.equal(dismissed.ui.notices.length, 0);
+	assert.equal(existsSync(join(dismissHome, "animations.json")), false);
+});
+
 test("prompt uses the compact banner cadence and releases its unref timer at settlement", (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	writeFileSync(join(configHome, "animations.json"), '{"schema":"gentle-pi.animations/v1","policy":"quality"}');
 	const delays: number[] = [];
 	let active = 0;
 	let unrefs = 0;
@@ -427,7 +605,7 @@ test("prompt uses the compact banner cadence and releases its unref timer at set
 	});
 	t.mock.method(globalThis, "clearInterval", () => { active--; });
 	const { pi, handlers } = fakePi();
-	gentleShell(pi, {});
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
 	const { ctx, ui } = fakeContext();
 	const editor = installedPrompt(ctx, ui, handlers);
 	assert.equal(active, 0);
@@ -440,6 +618,673 @@ test("prompt uses the compact banner cadence and releases its unref timer at set
 	assert.equal(active, 0);
 });
 
+// ---------------------------------------------------------------------------
+// double-esc-cancel (issue #1163): opt-in, off by default. While the prompt
+// is working and autocomplete is hidden, the first Esc is swallowed and the
+// frame shows a hint; a second Esc within the window falls through to
+// CustomEditor's own handleInput so Pi's onEscape performs the abort exactly
+// as it always has. Idle double-Esc (tree/fork), bash-mode Esc, and
+// autocomplete cancel live entirely in Pi's own onEscape/CustomEditor and are
+// untouched by this gate.
+// ---------------------------------------------------------------------------
+
+const escapeKeybindings = { matches: (_data: string, keybinding: string) => keybinding === "app.interrupt" };
+
+test("double-esc-cancel default off: a single Esc while working still aborts immediately, exactly as before", (t) => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 1);
+	assert.doesNotMatch(stripAnsi(editor.render(60).join("\n")), /esc again to cancel/);
+	editor.dispose();
+});
+
+function scopedDoubleEscCancelConfigHome(t: { after(callback: () => void): void }): string {
+	const configHome = mkdtempSync(join(tmpdir(), "gp-esc-cfg-"));
+	t.after(() => rmSync(configHome, { recursive: true, force: true }));
+	return configHome;
+}
+
+test("double-esc-cancel enabled: the first Esc while working is swallowed and shows the hint instead of aborting", (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_DOUBLE_ESC_CANCEL: "on", GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 0, "the first Esc must be swallowed, not aborted");
+	assert.match(stripAnsi(editor.render(60).join("\n")), /esc again to cancel/);
+	editor.dispose();
+});
+
+test("double-esc-cancel enabled: a second Esc within the window falls through and aborts, clearing the hint", (t) => {
+	let now = 1_000_000;
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_DOUBLE_ESC_CANCEL: "on", GENTLE_PI_CONFIG_HOME: configHome }, { now: () => now });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 0);
+	now += 500;
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 1, "the second Esc within the window must fall through to abort");
+	assert.doesNotMatch(stripAnsi(editor.render(60).join("\n")), /esc again to cancel/);
+	editor.dispose();
+});
+
+test("double-esc-cancel enabled: an Esc after the window expires is a fresh first press, not an abort", (t) => {
+	let now = 1_000_000;
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_DOUBLE_ESC_CANCEL: "on", GENTLE_PI_CONFIG_HOME: configHome }, { now: () => now });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 0);
+	now += 1001;
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 0, "the window expired, so this must be treated as a new first press");
+	assert.match(stripAnsi(editor.render(60).join("\n")), /esc again to cancel/);
+	editor.dispose();
+});
+
+test("double-esc-cancel enabled: Esc while idle passes straight through, untouched by this gate", (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_DOUBLE_ESC_CANCEL: "on", GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	// agent_start never fired: the prompt stays idle.
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 1, "idle Esc must be unaffected by the policy");
+	editor.dispose();
+});
+
+test("double-esc-cancel enabled: Esc while autocomplete is visible bypasses this gate entirely", (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_DOUBLE_ESC_CANCEL: "on", GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	(editor as unknown as { isShowingAutocomplete(): boolean }).isShowingAutocomplete = () => true;
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	assert.doesNotMatch(stripAnsi(editor.render(60).join("\n")), /esc again to cancel/, "autocomplete must bypass the gate, matching CustomEditor's own guard");
+	editor.dispose();
+});
+
+// ---------------------------------------------------------------------------
+// Working-cancel keeps the queue moving (issue #1218). Pi's own onEscape
+// restores `[queuedText, currentText].filter(t => t.trim()).join("\n\n")`
+// into the editor and aborts. These tests fake that join in `onEscape` (the
+// same seam the double-esc-cancel tests above use), then check that the
+// user's own draft is all that is left in the editor and that the queued
+// text is sent exactly once, after the aborted run settles.
+// ---------------------------------------------------------------------------
+
+test("extractQueuedText reverses Pi's queued+draft join", () => {
+	assert.equal(extractQueuedText("follow up\n\ndraft reply", "draft reply"), "follow up");
+	assert.equal(extractQueuedText("draft reply", "draft reply"), "", "no queue: the join degenerates to the draft alone");
+	assert.equal(extractQueuedText("only queued", ""), "only queued", "empty draft: the join degenerates to the queue alone");
+	assert.equal(extractQueuedText("", ""), "", "both empty");
+	assert.equal(extractQueuedText("unrelated text", "draft reply"), undefined, "a shape that does not match the join is unrecognized, not an empty queue: Pi's own text must win, not be discarded");
+});
+
+test("extractQueuedText treats a whitespace-only draft as empty, matching Pi's own trim filter", () => {
+	assert.equal(extractQueuedText("only queued", "   "), "only queued", "a whitespace-only draft never survives Pi's filter, so the whole join is the queue");
+	assert.equal(extractQueuedText("", "   "), "", "whitespace-only draft with no queue is still no queue, not unrecognized");
+});
+
+test("working cancel: an aborted turn with a queued message sends it once settled and keeps the draft", (t) => {
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.onEscape = () => { editor.setText(`follow up\n\n${editor.getText()}`); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	assert.equal(editor.getText(), "draft reply", "the user's own draft stays in the editor");
+	assert.equal(sentMessages.length, 0, "nothing is sent until the aborted run settles");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.deepEqual(sentMessages.map((m) => m.content), ["follow up"]);
+	editor.dispose();
+});
+
+test("working cancel: an aborted turn with no queued messages behaves exactly as before, with no redundant setText", (t) => {
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	// Pi's own onEscape restore is the one real setText call on this path
+	// (it always writes the combined text, even when that equals the
+	// draft); the spy below counts every call, so it must see only that one
+	// and none added by abortAndDispatchQueued itself.
+	editor.onEscape = () => { editor.setText(editor.getText()); };
+	let setTextCalls = 0;
+	const originalSetText = editor.setText.bind(editor);
+	(editor as unknown as { setText(text: string): void }).setText = (text: string) => { setTextCalls++; originalSetText(text); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	assert.equal(setTextCalls, 1, "the no-queue path must not add its own write on top of Pi's own restore");
+	assert.equal(editor.getText(), "draft reply");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.equal(sentMessages.length, 0, "an empty queue must never trigger a send");
+	editor.dispose();
+});
+
+test("working cancel: an unrecognized restore shape leaves Pi's own text untouched and dispatches nothing", (t) => {
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	// Simulates a future Pi restore shape this code does not recognize.
+	editor.onEscape = () => { editor.setText("an unrecognized shape"); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	assert.equal(editor.getText(), "an unrecognized shape", "Pi's own restore wins on a shape mismatch; nothing here overwrites it");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.equal(sentMessages.length, 0, "an unrecognized shape must never be dispatched as if it were queued text");
+	editor.dispose();
+});
+
+test("working cancel: an empty draft with a queued message sends the whole queue and leaves the editor empty", (t) => {
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.onEscape = () => { editor.setText("only queued"); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	assert.equal(editor.getText(), "", "an empty draft stays empty");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.deepEqual(sentMessages.map((m) => m.content), ["only queued"]);
+	editor.dispose();
+});
+
+test("working cancel: the same dispatch applies to the confirming second Esc when double-esc-cancel is enabled", (t) => {
+	let now = 1_000_000;
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_DOUBLE_ESC_CANCEL: "on", GENTLE_PI_CONFIG_HOME: configHome }, { now: () => now });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.onEscape = () => { editor.setText(`follow up\n\n${editor.getText()}`); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	now += 500;
+	editor.handleInput("\x1b");
+	assert.equal(editor.getText(), "draft reply");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.deepEqual(sentMessages.map((m) => m.content), ["follow up"]);
+	editor.dispose();
+});
+
+test("working cancel: queued text is never sent twice even if agent_settled fires again", (t) => {
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.onEscape = () => { editor.setText(`follow up\n\n${editor.getText()}`); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.deepEqual(sentMessages.map((m) => m.content), ["follow up"]);
+	editor.dispose();
+});
+
+test("working cancel: a new agent_start before the aborted run settles keeps the pending text and sends it once that turn settles", (t) => {
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.onEscape = () => { editor.setText(`follow up\n\n${editor.getText()}`); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	// The user sent the draft (or another turn started) before the aborted
+	// run's own agent_settled fired. Nothing is sent from inside agent_start:
+	// Pi is mid-turn there, so the text waits for that turn to settle.
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	assert.equal(sentMessages.length, 0, "never send from inside agent_start");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.deepEqual(sentMessages.map((m) => ({ content: m.content, deliverAs: m.options?.deliverAs })), [{ content: "follow up", deliverAs: undefined }]);
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.equal(sentMessages.length, 1, "the pending text must not be delivered a second time");
+	editor.dispose();
+});
+
+test("working cancel: a whitespace-only recognized queue is treated as no queue and never dispatched", (t) => {
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.onEscape = () => { editor.setText(`   \n\n${editor.getText()}`); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.equal(sentMessages.length, 0, "whitespace is not a message");
+	assert.equal(editor.getText(), "draft reply", "the recognized whitespace prefix is stripped and the draft comes back alone");
+	editor.dispose();
+});
+
+test("working cancel: a failing sendUserMessage on settle is reported, not thrown, and the prompt still leaves the working state", (t) => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.onEscape = () => { editor.setText(`follow up\n\n${editor.getText()}`); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	(pi as unknown as { sendUserMessage: (content: string) => void }).sendUserMessage = () => { throw new Error("session is switching"); };
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.ok(ui.notices.some((notice) => /session is switching/.test(notice)), "the failure surfaces as a notice");
+	assert.equal(editor.getText(), "follow up\n\ndraft reply", "the queued text is put back in front of the draft, exactly as Pi's own restore would have left it");
+	assert.doesNotMatch(stripAnsi(editor.render(60).join("\n")), /esc again to cancel/, "the prompt is idle again");
+	editor.dispose();
+});
+
+test("working cancel: a failing send reported through a context without UI still restores the queued text into the editor", (t) => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const headless = fakeContext({ hasUI: false });
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.onEscape = () => { editor.setText(`follow up\n\n${editor.getText()}`); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	(pi as unknown as { sendUserMessage: (content: string) => void }).sendUserMessage = () => { throw new Error("session is switching"); };
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, headless.ctx);
+	assert.equal(headless.ui.notices.length, 0, "no UI, no notice");
+	assert.equal(editor.getText(), "follow up\n\ndraft reply", "with or without a UI to tell the user, the text is never dropped");
+	editor.dispose();
+});
+
+test("working cancel: agent_settled never sends while another turn is still in flight; the text waits for an idle settle", (t) => {
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const busy = fakeContext({ idle: false }).ctx;
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.onEscape = () => { editor.setText(`follow up\n\n${editor.getText()}`); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, busy);
+	assert.equal(sentMessages.length, 0, "a settle reported while not idle must not inject the text mid-turn");
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 1, "a run is still in flight, so the prompt stays working and Esc takes the cancel path");
+	assert.doesNotMatch(stripAnsi(editor.render(60).join("\n")), /esc again to clear/, "not the idle clear");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.deepEqual(sentMessages.map((m) => m.content), ["follow up"]);
+	editor.dispose();
+});
+
+test("working cancel: two aborts before an idle settle deliver both queued texts, in order, as one message", (t) => {
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const busy = fakeContext({ idle: false }).ctx;
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	let aborts = 0;
+	editor.onEscape = () => { aborts++; editor.setText(aborts === 1 ? "first" : "second"); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, busy);
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.deepEqual(sentMessages.map((m) => m.content), ["first\n\nsecond"], "nothing from the first abort is lost, and order is preserved");
+	editor.dispose();
+});
+
+test("working cancel: pending queued text never crosses a session boundary", (t) => {
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.onEscape = () => { editor.setText(`follow up\n\n${editor.getText()}`); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	for (const handler of handlers.get("session_shutdown") ?? []) handler({}, ctx);
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.equal(sentMessages.length, 0, "the old session's queued text must not be sent into the next session");
+});
+
+test("working cancel: agent_settled firing first delivers the pending text without a deliverAs override", (t) => {
+	const { pi, handlers, sentMessages } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.onEscape = () => { editor.setText(`follow up\n\n${editor.getText()}`); };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	for (const handler of handlers.get("agent_settled") ?? []) handler({}, ctx);
+	assert.deepEqual(sentMessages.map((m) => ({ content: m.content, deliverAs: m.options?.deliverAs })), [{ content: "follow up", deliverAs: undefined }]);
+	// The next turn's own agent_start must not re-deliver the already-sent text.
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	assert.equal(sentMessages.length, 1);
+	editor.dispose();
+});
+
+// ---------------------------------------------------------------------------
+// Idle double-Esc clears the draft (issue #1218). With the prompt idle,
+// autocomplete hidden, and a non-empty draft, a first Esc shows a hint
+// instead of doing nothing; a second Esc within 500ms adds the draft to
+// history and clears it. An empty editor, autocomplete, or the working state
+// are all untouched: Pi's own idle double-Esc (tree/fork) and the
+// working-cancel gate above keep deciding those cases.
+// ---------------------------------------------------------------------------
+
+test("idle draft: the first Esc shows the clear hint and keeps the text", (t) => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 0, "the first Esc must be swallowed, not passed to Pi's own idle handler");
+	assert.equal(editor.getText(), "draft reply");
+	assert.match(stripAnsi(editor.render(60).join("\n")), /esc again to clear/);
+	editor.dispose();
+});
+
+test("idle draft: a second Esc within the window adds the draft to history and clears it", (t) => {
+	let now = 1_000_000;
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) }, { now: () => now });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	const history: string[] = [];
+	(editor as unknown as { addToHistory(text: string): void }).addToHistory = (text: string) => history.push(text);
+	editor.handleInput("\x1b");
+	now += 400;
+	editor.handleInput("\x1b");
+	assert.deepEqual(history, ["draft reply"]);
+	assert.equal(editor.getText(), "");
+	assert.doesNotMatch(stripAnsi(editor.render(60).join("\n")), /esc again to clear/);
+	editor.dispose();
+});
+
+test("idle draft: an Esc after the window expires is a fresh first press, not a clear", (t) => {
+	let now = 1_000_000;
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) }, { now: () => now });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.handleInput("\x1b");
+	now += 501;
+	editor.handleInput("\x1b");
+	assert.equal(editor.getText(), "draft reply", "the window expired, so this is a new first press, not a clear");
+	assert.match(stripAnsi(editor.render(60).join("\n")), /esc again to clear/);
+	editor.dispose();
+});
+
+test("idle empty editor: Esc passes straight through to Pi's own tree/fork double-Esc", (t) => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 1, "an empty editor must be untouched by the idle-clear gate");
+	editor.dispose();
+});
+
+test("idle draft: Esc while autocomplete is visible bypasses the idle-clear gate", (t) => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	(editor as unknown as { isShowingAutocomplete(): boolean }).isShowingAutocomplete = () => true;
+	editor.handleInput("\x1b");
+	assert.equal(editor.getText(), "draft reply", "autocomplete cancel must never clear the draft");
+	assert.doesNotMatch(stripAnsi(editor.render(60).join("\n")), /esc again to clear/, "autocomplete must bypass the idle-clear gate, matching CustomEditor's own guard");
+	editor.dispose();
+});
+
+test("working state: a non-empty draft's Esc is decided by the working-cancel gate, never the idle-clear hint", (t) => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.onEscape = () => { editor.setText(editor.getText()); };
+	editor.handleInput("\x1b");
+	assert.doesNotMatch(stripAnsi(editor.render(60).join("\n")), /esc again to clear/, "working must never show the idle-clear hint");
+	editor.dispose();
+});
+
+test("idle draft: editing the text between two Esc presses starts a fresh clear window instead of clearing the edit away", (t) => {
+	let now = 1_000_000;
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) }, { now: () => now });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("draft reply");
+	editor.handleInput("\x1b");
+	editor.setText("draft reply, edited");
+	assert.doesNotMatch(stripAnsi(editor.render(60).join("\n")), /esc again to clear/, "the edit invalidates the pending clear, so the hint goes away with it");
+	now += 400;
+	editor.handleInput("\x1b");
+	assert.equal(editor.getText(), "draft reply, edited", "an edit invalidates the earlier snapshot, so this must not clear");
+	assert.match(stripAnsi(editor.render(60).join("\n")), /esc again to clear/, "the edit starts a fresh first press, with its own hint");
+	now += 400;
+	editor.handleInput("\x1b");
+	assert.equal(editor.getText(), "", "the fresh window's own second Esc, on the unchanged edited text, does clear");
+	editor.dispose();
+});
+
+test("idle draft: typing and deleting between two Esc presses still invalidates the pending clear", (t) => {
+	let now = 1_000_000;
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) }, { now: () => now });
+	const { ctx, ui } = fakeContext();
+	// Esc-only matching: ordinary keystrokes must reach the editor as text.
+	const preciseEscape = { matches: (data: string, keybinding: string) => keybinding === "app.interrupt" && data === "\x1b" };
+	const editor = installedPrompt(ctx, ui, handlers, preciseEscape);
+	editor.setText("draft reply");
+	editor.handleInput("\x1b");
+	editor.handleInput("x");
+	editor.handleInput("\x7f");
+	assert.equal(editor.getText(), "draft reply", "type then backspace lands on the same text");
+	now += 400;
+	editor.handleInput("\x1b");
+	assert.equal(editor.getText(), "draft reply", "an intervening keystroke invalidates the confirmation even when the text ends up identical");
+	editor.dispose();
+});
+
+test("idle draft: a bash-mode draft's Esc bypasses the idle-clear gate entirely", (t) => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("!ls");
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 1, "a bash-mode draft's first Esc must reach Pi's own bash-mode onEscape, which clears bash mode");
+	assert.equal(editor.getText(), "!ls", "this gate never touches bash-mode text; Pi's own onEscape owns it");
+	assert.doesNotMatch(stripAnsi(editor.render(60).join("\n")), /esc again to clear/, "bash mode must bypass the idle-clear gate, matching Pi's own bash-mode Esc");
+	editor.dispose();
+});
+
+test("idle draft: a bash-mode draft with leading whitespace still bypasses the idle-clear gate", (t) => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: scopedDoubleEscCancelConfigHome(t) });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	editor.setText("  !ls");
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 1, "Pi detects bash mode from the trimmed start of the text, so this gate must match the same rule");
+	editor.dispose();
+});
+
+// ---------------------------------------------------------------------------
+// /gentle:double-esc-cancel (issue #1163). Unlike /gentle:background-subagents,
+// no argument toggles the effective policy rather than merely reporting it.
+// ---------------------------------------------------------------------------
+
+test("gentle:double-esc-cancel is registered and declares user-initiated sub-actions with a toggling no-argument form", () => {
+	const { pi, commands } = fakePi();
+	gentleShell(pi, {});
+	const command = commands.get("gentle:double-esc-cancel");
+	assert.ok(command, "gentle:double-esc-cancel must be registered");
+	assert.match(command!.description ?? "", /status\|enable\|disable/);
+	assert.match(command!.description ?? "", /no argument toggles/);
+});
+
+test("gentle:double-esc-cancel status reports off by default and writes nothing", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	await commands.get("gentle:double-esc-cancel")!.handler("status", ctx);
+	assert.equal(ui.notices.length, 1);
+	assert.match(ui.notices[0]!, /^double-esc-cancel: off \(decided by built-in default\)/);
+	assert.equal(existsSync(join(configHome, "double-esc-cancel.json")), false);
+});
+
+test("gentle:double-esc-cancel enable writes the global file, reports it, and takes effect immediately", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	await commands.get("gentle:double-esc-cancel")!.handler("enable", ctx);
+	assert.match(ui.notices[0]!, /^double-esc-cancel: on \(decided by global file/);
+	assert.match(ui.notices[0]!, /Wrote on to the global file/);
+	assert.deepEqual(
+		JSON.parse(readFileSync(join(configHome, "double-esc-cancel.json"), "utf8")),
+		{ schema: "gentle-pi.double-esc-cancel/v1", policy: "on" },
+	);
+});
+
+test("gentle:double-esc-cancel disable writes off", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	await commands.get("gentle:double-esc-cancel")!.handler("enable", ctx);
+	await commands.get("gentle:double-esc-cancel")!.handler("disable", ctx);
+	assert.match(ui.notices[1]!, /^double-esc-cancel: off \(decided by global file/);
+	assert.deepEqual(
+		JSON.parse(readFileSync(join(configHome, "double-esc-cancel.json"), "utf8")),
+		{ schema: "gentle-pi.double-esc-cancel/v1", policy: "off" },
+	);
+});
+
+test("gentle:double-esc-cancel with no argument toggles the effective policy each time", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	await commands.get("gentle:double-esc-cancel")!.handler("", ctx);
+	assert.match(ui.notices[0]!, /^double-esc-cancel: on /, "off -> on on the first toggle");
+	await commands.get("gentle:double-esc-cancel")!.handler("", ctx);
+	assert.match(ui.notices[1]!, /^double-esc-cancel: off /, "on -> off on the second toggle");
+});
+
+test("gentle:double-esc-cancel reports a malformed global file as fail-closed, not as an ordinary off", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	mkdirSync(configHome, { recursive: true });
+	writeFileSync(join(configHome, "double-esc-cancel.json"), "{malformed");
+	const { pi, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	await commands.get("gentle:double-esc-cancel")!.handler("status", ctx);
+	assert.match(ui.notices[0]!, /present but malformed/);
+});
+
+test("gentle:double-esc-cancel an unknown sub-action warns and changes nothing", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	await commands.get("gentle:double-esc-cancel")!.handler("toggle", ctx);
+	assert.match(ui.notices[0]!, /Unknown \/gentle:double-esc-cancel sub-action "toggle"/);
+	assert.equal(existsSync(join(configHome, "double-esc-cancel.json")), false);
+});
+
+test("gentle:double-esc-cancel enable updates the in-memory policy so an already-installed prompt picks it up without re-reading the file", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, handlers, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 1, "off by default: the first Esc still aborts");
+	await commands.get("gentle:double-esc-cancel")!.handler("enable", ctx);
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 1, "now on: the same prompt instance must swallow the first Esc instead of aborting");
+	assert.match(stripAnsi(editor.render(60).join("\n")), /esc again to cancel/);
+	editor.dispose();
+});
+
+test("gentle:double-esc-cancel re-syncs the keypress gate from the global file so status, toggle direction, and Esc behavior agree", async (t) => {
+	const configHome = scopedDoubleEscCancelConfigHome(t);
+	const { pi, handlers, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: configHome });
+	const { ctx, ui } = fakeContext();
+	const editor = installedPrompt(ctx, ui, handlers, escapeKeybindings);
+	let aborted = 0;
+	editor.onEscape = () => { aborted++; };
+	for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+	// Another session (or a hand edit) turns the preference on underneath this one.
+	mkdirSync(configHome, { recursive: true });
+	writeFileSync(join(configHome, "double-esc-cancel.json"), JSON.stringify({ schema: "gentle-pi.double-esc-cancel/v1", policy: "on" }));
+	await commands.get("gentle:double-esc-cancel")!.handler("status", ctx);
+	assert.match(ui.notices[0]!, /^double-esc-cancel: on \(decided by global file/);
+	editor.handleInput("\x1b");
+	assert.equal(aborted, 0, "status reported on, so the gate must swallow the first Esc rather than abort");
+	assert.match(stripAnsi(editor.render(60).join("\n")), /esc again to cancel/);
+	// The no-argument toggle flips relative to that same on-disk value: on -> off.
+	await commands.get("gentle:double-esc-cancel")!.handler("", ctx);
+	assert.match(ui.notices[1]!, /^double-esc-cancel: off /);
+	assert.deepEqual(JSON.parse(readFileSync(join(configHome, "double-esc-cancel.json"), "utf8")), { schema: "gentle-pi.double-esc-cancel/v1", policy: "off" });
+	editor.dispose();
+});
+
 test("gentleShell leaves an editor another extension already installed", () => {
 	const { pi, handlers } = fakePi();
 	gentleShell(pi, {});
@@ -508,6 +1353,15 @@ test("captured changes update the widget and bar without repository scans", asyn
  await fire(handlers,"session_shutdown",ctx);
 });
 
+
+// The changes overlay may ask Git for each captured root's HEAD label, and
+// nothing else: no status, diff, numstat or worktree scan behind the user's
+// back. Labelling is metadata, scanning is the behaviour these tests forbid.
+const onlyHeadLabels = (git: readonly string[][]) => git.every((args) => {
+ const command = args[0] === "-C" ? args.slice(2) : args;
+ return command[0] === "symbolic-ref" || (command[0] === "rev-parse" && command.includes("--verify"));
+});
+
 test("Changes opens only for captured mutations, not registered dirty roots", async () => {
  const {pi,handlers,commands,tools,git}=fakePi();
  gentleShell(pi,{});
@@ -522,7 +1376,7 @@ test("Changes opens only for captured mutations, not registered dirty roots", as
  const opened=commands.get("gentle:changes")!.handler("",ctx);
  await overlayReady;
  assert.match(ui.overlayView!.render(140).join("\n"),/linked/);
- assert.equal(git.length,0);
+ assert.ok(onlyHeadLabels(git), `overlay ran more than HEAD labelling: ${JSON.stringify(git)}`);
  ui.closeOverlay?.(); await opened;
  await fire(handlers,"session_shutdown",ctx);
 });
@@ -545,7 +1399,7 @@ test("overlay groups captured roots and refreshes same-count diffs without HEAD
   await new Promise(resolve=>setTimeout(resolve,20));
   assert.match(ui.overlayView!.render(140).join("\n"),/second/);
   assert.doesNotMatch(ui.overlayView!.render(140).join("\n"),/first/);
-  assert.equal(git.length,0);
+  assert.ok(onlyHeadLabels(git), `overlay ran more than HEAD labelling: ${JSON.stringify(git)}`);
  } finally { ui.closeOverlay?.(); await opened; await fire(handlers,"session_shutdown",ctx); }
 });
 
@@ -859,6 +1713,240 @@ test("a provider switch refreshes the new provider inside the same window", asyn
 	assert.equal(calls[1].url, "https://cloud-api.nan.builders/api/usage/quota");
 });
 
+// A generic hook: any extension can register a usage source for its own
+// provider on `pi.events`, and gentle-shell dispatches to it exactly like it
+// dispatches to the built-in Codex/NaN fetchers, without knowing the
+// provider's name ahead of time.
+
+function acmeSource(onFetch: (apiKey: string | undefined) => void, plan = "Acme cloud"): unknown {
+	return {
+		schema: USAGE_SOURCE_SCHEMA,
+		provider: "acme-cloud",
+		fetch: async (apiKey: string | undefined) => {
+			onFetch(apiKey);
+			return {
+				provider: "acme-cloud",
+				plan,
+				limits: [{ name: "acme-cloud", windows: [{ label: "week", usedPercent: 40, windowSeconds: 604_800, resetAt: null }], limitReached: false }],
+				fetchedAt: 0,
+			};
+		},
+	};
+}
+
+test("gentleShell fetches usage through a source registered before session start", async () => {
+	const { pi, handlers } = fakePi();
+	const seen: Array<string | undefined> = [];
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { now: () => 1_788_600_000_000 });
+	pi.events.emit(USAGE_SOURCE_EVENT, acmeSource((apiKey) => seen.push(apiKey)));
+	const { ctx, ui } = fakeContext({ token: "acme-token" });
+	(ctx as unknown as { model: { provider: string } }).model.provider = "acme-cloud";
+	await fire(handlers, "session_start", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.deepEqual(seen, ["acme-token"], "the registered fetch gets the api key modelRegistry resolves for its provider");
+	assert.match(renderFooter(ui), /acme-cloud week ▰▰▰▱▱▱▱▱ 40%/);
+});
+
+test("gentleShell forces one refresh when a usage source registers after session start for the active provider", async () => {
+	const { pi, handlers } = fakePi();
+	let calls = 0;
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { now: () => 1_788_600_000_000 });
+	const { ctx, ui } = fakeContext({ token: "acme-token" });
+	(ctx as unknown as { model: { provider: string } }).model.provider = "acme-cloud";
+	await fire(handlers, "session_start", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.doesNotMatch(renderFooter(ui), /acme-cloud/, "no source registered yet, nothing to show");
+
+	pi.events.emit(USAGE_SOURCE_EVENT, acmeSource(() => { calls += 1; }));
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.equal(calls, 1, "late registration for the active provider triggers one forced refresh, not a wait for the next turn");
+	assert.match(renderFooter(ui), /acme-cloud week ▰▰▰▱▱▱▱▱ 40%/);
+});
+
+test("a usage source registered for a different provider does not force a refresh", async () => {
+	const { pi, handlers } = fakePi();
+	let calls = 0;
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { now: () => 1_788_600_000_000 });
+	const { ctx, ui } = fakeContext({ token: "acme-token" });
+	(ctx as unknown as { model: { provider: string } }).model.provider = "openai-codex";
+	await fire(handlers, "session_start", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+
+	pi.events.emit(USAGE_SOURCE_EVENT, acmeSource(() => { calls += 1; }));
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.equal(calls, 0, "the active provider is codex, so an acme-cloud registration fetches nothing yet");
+	assert.doesNotMatch(renderFooter(ui), /acme-cloud/);
+});
+
+test("gentleShell shows the unsupported note for a provider with no built-in or registered source", async () => {
+	const { pi, handlers, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { now: () => 1_788_600_000_000 });
+	const { ctx, ui } = fakeContext({ token: undefined });
+	(ctx as unknown as { model: { provider: string } }).model.provider = "acme-cloud";
+	await fire(handlers, "session_start", ctx);
+	const opened = commands.get("gentle:usage")!.handler("", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	const plain = ui.overlayView!.render(90).map(stripAnsi);
+	assert.match(plain[1], /✿ acme-cloud · no subscription usage for this provider/);
+	ui.closeOverlay?.();
+	await opened;
+});
+
+test("gentleShell ignores a malformed usage-source registration payload", async () => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { now: () => 1_788_600_000_000 });
+	pi.events.emit(USAGE_SOURCE_EVENT, { schema: "wrong-schema", provider: "acme-cloud", fetch: async () => undefined });
+	pi.events.emit(USAGE_SOURCE_EVENT, { schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", fetch: "not-a-function" });
+	pi.events.emit(USAGE_SOURCE_EVENT, "not-an-object");
+	pi.events.emit(USAGE_SOURCE_EVENT, undefined);
+	const { ctx, ui } = fakeContext({ token: undefined });
+	(ctx as unknown as { model: { provider: string } }).model.provider = "acme-cloud";
+	await fire(handlers, "session_start", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.doesNotMatch(renderFooter(ui), /acme-cloud/, "no malformed payload registered a usable source");
+});
+
+// A registered source is foreign code running inside a fire-and-forget
+// refresh (`void refreshUsage(...)`, both at session_start and on a late
+// registration): if its fetch rejects and nothing catches it, the rejection
+// is unhandled and, under Node's default policy, takes the whole process
+// down. The doc promises a foreign source is "ignored rather than crashing
+// the shell", so a throw must degrade exactly like a built-in fetcher's.
+test("a registered source's rejecting fetch never crashes the shell or poisons the store", async () => {
+	const { pi, handlers, commands } = fakePi();
+	let calls = 0;
+	const rejectingSource = () => ({
+		schema: USAGE_SOURCE_SCHEMA,
+		provider: "acme-cloud",
+		fetch: async () => {
+			calls += 1;
+			throw new Error("acme is down");
+		},
+	});
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { now: () => 1_788_600_000_000 });
+	const { ctx, ui } = fakeContext({ token: "acme-token" });
+	(ctx as unknown as { model: { provider: string } }).model.provider = "acme-cloud";
+
+	const unhandled: unknown[] = [];
+	const onUnhandled = (reason: unknown) => unhandled.push(reason);
+	process.on("unhandledRejection", onUnhandled);
+	try {
+		// Registered before session start: session_start's own fire-and-forget
+		// refresh dispatches straight to the rejecting fetch.
+		pi.events.emit(USAGE_SOURCE_EVENT, rejectingSource());
+		await fire(handlers, "session_start", ctx);
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		assert.equal(calls, 1);
+		assert.doesNotMatch(renderFooter(ui), /acme-cloud/, "a rejecting fetch must never be recorded as a snapshot");
+
+		// A second, late registration for the already-active provider dispatches
+		// through the USAGE_SOURCE_EVENT handler's own fire-and-forget refresh.
+		pi.events.emit(USAGE_SOURCE_EVENT, rejectingSource());
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		assert.equal(calls, 2);
+		assert.doesNotMatch(renderFooter(ui), /acme-cloud/);
+	} finally {
+		process.off("unhandledRejection", onUnhandled);
+	}
+	assert.deepEqual(unhandled, [], "a foreign source's rejection must never surface as an unhandled rejection");
+
+	// The panel still explains itself with the pending note, never a crash,
+	// even through the awaited refresh openUsage runs on open.
+	const opened = commands.get("gentle:usage")!.handler("", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	const plain = ui.overlayView!.render(90).map(stripAnsi);
+	assert.match(plain[1], /✿ acme-cloud · no usage yet · r to fetch/);
+	ui.closeOverlay?.();
+	await opened;
+});
+
+// A registered source's resolved value is foreign code's own object: it must
+// be validated like any other parsed payload (never trusted to name the
+// provider it actually is, never trusted to be well-formed), and a source
+// that gets replaced mid-flight must never let its late, stale answer land
+// after the replacement already recorded its own.
+
+test("a registered source resolving usage for another provider is rejected without overwriting that provider's snapshot", async () => {
+	const { pi, handlers } = fakePi();
+	const { fetchFn } = fakeFetch(NAN_QUOTA_PAYLOAD);
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { fetch: fetchFn, now: () => 1_788_600_000_000 });
+	const { ctx, ui } = fakeContext({ token: "sk-nan-secret" });
+	(ctx as unknown as { model: { provider: string } }).model.provider = "nan";
+	await fire(handlers, "session_start", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.match(renderFooter(ui), /nan total ▰+▱+/, "the real nan snapshot recorded first");
+
+	(ctx as unknown as { model: { provider: string } }).model.provider = "acme-cloud";
+	pi.events.emit(USAGE_SOURCE_EVENT, {
+		schema: USAGE_SOURCE_SCHEMA,
+		provider: "acme-cloud",
+		fetch: async () => ({ provider: "nan", plan: undefined, limits: [], fetchedAt: 0 }),
+	});
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.doesNotMatch(renderFooter(ui), /acme-cloud/, "a resolution naming another provider must not surface as the active one");
+
+	(ctx as unknown as { model: { provider: string } }).model.provider = "nan";
+	assert.match(renderFooter(ui), /nan total ▰+▱+/, "the real nan snapshot must survive a mismatched acme-cloud resolution untouched");
+});
+
+test("gentleShell leaves the pending note when a registered source resolves a malformed usage", async () => {
+	const { pi, handlers, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { now: () => 1_788_600_000_000 });
+	pi.events.emit(USAGE_SOURCE_EVENT, {
+		schema: USAGE_SOURCE_SCHEMA,
+		provider: "acme-cloud",
+		fetch: async () => ({ provider: "acme-cloud", plan: "Acme", fetchedAt: 0, limits: "nope" }),
+	});
+	const { ctx, ui } = fakeContext({ token: "acme-token" });
+	(ctx as unknown as { model: { provider: string } }).model.provider = "acme-cloud";
+	await fire(handlers, "session_start", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.doesNotMatch(renderFooter(ui), /acme-cloud/, "a malformed result must never be recorded");
+
+	const opened = commands.get("gentle:usage")!.handler("", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	const plain = ui.overlayView!.render(90).map(stripAnsi);
+	assert.match(plain[1], /✿ acme-cloud · no usage yet · r to fetch/);
+	ui.closeOverlay?.();
+	await opened;
+});
+
+test("a slow fetch from a replaced source never records after its replacement resolves", async () => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { now: () => 1_788_600_000_000 });
+	const { ctx, ui } = fakeContext({ token: "acme-token" });
+	(ctx as unknown as { model: { provider: string } }).model.provider = "acme-cloud";
+
+	let resolveSlow!: (value: unknown) => void;
+	const slow = new Promise((resolve) => { resolveSlow = resolve; });
+	pi.events.emit(USAGE_SOURCE_EVENT, {
+		schema: USAGE_SOURCE_SCHEMA,
+		provider: "acme-cloud",
+		fetch: async () => {
+			await slow;
+			return { provider: "acme-cloud", plan: "Stale", fetchedAt: 0, limits: [{ name: "acme-cloud", limitReached: false, windows: [{ label: "week", usedPercent: 10, windowSeconds: 604_800, resetAt: null }] }] };
+		},
+	});
+	await fire(handlers, "session_start", ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.doesNotMatch(renderFooter(ui), /acme-cloud/, "the slow fetch has not resolved yet");
+
+	// Replace the source before the slow fetch resolves; the late registration
+	// forces its own refresh, which resolves immediately.
+	pi.events.emit(USAGE_SOURCE_EVENT, {
+		schema: USAGE_SOURCE_SCHEMA,
+		provider: "acme-cloud",
+		fetch: async () => ({ provider: "acme-cloud", plan: "Fresh", fetchedAt: 0, limits: [{ name: "acme-cloud", limitReached: false, windows: [{ label: "week", usedPercent: 40, windowSeconds: 604_800, resetAt: null }] }] }),
+	});
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.match(renderFooter(ui), /acme-cloud week ▰▰▰▱▱▱▱▱ 40%/, "the replacement's own refresh recorded first");
+
+	// Now let the stale fetch resolve; it must never overwrite the fresh record.
+	resolveSlow(undefined);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.match(renderFooter(ui), /acme-cloud week ▰▰▰▱▱▱▱▱ 40%/, "the stale refresh must never record after being replaced");
+});
+
 test("gentleShell records SSE rate-limit headers from provider responses", async () => {
 	const { pi, handlers } = fakePi();
 	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { fetch: fakeFetch({}, false).fetchFn, now: () => 0 });
@@ -891,6 +1979,32 @@ test("gentleShell registers /gentle:usage and opens the subscriptions overlay",
 	await opened;
 });
 
+test("usageShortcut defaults to alt+u and can be overridden or disabled", () => {
+	assert.equal(usageShortcut({}), "alt+u");
+	assert.equal(usageShortcut({ GENTLE_PI_SHELL_USAGE_KEY: "ctrl+shift+u" }), "ctrl+shift+u");
+	assert.equal(usageShortcut({ GENTLE_PI_SHELL_USAGE_KEY: "off" }), undefined);
+	assert.equal(usageShortcut({ GENTLE_PI_SHELL_USAGE_KEY: "" }), undefined);
+});
+
+test("gentleShell binds the usage shortcut to the same handler as /gentle:usage", async () => {
+	const { pi, handlers, shortcuts } = fakePi();
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { fetch: fakeFetch().fetchFn, now: () => 1_788_600_000_000 });
+	const { ctx, ui } = fakeContext({ token: JWT });
+	await fire(handlers, "session_start", ctx);
+	const shortcut = shortcuts.get("alt+u");
+	assert.ok(shortcut, "alt+u not registered");
+	const opened = shortcut.handler(ctx);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	const plain = ui.overlayView!.render(90).map(stripAnsi);
+	assert.match(plain[0], /Subscriptions/);
+	ui.closeOverlay?.();
+	await opened;
+
+	const silent = fakePi();
+	gentleShell(silent.pi, { GENTLE_PI_SHELL_USAGE_KEY: "off" });
+	assert.equal(silent.shortcuts.has("alt+u"), false, "the usage shortcut must not register when disabled");
+});
+
 test("gentleShell draws the review preflight message as a Gentle card", () => {
 	const { pi } = fakePi();
 	gentleShell(pi, {});
@@ -909,6 +2023,17 @@ test("gentleShell draws the review preflight message as a Gentle card", () => {
 	assert.equal(collapsed.length, 3);
 });
 
+test("the review preflight card paints the rose INFO frame (border) and title (accent)", () => {
+	const { pi } = fakePi();
+	gentleShell(pi, {});
+	const renderer = renderers.get("gentle-pi.review-preflight")!;
+	const taggedTheme = { ...plainTheme, fg: (color: string, text: string) => `<${color}>${text}</${color}>` };
+	const message = { customType: "gentle-pi.review-preflight", content: "Receipt-driven development is enabled." };
+	const lines = renderer(message, { expanded: true }, taggedTheme).render(60);
+	assert.match(lines[0]!, /^<border>╭<\/border>/);
+	assert.match(lines[0]!, /<accent>✿ Gentle AI<\/accent>/);
+});
+
 test("gentleShell keeps a dev-binary override visible above the editor for the whole session", async () => {
 	const { pi, handlers } = fakePi();
 	const deps = { fetch: fakeFetch({}, false).fetchFn, now: () => 0, devBinary: () => ({ state: "active" as const, path: "/Users/me/go/bin/gentle-ai", sha256: "6e53bfc6305a3949deadbeef" }) };