gentle-pi 2.4.0 → 2.6.0

package/tests/asset-installation-runtime.test.ts

@@ -0,0 +1,108 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+async function proveLazyDiscovery(): Promise<void> {
+	const {
+		createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices,
+		ModelRuntime, SessionManager, SettingsManager,
+	} = await import("@earendil-works/pi-coding-agent");
+	const cwd = process.cwd();
+	const agentDir = process.env.PI_CODING_AGENT_DIR!;
+	const shim = join(cwd, "extensions.ts");
+	const source = (name: string) => JSON.stringify(new URL(`../extensions/${name}.ts`, import.meta.url).href);
+	writeFileSync(shim, `
+import { createGentleAiExtension } from ${source("gentle-ai")};
+import gentleAgents from ${source("gentle-agents")};
+import sddInit from ${source("sdd-init")};
+export default function (pi) {
+  createGentleAiExtension({ nativeReviewCli: null, candidateViews: null, processEnv: {} })(pi);
+  gentleAgents(pi);
+  sddInit(pi);
+}
+`);
+	const modelRuntime = await ModelRuntime.create({
+		authPath: join(agentDir, "empty-auth.json"),
+		modelsPath: null,
+		modelsStorePath: join(agentDir, "models-store.json"),
+		allowModelNetwork: false,
+	});
+	const runtime = await createAgentSessionRuntime(async ({ cwd, sessionManager, sessionStartEvent }) => {
+		const services = await createAgentSessionServices({
+			cwd, agentDir, modelRuntime,
+			settingsManager: SettingsManager.inMemory({ retry: { enabled: false }, compaction: { enabled: false } }),
+			resourceLoaderOptions: {
+				noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true,
+				additionalExtensionPaths: [shim],
+			},
+		});
+		assert.deepEqual(services.resourceLoader.getExtensions().errors, []);
+		assert.deepEqual(services.diagnostics, []);
+		return {
+			...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent, tools: ["subagent_list_agents"] })),
+			services, diagnostics: services.diagnostics,
+		};
+	}, { cwd, agentDir, sessionManager: SessionManager.inMemory(cwd) });
+	try {
+		await runtime.session.bindExtensions({ mode: "print" });
+		const session = runtime.session;
+		const list = session.agent.state.tools.find(tool => tool.name === "subagent_list_agents");
+		assert.ok(list, "actual SDK must expose the wrapped discovery tool");
+		const names = async () => {
+			const result = await list.execute("asset-discovery", {});
+			return result.content.filter(part => part.type === "text").map(part => part.text).join("\n");
+		};
+		const before = await names();
+		assert.match(before, /- gentle-ai-explore \(global\)/);
+		assert.match(before, /- review-risk \(global\)/);
+		assert.doesNotMatch(before, /- sdd-/, "fresh startup must not install SDD definitions");
+		assert.equal(existsSync(join(agentDir, "chains", "sdd-full.chain.md")), false);
+		assert.equal(existsSync(join(agentDir, "gentle-ai", "support")), false);
+		await session.prompt("/gentle:install-sdd");
+		assert.strictEqual(runtime.session, session);
+		const after = await names();
+		for (const name of ["gentle-ai-explore", "review-risk", "sdd-init", "sdd-apply"]) {
+			assert.ok(after.includes(`- ${name} (global)`), `same-session discovery must include ${name}`);
+		}
+		for (const file of ["sdd-status-contract.md", "strict-tdd.md", "strict-tdd-verify.md"]) {
+			assert.ok(existsSync(join(agentDir, "gentle-ai", "support", file)), `missing support: ${file}`);
+		}
+		assert.ok(existsSync(join(agentDir, "chains", "sdd-full.chain.md")));
+		assert.equal(session.messages.length, 0, "slash activation must not start a model turn");
+		console.log("SDK discovery: delegation/review only -> /gentle:install-sdd -> same-session sdd-init/sdd-apply and support");
+	} finally {
+		await runtime.dispose();
+	}
+}
+
+if (process.env.GENTLE_PI_ASSET_PROOF_CHILD === "1") {
+	await proveLazyDiscovery();
+} else {
+	test("actual SDK discovers SDD only after explicit activation in the same session", () => {
+		const root = mkdtempSync(join(tmpdir(), "gentle-pi-assets-sdk-"));
+		try {
+			const home = join(root, "home");
+			const cwd = join(root, "project");
+			const agentDir = join(home, ".pi", "agent");
+			for (const path of [cwd, agentDir]) mkdirSync(path, { recursive: true });
+			const result = spawnSync(process.execPath, ["--experimental-strip-types", fileURLToPath(import.meta.url)], {
+				cwd, encoding: "utf8", timeout: 30_000,
+				env: {
+					PATH: `${dirname(process.execPath)}:/usr/bin:/bin`, HOME: home, TMPDIR: root,
+					PI_CODING_AGENT_DIR: agentDir, GENTLE_PI_AGENT_HOME: agentDir,
+					GENTLE_PI_CONFIG_HOME: join(home, "config"), XDG_CONFIG_HOME: join(home, ".config"),
+					PI_OFFLINE: "1", GENTLE_PI_ASSET_PROOF_CHILD: "1",
+				},
+			});
+			assert.ifError(result.error);
+			assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+			assert.match(result.stdout, /SDK discovery: delegation\/review only/);
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+}

package/tests/autonomous-guard.test.ts

@@ -5,7 +5,7 @@ import { dirname, join } from "node:path";
 import test from "node:test";
 import { __testing } from "../extensions/gentle-ai.ts";
 
-const { classifyGuardedCommand } = __testing;
+const { classifyGuardedCommand, evaluateGuardedCommand, guardedCommandPreview, guardedCommandTitle } = __testing;
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -129,6 +129,121 @@ test("classifyGuardedCommand: git push plain allowed when autonomousMode=true an
 	assert.equal(result, "allow");
 });
 
+test("classifyGuardedCommand: configured push allow is remote-agnostic and unchanged", () => {
+	const config = { autonomousMode: true, guardedCommands: { gitPush: "allow" as const } };
+	for (const command of [
+		"git push origin feature/test",
+		"git push upstream feature/test",
+		"git push fork feature/test",
+		"git push",
+		"git push feature/test && git status",
+		"echo done || git push origin feature/test",
+	]) {
+		assert.equal(classifyGuardedCommand(command, config), "allow", command);
+	}
+	assert.equal(
+		classifyGuardedCommand("git push origin feature/test", { autonomousMode: true, guardedCommands: { gitPush: "block" } }),
+		"block",
+	);
+	for (const command of [
+		"git push -f origin feature/test",
+		"git push --force origin main",
+		"git push --force-with-lease origin feature/test",
+	]) {
+		assert.equal(classifyGuardedCommand(command, config), "block", command);
+	}
+});
+
+// ---------------------------------------------------------------------------
+// Guarded command preview — presentation-only centering
+// ---------------------------------------------------------------------------
+
+test("guardedCommandPreview: long late matched action stays visible in preview", () => {
+	const prefix = "noise ".repeat(80);
+	const command = `${prefix}git push origin feature/test`;
+	// Contract: the caller owns the trigger index. confirmCommand hands over
+	// evaluation.triggerIndex, so the preview always centers on the matched
+	// action supplied by the evaluator.
+	const triggerIndex = command.indexOf("git push");
+	const preview = guardedCommandPreview(command, triggerIndex);
+	assert.match(preview, /git push origin feature\/test/);
+	assert.ok(preview.startsWith("…"), "preview elides leading context near a late match");
+});
+
+test("guardedCommandPreview: late non-push action visible, elided, and width-bounded", () => {
+	const prefix = "noise ".repeat(80);
+	const command = `${prefix}npm publish --tag beta`;
+	const triggerIndex = command.indexOf("npm publish");
+	const preview = guardedCommandPreview(command, triggerIndex);
+	assert.match(preview, /npm publish --tag beta/);
+	assert.ok(preview.startsWith("…"), "preview elides leading context near a late match");
+	// Bounded visible width: 1 leading ellipsis + up to 179 content chars (budget 180).
+	assert.ok(preview.length <= 180, `preview exceeds bounded width: ${preview.length}`);
+});
+
+// ---------------------------------------------------------------------------
+// Guarded command title — presentation-only, action-specific
+// ---------------------------------------------------------------------------
+
+test("guardedCommandTitle: exact action-specific titles per guarded key", () => {
+	assert.equal(guardedCommandTitle("gitPush"), "Allow guarded git push?");
+	assert.equal(guardedCommandTitle("gitRebase"), "Allow guarded git rebase?");
+	assert.equal(
+		guardedCommandTitle("gitBranchDeleteForce"),
+		"Allow guarded forced git branch deletion?",
+	);
+	assert.equal(guardedCommandTitle("npmPublish"), "Allow guarded npm publish?");
+	assert.equal(guardedCommandTitle("piRemove"), "Allow guarded pi remove?");
+});
+
+test("guardedCommandTitle: unkeyed guarded command falls back to generic title", () => {
+	assert.equal(guardedCommandTitle(undefined), "Allow guarded command?");
+});
+
+test("evaluateGuardedCommand: collects guarded matches in command order and applies full-command precedence", () => {
+	const command = "npm publish && git push origin main && git rebase main";
+	const evaluation = evaluateGuardedCommand(command, {
+		autonomousMode: true,
+		guardedCommands: { gitPush: "allow", gitRebase: "confirm", npmPublish: "block" },
+	});
+	assert.deepEqual(evaluation.matches.map((match) => [match.key, match.action]), [
+		["npmPublish", "block"],
+		["gitPush", "allow"],
+		["gitRebase", "confirm"],
+	]);
+	assert.deepEqual(evaluation.matches.map((match) => command.slice(match.triggerIndex).split(/\s/, 1)[0]), ["publish", "push", "rebase"]);
+	assert.equal(evaluation.action, "block");
+
+	assert.equal(evaluateGuardedCommand("git rebase main && git push --force origin main", {
+		autonomousMode: true,
+		guardedCommands: { gitRebase: "allow", gitPush: "allow" },
+	}).action, "block", "a later hard deny overrides an earlier allowed action");
+});
+
+test("evaluateGuardedCommand: git -C stores the push token offset for bounded previews", () => {
+	const command = `git -C /${"very-long-path/".repeat(30)} push origin main`;
+	const evaluation = evaluateGuardedCommand(command, { autonomousMode: false, guardedCommands: {} });
+	assert.equal(command.slice(evaluation.triggerIndex, evaluation.triggerIndex + 4), "push");
+	assert.match(guardedCommandPreview(command, evaluation.triggerIndex), /push origin main/);
+});
+
+test("evaluateGuardedCommand: git -C path containing push still offsets the push action", () => {
+	const command = `git -C /${"push-path/".repeat(30)} push origin main`;
+	const evaluation = evaluateGuardedCommand(command, { autonomousMode: false, guardedCommands: {} });
+	assert.equal(evaluation.triggerIndex, command.lastIndexOf("push"));
+	assert.match(guardedCommandPreview(command, evaluation.triggerIndex), /push origin main/);
+});
+
+test("evaluateGuardedCommand: repeated forced branch deletions remain separate matches", () => {
+	const command = "git branch --delete --force old && git branch --delete --force older";
+	const evaluation = evaluateGuardedCommand(command, { autonomousMode: false, guardedCommands: {} });
+	assert.deepEqual(evaluation.matches.map((match) => match.key), ["gitBranchDeleteForce", "gitBranchDeleteForce"]);
+	assert.equal(
+		guardedCommandTitle(evaluation.key, evaluation.matches),
+		"Allow guarded actions: forced git branch deletion; forced git branch deletion?",
+	);
+});
+
 test("classifyGuardedCommand: git push plain still confirm when autonomousMode=false even with gitPush=allow in config", () => {
 	const result = classifyGuardedCommand("git push origin feature/test", {
 		autonomousMode: false,

package/tests/codegraph-tools.test.ts

@@ -1,12 +1,14 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir, 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 codeGraphTools, {
 	createCodeGraphTool,
+	codeGraphNodeScript,
+	findCodeGraphNodeScriptOnPath,
 	type CodeGraphRunner,
 } from "../extensions/codegraph-tools.ts";
 
@@ -189,7 +191,7 @@ test("CodeGraph tool rejects incomplete or oversized query requests before runni
 });
 
 test("CodeGraph tool registration exposes a single constrained custom tool", () => {
-	const tools: Array<{ name: string; parameters: Record<string, unknown> }> = [];
+	const tools: Array<{ name: string; renderShell?: string; parameters: Record<string, unknown> }> = [];
 	const pi = {
 		registerTool(tool: { name: string; parameters: Record<string, unknown> }) {
 			tools.push(tool);
@@ -200,6 +202,7 @@ test("CodeGraph tool registration exposes a single constrained custom tool", ()
 
 	assert.equal(tools.length, 1);
 	assert.equal(tools[0]?.name, "codegraph");
+	assert.equal(tools[0]?.renderShell, "self", "CodeGraph must not inherit Pi's painted Box");
 	assert.deepEqual(tools[0]?.parameters, {
 		type: "object",
 		additionalProperties: false,
@@ -211,3 +214,110 @@ test("CodeGraph tool registration exposes a single constrained custom tool", ()
 		},
 	});
 });
+
+function writeCodeGraphPackage(binDir: string, scriptSource = "#!/usr/bin/env node\n"): string {
+	const pkgRoot = join(binDir, "node_modules", "@colbymchenry", "codegraph");
+	mkdirSync(pkgRoot, { recursive: true });
+	const scriptTarget = join(pkgRoot, "npm-shim.js");
+	writeFileSync(scriptTarget, scriptSource);
+	writeFileSync(
+		join(pkgRoot, "package.json"),
+		JSON.stringify({
+			name: "@colbymchenry/codegraph",
+			version: "1.0.0",
+			bin: { codegraph: "npm-shim.js" },
+		}),
+	);
+	writeFileSync(
+		join(binDir, "codegraph.cmd"),
+		"@ECHO off\nnode \"%~dp0\\node_modules\\@colbymchenry\\codegraph\\npm-shim.js\" %*\n",
+	);
+	return scriptTarget;
+}
+
+function withWindowsPath(t: test.TestContext, path: string): void {
+	const previousPath = process.env.PATH;
+	const previousWindowsPath = process.env.Path;
+	const windowsPath = process.platform === "win32"
+		? `${path};${previousWindowsPath ?? previousPath ?? ""}`
+		: path;
+	process.env.Path = windowsPath;
+	process.env.PATH = windowsPath;
+	t.after(() => {
+		if (previousPath === undefined) delete process.env.PATH;
+		else process.env.PATH = previousPath;
+		if (previousWindowsPath === undefined) delete process.env.Path;
+		else process.env.Path = previousWindowsPath;
+	});
+}
+
+test("Windows shim helpers skip stale PATH shims before resolving the npm script", (t) => {
+	const staleBinDir = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-stale-bin-")));
+	const validBinDir = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-valid-bin-")));
+	t.after(() => rmSync(staleBinDir, { recursive: true, force: true }));
+	t.after(() => rmSync(validBinDir, { recursive: true, force: true }));
+	writeFileSync(join(staleBinDir, "codegraph.cmd"), "@ECHO off\n");
+	const stalePkgRoot = join(staleBinDir, "node_modules", "@colbymchenry", "codegraph");
+	mkdirSync(stalePkgRoot, { recursive: true });
+	writeFileSync(join(stalePkgRoot, "package.json"), JSON.stringify({ bin: { codegraph: "." } }));
+	const scriptTarget = writeCodeGraphPackage(validBinDir);
+
+	withWindowsPath(t, `${staleBinDir};${validBinDir}`);
+
+	assert.equal(codeGraphNodeScript(join(staleBinDir, "codegraph.cmd")), undefined);
+	assert.equal(findCodeGraphNodeScriptOnPath(), scriptTarget);
+});
+
+test("Windows shim helpers resolve quoted PATH entries in order without stripping unmatched quotes", (t) => {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-quoted-bin-")));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const firstBin = join(root, "Program Files", "nodejs");
+	const secondBin = join(root, "other-bin");
+	const firstScript = writeCodeGraphPackage(firstBin);
+	const secondScript = writeCodeGraphPackage(secondBin);
+	withWindowsPath(t, `"${firstBin}";${secondBin}`);
+
+	assert.equal(findCodeGraphNodeScriptOnPath(), firstScript);
+	for (const [path, expected] of [
+		[`${firstBin};"${secondBin}"`, firstScript],
+		[`"${firstBin};${secondBin}`, secondScript],
+		[`${firstBin}";${secondBin}`, secondScript],
+		[`${secondBin};"${firstBin}"`, secondScript],
+	]) {
+		process.env.Path = path;
+		process.env.PATH = path;
+		assert.equal(findCodeGraphNodeScriptOnPath(), expected);
+	}
+});
+
+test("Windows launcher passes command metacharacters as one literal argv value", async (t) => {
+	const binDir = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-bin-")));
+	t.after(() => rmSync(binDir, { recursive: true, force: true }));
+	writeCodeGraphPackage(binDir, "process.stdout.write(JSON.stringify(process.argv.slice(2)));\n");
+	const cwd = workspace(t);
+	if (process.platform !== "win32") {
+		const gitShim = join(binDir, "git");
+		writeFileSync(gitShim, "#!/bin/sh\nprintf '%s\\n' \"$PWD\"\n");
+		chmodSync(gitShim, 0o755);
+	}
+	withWindowsPath(t, binDir);
+
+	const previousPlatform = process.platform;
+	Object.defineProperty(process, "platform", { configurable: true, value: "win32" });
+	t.after(() => Object.defineProperty(process, "platform", { configurable: true, value: previousPlatform }));
+
+	const query = "literal & echo injected > shell-injection.txt";
+	const result = await createCodeGraphTool().execute(
+		"test",
+		{ operation: "query", query },
+		undefined,
+		undefined,
+		{ cwd } as ExtensionContext,
+	);
+
+	assert.deepEqual(result.content, [{
+		type: "text",
+		text: JSON.stringify(["query", "--path", cwd, "--limit", "10", "--", query]),
+	}]);
+	assert.equal(existsSync(join(cwd, "shell-injection.txt")), false);
+});

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

@@ -92,7 +92,7 @@ test("SDD executor coverage is exhaustive against actual agent files", () => {
 	// the allowlist matches reality so coverage cannot silently drift.
 	const expected = [
 		"sdd-apply.md", "sdd-archive.md", "sdd-design.md", "sdd-explore.md",
-		"sdd-init.md", "sdd-onboard.md", "sdd-proposal.md", "sdd-research.md",
+		"sdd-init.md", "sdd-onboard.md", "sdd-proposal.md", "sdd-remediate.md", "sdd-research.md",
 		"sdd-spec.md", "sdd-status.md", "sdd-sync.md", "sdd-tasks.md",
 		"sdd-verify.md",
 	];

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

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import { __testing } from "../../extensions/gentle-ai.ts";
+import { CandidateViewRegistry } from "../../lib/review-candidate-view.ts";
 import {
 	NATIVE_REVIEW_ERROR_CODE,
 	NativeReviewCliError,
@@ -13,6 +14,7 @@ import {
 	createNodeExecFileAdapter,
 	type ExecFileAdapter,
 } from "../../lib/native-review-cli.ts";
+import type { ReviewStatusV3 } from "../../lib/review-integration-v2.ts";
 import { requireDevBinary } from "../support/native-binary-gate.ts";
 
 // Organic RDD Parity: candidate-bound dev-binary journeys.
@@ -43,6 +45,35 @@ function bridgeAdapter(binary: string, calls: NativeCall[]): ExecFileAdapter {
 	};
 }
 
+function selectedStatusFieldNames(stdout: string): string {
+	try {
+		const status = JSON.parse(stdout) as Record<string, unknown>;
+		const projection = status.projection as Record<string, unknown> | undefined;
+		const transition = status.next_transition as Record<string, unknown> | undefined;
+		const execute = transition?.execute as Record<string, unknown> | undefined;
+		const argument = Array.isArray(execute?.arguments) ? execute.arguments[0] as Record<string, unknown> | undefined : undefined;
+		const names = (prefix: string, value?: Record<string, unknown>) => value === undefined ? [] : Object.keys(value).sort().map((key) => `${prefix}.${key}`);
+		return [...names("status", status), ...names("status.projection", projection), ...names("status.next_transition", transition), ...names("status.next_transition.execute", execute), ...names("status.next_transition.execute.arguments[]", argument)].join(", ");
+	} catch {
+		return "status JSON";
+	}
+}
+
+function controllerResultStructure(result: Record<string, unknown>): string {
+	const diagnostics = typeof result.diagnostics === "object" && result.diagnostics !== null && !Array.isArray(result.diagnostics)
+		? result.diagnostics as Record<string, unknown>
+		: undefined;
+	const safeCode = (name: string, value: unknown) => typeof value === "string" && /^[a-z0-9][a-z0-9._-]*$/.test(value) ? `${name}=${value}` : undefined;
+	const safeBooleanNames = ["candidate_view_created", "candidate_view_pre_native", "native_invocation_attempted", "lineage_created", "mutation_performed", "reset_eligible"];
+	return [
+		`keys=[${Object.keys(result).sort().join(",")}]`,
+		...(diagnostics === undefined ? [] : [`diagnostics.keys=[${Object.keys(diagnostics).sort().join(",")}]`]),
+		safeCode("operation", result.operation), safeCode("status", result.status), safeCode("outcome", result.outcome), safeCode("reason", result.reason),
+		safeCode("diagnostics.error_code", diagnostics?.error_code), safeCode("diagnostics.code", diagnostics?.code), safeCode("diagnostics.reason", diagnostics?.reason),
+		...safeBooleanNames.flatMap((name) => typeof result[name] === "boolean" ? [`${name}=${String(result[name])}`] : []),
+	].filter((value): value is string => value !== undefined).join("; ");
+}
+
 function journeyNative(binary: string): { native: NativeReviewCliV216; calls: NativeCall[] } {
 	const calls: NativeCall[] = [];
 	return { native: new NativeReviewCliV216(bridgeAdapter(binary, calls), binary), calls };
@@ -202,6 +233,85 @@ test("dev-binary: an empty candidate exposes the current STATUS refusal and neve
 	assert.equal(calls.filter((arguments_) => arguments_.at(0) === "review" && arguments_.at(1) === "start").length, 0);
 });
 
+test("dev-binary: v7 intended-untracked selection decodes both selected statuses before START", { skip: !RUNNABLE }, async (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "app.ts"), "export const value = 1;\n");
+	git(cwd, "add", "app.ts");
+	git(cwd, "commit", "-qm", "test: base candidate");
+	writeFileSync(join(cwd, "app.ts"), "export const value = 2;\n");
+	writeFileSync(join(cwd, "chosen.md"), "# Chosen\n");
+
+	const calls: NativeCall[] = [], selectedWireFields: string[] = [];
+	let interceptedStarts = 0;
+	let delegatedStarts = 0;
+	const startIntercept = new Error("test-only native START intercept");
+	const real = createNodeExecFileAdapter();
+	const adapter: ExecFileAdapter = async (request) => {
+		calls.push([...request.arguments]);
+		if (request.arguments.at(0) === "review" && request.arguments.at(1) === "start") {
+			interceptedStarts += 1;
+			throw startIntercept;
+		}
+		if (request.arguments.at(0) === "review" && request.arguments.at(1) === "start") delegatedStarts += 1;
+		const result = await real({ ...request, file: DEV_BINARY! });
+		if (request.arguments.some((argument) => argument.startsWith("--intended-untracked-selection="))) selectedWireFields.push(selectedStatusFieldNames(result.stdout));
+		return result;
+	};
+	const native = new NativeReviewCliV216(adapter, DEV_BINARY!);
+	const targetStatus = native.targetStatus.bind(native);
+	const selectedStatuses: ReviewStatusV3[] = [];
+	const selectedFailures: Array<{ call: number; code: string }> = [];
+	let selectedStatusCalls = 0;
+	native.targetStatus = async (request) => {
+		if (request.intendedUntrackedSelection === undefined) return targetStatus(request);
+		selectedStatusCalls += 1;
+		try {
+			const status = await targetStatus(request);
+			selectedStatuses.push(status);
+			return status;
+		} catch (error) {
+			selectedFailures.push({ call: selectedStatusCalls, code: error instanceof NativeReviewCliError ? error.code : "unexpected-error" });
+			throw error;
+		}
+	};
+
+	const candidateViews = new CandidateViewRegistry(), retainedSelections = new Map();
+	await enableReview(native, cwd);
+	const initial = await __testing.executeReviewControllerOperation({ operation: "status" }, cwd, native, undefined, candidateViews, undefined, retainedSelections);
+	assert.equal((initial.result as Record<string, unknown> | undefined)?.schema, "gentle-ai.review-integration.status/v7", "initial status.schema");
+	assert.equal(typeof initial.selectionBinding, "string", "initial selectionBinding");
+	const result = await __testing.executeReviewControllerOperation({ operation: "select-intended-untracked", selectionBinding: initial.selectionBinding as string, intendedUntracked: ["chosen.md"] } as never, cwd, native, undefined, candidateViews, undefined, retainedSelections);
+
+	if (selectedStatusCalls !== 2) assert.fail(`intended-selection STATUS call count=${selectedStatusCalls}; ${controllerResultStructure(result)}`);
+	if (selectedFailures.length > 0) {
+		const failure = selectedFailures[0]!;
+		assert.fail(`selected STATUS call ${failure.call} decode failed at fields: ${selectedWireFields[failure.call - 1] ?? "status"}; error=${failure.code}`);
+	}
+	assert.equal(selectedStatusCalls, 2, "intended-selection STATUS call count");
+	assert.equal(selectedStatuses.length, 2, "decoded intended-selection STATUS count");
+	for (const [index, status] of selectedStatuses.entries()) {
+		assert.equal(status.raw.schema, "gentle-ai.review-integration.status/v7", `selected STATUS call ${index + 1} status.schema`);
+		assert.deepEqual(status.projection.intendedUntracked, ["chosen.md"], `selected STATUS call ${index + 1} status.projection.intended_untracked`);
+		assert.equal(status.nextTransition?.kind, "execute", `selected STATUS call ${index + 1} status.next_transition.kind`);
+		assert.equal(status.nextTransition?.execute?.operation, "review.start", `selected STATUS call ${index + 1} status.next_transition.execute.operation`);
+		assert.ok((status.nextTransition?.execute?.arguments.length ?? 0) > 0, `selected STATUS call ${index + 1} status.next_transition.execute.arguments`);
+		assert.equal(status.nextTransition?.execute?.arguments.every((argument) => typeof argument.token === "string" && argument.token.length > 0), true, `selected STATUS call ${index + 1} status.next_transition.execute.arguments[].token`);
+	}
+	assert.equal(interceptedStarts, 1, "adapter must intercept the one native review.start attempt");
+	assert.equal(delegatedStarts, 0, "intercepted native START must not reach the real adapter");
+	assert.equal(calls.filter((arguments_) => arguments_.at(0) === "review" && arguments_.at(1) === "start").length, 1, "native review.start adapter attempt count");
+	assert.equal(result.outcome, "native-mutation-status-reconciled", "controller result after intentional START intercept");
+	assert.equal("lineage_id" in result, false, "intercepted START must report no lineage binding");
+	assert.equal("authority" in result, false, "intercepted START must report no authority binding");
+	assert.equal("lineage_created" in result, false, "reconciled unknown mutation must not claim lineage creation");
+	assert.equal("mutation_performed" in result, false, "reconciled unknown mutation must not claim a mutation result");
+	assert.equal(result.mutation_outcome, "unknown", "the controller cannot prove mutation status after an intercepted launch");
+	assert.match(String(result.required_status_action), /Run target-scoped review\.status/, "ambiguous START must retain its executable-safe STATUS instruction");
+	assert.equal(result.next_action, "start", "the reconciled provider action remains visible without authoring a replay");
+	const after = await native.targetStatus({ cwd, agent: "pi" });
+	assert.equal(after.authority, undefined, "post-intercept STATUS must not expose authority");
+});
+
 test("dev-binary: a low-risk START closes the review with no receipt or follow-up capture", { skip: !RUNNABLE }, async (t) => {
 	const cwd = repository(t);
 	writeFileSync(join(cwd, "guide.md"), "# Guide\n\nBase\n");

package/tests/feature-request-form.test.ts

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import test from "node:test";
+
+// Reuse Pi's existing YAML dependency without adding a package dependency.
+const piRequire = createRequire(import.meta.resolve("@earendil-works/pi-coding-agent"));
+const { parseDocument } = piRequire("yaml");
+const formUrl = new URL("../.github/ISSUE_TEMPLATE/feature_request.yml", import.meta.url);
+
+function readForm() {
+	const document = parseDocument(readFileSync(formUrl, "utf8"), { uniqueKeys: true });
+	assert.deepEqual(document.errors, [], "the issue form must be valid, unambiguous YAML");
+	return document.toJS();
+}
+
+test("feature request form has supported structure and only intake labels", () => {
+	const form = readForm();
+	assert.deepEqual(Object.keys(form).sort(), ["body", "description", "labels", "name"]);
+	assert.equal(form.name, "Feature Request");
+	assert.equal(typeof form.description, "string");
+	assert.ok(form.description.trim().length > 0);
+	// Exact allowlist also rejects approval, exception, and other privileged labels.
+	assert.deepEqual(form.labels, ["enhancement", "status:needs-review"]);
+	assert.ok(Array.isArray(form.body));
+	assert.deepEqual(form.body.map((field) => field.id), [
+		"preflight", "problem", "outcome", "alternatives", "context",
+	]);
+	for (const field of form.body) {
+		assert.ok(["checkboxes", "textarea"].includes(field.type));
+		assert.match(field.id, /^[a-zA-Z0-9_-]+$/);
+		assert.equal(typeof field.attributes.label, "string");
+		assert.ok(field.attributes.label.trim().length > 0);
+		assert.deepEqual(Object.keys(field).sort(), field.type === "checkboxes"
+			? ["attributes", "id", "type"]
+			: ["attributes", "id", "type", "validations"]);
+	}
+});
+
+test("duplicate and privacy affirmations are individually required", () => {
+	const [preflight] = readForm().body;
+	assert.equal(preflight.type, "checkboxes");
+	assert.deepEqual(preflight.attributes.options, [
+		{
+			label: "I searched open and closed issues and did not find a request for this feature.",
+			required: true,
+		},
+		{
+			label: "I reviewed this request and removed credentials, tokens, private paths, hostnames, and other sensitive data.",
+			required: true,
+		},
+	]);
+});
+
+test("feature questions require problem and outcome but keep alternatives and context optional", () => {
+	const questions = readForm().body.slice(1);
+	assert.deepEqual(questions.map((field) => ({
+		type: field.type,
+		label: field.attributes.label,
+		validations: field.validations,
+	})), [
+		{ type: "textarea", label: "Problem or opportunity", validations: { required: true } },
+		{ type: "textarea", label: "Proposed outcome", validations: { required: true } },
+		{ type: "textarea", label: "Alternatives considered", validations: { required: false } },
+		{ type: "textarea", label: "Additional context", validations: { required: false } },
+	]);
+});

package/tests/fixtures/agents-messaging-child.mjs

@@ -0,0 +1,5 @@
+process.on("message", (message) => {
+	if (message?.kind !== "ack") return;
+	process.stdout.write(`${JSON.stringify({ accepted: message.accepted === true })}\n`, () => process.exit(0));
+});
+process.send({ id: "n1", kind: "notification", message: "fixture ready" });

package/tests/fixtures/agents-process-child.mjs

@@ -0,0 +1,23 @@
+import { spawn } from "node:child_process";
+
+const descendant = spawn(process.execPath, ["-e", "process.on('SIGTERM', () => {}); process.stdout.write('ready'); setInterval(() => {}, 1000);"], { stdio: ["ignore", "pipe", "ignore"] });
+descendant.stdout.once("data", () => {
+	console.log(`DESCENDANT:${descendant.pid}`);
+	if (process.env.AGENTS_PROCESS_CHILD_EXIT_AFTER_READY === "1") process.exit(0);
+});
+process.on("SIGTERM", () => {
+	if (process.env.AGENTS_PROCESS_CHILD_EXIT_ON_TERM === "1") process.exit(0);
+});
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+	for (const line of chunk.split("\n")) {
+		if (!line) continue;
+		try {
+			const command = JSON.parse(line);
+			process.stdout.write(`${JSON.stringify({ type: "response", id: command.id, success: true })}\n`);
+		} catch {
+			// Ignore malformed input; the runner owns the RPC protocol.
+		}
+	}
+});
+setInterval(() => {}, 1000);

package/tests/fixtures/runtime-metrics-native-batches.json

@@ -0,0 +1,6 @@
+{
+  "schema_sha256": "26be905d39fe8274e049e1270553695b7540a3b24571d42eb7d96c5a7deb48b5",
+  "batches": [
+    "{\"schema\":\"gentle-ai.telemetry-runtime-aggregate/v1\",\"registry\":1,\"host\":\"pi\",\"rows\":[{\"model\":{\"provider\":\"openai\",\"id\":\"gpt-5.4\"},\"model_evidence\":\"response\",\"agent_kind\":\"built_in\",\"agent_class\":\"worker\",\"selected_effort\":\"high\",\"effective_effort\":\"low\",\"launches\":null,\"responses\":1,\"input_tokens\":{\"reported\":1,\"unavailable\":0,\"unsupported\":0,\"sum\":7},\"output_tokens\":{\"reported\":1,\"unavailable\":0,\"unsupported\":0,\"sum\":7},\"cache_read_tokens\":{\"reported\":1,\"unavailable\":0,\"unsupported\":0,\"sum\":7},\"cache_creation_tokens\":{\"reported\":1,\"unavailable\":0,\"unsupported\":0,\"sum\":7},\"reasoning_tokens\":{\"reported\":1,\"unavailable\":0,\"unsupported\":0,\"sum\":7},\"total_tokens\":{\"reported\":1,\"unavailable\":0,\"unsupported\":0,\"sum\":7},\"error_category\":\"none\",\"duration\":{\"kind\":\"unavailable\",\"measured_count\":0,\"sum_ms\":null}}]}"
+  ]
+}