gentle-pi 3.2.0 → 3.2.1

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

@@ -0,0 +1,293 @@
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import {
+	ODD_ROUTING_BLOCK_PREFIX,
+	ODD_ROUTING_FIXTURE_RELATIVE,
+	ODD_ROUTING_SOURCE_PATH,
+	ODD_ROUTING_SOURCE_REPO,
+	assertCleanGentleAiCheckout,
+	parseOddRoutingFixture,
+	renderOddRoutingFixture,
+	resolveOddRoutingProvenance,
+	sha256Hex,
+} from "../scripts/mirror-odd-routing.mjs";
+
+// ---------------------------------------------------------------------------
+// ODD routing drift ratchet (gentle-pi#1147 follow-up)
+//
+// gentle-pi hand-mirrors the always-on ODD routing block rendered by gentle-ai
+// `internal/components/agentguidance/routing.go` (RenderRouting). There is no
+// automated sync, so a canonical change leaves the pi mirror stale with nothing
+// catching it. This ratchet vendored-snapshots the canonical block into
+// `fixtures/odd-routing-canonical.md` (regenerated via `npm run
+// mirror:odd-routing`) and fails when a mandatory-delegation clause is dropped
+// either from the canonical fixture or from a pi mirror surface.
+//
+// Regeneration writes ONLY the fixture; this ratchet never auto-rewrites mirror
+// assets, so drift stays visible as a deliberate diff.
+// ---------------------------------------------------------------------------
+
+const REPO_ROOT = join(import.meta.dirname, "..");
+const FIXTURE_PATH = join(REPO_ROOT, ...ODD_ROUTING_FIXTURE_RELATIVE.split("/"));
+const DELEGATION_PATH = join(REPO_ROOT, "assets", "orchestrator-delegation.md");
+const CORE_PATH = join(REPO_ROOT, "assets", "orchestrator.md");
+const EXTENSION_PATH = join(REPO_ROOT, "extensions", "gentle-ai.ts");
+
+const readRepo = (absolutePath: string): string => readFileSync(absolutePath, "utf8");
+
+// A mandatory-delegation semantic anchor: the clause the canonical block must
+// still carry, plus the wording each pi mirror surface is expected to carry.
+// A canonical change that drops `canonical` is caught here on regeneration
+// because the fixture no longer carries it.
+interface RoutingAnchor {
+	label: string;
+	canonical: string;
+	mirrors: ReadonlyArray<{ surface: string; includes: string }>;
+}
+
+const DELEGATION = "assets/orchestrator-delegation.md";
+const CORE = "assets/orchestrator.md";
+const EXTENSION = "extensions/gentle-ai.ts";
+
+const ANCHORS: readonly RoutingAnchor[] = [
+	{
+		label: "mandatory delegation triggers heading",
+		canonical: "### Mandatory Delegation Triggers",
+		mirrors: [
+			{ surface: DELEGATION, includes: "#### Mandatory Delegation Triggers" },
+			{ surface: CORE, includes: "Mandatory Delegation Triggers" },
+		],
+	},
+	{
+		label: "triggers are mandatory, not advisory",
+		canonical: "These triggers are mandatory, not advisory.",
+		mirrors: [
+			{ surface: DELEGATION, includes: "These triggers are mandatory, not advisory." },
+			{ surface: EXTENSION, includes: "These triggers are mandatory, not advisory" },
+		],
+	},
+	{
+		label: "stop and delegate through the runtime's subagent mechanism",
+		canonical: "stop and delegate through the runtime's subagent mechanism before continuing",
+		mirrors: [
+			{ surface: DELEGATION, includes: "stop and delegate through the runtime's subagent mechanism before continuing" },
+		],
+	},
+	{
+		label: "executing past a fired trigger is a routing defect",
+		canonical: "executing past a fired trigger inline is a routing defect even if the work succeeds",
+		mirrors: [
+			{ surface: DELEGATION, includes: "executing past a fired trigger inline is a routing defect even if the work succeeds" },
+			{ surface: EXTENSION, includes: "executing past a fired trigger inline is a routing defect even if the work succeeds" },
+		],
+	},
+	{
+		label: "mapping trigger at 4 or more files",
+		canonical: "**Mapping trigger:** when understanding the work requires 4 or more files",
+		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" },
+		],
+	},
+	{
+		label: "writer trigger at 2 or more non-trivial files",
+		canonical: "**Writer trigger:** when implementation touches 2 or more non-trivial files",
+		mirrors: [
+			{ surface: DELEGATION, includes: "**Writer trigger (Multi-file write rule):** when implementation touches 2 or more non-trivial files" },
+			{ surface: CORE, includes: "**Multi-file write rule** — 2+ non-trivial files touched" },
+		],
+	},
+	{
+		label: "preparation trigger",
+		canonical: "**Preparation trigger:**",
+		mirrors: [{ surface: DELEGATION, includes: "**Preparation trigger:**" }],
+	},
+	{
+		label: "long-session backstop",
+		canonical: "**Long-session backstop:**",
+		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" },
+		],
+	},
+	{
+		label: "route declaration records the chosen route per task",
+		canonical: "**Route declaration:**",
+		mirrors: [
+			{ surface: DELEGATION, includes: "record the chosen route per task" },
+		],
+	},
+	{
+		label: "triggers never select SDD",
+		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" },
+		],
+	},
+	{
+		label: "ODD step 6 honors its mandatory delegation triggers",
+		canonical: "honoring its mandatory delegation triggers",
+		mirrors: [{ surface: EXTENSION, includes: "honoring its mandatory delegation triggers" }],
+	},
+];
+
+// Condensed trigger rows that live only in the always-on core prompt; the
+// canonical RenderRouting block does not carry the incident or verification
+// rows, so they are mirror-only and not fixture-derived anchors.
+const CORE_ONLY_TRIGGERS = [
+	"**Incident rule** — diagnose wrong cwd/worktree/git/tooling incidents separately",
+	"**Verification rule** — executing/delegating verification commands",
+] as const;
+
+function fixtureBody(): string {
+	assert.ok(
+		existsSync(FIXTURE_PATH),
+		`missing canonical fixture ${ODD_ROUTING_FIXTURE_RELATIVE}; regenerate it with \`npm run mirror:odd-routing\``,
+	);
+	return parseOddRoutingFixture(readRepo(FIXTURE_PATH)).body;
+}
+
+// ---------------------------------------------------------------------------
+// 1 — Fixture provenance readback
+// ---------------------------------------------------------------------------
+
+test("the canonical routing fixture exists with managed provenance (source repo, commit, digest)", () => {
+	assert.ok(
+		existsSync(FIXTURE_PATH),
+		`missing canonical fixture ${ODD_ROUTING_FIXTURE_RELATIVE}; regenerate it with \`npm run mirror:odd-routing\``,
+	);
+	const { header } = parseOddRoutingFixture(readRepo(FIXTURE_PATH));
+	assert.equal(header.source_repo, ODD_ROUTING_SOURCE_REPO);
+	assert.equal(header.source_path, ODD_ROUTING_SOURCE_PATH);
+	assert.match(header.source_commit ?? "", /^[0-9a-f]{40}$/, "fixture must record the gentle-ai source commit");
+	assert.match(header.generated_at ?? "", /^\d{4}-\d{2}-\d{2}T/, "fixture must record a generation date");
+	assert.match(header.block_sha256 ?? "", /^[0-9a-f]{64}$/, "fixture must record the block body digest");
+});
+
+test("the fixture digest matches its block body byte-for-byte", () => {
+	const { header, body } = parseOddRoutingFixture(readRepo(FIXTURE_PATH));
+	assert.equal(header.block_sha256, sha256Hex(body), "the fixture body was hand-edited without regenerating its digest");
+});
+
+// ---------------------------------------------------------------------------
+// 2 — Canonical fixture carries every mandatory anchor
+// ---------------------------------------------------------------------------
+
+test("the canonical fixture carries every mandatory-delegation anchor", () => {
+	const body = fixtureBody();
+	for (const anchor of ANCHORS) {
+		assert.ok(body.includes(anchor.canonical), `canonical fixture dropped anchor: ${anchor.label}`);
+	}
+});
+
+// ---------------------------------------------------------------------------
+// 3 — Every pi mirror surface carries the mapped anchor
+// ---------------------------------------------------------------------------
+
+test("the pi mirror surfaces carry every mapped mandatory-delegation anchor", () => {
+	const surfaces: Record<string, string> = {
+		[DELEGATION]: readRepo(DELEGATION_PATH),
+		[CORE]: readRepo(CORE_PATH),
+		[EXTENSION]: readRepo(EXTENSION_PATH),
+	};
+	for (const anchor of ANCHORS) {
+		for (const mirror of anchor.mirrors) {
+			const text = surfaces[mirror.surface];
+			assert.ok(text !== undefined, `unknown mirror surface ${mirror.surface}`);
+			assert.ok(
+				text.includes(mirror.includes),
+				`${mirror.surface} is missing the mirror of "${anchor.label}": ${JSON.stringify(mirror.includes)}`,
+			);
+		}
+	}
+});
+
+test("the always-on core prompt carries the condensed incident and verification trigger rows", () => {
+	const core = readRepo(CORE_PATH);
+	for (const row of CORE_ONLY_TRIGGERS) {
+		assert.ok(core.includes(row), `assets/orchestrator.md is missing condensed trigger row: ${JSON.stringify(row)}`);
+	}
+});
+
+// ---------------------------------------------------------------------------
+// 4 — Regeneration provenance: idempotent and fail-closed
+// ---------------------------------------------------------------------------
+
+// The fixture header claims provenance from the source commit, so regeneration
+// must be byte-reproducible: the same gentle-ai commit must not produce a
+// date-only diff. `generated_at` therefore tracks the source commit's committer
+// date instead of wall-clock time.
+test("fixture rendering is idempotent and derives generated_at from the source commit", () => {
+	const sourceCommit = "e7729359fd9d6cb691ed2a88e8f72b1372f7c92e";
+	const committerDate = "2026-09-18T13:49:03+02:00";
+	const fakeGit = (args: readonly string[]): string => {
+		switch (args[0]) {
+			case "status":
+				return "";
+			case "rev-parse":
+				return `${sourceCommit}\n`;
+			case "show":
+				return `${committerDate}\n`;
+			default:
+				throw new Error(`unexpected git invocation: ${args.join(" ")}`);
+		}
+	};
+	const block = `${ODD_ROUTING_BLOCK_PREFIX}\n\n- a canonical clause\n`;
+	const first = renderOddRoutingFixture(block, resolveOddRoutingProvenance("/fake/gentle-ai", fakeGit));
+	const second = renderOddRoutingFixture(block, resolveOddRoutingProvenance("/fake/gentle-ai", fakeGit));
+	assert.equal(first, second, "rendering the same source commit twice must be byte-identical");
+	const { header } = parseOddRoutingFixture(first);
+	assert.equal(header.source_commit, sourceCommit);
+	assert.equal(
+		header.generated_at,
+		committerDate,
+		"generated_at must track the source commit's committer date, not wall-clock time",
+	);
+});
+
+// A dirty checkout would render uncommitted content under the committed
+// provenance claim, so the mirror fails closed before rendering and names the
+// tracked paths. Untracked files (the odd/tasks notes) must never block.
+test("the mirror fails closed on a dirty source checkout and names the tracked paths", () => {
+	const recordedCalls: string[][] = [];
+	const cleanGit = (args: readonly string[]): string => {
+		recordedCalls.push([...args]);
+		switch (args[0]) {
+			case "status":
+				return "";
+			case "rev-parse":
+				return `${"a".repeat(40)}\n`;
+			case "show":
+				return "2026-09-18T13:49:03+02:00\n";
+			default:
+				throw new Error(`unexpected git invocation: ${args.join(" ")}`);
+		}
+	};
+	resolveOddRoutingProvenance("/fake/gentle-ai", cleanGit);
+	assert.deepEqual(
+		recordedCalls.find((args) => args[0] === "status"),
+		["status", "--porcelain", "--untracked-files=no"],
+		"the dirty guard must ignore untracked files",
+	);
+
+	assert.doesNotThrow(() => assertCleanGentleAiCheckout(""));
+	const dirtyGit = (args: readonly string[]): string => {
+		if (args[0] === "status") {
+			return " M internal/components/agentguidance/routing.go\n M scripts/other.mjs\n";
+		}
+		throw new Error(`unexpected git invocation: ${args.join(" ")}`);
+	};
+	assert.throws(
+		() => resolveOddRoutingProvenance("/fake/gentle-ai", dirtyGit),
+		(error: unknown) => {
+			assert.ok(error instanceof Error);
+			assert.match(
+				error.message,
+				/gentle-ai checkout is dirty; provenance would be unverifiable: internal\/components\/agentguidance\/routing\.go, scripts\/other\.mjs\. Commit or stash first\./,
+			);
+			return true;
+		},
+	);
+});

package/tests/odd-routing-contract.test.ts

@@ -204,6 +204,63 @@ test("ODD forwards configured TDD without equating test presence with enablement
 	assert.doesNotMatch(wrapper, /If tests exist, use strict TDD/);
 });
 
+test("mandatory delegation triggers are behavioral in the lazy canonical port and the always-on ODD step", () => {
+	for (const clause of [
+		"These triggers are mandatory, not advisory.",
+		"stop and delegate through the runtime's subagent mechanism before continuing",
+		"executing past a fired trigger inline is a routing defect even if the work succeeds",
+		"**Mapping trigger",
+		"**Writer trigger",
+		"**Preparation trigger:**",
+		"**Long-session backstop",
+		"pause and delegate the next bounded unit of work",
+		"**Route declaration:**",
+		"record the chosen route per task",
+		"so skipped delegation is observable instead of silent",
+		"These triggers never select SDD and never create SDD artifacts",
+	]) {
+		assert.ok(delegation.includes(clause), `lazy canonical port is missing mandatory delegation clause: ${clause}`);
+	}
+	assert.ok(
+		wrapper.includes("honoring its mandatory delegation triggers"),
+		"the always-on ODD step 6 must honor its mandatory delegation triggers",
+	);
+	assert.ok(
+		wrapper.includes("executing past a fired trigger inline is a routing defect"),
+		"the always-on ODD protocol must state that skipping a fired trigger is a routing defect",
+	);
+});
+
+test("core and lazy canonical trigger lists agree in numbering and semantics", () => {
+	for (const entry of [
+		"1. **4-file rule**",
+		"2. **Multi-file write rule**",
+		"3. **Incident rule**",
+		"4. **Long-session rule**",
+		"5. **Verification rule**",
+	]) {
+		assert.ok(core.includes(entry), `always-on core trigger list is missing: ${entry}`);
+	}
+	for (const entry of [
+		"1. **Mapping trigger (4-file rule):**",
+		"2. **Writer trigger (Multi-file write rule):**",
+		"3. **Incident rule:**",
+		"4. **Long-session backstop (Long-session rule):**",
+		"5. **Verification rule**",
+	]) {
+		assert.ok(delegation.includes(entry), `lazy canonical trigger list is missing: ${entry}`);
+	}
+	for (const stale of [
+		"**Bounded read rule**",
+		"**Write rule**",
+		"**Context rule**",
+		"**Per-action rule**",
+		"**Optional SDD rule**",
+	]) {
+		assert.ok(!delegation.includes(stale), `reconciled canonical list retains stale trigger framing: ${stale}`);
+	}
+});
+
 test("ODD protocol is always-on in the rendered system prompt and runs by default", () => {
 	const orderedClauses = [
 		"Default workflow: Organic Driven Development (MANDATORY)",

package/tests/opaque-pi-reviewer-adapter.test.ts

@@ -8,6 +8,7 @@ import {
 	OPAQUE_PI_REVIEWER_ARGV,
 	OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE,
 	OpaquePiReviewerTransportError,
+	extractPiAssistantText,
 	resolvePiLaunch,
 	runOpaquePiReviewer,
 } from "../lib/opaque-pi-reviewer-adapter.ts";
@@ -43,10 +44,12 @@ const PROMPT_BYTES = Buffer.concat([
 	Buffer.from("opaque prompt\r\n\u0000", "utf8"),
 	Buffer.from([0x01, 0xff, 0xfe, 0x00]),
 ]);
-const OUTPUT_BYTES = Buffer.concat([
-	Buffer.from("opaque output\r\n\u0000", "utf8"),
-	Buffer.from([0x07, 0xff, 0xfe, 0x00]),
-]);
+const DEFAULT_OUTPUT_TEXT = "opaque output\r\n\u03b5 \u2014 unicode stays intact\n";
+
+const OUTPUT_BYTES = piEventStream(
+	...userTurn("opaque prompt"),
+	...assistantTurn([{ type: "text", text: DEFAULT_OUTPUT_TEXT }]),
+);
 
 interface OpaqueHarness {
 	directory: string;
@@ -94,6 +97,34 @@ function readLog(path: string): OpaquePiLog[] {
 		.map((line) => JSON.parse(line) as OpaquePiLog);
 }
 
+// The reviewer child runs `pi --mode json`, so its stdout is a newline-
+// delimited pi event stream. These helpers build the minimal stream shapes the
+// extraction has to understand, including the shapes behind the empty-output
+// field reports (#1140: a reviewer that answers with a tool call writes zero
+// usable bytes in text mode and exits 0 in silence).
+function piEventStream(...events: readonly unknown[]): Buffer {
+	return Buffer.from(events.map((event) => JSON.stringify(event)).join("\n") + "\n", "utf8");
+}
+
+function userTurn(text: string): unknown[] {
+	const message = { role: "user", content: [{ type: "text", text }] };
+	return [
+		{ type: "message_start", message },
+		{ type: "message_end", message },
+	];
+}
+
+function assistantTurn(parts: readonly Record<string, unknown>[], reviewerModel?: string): unknown[] {
+	const content = parts.map((part) => ({ ...part }));
+	const message: Record<string, unknown> = { role: "assistant", content };
+	if (reviewerModel !== undefined) message.model = reviewerModel;
+	return [
+		{ type: "message_start", message },
+		{ type: "message_end", message },
+		{ type: "agent_end", messages: [message] },
+	];
+}
+
 async function rejectsWithTransportError(
 	promise: Promise<unknown>,
 	kind: (typeof OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE)[keyof typeof OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE],
@@ -107,8 +138,22 @@ async function rejectsWithTransportError(
 	return caught!;
 }
 
-test("the opaque adapter streams arbitrary prompt and stdout bytes verbatim through the fixed Pi subprocess", async (t) => {
-	const fixture = harness(t);
+// #1140/#1156: the child runs `pi --mode json` and the transport emits the
+// final assistant text of that event stream. The prompt side stays byte-
+// verbatim; the output side is pi's own envelope, so a silent or unintelligible
+// run becomes a typed, evidenced failure instead of zero bytes and exit 0.
+const OUTPUT_TEXT = "opaque output\r\n\u03b5 \u2014 unicode stays intact\nsecond assistant text part";
+
+function eventStreamFor(text: string): Buffer {
+	return piEventStream(
+		...userTurn("opaque prompt"),
+		...assistantTurn([{ type: "text", text }], "pi-test-model"),
+		{ type: "agent_settled" },
+	);
+}
+
+test("the opaque adapter streams the prompt verbatim and emits the pi event stream's final assistant text", async (t) => {
+	const fixture = harness(t, { OPAQUE_PI_OUTPUT_B64: eventStreamFor(OUTPUT_TEXT).toString("base64") });
 	const result = await runOpaquePiReviewer(PROMPT_BYTES, {
 		piExecutable: fixture.pi,
 		environment: fixture.environment,
@@ -116,8 +161,8 @@ test("the opaque adapter streams arbitrary prompt and stdout bytes verbatim thro
 	});
 
 	assert.equal(result.promptByteLength, PROMPT_BYTES.length);
-	assert.equal(result.stdoutByteLength, OUTPUT_BYTES.length);
-	assert.deepEqual(result.stdout, OUTPUT_BYTES);
+	assert.equal(result.stdoutByteLength, Buffer.byteLength(OUTPUT_TEXT));
+	assert.deepEqual(result.stdout, Buffer.from(OUTPUT_TEXT, "utf8"));
 	assert.deepEqual(readFileSync(fixture.stdinCapturePath), PROMPT_BYTES);
 
 	const calls = readLog(fixture.logPath);
@@ -129,6 +174,100 @@ test("the opaque adapter streams arbitrary prompt and stdout bytes verbatim thro
 	assert.equal(existsSync(calls[0]!.cwd), false, "the empty scratch directory is removed after success");
 });
 
+test("the extraction mirrors the pi event stream: every assistant text part in order, nothing else", () => {
+	const streamed = piEventStream(
+		...userTurn("prompt"),
+		...assistantTurn([{ type: "thinking", thinking: "hidden" }, { type: "text", text: "first " }], "pi-a"),
+		...assistantTurn([{ type: "text", text: "second" }], "pi-b"),
+	);
+	const extracted = extractPiAssistantText(streamed);
+	assert.equal(extracted.kind, "text");
+	if (extracted.kind === "text") assert.equal(extracted.text, "first second");
+
+	const single = extractPiAssistantText(eventStreamFor("{\"findings\": []}"));
+	assert.equal(single.kind, "text");
+	if (single.kind === "text") assert.equal(single.text, "{\"findings\": []}");
+
+	// A stream pi could not have produced is not silently passed through.
+	assert.equal(extractPiAssistantText(Buffer.from("garbage, not an event stream", "utf8")).kind, "none");
+	assert.equal(extractPiAssistantText(Buffer.alloc(0)).kind, "none");
+});
+
+test("a silent or unintelligible reviewer run fails typed with the evidence the event stream carries", async (t) => {
+	const fixture = harness(t);
+
+	const silent = await rejectsWithTransportError(
+		runOpaquePiReviewer(PROMPT_BYTES, { piExecutable: fixture.pi, environment: { ...fixture.environment, OPAQUE_PI_MODE: "empty" }, timeoutMs: 10_000 }),
+		OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.EMPTY_OUTPUT,
+	);
+	assert.equal(silent.evidence?.stdoutKind, "no-output");
+
+	const unintelligible = await rejectsWithTransportError(
+		runOpaquePiReviewer(PROMPT_BYTES, { piExecutable: fixture.pi, environment: { ...fixture.environment, OPAQUE_PI_OUTPUT_B64: Buffer.from("not json at all", "utf8").toString("base64") }, timeoutMs: 10_000 }),
+		OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.EMPTY_OUTPUT,
+	);
+	assert.equal(unintelligible.evidence?.stdoutKind, "not-a-pi-event-stream");
+	assert.match(unintelligible.message, /no assistant text|not a pi event stream|no output/i);
+
+	const textless = await rejectsWithTransportError(
+		runOpaquePiReviewer(PROMPT_BYTES, { piExecutable: fixture.pi, environment: { ...fixture.environment, OPAQUE_PI_OUTPUT_B64: piEventStream(...userTurn("prompt"), { type: "agent_settled" }).toString("base64") }, timeoutMs: 10_000 }),
+		OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.EMPTY_OUTPUT,
+	);
+	assert.equal(textless.evidence?.stdoutKind, "no-assistant-text");
+});
+
+test("a reviewer run that spent its turn on a tool call reports that in the evidence instead of vanishing", async (t) => {
+	const fixture = harness(t, {
+		OPAQUE_PI_OUTPUT_B64: piEventStream(
+			...userTurn("prompt"),
+			...assistantTurn([{ type: "toolCall", id: "call_1", name: "bash" }], "nan/deepseek-v4-flash"),
+		).toString("base64"),
+	});
+	const error = await rejectsWithTransportError(
+		runOpaquePiReviewer(PROMPT_BYTES, { piExecutable: fixture.pi, environment: fixture.environment, timeoutMs: 10_000 }),
+		OPAQUE_PI_REVIEWER_TRANSPORT_FAILURE.EMPTY_OUTPUT,
+	);
+	assert.equal(error.evidence?.stdoutKind, "no-assistant-text");
+	assert.equal(error.evidence?.toolCallAttempted, true);
+	assert.equal(error.evidence?.reviewerModel, "nan/deepseek-v4-flash");
+	assert.match(error.message, /tool call/i);
+	assert.match(error.message, /nan\/deepseek-v4-flash/);
+});
+
+test("a tool-call attempt followed by text still yields the text", async (t) => {
+	const fixture = harness(t, {
+		OPAQUE_PI_OUTPUT_B64: piEventStream(
+			...userTurn("prompt"),
+			...assistantTurn([{ type: "toolCall", id: "call_1", name: "bash" }]),
+			...assistantTurn([{ type: "text", text: "{\"verdict\": \"pass\"}" }], "nan/glm5.3-flash"),
+		).toString("base64"),
+	});
+	const result = await runOpaquePiReviewer(PROMPT_BYTES, { piExecutable: fixture.pi, environment: fixture.environment, timeoutMs: 10_000 });
+	assert.deepEqual(result.stdout, Buffer.from("{\"verdict\": \"pass\"}", "utf8"));
+});
+
+test("caller-owned launch arguments ride the frozen argv verbatim and are validated before spawn", async (t) => {
+	const fixture = harness(t, { OPAQUE_PI_OUTPUT_B64: eventStreamFor("ok").toString("base64") });
+	await runOpaquePiReviewer(PROMPT_BYTES, {
+		piExecutable: fixture.pi,
+		environment: fixture.environment,
+		timeoutMs: 10_000,
+		extraArguments: ["--model", "nan/glm5.3-flash", "-e", "/abs/auth-adapter.ts"],
+	});
+	const calls = readLog(fixture.logPath);
+	assert.equal(calls.length, 1);
+	assert.deepEqual(calls[0]!.argv, [...OPAQUE_PI_REVIEWER_ARGV, "--model", "nan/glm5.3-flash", "-e", "/abs/auth-adapter.ts"]);
+
+	await assert.rejects(
+		runOpaquePiReviewer(PROMPT_BYTES, { piExecutable: fixture.pi, environment: fixture.environment, timeoutMs: 10_000, extraArguments: ["--model", ""] }),
+		/non-empty/,
+	);
+	await assert.rejects(
+		runOpaquePiReviewer(PROMPT_BYTES, { piExecutable: fixture.pi, environment: fixture.environment, timeoutMs: 10_000, extraArguments: [42 as unknown as string] }),
+		/non-empty/,
+	);
+});
+
 test("the opaque adapter returns typed transport errors for launch, nonzero, empty, timeout, and cancellation", async (t) => {
 	const fixture = harness(t);
 	await rejectsWithTransportError(
@@ -228,8 +367,13 @@ test("the opaque adapter has no review lifecycle imports or identifiers", () =>
 	const adapterPath = fileURLToPath(new URL("../lib/opaque-pi-reviewer-adapter.ts", import.meta.url));
 	const source = readFileSync(adapterPath, "utf8");
 	assert.doesNotMatch(source, /review-integration|gentle-ai|materialize|submit/i);
+	// The guard reads source, not strings: the one lifecycle-shaped word the
+	// transport may spell is pi's own quoted wire key for the selection the
+	// child reports in its events (#1140). It is data there, never an
+	// identifier, so it is stripped before the scan.
+	const withoutWireKeys = source.replaceAll('"model"', '""');
 	for (const identifier of ["lineage", "target", "revision", "receipt", "lens", "order", "subject", "schema", "capture", "submission", "status", "model", "provider", "profile"]) {
-		assert.doesNotMatch(source, new RegExp(`\\b${identifier}\\b`, "i"), `adapter must not contain lifecycle identifier ${identifier}`);
+		assert.doesNotMatch(withoutWireKeys, new RegExp(`\\b${identifier}\\b`, "i"), `adapter must not contain lifecycle identifier ${identifier}`);
 	}
 });
 

package/tests/package-manifest.test.ts

@@ -309,20 +309,20 @@ test("package manifest installs pi-pretty through a wrapper without bundling nat
 	);
 });
 
-test("package verification binds the published Gentle AI v3.1.0 runtime pin", () => {
+test("package verification binds the published Gentle AI v3.2.1 runtime pin", () => {
 	const installer = readFileSync(join(PACKAGE_ROOT, "scripts", "gentle-ai-installer.mjs"), "utf8");
 	const binary = readFileSync(join(PACKAGE_ROOT, "lib", "gentle-ai-binary.ts"), "utf8");
 	const verifier = readFileSync(join(PACKAGE_ROOT, "scripts", "verify-package-files.mjs"), "utf8");
 
-	assert.match(installer, /INSTALLER_VERSION = "3\.1\.0"/);
+	assert.match(installer, /INSTALLER_VERSION = "3\.2\.1"/);
 	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_PACKAGE.*GENTLE_AI_WINDOWS_SOURCE_MODULE/);
-	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:CrZlui5N8\/RSmxvn\/7usKe6q1EvRt7y6dyfEwjstmJw="/);
+	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:0QFo0ERv8\/3lgTepEG0E\/P7yD9qXXCx2M7ppQviVHMo="/);
 	assert.match(installer, /GOTOOLCHAIN: "local"/);
 	assert.match(installer, /GOSUMDB: "sum\.golang\.org"/);
 	assert.match(binary, /GENTLE_AI_VERSION = INSTALLER_VERSION/);
 	assert.match(binary, /GO_SUMDB_SOURCE_BUILD/);
 	assert.match(binary, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM/);
-	assert.match(verifier, /v3\.1\.0/);
+	assert.match(verifier, /v3\.2\.1/);
 });
 
 
@@ -1574,9 +1574,9 @@ test("pi-pretty wrapper uses cached ESM loading for compiled and pnpm symlink in
 	assert.match(wrapper, /quietToolsEnabled/);
 });
 
-test("Gentle Shell v3.2.0 package and runtime stop before publication", () => {
+test("Gentle Shell v3.2.1 package and runtime stop before publication", () => {
 	const packageJson = readPackageJson();
-	assert.equal(packageJson.version, "3.2.0", "the release manifest must remain explicitly pinned to v3.2.0");
+	assert.equal(packageJson.version, "3.2.1", "the release manifest must remain explicitly pinned to v3.2.1");
 	assert.equal(
 		packageJson.scripts?.test,
 		"node --experimental-strip-types --test tests/*.test.ts && pnpm run check:provider-contract && pnpm run test:harness",