gentle-pi 4.0.0 → 4.2.0

package/tests/command-palette.test.ts

@@ -136,7 +136,7 @@ const GROUPS: CommandPaletteGroup[] = [
 	},
 	{
 		title: "Session",
-		items: [{ command: "gentle:changes", label: "Browse captured changes", shortcut: "alt+g" }],
+		items: [{ command: "gentle:changes", label: "Browse changes", shortcut: "alt+g" }],
 	},
 ];
 
@@ -245,9 +245,9 @@ test("render shows group titles and one row per item, with the shortcut right-al
 	assert.match(lines, /Session/);
 	assert.match(lines, /Assign models and effort/);
 	assert.match(lines, /Agent-model profiles/);
-	const changesLine = render(GROUPS, "").find((line) => line.includes("Browse captured changes"));
-	assert.ok(changesLine, "expected a row for Browse captured changes");
-	assert.match(changesLine!, /Browse captured changes[\s\S]*alt\+g/);
+	const changesLine = render(GROUPS, "").find((line) => line.includes("Browse changes"));
+	assert.ok(changesLine, "expected a row for Browse changes");
+	assert.match(changesLine!, /Browse changes[\s\S]*alt\+g/);
 });
 
 test("render omits the shortcut column for an item without one", () => {
@@ -376,7 +376,7 @@ test("COMMAND_PALETTE_CATALOG matches the curated command set, in order", () =>
 		"gentle:toggle-text-logo",
 		"gentle:dev-binary",
 	]);
-	assert.deepEqual(byTitle("Session"), ["gentle:yolo", "gentle:changes", "gentle:agents", "gentle:usage", "gentle:review-session-permission"]);
+	assert.deepEqual(byTitle("Session"), ["gentle:yolo", "gentle:changes", "gentle:agents", "gentle:jobs", "gentle:usage", "gentle:review-session-permission"]);
 	assert.deepEqual(byTitle("Diagnostics"), ["gentle:status", "gentle:doctor"]);
 	assert.equal(byTitle("SDD"), undefined);
 	assert.deepEqual(byTitle("Skills"), ["skill-registry:refresh"]);

package/tests/context-threshold.test.ts

@@ -0,0 +1,31 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { CONTEXT_HIGH_PERCENT, ContextHighLatch } from "../lib/context-threshold.ts";
+
+test("warns exactly once when a reading reaches the threshold, then stays silent", () => {
+	assert.equal(CONTEXT_HIGH_PERCENT, 90);
+	const latch = new ContextHighLatch();
+	assert.equal(latch.observe(0), false);
+	assert.equal(latch.observe(89.9), false);
+	assert.equal(latch.observe(90), true, "the threshold is inclusive");
+	for (const percent of [90, 91, 99, 140]) assert.equal(latch.observe(percent), false, `same episode at ${percent}% must not warn again`);
+});
+
+test("unknown readings preserve the latch; a below-threshold reading rearms it", () => {
+	const latch = new ContextHighLatch();
+	assert.equal(latch.observe(95), true);
+	assert.equal(latch.observe(null), false, "a null reading after compaction is not a rearm");
+	assert.equal(latch.observe(undefined), false);
+	assert.equal(latch.observe(96), false, "the same episode cannot warn twice across an unknown reading");
+	assert.equal(latch.observe(80), false);
+	assert.equal(latch.observe(91), true, "dropping below the threshold starts a new episode");
+});
+
+test("only an explicit rearm starts a new episode and non-finite readings never warn", () => {
+	const latch = new ContextHighLatch();
+	assert.equal(latch.observe(94), true);
+	latch.rearm();
+	assert.equal(latch.observe(94), true, "a successful compaction or new session rearms");
+	assert.equal(latch.observe(94), false);
+	for (const value of [Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY]) assert.equal(latch.observe(value), false);
+});

package/tests/delegate-for-reason-contract.test.ts

@@ -0,0 +1,327 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+import { HIGH_RISK_ITEMS } from "../lib/review-risk-assessment.ts";
+import { readDelegationDetail } from "./support/orchestrator-modules.ts";
+
+// gentle-shell#1731: the delegated writer fires on named reasons (parallelism,
+// context), never on task size. A large task keeps the ODD logbook (#1494
+// resume test) and works inline when no reason fires. T24 (L49) turned the
+// cost reason off: a price ratio never fires the Writer rule, while configured
+// per-agent model routing still applies to writers launched for other reasons.
+// These are instruction-delivery contracts, not proof of model adherence.
+
+const read = (relative: string): string => readFileSync(join(import.meta.dirname, "..", relative), "utf8");
+const core = read("assets/orchestrator.md");
+const delegation = readDelegationDetail();
+const writer = read("assets/orchestrator-writer.md");
+const verification = read("assets/orchestrator-verification.md");
+const skill = read("skills/gentle-ai/SKILL.md");
+
+function lineStarting(text: string, prefix: string): string {
+	const line = text.split("\n").find((entry) => entry.startsWith(prefix));
+	assert.ok(line, `missing line starting with: ${prefix}`);
+	return line;
+}
+
+const coreWriter = lineStarting(core, "5. **Writer rule**");
+const delegationWriter = lineStarting(delegation, "5. **Writer trigger (Writer rule):**");
+
+test("AC1: the core writer rule fires on named reasons, never on size or file count", () => {
+	for (const clause of [
+		"never by file count or a large task alone",
+		"`orchestrator-writer.md`",
+		"2+ independent units, disjoint files, each heavier than a subagent start",
+		"Context backstop",
+	]) {
+		assert.ok(coreWriter.includes(clause), `core Writer rule is missing: ${clause}`);
+	}
+	assert.ok(!core.includes("large task → one bounded `gentle-ai-worker` per task"), "core keeps the size-based writer rule");
+	assert.ok(
+		core.includes("large tasks get ODD tracking and workers only by the Writer rule, else inline"),
+		"core Task Size must keep tracking for large tasks and run them inline without a writer reason",
+	);
+});
+
+test("AC1: the lazy writer trigger names its reasons and keeps the logbook on the inline path", () => {
+	for (const clause of [
+		"a large task alone never delegates, and file count never fires this trigger",
+		"Delegate one bounded writer per unit only for a named reason",
+		"(a) parallelism",
+		"(b) context",
+		"Without a reason, the parent works inline, following the logbook (feature document, mirror, `todo`, work-unit commits)",
+	]) {
+		assert.ok(delegationWriter.includes(clause), `lazy Writer trigger is missing: ${clause}`);
+	}
+	for (const [path, text] of Object.entries({ delegation, writer, skill })) {
+		assert.ok(!text.includes("a large task delegates one bounded writer per task"), `${path} keeps the size-based writer trigger`);
+		assert.ok(!text.includes("one writer per task"), `${path} keeps one writer per task`);
+		assert.ok(!text.includes("a large task (track and writer)"), `${path} still fires the writer on size`);
+	}
+	assert.ok(writer.includes("never on size alone"), "the writer module must say the Writer rule never fires on size alone");
+	assert.ok(skill.includes("a writer reason (parallel units or context)"), "the skill must name the writer reasons");
+});
+
+test("AC2: parallelism needs 2+ independent units, disjoint files, each heavier than a subagent start", () => {
+	assert.ok(
+		delegationWriter.includes(
+			"(a) parallelism — 2+ independent units with disjoint files, each clearly heavier than starting a subagent; medium tasks included",
+		),
+		"lazy Writer trigger must state the parallelism threshold",
+	);
+	assert.ok(writer.includes("parallel units"), "the writer module must name the parallelism reason");
+});
+
+test("T24/L49: a price ratio no longer fires the Writer rule", () => {
+	assert.doesNotMatch(coreWriter, /ratio|price|Model routing|small path/i, "core Writer rule still fires on cost");
+	assert.ok(!core.includes("Model routing:"), "the orchestrator core never carries the fact line");
+	const intro = lineStarting(writer, "Parent Pi session only.");
+	assert.ok(intro.includes("The Writer rule fires on a named reason (parallel units, the context backstop), never on size alone or a price ratio"), "the writer module must name only the remaining reasons");
+	assert.doesNotMatch(writer, /about 3x|price ratio of|- \*\*Model routing\*\*/, "the writer module keeps the cost reason");
+	// T24 follow-up: no surface names the price ratio as a writer reason.
+	for (const [path, text] of Object.entries({ delegationWriter, skill, readme: read("docs/readme-reference.md") })) {
+		assert.doesNotMatch(text, /model routing —|price ratio of about 3x/, `${path} still names the cost reason`);
+	}
+});
+
+test("T24/L49: configured per-agent model routing still applies to writers launched for other reasons", () => {
+	const intro = lineStarting(writer, "Parent Pi session only.");
+	assert.ok(intro.includes("Configured per-agent models (`subagents.json` `model_profiles`) still apply to every writer it launches."), "the writer module must keep configured routing");
+	assert.ok(
+		delegation.includes("Let `pi-subagents` resolve model and thinking from `.pi/settings.json`, `.pi/subagents.json`, global subagent config, and runtime defaults."),
+		"delegated launches must keep resolving configured models",
+	);
+});
+
+test("AC4: verification stays risk-gated and the writer reasons never include risk", () => {
+	assert.ok(
+		core.includes(
+			"3. **Verification rule** — high risk → independent `gentle-ai-verify` after the change's own checks (`orchestrator-verification.md`); otherwise checks run inline.",
+		),
+		"core Verification rule changed",
+	);
+	assert.ok(
+		delegation.includes(
+			"3. **Verification rule** (gentle-pi#661/#662, RDD-aware): a high-risk change (Task Size) gets an independent `gentle-ai-verify` run after the change's own checks; otherwise whoever made the change runs its focused test and suite inline, small tasks included.",
+		),
+		"lazy Verification rule changed",
+	);
+	for (const [label, text] of Object.entries({ coreWriter, delegationWriter })) {
+		assert.ok(!/high risk|high-risk|verify/i.test(text), `${label} mixes risk or verification into the writer reasons`);
+	}
+	assert.ok(!writer.includes("(1) data or irreversible effects"), "the writer module restates the high-risk list");
+});
+
+// T3 (S5-S7, AC5): the parallel review protocol lives in the lazy verification
+// module, so it loads only when delegation happens.
+function sectionFrom(text: string, heading: string): string {
+	const start = text.indexOf(heading);
+	assert.ok(start >= 0, `missing section: ${heading}`);
+	const next = text.indexOf("\n## ", start + heading.length);
+	return text.slice(start, next < 0 ? undefined : next + 1);
+}
+
+const reviewSection = (): string => sectionFrom(verification, "## Parallel review protocol (gentle-shell#1731)");
+
+function reviewItem(prefix: string): string {
+	return lineStarting(reviewSection(), prefix);
+}
+
+test("AC5/S5: every worker self-reviews against the spec by reference before returning", () => {
+	const item = reviewItem("1. **Self-review**");
+	for (const clause of [
+		"in its own session before returning",
+		"spec sections by reference (#1713)",
+		"the request's authorized examples, tests, and typecheck",
+		"fixes and continues",
+		"requirement by requirement",
+		"Low and medium risk need nothing else.",
+	]) {
+		assert.ok(item.includes(clause), `self-review item is missing: ${clause}`);
+	}
+	assert.ok(writer.includes("Parallel review protocol") && writer.includes("`orchestrator-verification.md`"), "the writer module must point at the review protocol");
+});
+
+test("AC5/S6/L4: per-worker independent verify fires only on assess or escalate, never on the summary alone", () => {
+	const item = reviewItem("2. **Independent verify per unit**");
+	for (const clause of [
+		"in parallel when several finish together",
+		"only when that unit is high risk",
+		"`assess` over its actual diff",
+		"the worker's own `escalate`",
+		"never inferred from the worker's summary alone",
+		'its work-unit commit (`{"baseRef":"<previous>","committedOnly":true}`)',
+		"its own isolated worktree",
+	]) {
+		assert.ok(item.includes(clause), `independent verify item is missing: ${clause}`);
+	}
+	assert.ok(!reviewSection().includes("(1) data or irreversible effects"), "the protocol restates the high-risk list instead of referencing it");
+	assert.ok(item.includes("high-risk list in Task Size"), "the protocol must reference the core high-risk list");
+});
+
+test("AC5/S7: one inline full-suite seam check after parallel units", () => {
+	const item = reviewItem("3. **Seam check**");
+	for (const clause of ["after parallel units finish", "one inline full-suite command", "parent spot check", "seams between units"]) {
+		assert.ok(item.includes(clause), `seam check item is missing: ${clause}`);
+	}
+});
+
+// T12 (S4, S6; L24): in the bench verify ran once per worker cycle instead of
+// once per unit, and a parent scoped it to "T1 only".
+test("T12/S6: one independent verify per delegated unit after its self-review, never per worker cycle", () => {
+	const item = reviewItem("2. **Independent verify per unit**");
+	for (const clause of [
+		"once, after its final self-review",
+		"never per worker cycle or retry",
+		"its Risk line",
+		"small-model bias per the tier table",
+	]) {
+		assert.ok(item.includes(clause), `independent verify timing is missing: ${clause}`);
+	}
+	assert.ok(!item.includes("(1) "), "the timing rule restates the high-risk list");
+});
+
+// T15 (S6, L38): after3 B x4 paid two same-model verifies with 0 defects,
+// while verify caught real defects in smaller-model (Luna) writer code.
+test("T15/S6: same-model inline code over several deliveries gets one verify at the feature's end; smaller-model writer code stays per unit", () => {
+	const item = reviewItem("2. **Independent verify per unit**");
+	for (const clause of [
+		"Same-model inline code over several deliveries of one feature",
+		"one verify at the feature's end",
+		"smaller-model writer code stays per unit",
+		"only when that unit is high risk",
+		"small-model bias per the tier table",
+	]) {
+		assert.ok(item.includes(clause), `independent verify exception is missing: ${clause}`);
+	}
+});
+
+test("T11/S4: the parent hands verify the whole spec, authorizes its probes and resolves every unmet item", () => {
+	const item = reviewItem("4. **Verify handoff**");
+	for (const clause of [
+		"the whole feature document",
+		"every `S#`, never one task",
+		"the baseline commit",
+		"probes on isolated state",
+		"typecheck",
+		"`gentle-ai-verify` holds the checklist",
+		"every unmet item before closing",
+		"the writer commits its probes as regression tests",
+	]) {
+		assert.ok(item.includes(clause), `verify handoff item is missing: ${clause}`);
+	}
+});
+
+// verify-always-rdd-high S1 deliberately rewrote this section: verification follows the
+// risk tier in every RDD state. The pin still guards against accidental drift.
+test("AC4/S4: the normative verification rule text is unchanged by the review protocol", () => {
+	const normative = sectionFrom(verification, "## Verification rule (normative)");
+	assert.equal(
+		createHash("sha256").update(normative).digest("hex"),
+		"1f66f6998c4659fb08d81b83d350dcf5e8279b3f04a9e1a3a2951ed2abe7e54b",
+		"the normative Verification rule section changed",
+	);
+	assert.ok(verification.includes("or a delegated writer returns"), "the module must still load when a delegated writer returns");
+});
+
+test("S1: the small path stays inline and no lazy surface keeps the size-based writer route", () => {
+	assert.ok(core.includes("No explore, worker, or verifier"), "small path must stay inline");
+	assert.ok(!delegation.includes("| Write a large (tracked) task | — | ✅ one writer per task |"), "delegation table keeps the size-based writer row");
+	assert.ok(delegation.includes("| Write a large task with no Writer rule reason | ✅ following the logbook | — |"), "delegation table must route a reasonless large task inline");
+	assert.ok(!delegation.includes("implementing a large tracked task (writer)"), "Simple Delegation keeps the size-based writer route");
+});
+
+// T7-T9 (L14): the bench showed the rules decide WHETHER to delegate but not
+// HOW. T7 forces a risk declaration on every code change, small path included,
+// so it lives in the always-on core. T9 binds how the parallelism reason
+// launches writers, so it lives in the lazy writer module (T24 retired T8's
+// cost-reason launch rule with the cost reason itself).
+const taskSize = sectionFrom(core, "## Task Size");
+
+test("T7/AC4: every code change closes with a forced risk line that routes any listed item to independent verify", () => {
+	const rule = lineStarting(taskSize, "**Risk line**");
+	for (const clause of [
+		"close every code change, small path or delegated",
+		"`Risk: item N (reason)`",
+		"`Risk: none`",
+		"per the list",
+		"any item → Verification rule",
+	]) {
+		assert.ok(rule.includes(clause), `risk line rule is missing: ${clause}`);
+	}
+	const highRisk = taskSize.indexOf("**High risk**");
+	assert.ok(highRisk >= 0 && taskSize.indexOf("**Risk line**") > highRisk, "the risk line must follow the high-risk list it is checked against");
+	// The small path loads no lazy module, so the rule must render in the always-on prompt.
+	assert.ok(__testing.getOrchestratorPrompt().includes(rule), "the risk line must reach the always-on prompt");
+	for (const [path, text] of Object.entries({ delegation, writer, verification })) {
+		assert.ok(!text.includes("`Risk: item N (reason)`"), `${path} restates the core risk line`);
+	}
+});
+
+// T10 (S4, L19-L21): the risk line tagged items 1 and 3 for additive features,
+// so verify ran on most tasks. High risk is changing or breaking existing
+// things, not adding.
+function highRiskItem(n: number): string {
+	const list = lineStarting(taskSize, "**High risk**");
+	const start = list.indexOf(`(${n}) `);
+	const next = list.indexOf(`; (${n + 1}) `, start);
+	const end = next >= 0 ? next : list.indexOf(". ", start);
+	assert.ok(start >= 0 && end > start, `high-risk item ${n} is missing`);
+	return list.slice(start, end);
+}
+
+test("T10/AC4: item 1 covers changing stored data or unvalidated writes, not ordinary new records", () => {
+	const item = highRiskItem(1);
+	for (const clause of ["migrations", "rewriting or deleting stored data", "format changes", "writing data without validation", "not saving new records"]) {
+		assert.ok(item.includes(clause), `item 1 is missing: ${clause}`);
+	}
+	assert.ok(!item.includes("persisted data"), "item 1 keeps the broad persisted-data form");
+});
+
+test("T10/AC4: item 3 covers changing or removing consumed contracts, not adding a flag, command or optional field", () => {
+	const item = highRiskItem(3);
+	assert.ok(item.startsWith("(3) changing or removing contracts others already consume ("), `item 3 is not limited to existing contracts: ${item}`);
+	for (const clause of ["public API", "CLI flags", "config formats", "exports", "mirrored prompts", "not adding a flag, command or optional field"]) {
+		assert.ok(item.includes(clause), `item 3 is missing: ${clause}`);
+	}
+});
+
+test("T10: escalate labels name the core high-risk items", () => {
+	for (const [n, label] of Object.entries(HIGH_RISK_ITEMS)) {
+		assert.ok(highRiskItem(Number(n)).startsWith(`(${n}) ${label}`), `escalate label ${n} drifts from the core list: ${label}`);
+	}
+});
+
+test("T9/AC2: the parallelism reason launches every unit together in background and waits for all", () => {
+	const parallel = lineStarting(writer, "- **Parallelism**");
+	for (const clause of [
+		"every disjoint unit in the same turn",
+		'`subagent_run` with `mode: "background"`',
+		"wait for all completions",
+		"serial launches void the reason",
+		"work inline",
+		"Seam check",
+	]) {
+		assert.ok(parallel.includes(clause), `writer parallelism launch rule is missing: ${clause}`);
+	}
+	assert.ok(!/high risk|high-risk|verify/i.test(parallel), "parallel mixes risk or verification into the writer reasons");
+});
+
+// T4 (S2, AC6): the runtime rejects an overlapping live writer at admission,
+// so the single-writer wording relaxes to disjoint surfaces or isolated worktrees.
+test("AC6: parallel writers need disjoint Allowed edit surfaces (runtime-enforced) or isolated worktrees", () => {
+	const rule = "arallel writers only with disjoint Allowed edit surfaces (runtime-enforced) or isolated worktrees";
+	const harness = read("extensions/gentle-ai.ts");
+	const docs = read("docs/readme-reference.md");
+	assert.ok(core.includes(`- P${rule}.`), "core Safety must carry the relaxed writer rule");
+	assert.ok(harness.includes(`- P${rule}.`), "harness principles must carry the relaxed writer rule");
+	for (const [path, text] of Object.entries({ core, delegation, harness, skill, docs })) {
+		assert.ok(text.includes(rule), `${path} is missing the relaxed writer rule`);
+		for (const retired of ["single-threaded", "Never run parallel writers in one worktree", "do not run parallel writers unless isolated worktrees", "preserves a single writer thread", "one writer per task"]) {
+			assert.ok(!text.includes(retired), `${path} keeps the single-writer wording: ${retired}`);
+		}
+	}
+});

package/tests/delegated-key-learnings-contract.test.ts

@@ -4,6 +4,7 @@ import { dirname, join, relative, sep } from "node:path";
 import { tmpdir } from "node:os";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
+import { readDelegationDetail } from "./support/orchestrator-modules.ts";
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const AGENTS = join(ROOT, "assets", "agents");
@@ -53,7 +54,7 @@ function strictJsonAgents(): string[] {
 }
 
 test("generic delegation contract instructs the same `## Key Learnings` closing block", () => {
-	const delegation = readFileSync(join(ASSETS, "orchestrator-delegation.md"), "utf8");
+	const delegation = readDelegationDetail();
 	const section = readSection(delegation, "Key Learnings closing block");
 	assert.ok(section, "orchestrator-delegation.md must have a Key Learnings closing block section");
 	for (const [label, regex] of KL_SEMANTICS) {
@@ -159,6 +160,6 @@ test("strict review and Judgment Day agents do not gain Key Learnings or trailin
 });
 
 test("the canonical Key Learnings heading has no trailing colon in any asset", () => {
-	const delegation = readFileSync(join(ASSETS, "orchestrator-delegation.md"), "utf8");
+	const delegation = readDelegationDetail();
 	assert.doesNotMatch(delegation, /`## Key Learnings:`/);
 });

package/tests/devbinary/native-review-parity.devtest.ts

@@ -32,7 +32,7 @@ const devBinaryGate = requireDevBinary({
 	exists: typeof DEV_BINARY === "string" && DEV_BINARY.length > 0 && DEV_BINARY.startsWith("/") && existsSync(DEV_BINARY),
 	env: process.env,
 });
-if (!devBinaryGate.run) console.log(`tests/devbinary/native-review-parity.devtest.ts: ${devBinaryGate.reason}`);
+if (devBinaryGate.run === false) console.log(`tests/devbinary/native-review-parity.devtest.ts: ${devBinaryGate.reason}`);
 const RUNNABLE = devBinaryGate.run;
 const DEV_HOME = mkdtempSync(join(tmpdir(), "gentle-pi-dev-binary-home-"));
 const ORIGINAL_HOME = process.env.HOME;

package/tests/devbinary/pi-host-relay.devtest.ts

@@ -85,9 +85,9 @@ const relayDevBinaryGate = POSIX
 	})
 	: { run: false as const, reason: "Windows is explicitly skipped until a native fake-pi.exe exists; this test never enables a shell fallback." };
 const RUNNABLE = POSIX && primaryDevBinaryGate.run && relayDevBinaryGate.run;
-if (!POSIX) console.log(`tests/devbinary/pi-host-relay.devtest.ts: ${relayDevBinaryGate.reason}`);
-if (!primaryDevBinaryGate.run) console.log(`tests/devbinary/pi-host-relay.devtest.ts: ${primaryDevBinaryGate.reason}`);
-if (!relayDevBinaryGate.run && POSIX) console.log(`tests/devbinary/pi-host-relay.devtest.ts: ${relayDevBinaryGate.reason}`);
+if (relayDevBinaryGate.run === false && !POSIX) console.log(`tests/devbinary/pi-host-relay.devtest.ts: ${relayDevBinaryGate.reason}`);
+if (primaryDevBinaryGate.run === false) console.log(`tests/devbinary/pi-host-relay.devtest.ts: ${primaryDevBinaryGate.reason}`);
+if (relayDevBinaryGate.run === false && POSIX) console.log(`tests/devbinary/pi-host-relay.devtest.ts: ${relayDevBinaryGate.reason}`);
 
 const ZERO_FINDING_PATHS = Object.freeze([".github/workflows/relay.yml"]);
 
@@ -530,6 +530,176 @@ test("dev-binary: a garbage reviewer result is refused at admission as a proven
 	assert.equal(reoffered, true, "the unconsumed slot must be reoffered by fresh STATUS");
 });
 
+test("dev-binary: Pi returns a terminal single-lens escalation from the real committed candidate capture", { skip: !RUNNABLE }, async (t) => {
+	const cwd = repository(t, "gentle-pi-escalation-");
+	const home = mkdtempSync(join(tmpdir(), "gentle-pi-escalation-home-"));
+	t.after(() => { rmSync(home, { recursive: true, force: true }); __testing.setReviewHostRelayRunnerForTesting(); });
+	const environment = { ...reviewEnvironment(home), GENTLE_PI_CONFIG_HOME: join(home, "config"), GENTLE_PI_AGENT_HOME: join(home, "agent") }, binary = RELAY_DEV_BINARY!;
+	const baseRef = git(cwd, "rev-parse", "HEAD");
+	writeFileSync(join(cwd, "app.ts"), "export const value = 2;\n");
+	git(cwd, "add", "app.ts");
+	git(cwd, "commit", "-qm", "candidate");
+	enableGlobalReview(binary, cwd, cwd, environment);
+	const calls: NativeProcessCall[] = [];
+	const { controller, capture } = reviewToolsForNative(devNativeCli(binary, environment, calls));
+	const context = sessionContext(cwd), selector = { baseRef, committedOnly: true };
+	await controller.execute("escalation-inspect", { operation: "inspect", workspaceRoot: cwd }, undefined, undefined, context);
+	const prompted = record((await controller.execute("escalation-start", { operation: "start", workspaceRoot: cwd, input: JSON.stringify({ mode: "ordinary", ...selector }) }, undefined, undefined, context)).details, "escalation start");
+	assert.equal(prompted.outcome, "native-review-consent-required");
+	const started = record((await controller.execute("escalation-consent", { operation: "answer-consent", input: JSON.stringify({ consentBinding: prompted.consent_binding, answer: "granted" }) }, undefined, undefined, context)).details, "escalation consent");
+	const lineage = stringValue(record(started.result, "escalation start result").lineage_id, "escalation lineage");
+	const statusParameters = { operation: "status", lineageId: lineage, workspaceRoot: cwd, input: JSON.stringify(selector) };
+	const before = record((await controller.execute("escalation-status", statusParameters, undefined, undefined, context)).details, "escalation status");
+	assert.equal(record(record(before.result, "initial status").projection, "committed projection").kind, "base-diff");
+	const binding = collectBindingFor(before, "review.capture-result");
+	const reviewer = fauxReviewerFor((subjectHash) => JSON.stringify({
+		subject_hash: subjectHash,
+		inspection: { status: "completed", paths: ["app.ts"] },
+		findings: [{ id: "R3-001", location: "app.ts:1", severity: "CRITICAL", claim: "synthetic severe finding with unknown causal origin", proof_refs: ["app.ts:1"], evidence_class: "deterministic", causal_disposition: "unknown" }],
+		evidence: ["inspected the frozen committed candidate"],
+	}));
+	__testing.setReviewHostRelayRunnerForTesting(async (request) => {
+		reviewer.enqueue();
+		return await runReviewHostRelaySlot({ ...request, gentleAiExecutable: binary, environment, reviewerRegistry: reviewer.registry, selection: reviewer.selection, routingKey: reviewer.routingKey });
+	});
+	const parameters = { lineageId: lineage, workspaceRoot: cwd, collectBinding: binding };
+	const forecast = record((await capture.execute("escalation-forecast", parameters, undefined, undefined, context)).details, "escalation forecast");
+	assert.equal(forecast.outcome, "reviewer-model-run-forecast");
+	assert.equal(record(forecast.cost_forecast, "escalation forecast cost").model_runs, 1);
+	assert.equal(reviewer.calls.length, 0);
+	const offset = calls.length;
+	const result = record((await capture.execute("escalation-capture", { ...parameters, reviewerRunAcknowledged: true }, undefined, undefined, context)).details, "escalation capture");
+	assert.equal(result.status, "closed", JSON.stringify(result));
+	assert.equal(result.state, "escalated");
+	const closure = record(result.closure, "escalation closure");
+	assert.deepEqual(closure.escalation, { cause: "unknown_causality", finding_ids: ["R3-001"] });
+	assert.equal(closure.acknowledgement, undefined);
+	assert.equal(result.next_action, undefined);
+	assert.equal(reviewer.calls.length, 1);
+	assert.equal(calls.slice(offset).filter((call) => call.arguments[1] === "status").length, 1, "capture closes without a post-success reconciliation");
+	const after = record((await controller.execute("escalation-terminal-status", statusParameters, undefined, undefined, context)).details, "terminal status");
+	const nativeStatus = record(after.result, "terminal native status");
+	assert.equal(record(nativeStatus.authority, "terminal authority").state, "escalated");
+	assert.equal(record(nativeStatus.authority, "terminal authority").revision, closure.store_revision);
+	assert.equal(record(nativeStatus.next_transition, "terminal transition").reason_code, "native_stop_required");
+	assert.deepEqual(nativeStatus.escalation, closure.escalation);
+});
+
+// gentle-pi#998: real admitted validator rejection must survive Pi's closure decoder.
+test("dev-binary: Pi preserves targeted-validator rejection evidence in an escalated correction closure", { skip: !RUNNABLE }, async (t) => {
+	const cwd = repository(t, "gentle-pi-validator-rejection-");
+	const home = mkdtempSync(join(tmpdir(), "gentle-pi-validator-rejection-home-"));
+	t.after(() => { rmSync(home, { recursive: true, force: true }); __testing.setReviewHostRelayRunnerForTesting(); });
+	const environment = { ...reviewEnvironment(home), GENTLE_PI_CONFIG_HOME: join(home, "config"), GENTLE_PI_AGENT_HOME: join(home, "agent"), PI_CODING_AGENT_DIR: join(home, "agent") };
+	const binary = RELAY_DEV_BINARY!;
+	assert.equal(realpathSync(binary), realpathSync(DEV_BINARY!));
+	writeFileSync(join(cwd, "app.ts"), "export const value = 2;\n");
+	enableGlobalReview(binary, cwd, cwd, environment);
+	const calls: NativeProcessCall[] = [];
+	const { controller, capture } = reviewToolsForNative(devNativeCli(binary, environment, calls));
+	const context = sessionContext(cwd);
+	const control = async (id: string, params: unknown) => record((await controller.execute(id, params, undefined, undefined, context)).details, id);
+	await control("rejection-inspect", { operation: "inspect", workspaceRoot: cwd });
+	const prompted = await control("rejection-start", { operation: "start", workspaceRoot: cwd, input: JSON.stringify({ mode: "ordinary" }) });
+	assert.equal(prompted.outcome, "native-review-consent-required");
+	const started = await control("rejection-consent", { operation: "answer-consent", input: JSON.stringify({ consentBinding: prompted.consent_binding, answer: "granted" }) });
+	const lineage = stringValue(record(started.result, "rejection start result").lineage_id, "rejection lineage");
+	const statusParameters = { operation: "status", workspaceRoot: cwd, lineageId: lineage };
+	const reviewer = fauxReviewerFor((subjectHash) => JSON.stringify({
+		subject_hash: subjectHash,
+		inspection: { status: "completed", paths: ["app.ts"] },
+		findings: [{ id: "R3-001", location: "app.ts:1", severity: "BLOCKER", claim: "value must be corrected", proof_refs: ["app.ts:1"], evidence_class: "deterministic", causal_disposition: "introduced" }],
+		evidence: ["inspected the frozen candidate"],
+	}));
+	let validator: ReturnType<typeof fauxReviewerFor> | undefined;
+	let emittedClosure: Record<string, unknown> | undefined;
+	const relayRoles: string[] = [];
+	__testing.setReviewHostRelayRunnerForTesting(async (request) => {
+		assert.equal(request.targetCwd, cwd);
+		const selected = request.routingKey === "review-validator" ? validator : reviewer;
+		assert.ok(selected, "validator fixture must be bound before capture");
+		relayRoles.push(request.routingKey!);
+		selected.enqueue();
+		const relay = await runReviewHostRelaySlot({ ...request, gentleAiExecutable: binary, environment, reviewerRegistry: selected.registry, selection: selected.selection, routingKey: request.routingKey });
+		if (request.routingKey === "review-validator") emittedClosure = record(JSON.parse(relay.submission) as unknown, "native rejection submission");
+		return relay;
+	});
+	const captureRole = async (id: string, binding: string) => {
+		const params = { lineageId: lineage, workspaceRoot: cwd, collectBinding: binding };
+		const modelCalls = reviewer.calls.length + (validator?.calls.length ?? 0), roleCalls = relayRoles.length;
+		const forecast = record((await capture.execute(`${id}-forecast`, params, undefined, undefined, context)).details, "rejection forecast");
+		assert.equal(forecast.outcome, "reviewer-model-run-forecast");
+		assert.equal(reviewer.calls.length + (validator?.calls.length ?? 0), modelCalls, "no model call before acknowledgement");
+		assert.equal(relayRoles.length, roleCalls, "no role replay before acknowledgement");
+		const result = record((await capture.execute(id, { ...params, reviewerRunAcknowledged: true }, undefined, undefined, context)).details, id);
+		assert.equal(reviewer.calls.length + (validator?.calls.length ?? 0), modelCalls + 1);
+		return result;
+	};
+	let correctionOpened = false;
+	for (let attempt = 0; attempt < 4; attempt += 1) {
+		const status = await control(`rejection-reviewer-status-${attempt}`, statusParameters);
+		const binding = collectBindingsFor(status, "review.capture-result")[0];
+		assert.ok(binding, "native STATUS must offer a reviewer slot");
+		const result = await captureRole(`rejection-reviewer-${attempt}`, binding);
+		assert.ok(["captured", "closed"].includes(stringValue(result.status, "reviewer capture status")));
+		if (result.closure !== undefined) {
+			assert.equal(record(result.closure, "reviewer closure").state, "correction_required");
+			correctionOpened = true;
+			break;
+		}
+	}
+	assert.equal(correctionOpened, true, "real admitted findings must open correction");
+	const correctionStatus = await control("rejection-correction-status", statusParameters);
+	const correctionBinding = collectBindingFor(correctionStatus, "review.capture-correction-plan");
+	const plan = record((await capture.execute("rejection-plan", { lineageId: lineage, workspaceRoot: cwd, collectBinding: correctionBinding, correctionLines: 1 }, undefined, undefined, context)).details, "correction plan");
+	assert.equal(record(plan.closure, "correction plan closure").state, "correction_required");
+	writeFileSync(join(cwd, "app.ts"), "export const value = 3;\n");
+	const validationStatus = await control("rejection-validation-status", statusParameters);
+	const binding = collectBindingFor(validationStatus, "review.capture-validation");
+	const request = record(parsedCollectBinding(binding).validationRequest, "native validation request");
+	const requestHash = collectBindingArgument(binding, "request-hash"), target = collectBindingArgument(binding, "target");
+	assert.equal(request.requestHash, requestHash);
+	assert.equal(request.correctionTargetIdentity, target);
+	assert.deepEqual(request.correctionPaths, ["app.ts"]);
+	const proof = {
+		targeted_validation_request_hash: requestHash,
+		correction_target_identity: target,
+		original_criteria: { passed: true, evidence: ["value correction satisfies original criteria"] },
+		correction_regression: { passed: false, evidence: ["corrected value breaks the consumer"], regressions: [{ id: "REG-001", location: "app.ts:1", claim: "value 3 breaks the consumer", proof_refs: ["app.ts:1", "focused regression check"] }] },
+		follow_ups: [{ observation: "consumer expectation needs investigation", proof_refs: ["app.ts:1"] }],
+	};
+	validator = fauxReviewerFor(() => JSON.stringify(proof));
+	const result = await captureRole("rejection-validation", binding);
+	assert.ok(emittedClosure, "real native submission must emit a closure");
+	t.diagnostic(`native rejection closure: ${JSON.stringify(emittedClosure)}`);
+	assert.equal(emittedClosure.operation, "review/capture-validation");
+	assert.equal(emittedClosure.state, "escalated");
+	assert.equal(emittedClosure.acknowledgement, undefined);
+	const escalation = record(emittedClosure.escalation, "native rejection escalation");
+	assert.equal(escalation.cause, "targeted_validator_rejected");
+	assert.deepEqual(emittedClosure.targeted_validator_evidence, proof);
+	const terminal = record(candidateJson(binary, cwd, ["review", "status", "--cwd", cwd, "--contract", "gentle-ai.review-integration/v2", "--agent", "pi", "--next-transition", "--lineage", lineage], environment), "persisted rejection STATUS");
+	assert.equal(record(terminal.authority, "terminal authority").state, "escalated");
+	assert.equal(record(terminal.authority, "terminal authority").revision, emittedClosure.store_revision);
+	assert.equal(record(terminal.next_transition, "terminal transition").kind, "stop");
+	assert.equal(record(terminal.next_transition, "terminal transition").reason_code, "native_stop_required");
+	assert.deepEqual(terminal.escalation, escalation);
+	assert.equal(validator.calls.length, 1);
+	assert.ok(validator.calls[0]!.promptText.includes(requestHash));
+	assert.equal(result.status, "closed", JSON.stringify(result));
+	assert.equal(result.outcome, "native-last-event-closure");
+	assert.equal(result.state, "escalated");
+	const closure = record(result.closure, "Pi rejection closure");
+	assert.equal(closure.operation, "review/capture-validation");
+	assert.equal(closure.lineage_id, lineage);
+	assert.equal(closure.store_revision, emittedClosure.store_revision);
+	assert.deepEqual(closure.escalation, escalation);
+	assert.deepEqual(closure.targeted_validator_evidence, proof, "Pi must preserve all native proof fields and hash bindings");
+	assert.equal(closure.acknowledgement, undefined);
+	assert.equal(result.next_action, undefined);
+	assert.equal(calls.some((call) => call.arguments[1] === "capture-validation"), false, "validation must use the registered host relay");
+});
+
 // This completes the same organic A -> B path through correction evidence,
 // host-mediated targeted validation, and terminal approval. The only
 // reviewers are the fixed faux registries below; no real model, provider, or