gentle-pi 4.1.0 → 4.3.0

package/tests/gentle-shell.test.ts

@@ -4,19 +4,23 @@ import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSy
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import test, { after } from "node:test";
+import test, { after, afterEach } from "node:test";
 import { initTheme, type ExtensionAPI, type ExtensionContext, type SlashCommandInfo, type SourceInfo } from "@earendil-works/pi-coding-agent";
-import { CURSOR_MARKER, matchesKey, visibleWidth, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, matchesKey, stripTerminalSequences as stripAnsi, TuiMainScreen, visibleWidth, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import installGentleShell, { backgroundChangeRefreshesSettled, buildShellBarModel, createActiveProfileReader, changesShortcut, devBinaryCard, extractQueuedText, fetchCodexUsage, fetchNanUsage, loadFileDiff, shellGitRunner, openInExternalEditor, usageShortcut, GentlePromptEditor } from "../extensions/gentle-shell.ts";
 import { CODEX_USAGE_URL, NAN_QUOTA_URL, USAGE_SOURCE_EVENT, USAGE_SOURCE_SCHEMA } from "../lib/shell-usage.ts";
 import { bindSessionProfile, clearSessionProfileBinding, resetSessionProfileBindingsForTesting } from "../lib/session-profile-binding.ts";
 import { createVimEditorAdapter, isAuditedPiEditorVersion } from "../lib/vim-editor-adapter.ts";
+import { readFrozenInheritedProfile, resetFrozenInheritedProfilesForTesting } from "../lib/session-profile-freeze.ts";
+
+// Fixture sessions share ids across tests; the inherited-profile freeze is
+// process state keyed by session id (gentle-shell#1064 slice 3b-ii).
+afterEach(() => resetFrozenInheritedProfilesForTesting());
 import { buildCommandPaletteGroups } from "../lib/command-palette-catalog.ts";
 import { CHANGE_STATUS, DIFF_MAX_BYTES, DIFF_MAX_LINES, DIFF_TOO_LARGE } from "../lib/shell-changes.ts";
 import { sidebarPart, sidebarState, type SidebarRail } from "../lib/shell-sidebar.ts";
 import { renderTodoCard } from "../lib/shell-todo.ts";
 import type { ShellBarTheme } from "../lib/shell-bar.ts";
-import { stripAnsi } from "../lib/terminal-theme.ts";
 import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
 import { decodeReviewStatusV3 } from "../lib/review-integration-v2.ts";
 import { REVIEW_SIDEBAR_EVENT } from "../lib/review-sidebar-state.ts";
@@ -84,6 +88,7 @@ interface FakeUi {
 	overlay: unknown;
 	overlayView: { render(width: number): string[]; handleInput(data: string): void } | undefined;
 	closeOverlay: (() => void) | undefined;
+	customOptions?: unknown[];
 }
 
 interface GitScript {
@@ -171,7 +176,7 @@ async function fire(handlers: Map<string, Array<(event: unknown, ctx: ExtensionC
 }
 
 function fakeContext(options: { theme?: typeof plainTheme & { getBgAnsi?(): string }; 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 };
+	const ui: FakeUi = { footerFactory: undefined, editorFactory: options.editorFactory, widgets: new Map(), widgetSets: 0, workingVisible: undefined, notices: [], overlay: undefined, overlayView: undefined, closeOverlay: undefined, customOptions: [] };
 	let resolveOverlay: () => void;
 	const overlayReady = new Promise<void>((resolve) => { resolveOverlay = resolve; });
 	const entries = options.entries ?? [];
@@ -222,8 +227,9 @@ function fakeContext(options: { theme?: typeof plainTheme & { getBgAnsi?(): stri
 			// whatever their `done` callback is given (see ExtensionUIContext.custom
 			// in pi-coding-agent), not always null. `closeOverlay` stays a
 			// null-resolving escape hatch for tests that only need to end the wait.
-			custom<T>(factory: (tui: unknown, theme: unknown, keybindings: unknown, done: (value: T) => void) => { render(width: number): string[]; handleInput(data: string): void }) {
+			custom<T>(factory: (tui: unknown, theme: unknown, keybindings: unknown, done: (value: T) => void) => { render(width: number): string[]; handleInput(data: string): void }, options?: unknown) {
 				ui.overlay = factory;
+				ui.customOptions?.push(options);
 				return new Promise<T | null>((resolve) => {
 					ui.closeOverlay = () => resolve(null);
 					// An identity bg mock hides focused rows; omit it so overlay navigation
@@ -751,7 +757,9 @@ test("profile polling refreshes both fullscreen surfaces only on change and stop
 	t.mock.method(globalThis, "clearInterval", (handle: { timer: (typeof intervals)[number] }) => { handle.timer.stopped = true; });
 	const { pi, handlers } = fakePi();
 	let resolutions = 0;
-	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: home, GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, {
+	// follow mode keeps the live p → P → G resolution, so a pin edit reaches the
+	// open session through the poll (gentle-shell#1064 slice 3b-ii).
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: home, GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off", GENTLE_PI_PROFILE_FOLLOW: "1" }, {
 		resolveWorktree: () => { resolutions++; return { root: repo, commonDir }; },
 	});
 	const first = fakeContext();
@@ -1800,6 +1808,8 @@ function reverseColumns(row: string): number[] {
 	let inverse = false;
 	let column = 0;
 	const selected: number[] = [];
+	const host = TuiMainScreen.prototype as unknown as { resolveFakeCursors(rows: string[]): string[] };
+	row = host.resolveFakeCursors.call({ showHardwareCursor: false }, [row])[0]!;
 	const tokens = row.match(/\x1b\[[0-9;]*m|\x1b_pi:c\x07|[^\x1b]/g) ?? [];
 	assert.equal(tokens.join(""), row);
 	for (const token of tokens) {
@@ -4767,6 +4777,35 @@ test("a registered worktree opens Changes as its own group", async () => {
  } finally { ui.closeOverlay?.(); await opened; await fire(handlers,"session_shutdown",ctx); }
 });
 
+// /gentle:changes opens like Gentle Agents: a full-terminal overlay whose
+// native fullscreen wrapper still routes mouse events to the changes view.
+test("Changes opens full screen and the wrapper keeps mouse hit-testing aligned", async () => {
+ const {pi,handlers,commands}=fakePi([{numstat:"",porcelain:" M file.ts\0?? dirty.ts\0"}]);
+ gentleShell(pi,{});
+ const {ctx,ui,overlayReady}=fakeContext();
+ await fire(handlers,"session_start",ctx);
+ const opened=commands.get("gentle:changes")!.handler("",ctx);
+ await overlayReady;
+ const overlay=ui.overlayView as unknown as { render(width: number): string[]; handleInput(data: string): void; handleMouse(event: unknown): unknown };
+ const at=(type: string, x: number, y: number) => ({ type, button: type === "move" ? "none" : "left", x, y, screenX: x, screenY: y, width: 140, height: 40, shift: false, alt: false, ctrl: false });
+ try {
+  assert.deepEqual(ui.customOptions?.at(-1), { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", margin: 0, anchor: "center" } });
+  assert.equal(overlay.render(140).length, 40, "the overlay uses every terminal row");
+  overlay.handleInput("\r");
+  overlay.render(140);
+  const { handled, render } = overlay.handleMouse(at("click", 3, 3)) as { handled?: boolean; render?: boolean };
+  assert.deepEqual({ handled, render }, { handled: true, render: true });
+  assert.match(overlay.render(140)[3]!, /▸   M file\.ts/, "a click through the wrapper selects the file");
+  overlay.handleInput("F");
+  assert.match(overlay.render(140)[1]!, /^│ M file\.ts +│$/, "F switches to diff-only inside the fullscreen overlay");
+ } finally { ui.closeOverlay?.(); await opened; }
+ const reopened=commands.get("gentle:changes")!.handler("",ctx);
+ for (let attempt=0; attempt<100 && ui.overlayView===overlay; attempt++) await new Promise((resolve)=>setTimeout(resolve,5));
+ try {
+  assert.match(ui.overlayView!.render(140)[1]!, /main · repo/, "diff-only mode is not persisted across openings");
+ } finally { ui.closeOverlay?.(); await reopened; await fire(handlers,"session_shutdown",ctx); }
+});
+
 test("new sessions do not inherit another session's worktrees", async () => {
  const h=fakePi(); gentleShell(h.pi,{});
  const first=fakeContext();
@@ -4841,7 +4880,7 @@ test("registered canonical root governs real Git discovery, status and diff desp
 	assert.ok(await loadFileDiff(bounded, { path: "tracked.txt", added: 70_001, deleted: 1, status: CHANGE_STATUS.MODIFIED }) === DIFF_TOO_LARGE);
 	const opened = h.commands.get("gentle:changes")!.handler("", ctx);
 	await overlayReady;
-	const trees = (ui.overlayView as unknown as { trees: Array<{ root: string; model: { files: Array<{ path: string }> } }> }).trees;
+	const trees = (ui.overlayView as unknown as { children: Array<{ trees: Array<{ root: string; model: { files: Array<{ path: string }> } }> }> }).children[0]!.trees;
 	assert.deepEqual(trees.map((tree) => [tree.root, tree.model.files.map((file) => file.path)]), [[selected, ["selected-only.txt", "tracked.txt"]]], "inherited routing never lists the foreign repository");
 	ui.closeOverlay?.();
 	await opened;
@@ -5945,7 +5984,10 @@ test("after a profile switch the panel stops presenting the old profile's provid
 	ui.closeOverlay?.();
 	await opened;
 
-	writeProfilesStore(home, { team: { reviewer: { model: "nan/glm5.3" } }, solo: {} }, "solo");
+	// An open session changes profile only through its own Enter (gentle-shell#1064
+	// slice 3b-ii): a new global default would leave its frozen routing in place.
+	bindSessionProfile("shell-session", "solo", {});
+	t.after(() => resetSessionProfileBindingsForTesting());
 	const reopened = commands.get("gentle:usage")!.handler("", ctx);
 	await settle();
 	assert.equal(ui.overlayView!.render(90).map(stripAnsi).some((line) => line.includes("nan")), false, "a provider recorded under the previous profile's routing is not current scope");
@@ -5953,6 +5995,61 @@ test("after a profile switch the panel stops presenting the old profile's provid
 	await reopened;
 });
 
+test("an open session keeps its frozen profile in the status and Usage scope when the defaults change", async (t) => {
+	const home = mkdtempSync(join(tmpdir(), "shell-frozen-"));
+	const commonDir = mkdtempSync(join(tmpdir(), "shell-frozen-git-"));
+	t.after(() => {
+		rmSync(home, { recursive: true, force: true });
+		rmSync(commonDir, { recursive: true, force: true });
+	});
+	mkdirSync(join(commonDir, "gentle-ai"), { recursive: true });
+	writeProfilesStore(home, { team: { reviewer: { model: "nan/glm5.3" } }, solo: { reviewer: { model: "openai-codex/gpt-5.5" } } }, "team");
+	const { pi, handlers, commands } = fakePi();
+	gentleShell(pi, { GENTLE_PI_CONFIG_HOME: home, GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { fetch: fakeFetch(NAN_QUOTA_PAYLOAD).fetchFn, now: () => 1_788_600_000_000, resolveWorktree: () => ({ root: "/repo", commonDir }) });
+	const { ctx, ui } = fakeContext({ token: JWT });
+	await fire(handlers, "session_start", ctx);
+	assert.equal(readFrozenInheritedProfile("shell-session")?.profile?.name, "team", "the session froze the global active profile at start");
+	writeProfilesStore(home, { team: { reviewer: { model: "nan/glm5.3" } }, solo: { reviewer: { model: "openai-codex/gpt-5.5" } } }, "solo");
+	writeFileSync(join(commonDir, "gentle-ai", "profile-pin.json"), JSON.stringify({ kind: "gentle-pi.agent_model_profile_pin", version: 1, profile: "solo" }));
+	const opened = commands.get("gentle:usage")!.handler("", ctx);
+	await settle();
+	assert.ok(openPanelLines(ui).some((line) => /^│ nan ·/.test(line)), "Usage keeps the frozen profile's nan route");
+	ui.closeOverlay?.();
+	await opened;
+	const factory = ui.footerFactory as (tui: unknown, theme: ShellBarTheme, data: unknown) => { dispose(): void };
+	const tui = { terminal: { rows: 40, columns: 160 }, requestRender() {} };
+	const component = factory(tui, plainTheme, { getGitBranch: () => "main", getExtensionStatuses: () => new Map(), getAvailableProviderCount: () => 1, onBranchChange: () => () => {} });
+	try {
+		const status = (sidebarState(tui as unknown as TUI).parts.get("footer") as SidebarRail).render(60).join("\n");
+		assert.match(status, /Profile.*team/, "the status keeps the bare global name of the frozen profile");
+		assert.doesNotMatch(status, /solo/);
+	} finally {
+		component.dispose();
+	}
+});
+
+test("active profile reader: a bound session shows its frozen profile, and follow shows the live default", (t) => {
+	const root = mkdtempSync(join(tmpdir(), "shell-profile-frozen-"));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const commonDir = join(root, "git");
+	mkdirSync(join(commonDir, "gentle-ai"), { recursive: true });
+	writeFileSync(join(root, "profiles.json"), JSON.stringify({ kind: "gentle-pi.agent_model_profiles", version: 1, active: "team", profiles: { team: {}, other: {} } }));
+	const pin = (profile: string) => writeFileSync(join(commonDir, "gentle-ai", "profile-pin.json"), JSON.stringify({ kind: "gentle-pi.agent_model_profile_pin", version: 1, profile }));
+	pin("other");
+	const frozen = createActiveProfileReader({ GENTLE_PI_CONFIG_HOME: root });
+	frozen.bind(root, () => ({ root, commonDir }), "session-frozen");
+	assert.equal(frozen(), "other (local)");
+	const follow = createActiveProfileReader({ GENTLE_PI_CONFIG_HOME: root, GENTLE_PI_PROFILE_FOLLOW: "1" });
+	follow.bind(root, () => ({ root, commonDir }), "session-follow");
+	assert.equal(follow(), "other (local)");
+	rmSync(join(commonDir, "gentle-ai", "profile-pin.json"));
+	assert.equal(frozen.refresh(), false, "the frozen label does not move");
+	assert.equal(frozen(), "other (local)");
+	assert.equal(follow.refresh(), true);
+	assert.equal(follow(), "team", "follow falls to the global active profile");
+	assert.equal(readFrozenInheritedProfile("session-follow"), undefined);
+});
+
 function openPanelLines(ui: FakeUi): string[] {
 	return ui.overlayView!.render(90).map(stripAnsi);
 }
@@ -6215,19 +6312,21 @@ test("an explicit session binding routes the Usage scope ahead of the pin and th
 
 // S9: the config home each of these reads resolves, per case. The OS home is
 // a temporary folder in every case, so no case can reach the real one.
-// "unset" and "empty" are exactly as before: an empty GENTLE_PI_CONFIG_HOME
-// names the current folder. "bundled" stands in for this package running from
-// a bundled install (testing overlay) whose prefix the launcher passed; the
-// user's own GENTLE_PI_CONFIG_HOME is then not this install's.
+// "unset" and "empty" both name ~/.pi/gentle-ai: an empty GENTLE_PI_CONFIG_HOME
+// counts as unset (#2201; it used to name the current folder). "bundled" stands
+// in for this package running from a bundled install (testing overlay) whose
+// prefix the launcher passed; the user's own GENTLE_PI_CONFIG_HOME is then not
+// this install's.
 type ConfigHomeCase = "unset" | "empty" | "bundled";
 function configHomeCase(t: { after: (fn: () => void) => void }, kind: ConfigHomeCase): { env: NodeJS.ProcessEnv; dir: string; userConfig: string } {
 	const base = realpathSync(mkdtempSync(join(tmpdir(), `config-home-${kind}-`)));
-	const saved = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE, GENTLE_PI_CONFIG_HOME: process.env.GENTLE_PI_CONFIG_HOME, GENTLE_SHELL_PREFIX: process.env.GENTLE_SHELL_PREFIX };
+	const saved = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE, GENTLE_PI_CONFIG_HOME: process.env.GENTLE_PI_CONFIG_HOME, GENTLE_SHELL_PREFIX: process.env.GENTLE_SHELL_PREFIX, GENTLE_SHELL_CONFIG_HOME: process.env.GENTLE_SHELL_CONFIG_HOME };
 	const cwd = process.cwd();
 	process.env.HOME = join(base, "home");
 	process.env.USERPROFILE = join(base, "home");
 	delete process.env.GENTLE_PI_CONFIG_HOME;
 	delete process.env.GENTLE_SHELL_PREFIX;
+	delete process.env.GENTLE_SHELL_CONFIG_HOME;
 	t.after(() => {
 		process.chdir(cwd);
 		setBundledInstallForTesting(undefined);
@@ -6242,7 +6341,7 @@ function configHomeCase(t: { after: (fn: () => void) => void }, kind: ConfigHome
 	if (kind === "empty") {
 		mkdirSync(join(base, "cwd"));
 		process.chdir(join(base, "cwd"));
-		return { env: { GENTLE_PI_CONFIG_HOME: "" }, dir: join(base, "cwd"), userConfig };
+		return { env: { GENTLE_PI_CONFIG_HOME: "" }, dir: join(base, "home", ".pi", "gentle-ai"), userConfig };
 	}
 	const prefix = join(base, "prefix");
 	mkdirSync(prefix);

package/tests/gentle-todo.test.ts

@@ -3,6 +3,7 @@ import test, { after, before } from "node:test";
 import { convertToLlm, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Component, TUI } from "@earendil-works/pi-tui";
 import gentleTodo, { todoCollapseKey, todoEnabled } from "../extensions/gentle-todo.ts";
+import { TODO_PROGRESS_EVENT } from "../lib/shell-todo.ts";
 import { CARD_STYLE, cardStyle, setCardStyle } from "../lib/shell-card.ts";
 import { stripAnsi } from "../lib/terminal-theme.ts";
 import { sidebarState } from "../lib/shell-sidebar.ts";
@@ -114,12 +115,27 @@ test("long Todo widgets stay bounded, scroll, resize and keep their collapse con
 		assert.equal((result.details.gentleTodo as { tasks: { title: string; note: string }[] }).tasks[0].title, title.trim());
 		assert.equal((result.details.gentleTodo as { tasks: { title: string; note: string }[] }).tasks[0].note, note.trim());
 		await shortcuts.get("ctrl+shift+t")!.handler(ctx);
-		await shortcuts.get("ctrl+shift+down")!.handler(ctx);
+		await shortcuts.get("alt+shift+down")!.handler(ctx);
 		assert.notDeepEqual(bottom.render(40), collapsed, "keyboard scrolling is available without mouse");
 	}
 	t.after(() => setCardStyle(CARD_STYLE.NEON));
 });
 
+test("Todo shortcuts never take a key Pi binds by default, so startup reports no shortcut conflict", async () => {
+	// Pi keeps its default table in dist/core/keybindings.js, next to the package entry.
+	const { KEYBINDINGS } = await import(new URL("core/keybindings.js", import.meta.resolve("@earendil-works/pi-coding-agent")).href) as
+		{ KEYBINDINGS: Record<string, { defaultKeys?: string | string[] }> };
+	assert.ok("tui.altScreen.previousPrompt" in KEYBINDINGS, "the table includes Pi's built-in prompt navigation");
+	const owners = new Map<string, string[]>();
+	for (const [id, binding] of Object.entries(KEYBINDINGS)) {
+		for (const key of ([] as string[]).concat(binding.defaultKeys ?? [])) owners.set(key, [...(owners.get(key) ?? []), id]);
+	}
+	const { pi, shortcuts } = fakePi();
+	gentleTodo(pi, {});
+	assert.deepEqual([...shortcuts.keys()].sort(), ["alt+shift+down", "alt+shift+up", "ctrl+shift+t"]);
+	for (const key of shortcuts.keys()) assert.equal(owners.get(key), undefined, `${key} is a Pi default for ${owners.get(key)?.join(", ")}`);
+});
+
 test("Todo keyboard scrolling targets the visible card after a cached sidebar breakpoint round-trip", async (t) => {
 	const node = Symbol.for("@earendil-works/pi-tui/layout-node");
 	for (const style of [CARD_STYLE.NEON, CARD_STYLE.FLOAT]) {
@@ -146,11 +162,11 @@ test("Todo keyboard scrolling targets the visible card after a cached sidebar br
 			bottom.render(40);
 			tui.terminal.columns = 160;
 			const before = railLines();
-			await shortcuts.get("ctrl+shift+down")!.handler(ctx);
+			await shortcuts.get("alt+shift+down")!.handler(ctx);
 			const after = railLines();
 			assert.notDeepEqual(after, before, "DOWN changes the visible cached rail, not the hidden bottom widget");
 			assert.match(after.join("\n"), /↑↓ 4–/);
-			await shortcuts.get("ctrl+shift+up")!.handler(ctx);
+			await shortcuts.get("alt+shift+up")!.handler(ctx);
 			assert.deepEqual(railLines(), before, "UP restores the expanded viewport");
 		} finally {
 			dispose();
@@ -288,11 +304,25 @@ function toolTurn(toolName = "read") {
 	return { message: { role: "assistant", content: [{ type: "toolCall", id: "call", name: toolName, arguments: {} }] }, toolResults: [] };
 }
 
-async function contextReminder(fire: ReturnType<typeof fakePi>["fire"], ctx: ExtensionContext) {
+type ContextMessage = { role: string; content: unknown; customType?: string; display?: boolean; timestamp?: number };
+
+async function contextMessages(fire: ReturnType<typeof fakePi>["fire"], ctx: ExtensionContext): Promise<ContextMessage[] | undefined> {
 	const messages = [{ role: "user", content: "Keep working", timestamp: 1 }];
-	const result = await fire("context", ctx, { messages }) as { messages: Array<{ role: string; content: unknown }> } | undefined;
+	const result = await fire("context", ctx, { messages }) as { messages: ContextMessage[] } | undefined;
 	assert.deepEqual(messages, [{ role: "user", content: "Keep working", timestamp: 1 }], "request-local injection must not mutate the input transcript");
-	return result;
+	if (result === undefined) return undefined;
+	assert.deepEqual(result.messages[0], { role: "user", content: "Keep working", timestamp: 1 }, "the transcript stays first; todo messages trail it");
+	return result.messages;
+}
+
+/** The request-local reminder, if the next model request carries one. */
+async function contextReminder(fire: ReturnType<typeof fakePi>["fire"], ctx: ExtensionContext): Promise<ContextMessage | undefined> {
+	return (await contextMessages(fire, ctx))?.find((message) => message.customType === "gentle-todo-reminder");
+}
+
+/** The request-local current-list message, if the next model request carries one (#1662). */
+async function contextState(fire: ReturnType<typeof fakePi>["fire"], ctx: ExtensionContext): Promise<ContextMessage | undefined> {
+	return (await contextMessages(fire, ctx))?.find((message) => message.customType === "gentle-todo-state");
 }
 
 async function workTurns(fire: ReturnType<typeof fakePi>["fire"], ctx: ExtensionContext, count: number) {
@@ -312,13 +342,14 @@ test("runtime reminder arrives after four tool-use turns, only once, without cha
 	await workTurns(fire, ctx, 3);
 	assert.equal(await contextReminder(fire, ctx), undefined);
 	await workTurns(fire, ctx, 1);
-	const result = await contextReminder(fire, ctx);
-	assert.ok(result, "the next model request must carry a reminder within the same run");
-	assert.equal(result.messages.length, 2);
-	assert.deepEqual(result.messages[0], { role: "user", content: "Keep working", timestamp: 1 });
-	assert.deepEqual(result.messages[1], { role: "custom", customType: "gentle-todo-reminder", content: REMINDER, display: false, timestamp: (result.messages[1] as { timestamp?: number }).timestamp });
-	const converted = convertToLlm(result.messages as Parameters<typeof convertToLlm>[0]);
-	assert.deepEqual(converted[1], { role: "user", content: [{ type: "text", text: REMINDER }], timestamp: (result.messages[1] as { timestamp?: number }).timestamp }, "Pi forwards the reminder as provider-compatible text");
+	const messages = await contextMessages(fire, ctx);
+	assert.ok(messages, "the next model request must carry a reminder within the same run");
+	assert.equal(messages.length, 3, "transcript, current list, then the reminder");
+	assert.equal(messages[1]!.customType, "gentle-todo-state");
+	const reminder = messages[2]!;
+	assert.deepEqual(reminder, { role: "custom", customType: "gentle-todo-reminder", content: REMINDER, display: false, timestamp: reminder.timestamp });
+	const converted = convertToLlm(messages as Parameters<typeof convertToLlm>[0]);
+	assert.deepEqual(converted[2], { role: "user", content: [{ type: "text", text: REMINDER }], timestamp: reminder.timestamp }, "Pi forwards the reminder as provider-compatible text");
 	await workTurns(fire, ctx, 4);
 	assert.equal(await contextReminder(fire, ctx), undefined, "no repeated nagging without a todo write");
 	const listed = await tool.execute("list", { action: "list" }, undefined, undefined, ctx);
@@ -418,31 +449,213 @@ function promptEvent(): { systemPrompt: string; systemPromptOptions: { appendSys
 	return { systemPrompt: "base", systemPromptOptions: { appendSystemPrompt: "" } };
 }
 
-test("every turn carries the open tasks in appendSystemPrompt (never a returned systemPrompt) and the card goes stale after two silent turns", async () => {
+test("the system prompt carries only a byte-stable todo block; the current list travels as a request-local message (#1662)", async () => {
 	const { pi, tools, fire } = fakePi();
 	gentleTodo(pi, {});
 	const { ctx, widget } = fakeContext();
 	await fire("session_start", ctx);
-	await fire("before_agent_start", ctx, promptEvent());
+	const emptyEvent = promptEvent();
+	assert.equal(await fire("before_agent_start", ctx, emptyEvent), undefined, "the handler must not return a replacement systemPrompt");
+	assert.match(emptyEvent.systemPromptOptions.appendSystemPrompt, /^## Todo list/);
+	assert.match(emptyEvent.systemPromptOptions.appendSystemPrompt, /mark a task in_progress before starting/);
+	assert.equal(await contextState(fire, ctx), undefined, "an empty list sends no state message");
+
 	await tools.get("todo")!.execute("c1", { action: "write", tasks: [{ title: "Fix the bug" }] }, undefined, undefined, ctx);
 	await fire("tool_execution_end", ctx, { toolName: "todo" });
-
 	const withTasksEvent = promptEvent();
-	const withTasksResult = await fire("before_agent_start", ctx, withTasksEvent);
-	assert.equal(withTasksResult, undefined, "the handler must not return a replacement systemPrompt");
-	assert.match(withTasksEvent.systemPromptOptions.appendSystemPrompt, /^## Todo list/);
-	assert.match(withTasksEvent.systemPromptOptions.appendSystemPrompt, /1\. \[pending\] Fix the bug/);
+	await fire("before_agent_start", ctx, withTasksEvent);
+	assert.equal(withTasksEvent.systemPromptOptions.appendSystemPrompt, emptyEvent.systemPromptOptions.appendSystemPrompt, "writing a list must not change the system prompt");
+	assert.doesNotMatch(withTasksEvent.systemPromptOptions.appendSystemPrompt, /Fix the bug/, "task content never enters the system prompt");
+	const state = await contextState(fire, ctx);
+	assert.ok(state, "open tasks arrive as a trailing request-local message");
+	assert.equal(state.role, "custom");
+	assert.equal(state.display, false);
+	assert.match(String(state.content), /1\. \[pending\] Fix the bug/);
 	assert.doesNotMatch(widget()![0], /stale/);
 
-	const staleEvent = promptEvent();
-	await fire("before_agent_start", ctx, staleEvent);
-	assert.match(staleEvent.systemPromptOptions.appendSystemPrompt, /stale: 2 turns without an update/);
-	assert.match(widget()![0], /ctrl\+shift\+t collapse/);
-	assert.match(widget()![1], /stale · 2 turns/);
+	// Silent turns: the UI card goes stale, the system prompt stays frozen (#1367).
+	for (const expected of ["stale · 2 turns", "stale · 3 turns"]) {
+		const silent = promptEvent();
+		await fire("before_agent_start", ctx, silent);
+		assert.equal(silent.systemPromptOptions.appendSystemPrompt, emptyEvent.systemPromptOptions.appendSystemPrompt);
+		assert.match(widget()![1], new RegExp(expected));
+	}
 
+	// Status, note, title and ordering changes reach the model through the message only.
 	await tools.get("todo")!.execute("c2", { action: "update", id: 1, status: "in_progress", note: "on it" }, undefined, undefined, ctx);
 	await fire("tool_execution_end", ctx, { toolName: "todo" });
+	const updatedEvent = promptEvent();
+	await fire("before_agent_start", ctx, updatedEvent);
+	assert.equal(updatedEvent.systemPromptOptions.appendSystemPrompt, emptyEvent.systemPromptOptions.appendSystemPrompt, "a status change must not change the system prompt");
+	assert.match(String((await contextState(fire, ctx))!.content), /1\. \[in_progress\] Fix the bug — on it/);
 	assert.doesNotMatch(widget()![0], /stale/);
+
+	await tools.get("todo")!.execute("c3", { action: "update", id: 1, status: "done" }, undefined, undefined, ctx);
+	await fire("tool_execution_end", ctx, { toolName: "todo" });
+	assert.equal(await contextState(fire, ctx), undefined, "a finished list sends no state message");
+	const finishedEvent = promptEvent();
+	await fire("before_agent_start", ctx, finishedEvent);
+	assert.equal(finishedEvent.systemPromptOptions.appendSystemPrompt, emptyEvent.systemPromptOptions.appendSystemPrompt, "finishing the list must not change the system prompt");
+});
+
+/**
+ * Drives the extension the way Pi's agent loop does (#2195): every model request
+ * runs the context handlers over the persisted transcript, and a custom message
+ * sent with triggerTurn false while streaming is appended to the transcript at
+ * turn_end, after the tool results (agent-session `_flushPendingCustomMessages`).
+ */
+function liveSession() {
+	const base = fakePi();
+	const queued: ContextMessage[] = [];
+	const pi = {
+		...base.pi,
+		sendMessage(message: { customType: string; content: string; display: boolean }, options: { triggerTurn?: boolean }) {
+			assert.equal(options.triggerTurn, false, "todo state must never start a turn");
+			queued.push({ role: "custom", customType: message.customType, content: message.content, display: message.display, timestamp: 0 });
+		},
+	} as unknown as ExtensionAPI;
+	gentleTodo(pi, {});
+	const { ctx } = fakeContext();
+	const transcript: ContextMessage[] = [{ role: "user", content: "Work on it", timestamp: 1 }];
+	const requests: ContextMessage[][] = [];
+	let call = 0;
+	const request = async () => {
+		const result = await base.fire("context", ctx, { messages: [...transcript] }) as { messages: ContextMessage[] } | undefined;
+		const messages = result?.messages ?? [...transcript];
+		requests.push(messages);
+		return messages;
+	};
+	/** One model request whose assistant reply calls `todo` (when params are given) or `read`. */
+	const turn = async (todo?: Record<string, unknown>) => {
+		await request();
+		call += 1;
+		const id = `call-${call}`;
+		const name = todo ? "todo" : "read";
+		const assistant = { role: "assistant", content: [{ type: "toolCall", id, name, arguments: todo ?? {} }], timestamp: 0 };
+		transcript.push(assistant);
+		if (todo) await base.tools.get("todo")!.execute(id, todo, undefined, undefined, ctx);
+		transcript.push({ role: "toolResult", content: [{ type: "text", text: "ok" }], timestamp: 0 });
+		await base.fire("turn_end", ctx, { message: assistant, toolResults: [] });
+		transcript.push(...queued.splice(0));
+	};
+	const assertAppendOnly = (from: number) => {
+		for (let index = from + 1; index < requests.length; index++) {
+			const previous = requests[index - 1]!;
+			assert.deepEqual(requests[index]!.slice(0, previous.length), previous, `request ${index} must extend request ${index - 1} byte for byte`);
+		}
+	};
+	const visibleState = (messages: ContextMessage[]) => [...messages].reverse().find((message) => message.customType === "gentle-todo-state")?.content;
+	return { ctx, fire: base.fire, transcript, requests, request, turn, assertAppendOnly, visibleState };
+}
+
+test("a todo write in a running tool loop reaches the transcript before the next request, which stays append-only (#2195)", async () => {
+	const live = liveSession();
+	await live.fire("session_start", live.ctx);
+	await live.turn({ action: "write", tasks: [{ title: "Fix the bug" }, { title: "Ship it" }] });
+	await live.turn();
+	await live.turn();
+	await live.turn({ action: "update", id: 1, status: "done" });
+	await live.turn();
+	await live.request();
+	assert.match(live.visibleState(live.requests.at(-1)!) as string, /1\. \[done\] Fix the bug\n2\. \[pending\] Ship it/);
+	live.assertAppendOnly(0);
+});
+
+test("closing every task does not leave a stale open list in the transcript (#2195)", async () => {
+	for (const close of [{ action: "update", id: 1, status: "done" }, { action: "update", id: 1, status: "dropped" }, { action: "clear" }]) {
+		const live = liveSession();
+		await live.fire("session_start", live.ctx);
+		await live.turn({ action: "write", tasks: [{ title: "Fix the bug" }] });
+		await live.turn(close);
+		await live.turn();
+		const messages = await live.request();
+		assert.equal(live.visibleState(messages), "Current todo list: no open tasks.", `${JSON.stringify(close)}: the model must not see the closed task as still open`);
+		live.assertAppendOnly(0);
+	}
+});
+
+test("an open list missing from the transcript (compaction, branch switch) is persisted again once, then requests stay append-only (#2195)", async () => {
+	const live = liveSession();
+	await live.fire("session_start", live.ctx);
+	await live.turn({ action: "write", tasks: [{ title: "Fix the bug" }] });
+	// Compaction summarises the head of the conversation, including the persisted state.
+	live.transcript.splice(0, live.transcript.length, { role: "user", content: "Summary of earlier work", timestamp: 2 });
+	const healedFrom = live.requests.length;
+	await live.turn();
+	await live.turn();
+	await live.turn();
+	await live.request();
+	for (const messages of live.requests.slice(healedFrom)) assert.match(String(live.visibleState(messages)), /\[pending\] Fix the bug/);
+	assert.equal(live.transcript.filter((message) => message.customType === "gentle-todo-state").length, 1, "the missing state is persisted exactly once");
+	live.assertAppendOnly(healedFrom + 1);
+});
+
+test("consecutive context requests with an unchanged Todo list preserve prefix stability (#2195)", async () => {
+	const { pi, tools, fire } = fakePi();
+	gentleTodo(pi, {});
+	const { ctx } = fakeContext();
+	await fire("session_start", ctx);
+	await tools.get("todo")!.execute("c1", { action: "write", tasks: [{ title: "Fix the bug" }] }, undefined, undefined, ctx);
+
+	// Request 1: first model request
+	const userMsg = { role: "user", content: "Work on it", timestamp: 100 };
+	const req1 = await fire("context", ctx, { messages: [userMsg] }) as { messages: Array<{ role: string; customType?: string }> };
+	assert.ok(req1, "req1 must return context messages");
+	assert.ok(req1.messages.some((m) => (m as { customType?: string }).customType === "gentle-todo-state"), "req1 must include gentle-todo-state");
+
+	// Model executes a tool (read), producing assistant message and tool result
+	const assistantMsg = { role: "assistant", content: [{ type: "toolCall", id: "read-1", name: "read", arguments: {} }], timestamp: 200 };
+	const toolResultMsg = { role: "toolResult", toolCallId: "read-1", content: [{ type: "text", text: "file content" }], timestamp: 300 };
+
+	// Request 2: next model request with unchanged todo list.
+	// The input messages to context include the transcript with the already-delivered state message
+	const inputReq2 = [...req1.messages, assistantMsg, toolResultMsg];
+	const req2 = await fire("context", ctx, { messages: inputReq2 }) as { messages: Array<{ role: string; customType?: string }> } | undefined;
+
+	// req2 must not append a redundant trailing gentle-todo-state that would invalidate prefix caching
+	const effectiveReq2 = req2?.messages ?? inputReq2;
+	assert.deepEqual(
+		effectiveReq2.slice(0, req1.messages.length),
+		req1.messages,
+		"req1 must be an exact prefix of req2 to preserve prompt caching",
+	);
+	// No duplicate trailing state message at the end of req2
+	const stateMessages = effectiveReq2.filter((m) => (m as { customType?: string }).customType === "gentle-todo-state");
+	assert.equal(stateMessages.length, 1, "must not append duplicate gentle-todo-state when unchanged");
+});
+
+test("todo write and update persist gentle-todo-state custom message to transcript (#2195)", async () => {
+	const sent: Array<{ message: unknown; options: unknown }> = [];
+	const base = fakePi();
+	const pi = {
+		...base.pi,
+		sendMessage(message: unknown, options: unknown) {
+			sent.push({ message, options });
+		},
+	} as unknown as ExtensionAPI;
+	gentleTodo(pi, {});
+	const { ctx } = fakeContext();
+	await base.fire("session_start", ctx);
+
+	// 1. todo write persists state
+	await base.tools.get("todo")!.execute("c1", { action: "write", tasks: [{ title: "Task 1" }] }, undefined, undefined, ctx);
+	assert.equal(sent.length, 1);
+	assert.deepEqual(sent[0]!.options, { triggerTurn: false });
+	const firstMsg = sent[0]!.message as { role: string; customType: string; content: string; display: boolean };
+	assert.equal(firstMsg.customType, "gentle-todo-state");
+	assert.equal(firstMsg.display, false);
+	assert.match(firstMsg.content, /1\. \[pending\] Task 1/);
+
+	// 2. todo update persists new state
+	await base.tools.get("todo")!.execute("c2", { action: "update", id: 1, status: "in_progress", note: "doing" }, undefined, undefined, ctx);
+	assert.equal(sent.length, 2);
+	assert.deepEqual(sent[1]!.options, { triggerTurn: false });
+	const secondMsg = sent[1]!.message as { content: string };
+	assert.match(secondMsg.content, /1\. \[in_progress\] Task 1 — doing/);
+
+	// 3. todo list does NOT persist extra messages
+	await base.tools.get("todo")!.execute("c3", { action: "list" }, undefined, undefined, ctx);
+	assert.equal(sent.length, 2, "read actions must not emit state messages");
 });
 
 test("before_agent_start is idempotent: a todo block already present in appendSystemPrompt is not duplicated", async () => {
@@ -555,8 +768,26 @@ test("a list left with only dropped tasks open finishes and clears; a blocked-on
 		await fire("agent_end", ctx);
 		const event = promptEvent();
 		await fire("before_agent_start", ctx, event);
-		assert.match(event.systemPromptOptions.appendSystemPrompt, /2\. \[blocked\] Deploy — waiting for an admin/);
-		assert.doesNotMatch(event.systemPromptOptions.appendSystemPrompt, /stale/);
+		assert.doesNotMatch(event.systemPromptOptions.appendSystemPrompt, /Deploy/);
+		assert.match(String((await contextState(fire, ctx))!.content), /2\. \[blocked\] Deploy — waiting for an admin/);
 	}
 	assert.match(widget()![2], /⊘ Deploy · waiting for an admin/);
 });
+
+// Harness roadmap T6: the todo list is the session's progress, so the runtime
+// publishes it for peers instead of asking the model to call orchestrator_session_id.
+test("a todo write emits the session's progress; list and errors emit nothing", async () => {
+	const { pi, tools } = fakePi();
+	const emitted: Array<{ name: string; data: unknown }> = [];
+	Object.assign(pi, { events: { emit: (name: string, data: unknown) => { emitted.push({ name, data }); }, on: () => () => {} } });
+	gentleTodo(pi, {});
+	const { ctx } = fakeContext();
+	const todo = (params: unknown) => tools.get("todo")!.execute("call", params, undefined, undefined, ctx);
+	await todo({ action: "write", tasks: [{ title: "Write parser", status: "done" }, { title: "Wire CLI", status: "in_progress" }, { title: "Docs" }] });
+	assert.deepEqual(emitted, [{ name: TODO_PROGRESS_EVENT, data: { sessionId: "s1", done: 1, total: 3, current: "Wire CLI" } }]);
+	await todo({ action: "list" });
+	await todo({ action: "update", id: 99, status: "done" });
+	assert.equal(emitted.length, 1, "list and a failed update publish nothing");
+	await todo({ action: "update", id: 2, status: "done" });
+	assert.deepEqual(emitted.at(-1)?.data, { sessionId: "s1", done: 2, total: 3, current: null });
+});