gentle-pi 3.7.0 → 4.0.0

package/tests/odd-phase-loader.test.ts

@@ -0,0 +1,253 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import test from "node:test";
+import { createJiti } from "jiti";
+import { initTheme } from "@earendil-works/pi-coding-agent";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+initTheme("dark");
+
+test("a child process cannot overwrite the primary process phase even with the same session id", async () => {
+	const registry = (await createJiti(import.meta.url, { moduleCache: false }).import<typeof import("../lib/odd-phase.ts")>("../lib/odd-phase.ts")).oddPhaseRegistry;
+	const sessionId = "process-isolation-test";
+	try {
+		registry.report(sessionId, "authorizing");
+		const output = execFileSync(process.execPath, ["--experimental-strip-types", "--input-type=module", "-e",
+			`import { oddPhaseRegistry } from ${JSON.stringify(new URL("../lib/odd-phase.ts", import.meta.url).href)}; console.log(oddPhaseRegistry.get("process-isolation-test") ?? "empty"); oddPhaseRegistry.report("process-isolation-test", "closing");`], { encoding: "utf8" });
+		assert.equal(output.trim(), "empty");
+		assert.equal(registry.get(sessionId), "authorizing");
+	} finally { registry.clear(sessionId); }
+});
+
+// Pi gives each extension its own uncached jiti loader. Exercise the actual
+// writer tool and reader prompt, not two imports through Node's module cache.
+test("separate extension loaders share only the active session's ODD phase and redraw", async () => {
+	const aiLoader = createJiti(import.meta.url, { moduleCache: false });
+	const shellLoader = createJiti(import.meta.url, { moduleCache: false });
+	const { createGentleAiExtension } = await aiLoader.import<typeof import("../extensions/gentle-ai.ts")>("../extensions/gentle-ai.ts");
+	const { default: shell } = await shellLoader.import<typeof import("../extensions/gentle-shell.ts")>("../extensions/gentle-shell.ts");
+	const aiRegistry = (await aiLoader.import<typeof import("../lib/odd-phase.ts")>("../lib/odd-phase.ts")).oddPhaseRegistry;
+	const shellRegistry = (await shellLoader.import<typeof import("../lib/odd-phase.ts")>("../lib/odd-phase.ts")).oddPhaseRegistry;
+	const tools = new Map<string, {
+		execute: (...args: unknown[]) => Promise<unknown>;
+		renderShell?: string;
+		renderCall?: (args: unknown, theme: unknown, context: unknown) => { render(width: number): string[]; invalidate(): void };
+		renderResult?: (result: unknown, options: unknown, theme: unknown, context: unknown) => { render(width: number): string[]; invalidate(): void };
+	}>();
+	const handlers = new Map<string, Array<(event: unknown, ctx: unknown) => unknown>>();
+	const pi = {
+		on(name: string, fn: (event: unknown, ctx: unknown) => unknown) { handlers.set(name, [...(handlers.get(name) ?? []), fn]); },
+		registerTool(tool: { name: string; execute: (...args: unknown[]) => Promise<unknown> }) { tools.set(tool.name, tool); },
+		registerCommand() {}, registerShortcut() {}, registerMessageRenderer() {}, appendEntry() {},
+		events: { on: () => () => {}, emit() {} },
+		exec: async () => ({ stdout: "", stderr: "", code: 0, killed: false }),
+	};
+	createGentleAiExtension({ nativeReviewCli: null } as never)(pi as never);
+	shell(pi as never, {}, { resolveWorktree: (path: string) => ({ root: path, commonDir: path }), gitRunner: () => async () => ({ stdout: "", stderr: "", code: 0, killed: false }), devBinary: () => undefined } as never);
+	let sessionId: string | undefined = "primary-loader-test";
+	let editorFactory: ((tui: unknown, theme: unknown, bindings: unknown) => { render(width: number): string[]; setAnimationPolicy(policy: string): void; dispose(): void }) | undefined;
+	let redraws = 0;
+	const ui = {
+		theme: { fg: (_color: string, text: string) => text, bold: (text: string) => text },
+		setFooter() {}, setWidget() {}, setWorkingVisible() {}, notify() {},
+		getEditorComponent: () => editorFactory,
+		setEditorComponent(factory: typeof editorFactory) { editorFactory = factory; },
+	};
+	const ctx = {
+		hasUI: true, mode: "tui", cwd: "/repo", ui,
+		sessionManager: { getSessionId: () => sessionId, getEntries: () => [], getCwd: () => "/repo" },
+		hasPendingMessages: () => false, isIdle: () => true,
+		modelRegistry: { isUsingOAuth: () => false },
+	};
+	const fire = async (name: string) => { for (const fn of handlers.get(name) ?? []) await fn({}, ctx); };
+	let editor: ReturnType<NonNullable<typeof editorFactory>> | undefined;
+	try {
+		await fire("session_start");
+		assert.ok(editorFactory, "Gentle Shell should install its prompt");
+		editor = editorFactory({ terminal: { rows: 40, columns: 120 }, requestRender() { redraws++; } }, { borderColor: (text: string) => text, selectList: {} }, { matches: () => false });
+		editor.setAnimationPolicy("potato");
+		await fire("agent_start");
+		const render = () => stripAnsi(editor!.render(60)[0]!);
+		assert.match(render(), /working…/);
+		assert.ok(tools.get("gentle_odd_phase"));
+		const report = (phase: string) => tools.get("gentle_odd_phase")!.execute("call", { phase }, undefined, undefined, ctx);
+		redraws = 0;
+		const phaseTool = tools.get("gentle_odd_phase")!;
+		const successful = await report("authorizing");
+		assert.equal(phaseTool.renderShell, "self", "Pi must not paint its default tool card");
+		const toolTheme = { fg: (_color: string, text: string) => text, bold: (text: string) => text };
+		const renderContext = (isError: boolean) => ({
+			args: { phase: "authorizing" }, toolCallId: "call", invalidate() {}, lastComponent: undefined,
+			state: {}, cwd: "/repo", executionStarted: true, argsComplete: true,
+			isPartial: false, expanded: false, showImages: false, isError,
+		});
+		const renderTool = (component: { render(width: number): string[]; invalidate(): void }) => component.render(80);
+		assert.ok(phaseTool.renderCall && phaseTool.renderResult);
+		assert.deepEqual(renderTool(phaseTool.renderCall({ phase: "authorizing" }, toolTheme, renderContext(false))), []);
+		assert.deepEqual(renderTool(phaseTool.renderResult(successful, { isPartial: false, expanded: false }, toolTheme, renderContext(false))), []);
+		assert.deepEqual(renderTool(phaseTool.renderResult(successful, { isPartial: false, expanded: true }, toolTheme, renderContext(false))), []);
+		assert.match(render(), /authorizing…/, "suppressing the transcript must not suppress the editor phase");
+		assert.ok(redraws > 0, "the phase must request redraw even without a pulse");
+		assert.equal(aiRegistry.get(sessionId), "authorizing");
+		assert.equal(shellRegistry.get(sessionId), "authorizing");
+		for (const [id, phase, expected] of [
+			["primary-loader-test", "not-a-phase", /Invalid ODD phase/],
+			[undefined, "exploring", /No active session/],
+		] as const) {
+			sessionId = id;
+			let message = "";
+			await assert.rejects(() => report(phase), (error: unknown) => {
+				assert.ok(error instanceof Error);
+				message = error.message;
+				assert.match(message, expected);
+				return true;
+			});
+			const failure = { content: [{ type: "text", text: message }], isError: true };
+			assert.match(renderTool(phaseTool.renderResult(failure, { isPartial: false, expanded: false }, toolTheme, renderContext(true))).join("\n"), expected);
+			assert.match(renderTool(phaseTool.renderResult(failure, { isPartial: false, expanded: true }, toolTheme, renderContext(true))).join("\n"), expected);
+		}
+		const callComponent = phaseTool.renderCall({ phase: "checking" }, toolTheme, renderContext(false));
+		const resultComponent = phaseTool.renderResult(successful, { isPartial: false, expanded: false }, toolTheme, renderContext(false));
+		for (const component of [callComponent, resultComponent]) {
+			assert.equal(typeof component.invalidate, "function");
+			component.invalidate();
+			assert.deepEqual(component.render(80), []);
+		}
+		sessionId = "primary-loader-test";
+		assert.match(render(), /authorizing…/, "a malformed report cannot erase the last valid phase");
+		const cleared = await report("clear");
+		assert.deepEqual(renderTool(phaseTool.renderResult(cleared, { isPartial: false, expanded: false }, toolTheme, renderContext(false))), []);
+		assert.match(render(), /working…/);
+		await report("authorizing");
+		sessionId = "child-session";
+		await report("exploring");
+		assert.equal(aiRegistry.get("primary-loader-test"), "authorizing");
+		sessionId = "primary-loader-test";
+		assert.match(render(), /authorizing…/);
+		await fire("agent_settled");
+		assert.equal(aiRegistry.get(sessionId), undefined);
+		await fire("agent_start");
+		assert.match(render(), /working…/);
+		await report("checking");
+		await fire("agent_start");
+		assert.match(render(), /working…/);
+		await report("closing");
+		await fire("session_shutdown");
+		assert.equal(aiRegistry.get(sessionId), undefined);
+		redraws = 0;
+		await report("planning");
+		assert.equal(redraws, 0, "shutdown must remove the old render callback");
+	} finally {
+		aiRegistry.clear("primary-loader-test");
+		aiRegistry.clear("child-session");
+		editor?.dispose();
+	}
+});
+
+// The label follows the primary session's own tool activity without any
+// gentle_odd_phase call; an explicit report still refines it.
+test("tool activity in the primary session drives the working label across extension loaders", async () => {
+	const aiLoader = createJiti(import.meta.url, { moduleCache: false });
+	const shellLoader = createJiti(import.meta.url, { moduleCache: false });
+	const { createGentleAiExtension } = await aiLoader.import<typeof import("../extensions/gentle-ai.ts")>("../extensions/gentle-ai.ts");
+	const { default: shell } = await shellLoader.import<typeof import("../extensions/gentle-shell.ts")>("../extensions/gentle-shell.ts");
+	const registry = (await aiLoader.import<typeof import("../lib/odd-phase.ts")>("../lib/odd-phase.ts")).oddPhaseRegistry;
+	const tools = new Map<string, { execute: (...args: unknown[]) => Promise<unknown> }>();
+	const handlers = new Map<string, Array<(event: unknown, ctx: unknown) => unknown>>();
+	const pi = {
+		on(name: string, fn: (event: unknown, ctx: unknown) => unknown) { handlers.set(name, [...(handlers.get(name) ?? []), fn]); },
+		registerTool(tool: { name: string; execute: (...args: unknown[]) => Promise<unknown> }) { tools.set(tool.name, tool); },
+		registerCommand() {}, registerShortcut() {}, registerMessageRenderer() {}, appendEntry() {},
+		events: { on: () => () => {}, emit() {} },
+		exec: async () => ({ stdout: "", stderr: "", code: 0, killed: false }),
+	};
+	createGentleAiExtension({ nativeReviewCli: null } as never)(pi as never);
+	shell(pi as never, {}, { resolveWorktree: (path: string) => ({ root: path, commonDir: path }), gitRunner: () => async () => ({ stdout: "", stderr: "", code: 0, killed: false }), devBinary: () => undefined } as never);
+	let sessionId = "tool-activity-loader-test";
+	let redraws = 0;
+	let editorFactory: ((tui: unknown, theme: unknown, bindings: unknown) => { render(width: number): string[]; setAnimationPolicy(policy: string): void; dispose(): void }) | undefined;
+	const ui = {
+		theme: { fg: (_color: string, text: string) => text, bold: (text: string) => text },
+		setFooter() {}, setWidget() {}, setWorkingVisible() {}, notify() {},
+		getEditorComponent: () => editorFactory,
+		setEditorComponent(factory: typeof editorFactory) { editorFactory = factory; },
+	};
+	const ctx = {
+		hasUI: true, mode: "tui", cwd: "/repo", ui,
+		sessionManager: { getSessionId: () => sessionId, getEntries: () => [], getCwd: () => "/repo" },
+		hasPendingMessages: () => false, isIdle: () => true,
+		modelRegistry: { isUsingOAuth: () => false },
+	};
+	const fire = async (name: string, event: unknown = {}, context: unknown = ctx) => { for (const fn of handlers.get(name) ?? []) await fn(event, context); };
+	const tool = (toolName: string, args: unknown = {}) => fire("tool_execution_start", { type: "tool_execution_start", toolCallId: `call-${toolName}`, toolName, args });
+	let editor: ReturnType<NonNullable<typeof editorFactory>> | undefined;
+	try {
+		await fire("session_start");
+		assert.ok(editorFactory, "Gentle Shell should install its prompt");
+		editor = editorFactory({ terminal: { rows: 40, columns: 120 }, requestRender() { redraws++; } }, { borderColor: (text: string) => text, selectList: {} }, { matches: () => false });
+		editor.setAnimationPolicy("potato");
+		await fire("agent_start");
+		const render = () => stripAnsi(editor!.render(60)[0]!);
+		assert.match(render(), /working…/);
+
+		await tool("read", { path: "lib/odd-phase.ts" });
+		assert.match(render(), /exploring…/, "reading a file shows exploring");
+		await tool("edit", { path: "lib/odd-phase.ts" });
+		assert.match(render(), /implementing…/, "editing shows implementing");
+		await tool("bash", { command: "pnpm test" });
+		assert.match(render(), /checking…/, "running tests shows checking");
+		await tool("ask_user_question", {});
+		assert.match(render(), /deciding…/, "asking the user shows deciding");
+		await tool("mcp__custom-tools__write", { path: "odd/tasks/feature.md" });
+		assert.match(render(), /planning…/, "MCP-prefixed names are normalized");
+		await tool("subagent_start", {});
+		await tool("bash", { command: "git push" });
+		await tool("unknown_tool", {});
+		assert.match(render(), /planning…/, "unknown tools and ambiguous commands leave the label unchanged");
+		await tool("subagent_run", { agent: "gentle-ai-worker", mode: "task", task: "implement" });
+		assert.match(render(), /implementing…/, "foreground worker launch replaces stale planning");
+		redraws = 0;
+		await tool("read", { path: "lib/odd-phase.ts" });
+		await tool("todo", {});
+		await tool("write", { path: "odd/tasks/feature.md" });
+		assert.match(render(), /implementing…/, "incidental reads and task bookkeeping cannot hide worker activity");
+		assert.equal(redraws, 0, "ignored signals do not redraw the editor");
+		await tool("subagent_run", { agent: "gentle-ai-verify", mode: "background", task: "verify" });
+		assert.match(render(), /checking…/, "background verifier launch replaces active implementation");
+		assert.equal(redraws, 1, "phase change redraws even under potato animation");
+		await tool("read", { path: "tests/odd-phase.test.ts" });
+		await tool("todo", {});
+		assert.match(render(), /checking…/);
+		await tool("subagent_run", { agent: "unknown", task: "gentle-ai-worker implementing" });
+		assert.match(render(), /checking…/, "unknown agent prose is not evidence");
+		await tool("subagent_run", { agent: "gentle-ai-explore", mode: "task" });
+		assert.match(render(), /exploring…/, "later delegated exploration is a real phase transition");
+		await tool("subagent_run", { agent: "gentle-ai-worker", mode: "background" });
+		assert.match(render(), /implementing…/, "background worker replaces stale exploring");
+		await tool("subagent_run", { agent: "gentle-ai-verify", mode: "task" });
+		assert.match(render(), /checking…/, "foreground verifier replaces stale work");
+		await tool("edit", { path: "lib/odd-phase.ts" });
+		assert.match(render(), /implementing…/, "a subsequent source edit can restart implementation");
+
+		await tools.get("gentle_odd_phase")!.execute("call", { phase: "researching" }, undefined, undefined, ctx);
+		await tool("gentle_odd_phase", { phase: "researching" });
+		await tool("grep", { pattern: "x" });
+		assert.match(render(), /researching…/, "an explicit phase survives a following grep");
+		await tool("edit", { path: "lib/odd-phase.ts" });
+		assert.match(render(), /implementing…/, "a stronger inferred phase overrides an explicit one");
+
+		await fire("agent_start");
+		assert.match(render(), /working…/, "a new turn starts unlabeled");
+		const childCtx = { ...ctx, mode: "rpc" };
+		await fire("tool_execution_start", { type: "tool_execution_start", toolCallId: "child", toolName: "subagent_run", args: { agent: "gentle-ai-worker" } }, childCtx);
+		assert.equal(registry.get(sessionId), undefined, "a headless RPC (subagent) process never infers a phase");
+		sessionId = "other-session";
+		await tool("subagent_run", { agent: "gentle-ai-verify" });
+		assert.equal(registry.get("tool-activity-loader-test"), undefined, "another session cannot relabel the primary session");
+		assert.equal(registry.get(sessionId), "checking");
+	} finally {
+		registry.clear("tool-activity-loader-test");
+		registry.clear("other-session");
+		editor?.dispose();
+	}
+});

package/tests/odd-phase.test.ts

@@ -0,0 +1,307 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isOddPhase, oddPhaseLabel, oddPhaseRegistry, ODD_PHASES, OddPhaseRegistry } from "../lib/odd-phase.ts";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+
+// Bounded ODD phase signal for the Gentle prompt's working label: inferred
+// from observed tool activity (lib/odd-phase-inference.ts) and refined by
+// explicit orchestrator reports through gentle_odd_phase.
+
+test("ODD_PHASES is the fixed orchestrator-reportable vocabulary covering every ODD protocol step (deciding covers both step 3 and step 4)", () => {
+	assert.deepEqual(ODD_PHASES, ["authorizing", "exploring", "researching", "deciding", "planning", "implementing", "checking", "closing"]);
+});
+
+test("isOddPhase accepts only the bounded vocabulary", () => {
+	for (const phase of ODD_PHASES) assert.equal(isOddPhase(phase), true);
+	assert.equal(isOddPhase("coding"), false);
+	assert.equal(isOddPhase(""), false);
+	assert.equal(isOddPhase(undefined), false);
+	assert.equal(isOddPhase(42), false);
+});
+
+test("oddPhaseLabel renders the working-style ellipsis label for every ODD_PHASES member", () => {
+	for (const phase of ODD_PHASES) assert.equal(oddPhaseLabel(phase), `${phase}…`);
+});
+
+test("OddPhaseRegistry.report stores a valid phase for a session and label() renders it", () => {
+	const registry = new OddPhaseRegistry();
+	assert.equal(registry.report("session-a", "exploring"), "exploring");
+	assert.equal(registry.get("session-a"), "exploring");
+	assert.equal(registry.label("session-a"), "exploring…");
+});
+
+test("OddPhaseRegistry.clear resets a session's phase directly", () => {
+	const registry = new OddPhaseRegistry();
+	registry.report("session-a", "checking");
+	registry.clear("session-a");
+	assert.equal(registry.get("session-a"), undefined);
+	assert.equal(registry.label("session-a"), undefined);
+});
+
+test("OddPhaseRegistry scopes phases per session; one session never sees another's report", () => {
+	const registry = new OddPhaseRegistry();
+	registry.report("session-a", "exploring");
+	registry.report("session-b", "checking");
+	assert.equal(registry.get("session-a"), "exploring");
+	assert.equal(registry.get("session-b"), "checking");
+	registry.clear("session-a");
+	assert.equal(registry.get("session-a"), undefined);
+	assert.equal(registry.get("session-b"), "checking", "clearing one session must not affect another");
+});
+
+test("OddPhaseRegistry ignores reports and reads without a session id", () => {
+	const registry = new OddPhaseRegistry();
+	assert.equal(registry.report(undefined, "exploring"), undefined);
+	assert.equal(registry.get(undefined), undefined);
+	assert.equal(registry.label(undefined), undefined);
+	registry.clear(undefined);
+});
+
+test("OddPhaseRegistry.report requests a redraw through the registered callback for that session", () => {
+	const registry = new OddPhaseRegistry();
+	let renders = 0;
+	registry.setRenderRequest("session-a", () => { renders += 1; });
+	registry.report("session-a", "authorizing");
+	assert.equal(renders, 1);
+	registry.report("session-a", "planning");
+	assert.equal(renders, 2);
+});
+
+test("OddPhaseRegistry.report without a session id never requests a redraw", () => {
+	const registry = new OddPhaseRegistry();
+	let renders = 0;
+	registry.setRenderRequest(undefined, () => { renders += 1; });
+	registry.report(undefined, "authorizing");
+	assert.equal(renders, 0);
+});
+
+test("OddPhaseRegistry.clear requests a redraw only when a phase actually existed", () => {
+	const registry = new OddPhaseRegistry();
+	let renders = 0;
+	registry.setRenderRequest("session-a", () => { renders += 1; });
+	registry.clear("session-a");
+	assert.equal(renders, 0, "clearing an already-empty phase must not request a needless redraw");
+	registry.report("session-a", "checking");
+	renders = 0;
+	registry.clear("session-a");
+	assert.equal(renders, 1);
+});
+
+test("OddPhaseRegistry never calls another session's render-request callback", () => {
+	const registry = new OddPhaseRegistry();
+	let rendersA = 0;
+	let rendersB = 0;
+	registry.setRenderRequest("session-a", () => { rendersA += 1; });
+	registry.setRenderRequest("session-b", () => { rendersB += 1; });
+	registry.report("session-a", "exploring");
+	assert.equal(rendersA, 1);
+	assert.equal(rendersB, 0);
+});
+
+test("OddPhaseRegistry.clearRenderRequest stops future redraw requests for that session", () => {
+	const registry = new OddPhaseRegistry();
+	let renders = 0;
+	registry.setRenderRequest("session-a", () => { renders += 1; });
+	registry.clearRenderRequest("session-a");
+	registry.report("session-a", "deciding");
+	assert.equal(renders, 0);
+});
+
+test("OddPhaseRegistry.infer sets the phase when nothing was reported", () => {
+	const registry = new OddPhaseRegistry();
+	assert.equal(registry.infer("session-a", "exploring"), "exploring");
+	assert.equal(registry.label("session-a"), "exploring…");
+});
+
+test("an inferred exploring never overrides an explicitly reported phase", () => {
+	const registry = new OddPhaseRegistry();
+	registry.report("session-a", "researching");
+	assert.equal(registry.infer("session-a", "exploring"), "researching");
+	assert.equal(registry.get("session-a"), "researching");
+});
+
+test("stronger inferred phases override an explicitly reported phase", () => {
+	for (const inferred of ["deciding", "planning", "implementing", "checking"] as const) {
+		const registry = new OddPhaseRegistry();
+		registry.report("session-a", "researching");
+		assert.equal(registry.infer("session-a", inferred), inferred);
+		assert.equal(registry.get("session-a"), inferred);
+	}
+});
+
+test("incidental reads and bookkeeping do not replace active implementation or verification", () => {
+	for (const active of ["implementing", "checking"] as const) {
+		const registry = new OddPhaseRegistry();
+		registry.report("session-a", "researching");
+		registry.infer("session-a", active);
+		assert.equal(registry.infer("session-a", "exploring"), active);
+		assert.equal(registry.infer("session-a", "planning"), active);
+		assert.equal(registry.get("session-a"), active);
+	}
+});
+
+test("inferring the phase already reported explicitly keeps it explicit", () => {
+	const registry = new OddPhaseRegistry();
+	registry.report("session-a", "implementing");
+	registry.infer("session-a", "implementing");
+	assert.equal(registry.infer("session-a", "exploring"), "implementing");
+});
+
+test("meaningful work transitions and explicit reports still change the phase", () => {
+	const registry = new OddPhaseRegistry();
+	registry.infer("session-a", "checking");
+	assert.equal(registry.infer("session-a", "implementing"), "implementing", "a later edit starts real work");
+	assert.equal(registry.infer("session-a", "checking"), "checking");
+	assert.equal(registry.infer("session-a", "exploring", "delegation"), "exploring", "a delegated exploration is deliberate");
+	assert.equal(registry.report("session-a", "closing"), "closing");
+	assert.equal(registry.infer("session-a", "exploring"), "closing");
+	registry.clear("session-a");
+	assert.equal(registry.infer("session-a", "exploring"), "exploring");
+});
+
+test("clear resets the explicit source so the next turn's inferred exploring applies", () => {
+	const registry = new OddPhaseRegistry();
+	registry.report("session-a", "researching");
+	registry.clear("session-a");
+	assert.equal(registry.infer("session-a", "exploring"), "exploring");
+});
+
+test("report with an inferred source behaves like infer-set state", () => {
+	const registry = new OddPhaseRegistry();
+	registry.report("session-a", "checking", "inferred");
+	assert.equal(registry.infer("session-a", "exploring"), "checking");
+});
+
+test("OddPhaseRegistry.infer redraws only when the label changes", () => {
+	const registry = new OddPhaseRegistry();
+	let renders = 0;
+	registry.setRenderRequest("session-a", () => { renders += 1; });
+	registry.infer("session-a", "exploring");
+	registry.infer("session-a", "exploring");
+	assert.equal(renders, 1, "repeated reads must not redraw on every tool call");
+	registry.report("session-a", "researching");
+	renders = 0;
+	registry.infer("session-a", "exploring");
+	assert.equal(renders, 0, "an ignored inference must not redraw");
+	registry.infer("session-a", "implementing");
+	assert.equal(renders, 1);
+	registry.infer("session-a", "planning");
+	registry.infer("session-a", "exploring");
+	assert.equal(renders, 1, "incidental signals never repaint active work");
+	registry.infer("session-a", "exploring", "delegation");
+	assert.equal(renders, 2, "a delegated exploration must repaint");
+});
+
+test("OddPhaseRegistry.infer without a session id is a no-op", () => {
+	const registry = new OddPhaseRegistry();
+	assert.equal(registry.infer(undefined, "exploring"), undefined);
+	assert.equal(registry.get(undefined), undefined);
+});
+
+test("OddPhaseRegistry report/clear without a registered render-request callback is a safe no-op", () => {
+	const registry = new OddPhaseRegistry();
+	assert.doesNotThrow(() => {
+		registry.report("session-a", "closing");
+		registry.clear("session-a");
+	});
+});
+
+interface RegisteredTool {
+	execute: (
+		toolCallId: string,
+		params: unknown,
+		signal: AbortSignal | undefined,
+		onUpdate: undefined,
+		ctx: ExtensionContext,
+	) => Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean }>;
+}
+
+function gentleOddPhaseTool(): RegisteredTool {
+	const tools = new Map<string, RegisteredTool>();
+	createGentleAiExtension({ nativeReviewCli: null } as unknown as Parameters<typeof createGentleAiExtension>[0])({
+		on() {},
+		registerTool(definition: RegisteredTool & { name: string }) { tools.set(definition.name, definition); },
+		registerCommand() {},
+	} as unknown as ExtensionAPI);
+	const tool = tools.get("gentle_odd_phase");
+	assert.ok(tool, "gentle_odd_phase must be registered");
+	return tool;
+}
+
+function toolContext(sessionId: string | undefined): ExtensionContext {
+	return { sessionManager: { getSessionId: () => sessionId } } as unknown as ExtensionContext;
+}
+
+test("gentle_odd_phase reports a valid phase for the calling session and returns details", async () => {
+	const tool = gentleOddPhaseTool();
+	const ctx = toolContext("tool-session-a");
+	try {
+		const result = await tool.execute("call-1", { phase: "researching" }, undefined, undefined, ctx);
+		assert.deepEqual((result as { details?: unknown }).details, { phase: "researching" });
+		assert.equal(oddPhaseRegistry.get("tool-session-a"), "researching");
+	} finally {
+		oddPhaseRegistry.clear("tool-session-a");
+	}
+});
+
+test("gentle_odd_phase 'clear' leaves the current phase mid-turn", async () => {
+	const tool = gentleOddPhaseTool();
+	const ctx = toolContext("tool-session-b");
+	try {
+		await tool.execute("call-1", { phase: "implementing" }, undefined, undefined, ctx);
+		const result = await tool.execute("call-2", { phase: "clear" }, undefined, undefined, ctx);
+		assert.deepEqual((result as { details?: unknown }).details, { phase: undefined });
+		assert.equal(oddPhaseRegistry.get("tool-session-b"), undefined);
+	} finally {
+		oddPhaseRegistry.clear("tool-session-b");
+	}
+});
+
+test("gentle_odd_phase throws (never falsely returns success) for a phase outside the bounded vocabulary", async () => {
+	// Pi's own contract: only a thrown error sets isError: true; a returned
+	// value never does, regardless of an isError property on it
+	// (docs/extensions.md "Signaling errors").
+	const tool = gentleOddPhaseTool();
+	const ctx = toolContext("tool-session-c");
+	try {
+		await assert.rejects(
+			() => tool.execute("call-1", { phase: "refactoring" }, undefined, undefined, ctx),
+			/Invalid ODD phase/,
+		);
+		assert.equal(oddPhaseRegistry.get("tool-session-c"), undefined);
+	} finally {
+		oddPhaseRegistry.clear("tool-session-c");
+	}
+});
+
+test("gentle_odd_phase preserves the prior reported phase when given an invalid token; only 'clear' resets it", async () => {
+	const tool = gentleOddPhaseTool();
+	const ctx = toolContext("tool-session-d");
+	try {
+		await tool.execute("call-1", { phase: "checking" }, undefined, undefined, ctx);
+		await assert.rejects(() => tool.execute("call-2", { phase: "refactoring" }, undefined, undefined, ctx));
+		assert.equal(oddPhaseRegistry.get("tool-session-d"), "checking", "an invalid token must never wipe the previously reported phase");
+	} finally {
+		oddPhaseRegistry.clear("tool-session-d");
+	}
+});
+
+test("gentle_odd_phase throws, not falsely succeeds, when there is no active session for a valid phase", async () => {
+	const tool = gentleOddPhaseTool();
+	const ctx = toolContext(undefined);
+	await assert.rejects(
+		() => tool.execute("call-1", { phase: "implementing" }, undefined, undefined, ctx),
+		(error: unknown) => {
+			assert.ok(error instanceof Error);
+			assert.doesNotMatch(error.message, /Invalid ODD phase/, "the phase itself was valid; the failure is the missing session, not an invalid token");
+			return true;
+		},
+	);
+});
+
+test("gentle_odd_phase throws for an invalid token even with no active session", async () => {
+	const tool = gentleOddPhaseTool();
+	const ctx = toolContext(undefined);
+	await assert.rejects(() => tool.execute("call-1", { phase: "refactoring" }, undefined, undefined, ctx));
+});

package/tests/odd-routing-canonical-ratchet.test.ts

@@ -86,9 +86,12 @@ const ANCHORS: readonly RoutingAnchor[] = [
 	{
 		label: "mapping trigger at 4 or more files",
 		canonical: "**Mapping trigger:** when understanding the work requires 4 or more files",
+		// Gentle Shell intentionally leads the canon here: the local mirrors carry
+		// the measured evidence-budget rule instead of the 4-file count (tracked by
+		// gentle-ai#5139). The canonical anchor stays until gentle-ai follows.
 		mirrors: [
-			{ surface: DELEGATION, includes: "**Mapping trigger (4-file rule):** when understanding the work requires 4 or more files" },
-			{ surface: CORE, includes: "**4-file rule** — 4+ files to understand" },
+			{ surface: DELEGATION, includes: "**Mapping trigger (Evidence-budget rule):** read inline only when the evidence fits one parallel batch of at most 3 calls" },
+			{ surface: CORE, includes: "**Evidence-budget rule** — read inline only if evidence fits one parallel batch (at most 3 calls, ~10k tokens" },
 		],
 	},
 	{
@@ -107,9 +110,11 @@ const ANCHORS: readonly RoutingAnchor[] = [
 	{
 		label: "long-session backstop",
 		canonical: "**Long-session backstop:**",
+		// Gentle Shell intentionally leads the canon here: a parent-context token
+		// backstop replaces the tool-call count (tracked by gentle-ai#5139).
 		mirrors: [
-			{ surface: DELEGATION, includes: "**Long-session backstop (Long-session rule):**" },
-			{ surface: CORE, includes: "**Long-session rule** — ~20 tool calls, 5 exploratory reads, or 2 non-mechanical edits without delegation" },
+			{ surface: DELEGATION, includes: "**Context backstop:** when the parent context passes ~150k tokens" },
+			{ surface: CORE, includes: "**Context backstop** — parent context past ~150k tokens" },
 		],
 	},
 	{
@@ -120,10 +125,10 @@ const ANCHORS: readonly RoutingAnchor[] = [
 		],
 	},
 	{
-		label: "triggers never select SDD",
+		label: "triggers select only the ODD topology",
 		canonical: "These triggers never select SDD and never create SDD artifacts",
 		mirrors: [
-			{ surface: DELEGATION, includes: "These triggers never select SDD and never create SDD artifacts" },
+			{ surface: DELEGATION, includes: "These triggers only choose between direct inline and delegated direct inside ODD" },
 		],
 	},
 	{