gentle-pi 2.3.0 → 2.5.0

package/tests/rdd-status-line.test.ts

@@ -0,0 +1,286 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+import {
+	NATIVE_REVIEW_MODE_OPERATION,
+	NATIVE_REVIEW_MODE_SOURCE,
+	type NativeReviewCli,
+	type NativeReviewModeRequest,
+	type NativeReviewModeResult,
+	type NativeReviewModeStatus,
+} from "../lib/native-review-cli.ts";
+
+// ---------------------------------------------------------------------------
+// gentle-pi#661: the always-on parent prompt renders a second status line,
+// `Receipt-driven development: on|off (decided by <source>)`, next to
+// `Background subagent policy`, sourced from the native review mode status
+// reader (`gentle-ai review mode status --json`, schema
+// `gentle-ai.rdd-mode-status/v1`, decoded to `NativeReviewModeStatus`).
+//
+// `getOrchestratorPrompt`/`renderOrchestratorPrompt` stay synchronous and
+// default `rddStatusLine` to the "unknown (native status unavailable)" line
+// -- the longest of the three renderable forms -- so a no-argument call IS
+// the worst case the canonical 8 KiB budget in
+// tests/orchestrator-budget.test.ts measures, not a smaller placeholder
+// production later exceeds. Production (before_agent_start) still resolves
+// and passes the real on/off/unknown line through `resolveRddStatusLine`,
+// bounded by `RDD_STATUS_TIMEOUT_MS` and memoized per cwd for
+// `RDD_STATUS_MEMO_TTL_MS` so a hung or repeatedly-invoked native reader
+// cannot stall or repeatedly respawn on every session/agent-start build.
+// ---------------------------------------------------------------------------
+
+const {
+	renderRddStatusLine,
+	resolveRddModeStatus,
+	resolveRddStatusLine,
+	getOrchestratorPrompt,
+	clearRddStatusMemoForTesting,
+	RDD_STATUS_TIMEOUT_MS,
+	RDD_STATUS_MEMO_TTL_MS,
+} = __testing;
+
+function fakeReviewMode(
+	result: NativeReviewModeResult | (() => never) | (() => Promise<never>),
+): Pick<NativeReviewCli, "reviewMode"> {
+	return {
+		async reviewMode(_request: NativeReviewModeRequest): Promise<NativeReviewModeResult> {
+			if (typeof result === "function") return result();
+			return result;
+		},
+	};
+}
+
+function modeResult(effective: "on" | "off", source: (typeof NATIVE_REVIEW_MODE_SOURCE)[keyof typeof NATIVE_REVIEW_MODE_SOURCE]): NativeReviewModeResult {
+	return {
+		operation: NATIVE_REVIEW_MODE_OPERATION.STATUS,
+		scope: "global",
+		status: {
+			global: effective,
+			cloneLocal: "",
+			effective,
+			source,
+		},
+	};
+}
+
+// A counting wrapper for memo tests: counts how many times reviewMode is
+// actually invoked, independent of how many times resolveRddModeStatus is
+// called.
+function countingReviewMode(result: NativeReviewModeResult): { cli: Pick<NativeReviewCli, "reviewMode">; calls: () => number } {
+	let calls = 0;
+	return {
+		cli: {
+			async reviewMode(_request: NativeReviewModeRequest): Promise<NativeReviewModeResult> {
+				calls += 1;
+				return result;
+			},
+		},
+		calls: () => calls,
+	};
+}
+
+test("renderRddStatusLine renders the fail-closed unknown line for an unresolved status", () => {
+	assert.equal(
+		renderRddStatusLine(undefined),
+		"Receipt-driven development: unknown (native status unavailable)",
+	);
+});
+
+test("renderRddStatusLine renders the effective mode and deciding source", () => {
+	assert.equal(
+		renderRddStatusLine({ global: "on", cloneLocal: "", effective: "on", source: NATIVE_REVIEW_MODE_SOURCE.GLOBAL }),
+		"Receipt-driven development: on (decided by global)",
+	);
+	assert.equal(
+		renderRddStatusLine({ global: "off", cloneLocal: "", effective: "off", source: NATIVE_REVIEW_MODE_SOURCE.DEFAULT }),
+		"Receipt-driven development: off (decided by default)",
+	);
+});
+
+test("renderRddStatusLine fails closed to unknown for a malformed or partial status object", () => {
+	// A bad upstream decode, a future field rename, or a hand-built fixture
+	// must never render an unrecognized value verbatim -- the render boundary
+	// validates independently of the type signature.
+	const malformed: readonly NativeReviewModeStatus[] = [
+		{} as NativeReviewModeStatus,
+		{ effective: "maybe" } as unknown as NativeReviewModeStatus,
+		{ effective: "on" } as NativeReviewModeStatus, // missing source
+		{ effective: "on", source: "not-a-real-source" } as unknown as NativeReviewModeStatus,
+		{ global: "on", cloneLocal: "", effective: "ON", source: NATIVE_REVIEW_MODE_SOURCE.GLOBAL } as unknown as NativeReviewModeStatus,
+		null as unknown as NativeReviewModeStatus,
+	];
+	for (const status of malformed) {
+		assert.equal(
+			renderRddStatusLine(status),
+			"Receipt-driven development: unknown (native status unavailable)",
+			`expected unknown line for ${JSON.stringify(status)}`,
+		);
+	}
+});
+
+test("resolveRddModeStatus reads the on status from a stubbed native reviewMode reader", async () => {
+	clearRddStatusMemoForTesting();
+	const status = await resolveRddModeStatus(fakeReviewMode(modeResult("on", NATIVE_REVIEW_MODE_SOURCE.CLONE_LOCAL)), "/repo-on");
+	assert.deepEqual(status, {
+		global: "on",
+		cloneLocal: "",
+		effective: "on",
+		source: "clone_local",
+	});
+});
+
+test("resolveRddModeStatus reads the off status from a stubbed native reviewMode reader", async () => {
+	clearRddStatusMemoForTesting();
+	const status = await resolveRddModeStatus(fakeReviewMode(modeResult("off", NATIVE_REVIEW_MODE_SOURCE.GLOBAL)), "/repo-off");
+	assert.equal(status?.effective, "off");
+	assert.equal(status?.source, "global");
+});
+
+test("resolveRddModeStatus resolves to undefined when the native review CLI wrapper is null or absent", async () => {
+	for (const wrapper of [undefined, null] as const) {
+		clearRddStatusMemoForTesting();
+		const status = await resolveRddModeStatus(wrapper, "/repo-no-wrapper");
+		assert.equal(status, undefined, `expected undefined for a ${wrapper === null ? "null" : "missing"} wrapper`);
+	}
+});
+
+test("resolveRddModeStatus resolves to undefined when the native reviewMode call rejects", async () => {
+	clearRddStatusMemoForTesting();
+	const status = await resolveRddModeStatus(
+		fakeReviewMode(() => {
+			throw new Error("native process failed");
+		}),
+		"/repo-rejecting",
+	);
+	assert.equal(status, undefined);
+});
+
+test("resolveRddModeStatus resolves to undefined within the deadline when reviewMode never settles", async () => {
+	// gentle-pi#661 native-review escalation: a hung `gentle-ai` child must
+	// not stall session start. resolveRddModeStatus races the call against
+	// its own abort listener, so this holds even for a stub reviewMode that
+	// itself ignores the passed `signal`, as a real hung child process would
+	// eventually be killed and reject via its own signal handling.
+	clearRddStatusMemoForTesting();
+	const neverSettling = fakeReviewMode(() => new Promise<never>(() => {}));
+	const deadlineMs = 150;
+	const start = Date.now();
+	const status = await resolveRddModeStatus(neverSettling, "/repo-hung", AbortSignal.timeout(deadlineMs));
+	const elapsed = Date.now() - start;
+	assert.equal(status, undefined);
+	assert.ok(elapsed < deadlineMs + 1000, `expected the read to resolve near the ${deadlineMs}ms deadline, took ${elapsed}ms`);
+});
+
+test("resolveRddModeStatus memoizes a resolved status per cwd for RDD_STATUS_MEMO_TTL_MS", async () => {
+	clearRddStatusMemoForTesting();
+	const { cli, calls } = countingReviewMode(modeResult("on", NATIVE_REVIEW_MODE_SOURCE.GLOBAL));
+	const cwd = "/repo-memo-hit";
+	const first = await resolveRddModeStatus(cli, cwd);
+	const second = await resolveRddModeStatus(cli, cwd);
+	assert.deepEqual(first, second);
+	assert.equal(calls(), 1, "a second call within the TTL must reuse the memoized status, not respawn the native reader");
+});
+
+test("resolveRddModeStatus re-reads once the memoized status expires", async () => {
+	clearRddStatusMemoForTesting();
+	const { cli, calls } = countingReviewMode(modeResult("on", NATIVE_REVIEW_MODE_SOURCE.GLOBAL));
+	const cwd = "/repo-memo-expiry";
+	let clock = 1_000_000;
+	const now = () => clock;
+	await resolveRddModeStatus(cli, cwd, undefined, now);
+	assert.equal(calls(), 1);
+	clock += RDD_STATUS_MEMO_TTL_MS + 1;
+	await resolveRddModeStatus(cli, cwd, undefined, now);
+	assert.equal(calls(), 2, "a call after the TTL elapses must re-read rather than reuse the stale memo");
+});
+
+test("resolveRddModeStatus memoizes independently per cwd", async () => {
+	clearRddStatusMemoForTesting();
+	const { cli, calls } = countingReviewMode(modeResult("on", NATIVE_REVIEW_MODE_SOURCE.GLOBAL));
+	await resolveRddModeStatus(cli, "/repo-a");
+	await resolveRddModeStatus(cli, "/repo-b");
+	assert.equal(calls(), 2, "distinct cwds must not share a memo entry");
+});
+
+test("resolveRddStatusLine renders on, off, and unavailable from the stubbed native reader", async () => {
+	clearRddStatusMemoForTesting();
+	assert.equal(
+		await resolveRddStatusLine(fakeReviewMode(modeResult("on", NATIVE_REVIEW_MODE_SOURCE.GLOBAL)), "/repo-line-on"),
+		"Receipt-driven development: on (decided by global)",
+	);
+	assert.equal(
+		await resolveRddStatusLine(fakeReviewMode(modeResult("off", NATIVE_REVIEW_MODE_SOURCE.DEFAULT)), "/repo-line-off"),
+		"Receipt-driven development: off (decided by default)",
+	);
+	assert.equal(
+		await resolveRddStatusLine(undefined, "/repo-line-unknown"),
+		"Receipt-driven development: unknown (native status unavailable)",
+	);
+});
+
+test("RDD_STATUS_TIMEOUT_MS is a small, positive bounded-deadline constant", () => {
+	assert.equal(typeof RDD_STATUS_TIMEOUT_MS, "number");
+	assert.ok(RDD_STATUS_TIMEOUT_MS > 0 && RDD_STATUS_TIMEOUT_MS <= 10_000);
+});
+
+test("getOrchestratorPrompt renders the resolved RDD status line next to the background policy line", () => {
+	const cwd = process.cwd();
+	for (const line of [
+		"Receipt-driven development: on (decided by global)",
+		"Receipt-driven development: off (decided by default)",
+		"Receipt-driven development: unknown (native status unavailable)",
+	]) {
+		const rendered = getOrchestratorPrompt(cwd, undefined, line);
+		assert.ok(rendered.includes(line), `rendered prompt missing RDD status line: ${line}`);
+		assert.match(rendered, /Background subagent policy: (?:on|off) \(capability: (?:ready|absent)\)/);
+	}
+});
+
+test("getOrchestratorPrompt defaults to the worst-case unknown RDD status line (budget-critical path)", () => {
+	// gentle-pi#661 follow-up: the no-argument default must BE the worst case
+	// the byte budget in tests/orchestrator-budget.test.ts measures, so a
+	// caller that never resolves a status renders the longest line rather
+	// than none at all.
+	const rendered = getOrchestratorPrompt();
+	assert.ok(rendered.includes("Receipt-driven development: unknown (native status unavailable)"));
+});
+
+test("the prompt cache key distinguishes on, off, and unknown so each renders a distinct prompt", () => {
+	const cwd = process.cwd();
+	const on = getOrchestratorPrompt(cwd, undefined, "Receipt-driven development: on (decided by global)");
+	const off = getOrchestratorPrompt(cwd, undefined, "Receipt-driven development: off (decided by default)");
+	const unknown = getOrchestratorPrompt(cwd, undefined, "Receipt-driven development: unknown (native status unavailable)");
+	const none = getOrchestratorPrompt(cwd);
+	assert.notEqual(on, off);
+	assert.notEqual(off, unknown);
+	assert.notEqual(on, unknown);
+	// The no-argument default renders the same worst-case "unknown" line, so
+	// it is the same prompt as the explicit unknown-line call.
+	assert.equal(none, unknown);
+	// Re-rendering the same status line returns the memoized prompt.
+	assert.equal(
+		getOrchestratorPrompt(cwd, undefined, "Receipt-driven development: on (decided by global)"),
+		on,
+	);
+});
+
+test("the on and off renders are never longer than the unknown (worst-case) render", () => {
+	// Every renderable NativeReviewModeSource crossed with on/off must stay at
+	// or under the "unknown (native status unavailable)" line's length, since
+	// the budget is sized against that one worst case. Sourced from the
+	// exported NATIVE_REVIEW_MODE_SOURCE constants, not a literal list, so a
+	// future source addition is exercised automatically.
+	const cwd = process.cwd();
+	const unknownLine = "Receipt-driven development: unknown (native status unavailable)";
+	const unknownBytes = Buffer.byteLength(getOrchestratorPrompt(cwd, undefined, unknownLine), "utf8");
+	for (const source of Object.values(NATIVE_REVIEW_MODE_SOURCE)) {
+		for (const effective of ["on", "off"] as const) {
+			const line = renderRddStatusLine({ global: effective, cloneLocal: "", effective, source });
+			const bytes = Buffer.byteLength(getOrchestratorPrompt(cwd, undefined, line), "utf8");
+			assert.ok(
+				bytes <= unknownBytes,
+				`"${line}" rendered ${bytes} B, longer than the unknown-line render at ${unknownBytes} B`,
+			);
+		}
+	}
+});

package/tests/review-agent-end-preflight.test.ts

@@ -0,0 +1,408 @@
+import assert from "node:assert/strict";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import type { NativeReviewCli } from "../lib/native-review-cli.ts";
+import type { ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+
+// gentle-pi#556 / gentle-ai#4051: with RDD enabled, the agent finished an
+// implementation and reported completion without ever entering the review
+// preflight. These tests cover the read-only, idempotent `agent_end` nudge
+// that reminds the agent to call gentle_review before reporting completion,
+// without ever starting a review or answering consent itself.
+//
+// gentle-pi#568: `session_start` records the target identity STATUS reports
+// at session start as a baseline, so `agent_end` skips a candidate that
+// already existed before this session touched the worktree (the user's own
+// pre-session work, not this session's output). These tests point
+// `GENTLE_PI_AGENT_HOME` and the session `cwd` at fresh temp directories so
+// `session_start`'s real SDD asset install and model config sweep never
+// touch this machine's actual home directory.
+
+type AnyHandler = (event: unknown, ctx: ExtensionContext) => unknown;
+type SentMessage = { message: Record<string, unknown>; options: Record<string, unknown> };
+
+function harness(nativeReviewCli: NativeReviewCli | null): {
+	handlers: Map<string, AnyHandler>;
+	sent: SentMessage[];
+} {
+	const handlers = new Map<string, AnyHandler>();
+	const sent: SentMessage[] = [];
+	const pi = {
+		on(name: string, handler: AnyHandler) {
+			handlers.set(name, handler);
+		},
+		events: { emit() {} },
+		registerCommand() {},
+		registerTool() {},
+		sendMessage(message: Record<string, unknown>, options: Record<string, unknown> = {}) {
+			sent.push({ message, options });
+		},
+	} as unknown as ExtensionAPI;
+	createGentleAiExtension({ nativeReviewCli })(pi);
+	return { handlers, sent };
+}
+
+function ctx(sessionId: string, hasUI = true, cwd = process.cwd()): ExtensionContext {
+	return {
+		cwd,
+		hasUI,
+		ui: { notify() {} },
+		sessionManager: { getSessionId: () => sessionId },
+	} as unknown as ExtensionContext;
+}
+
+async function withSessionStartEnv<T>(callback: (cwd: string) => Promise<T>): Promise<T> {
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+	const previousConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
+	process.env.GENTLE_PI_AGENT_HOME = await mkdtemp(join(tmpdir(), "gentle-pi-session-baseline-agent-home-"));
+	// Isolates both the model-config sweep and the dev-binary registration
+	// lookup from this machine's real ~/.pi/gentle-ai, so `session_start`'s
+	// unrelated notifications never leak into these assertions.
+	process.env.GENTLE_PI_CONFIG_HOME = await mkdtemp(join(tmpdir(), "gentle-pi-session-baseline-config-home-"));
+	try {
+		const cwd = await mkdtemp(join(tmpdir(), "gentle-pi-session-baseline-cwd-"));
+		return await callback(cwd);
+	} finally {
+		if (previousAgentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		if (previousConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousConfigHome;
+	}
+}
+
+function onMode(effective: "on" | "off"): NativeReviewCli["reviewMode"] {
+	return async () => ({
+		operation: "status",
+		scope: "clone",
+		status: { global: "", cloneLocal: effective === "on" ? "on" : "", effective, source: "clone_local" },
+	});
+}
+
+function executeStartStatus(targetIdentity: string): ReviewStatusV3 {
+	return {
+		applicability: "unrelated",
+		action: "start",
+		targetIdentity,
+		nextTransition: { kind: "execute", execute: { operation: "review.start", arguments: [] } },
+	} as unknown as ReviewStatusV3;
+}
+
+function collectStatus(targetIdentity: string): ReviewStatusV3 {
+	return {
+		applicability: "unrelated",
+		action: "start",
+		targetIdentity,
+		nextTransition: { kind: "collect", collect: { inputs: [] } },
+	} as unknown as ReviewStatusV3;
+}
+
+function stopStatus(targetIdentity: string): ReviewStatusV3 {
+	return {
+		applicability: "unrelated",
+		action: "start",
+		targetIdentity,
+		nextTransition: { kind: "stop" },
+	} as unknown as ReviewStatusV3;
+}
+
+const agentEndEvent = { type: "agent_end", messages: [] };
+
+test("agent_end performs no STATUS call and sends nothing when RDD is off", async () => {
+	const statusRequests: unknown[] = [];
+	const native = {
+		reviewMode: onMode("off"),
+		targetStatus: async (request: unknown) => {
+			statusRequests.push(request);
+			throw new Error("targetStatus must not be called when RDD is off");
+		},
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	assert.equal(typeof agentEnd, "function");
+	await agentEnd!(agentEndEvent, ctx("agent-end-rdd-off"));
+	assert.deepEqual(statusRequests, []);
+	assert.deepEqual(sent, []);
+});
+
+test("agent_end nudges exactly once when RDD is on and STATUS offers review.start", async () => {
+	const targetIdentity = `sha256:${"a".repeat(64)}`;
+	const statusRequests: Array<{ agent?: string }> = [];
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async (request: { agent?: string }) => {
+			statusRequests.push(request);
+			return executeStartStatus(targetIdentity);
+		},
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	await agentEnd!(agentEndEvent, ctx("agent-end-execute"));
+
+	assert.equal(sent.length, 1);
+	const [entry] = sent;
+	assert.equal(entry?.message.customType, "gentle-pi.review-preflight");
+	const content = String(entry?.message.content);
+	assert.match(content, /gentle_review/);
+	assert.ok(content.includes(targetIdentity), "message must name the target identity");
+	assert.equal(entry?.options.triggerTurn, true);
+	assert.equal(statusRequests[0]?.agent, "pi");
+});
+
+test("agent_end nudges once per target identity and again for a fresh identity", async () => {
+	let targetIdentity = `sha256:${"b".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	const session = ctx("agent-end-repeat");
+
+	await agentEnd!(agentEndEvent, session);
+	await agentEnd!(agentEndEvent, session);
+	assert.equal(sent.length, 1, "the same target identity nudges only once");
+
+	targetIdentity = `sha256:${"e".repeat(64)}`;
+	await agentEnd!(agentEndEvent, session);
+	assert.equal(sent.length, 2, "a different target identity nudges again");
+});
+
+test("agent_end sends nothing when STATUS offers collect or stop", async () => {
+	for (const [label, status] of [
+		["collect", collectStatus(`sha256:${"c".repeat(64)}`)],
+		["stop", stopStatus(`sha256:${"d".repeat(64)}`)],
+	] as const) {
+		const native = {
+			reviewMode: onMode("on"),
+			targetStatus: async () => status,
+		} as unknown as NativeReviewCli;
+		const { handlers, sent } = harness(native);
+		const agentEnd = handlers.get("agent_end");
+		await agentEnd!(agentEndEvent, ctx(`agent-end-${label}`));
+		assert.deepEqual(sent, [], label);
+	}
+});
+
+test("agent_end skips headless sessions before any native call", async () => {
+	const native = {
+		reviewMode: async () => {
+			throw new Error("reviewMode must not be called when hasUI is false");
+		},
+		targetStatus: async () => {
+			throw new Error("targetStatus must not be called when hasUI is false");
+		},
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	await agentEnd!(agentEndEvent, ctx("agent-end-no-ui", false));
+	assert.deepEqual(sent, []);
+});
+
+test("agent_end pairs a named agent's start with its own end, then still nudges for the primary loop's end", async () => {
+	const targetIdentity = `sha256:${"f".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const beforeAgentStart = handlers.get("before_agent_start");
+	const agentEnd = handlers.get("agent_end");
+	assert.equal(typeof beforeAgentStart, "function");
+	const session = ctx("agent-end-subagent");
+
+	await beforeAgentStart!({ agentName: "review-readability", systemPrompt: "" }, session);
+	await agentEnd!(agentEndEvent, session);
+	assert.deepEqual(sent, [], "the subagent's own loop end is suppressed");
+
+	await agentEnd!(agentEndEvent, session);
+	assert.equal(sent.length, 1, "the primary loop's end still nudges once the subagent's end is paired off");
+});
+
+test("agent_end resets the subagent depth when a fresh primary loop starts", async () => {
+	const targetIdentity = `sha256:${"1".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const beforeAgentStart = handlers.get("before_agent_start");
+	const agentEnd = handlers.get("agent_end");
+	const session = ctx("agent-end-subagent-reset");
+
+	await beforeAgentStart!({ agentName: "review-readability", systemPrompt: "" }, session);
+	await beforeAgentStart!({ systemPrompt: "" }, session);
+	await agentEnd!(agentEndEvent, session);
+
+	assert.equal(sent.length, 1, "a fresh primary-loop start resets the depth so its own end nudges");
+});
+
+test("agent_end handler exists but sends nothing when nativeReviewCli is null", async () => {
+	const { handlers, sent } = harness(null);
+	const agentEnd = handlers.get("agent_end");
+	assert.equal(typeof agentEnd, "function");
+	await agentEnd!(agentEndEvent, ctx("agent-end-null-cli"));
+	assert.deepEqual(sent, []);
+});
+
+test("agent_end sends nothing and does not throw when target STATUS rejects", async () => {
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => {
+			throw new Error("native status unavailable");
+		},
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	await assert.doesNotReject(async () => agentEnd!(agentEndEvent, ctx("agent-end-status-throws")));
+	assert.deepEqual(sent, []);
+});
+
+test("session_shutdown clears the nudged-target set for its session key", async () => {
+	const targetIdentity = `sha256:${"9".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	const { handlers, sent } = harness(native);
+	const agentEnd = handlers.get("agent_end");
+	const shutdown = handlers.get("session_shutdown");
+	assert.equal(typeof shutdown, "function");
+	const session = ctx("agent-end-shutdown");
+
+	await agentEnd!(agentEndEvent, session);
+	assert.equal(sent.length, 1);
+
+	await shutdown!({}, session);
+	await agentEnd!(agentEndEvent, session);
+	assert.equal(sent.length, 2, "shutdown clears the nudged set so the same identity nudges again");
+});
+
+test("session_start records the baseline target identity when RDD is on", async () => {
+	const targetIdentity = `sha256:${"2".repeat(64)}`;
+	const statusRequests: Array<{ agent?: string }> = [];
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async (request: { agent?: string }) => {
+			statusRequests.push(request);
+			return executeStartStatus(targetIdentity);
+		},
+	} as unknown as NativeReviewCli;
+	await withSessionStartEnv(async (cwd) => {
+		const { handlers, sent } = harness(native);
+		const sessionStart = handlers.get("session_start");
+		assert.equal(typeof sessionStart, "function");
+		const notifications: Array<{ message: string; severity: string }> = [];
+		const session = {
+			...ctx("session-baseline-record", true, cwd),
+			ui: { notify: (message: string, severity: string) => notifications.push({ message, severity }) },
+		};
+		await sessionStart!({}, session);
+		assert.equal(statusRequests[0]?.agent, "pi");
+		assert.deepEqual(sent, []);
+		assert.deepEqual(notifications, []);
+	});
+});
+
+test("agent_end skips the candidate that matches the session's recorded baseline, then nudges for a new one", async () => {
+	let targetIdentity = `sha256:${"3".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	await withSessionStartEnv(async (cwd) => {
+		const { handlers, sent } = harness(native);
+		const sessionStart = handlers.get("session_start");
+		const agentEnd = handlers.get("agent_end");
+		const session = ctx("session-baseline-skip", true, cwd);
+
+		await sessionStart!({}, session);
+		await agentEnd!(agentEndEvent, session);
+		assert.deepEqual(sent, [], "the baseline candidate predates the session and is not nudged");
+
+		targetIdentity = `sha256:${"4".repeat(64)}`;
+		await agentEnd!(agentEndEvent, session);
+		assert.equal(sent.length, 1, "a candidate identity different from the baseline still nudges");
+	});
+});
+
+test("session_start with RDD off records no baseline, so agent_end still reminds once", async () => {
+	const targetIdentity = `sha256:${"5".repeat(64)}`;
+	let mode: "on" | "off" = "off";
+	const statusRequests: unknown[] = [];
+	const native = {
+		reviewMode: async () => ({
+			operation: "status",
+			scope: "clone",
+			status: { global: "", cloneLocal: mode === "on" ? "on" : "", effective: mode, source: "clone_local" },
+		}),
+		targetStatus: async (request: unknown) => {
+			statusRequests.push(request);
+			if (mode === "off") throw new Error("targetStatus must not be called when RDD is off");
+			return executeStartStatus(targetIdentity);
+		},
+	} as unknown as NativeReviewCli;
+	await withSessionStartEnv(async (cwd) => {
+		const { handlers, sent } = harness(native);
+		const sessionStart = handlers.get("session_start");
+		const agentEnd = handlers.get("agent_end");
+		const session = ctx("session-baseline-rdd-off", true, cwd);
+
+		await sessionStart!({}, session);
+		assert.deepEqual(statusRequests, []);
+
+		mode = "on";
+		await agentEnd!(agentEndEvent, session);
+		assert.equal(sent.length, 1, "no baseline was recorded while RDD was off, so the first dirty candidate still reminds");
+	});
+});
+
+test("session_start whose targetStatus rejects records no baseline, so agent_end still reminds once", async () => {
+	const targetIdentity = `sha256:${"6".repeat(64)}`;
+	let shouldThrow = true;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => {
+			if (shouldThrow) throw new Error("native status unavailable at session start");
+			return executeStartStatus(targetIdentity);
+		},
+	} as unknown as NativeReviewCli;
+	await withSessionStartEnv(async (cwd) => {
+		const { handlers, sent } = harness(native);
+		const sessionStart = handlers.get("session_start");
+		const agentEnd = handlers.get("agent_end");
+		const session = ctx("session-baseline-throws", true, cwd);
+
+		await assert.doesNotReject(async () => sessionStart!({}, session));
+
+		shouldThrow = false;
+		await agentEnd!(agentEndEvent, session);
+		assert.equal(sent.length, 1, "STATUS threw at session_start, so no baseline was recorded and the candidate still reminds");
+	});
+});
+
+test("session_shutdown clears the recorded baseline so the same identity reminds again", async () => {
+	const targetIdentity = `sha256:${"7".repeat(64)}`;
+	const native = {
+		reviewMode: onMode("on"),
+		targetStatus: async () => executeStartStatus(targetIdentity),
+	} as unknown as NativeReviewCli;
+	await withSessionStartEnv(async (cwd) => {
+		const { handlers, sent } = harness(native);
+		const sessionStart = handlers.get("session_start");
+		const agentEnd = handlers.get("agent_end");
+		const shutdown = handlers.get("session_shutdown");
+		const session = ctx("session-baseline-shutdown", true, cwd);
+
+		await sessionStart!({}, session);
+		await agentEnd!(agentEndEvent, session);
+		assert.deepEqual(sent, [], "the baseline candidate is skipped");
+
+		await shutdown!({}, session);
+		await agentEnd!(agentEndEvent, session);
+		assert.equal(sent.length, 1, "shutdown cleared the baseline, so the same identity reminds again in the next session");
+	});
+});