gentle-pi 1.0.5 → 1.0.6

package/extensions/gentle-ai.ts

@@ -4499,9 +4499,13 @@ function nativeStartRejection(reason: string, field?: string): Record<string, un
 }
 
 function nativeOperationFailure(operation: ReviewControllerOperation, error: unknown): Record<string, unknown> {
-	const value = error as { mutationOutcome?: unknown; nextAction?: unknown; diagnostics?: unknown; launchAttempted?: unknown };
+	const value = error as { mutationOutcome?: unknown; nextAction?: unknown; diagnostics?: unknown; launchAttempted?: unknown; candidateViewPreNative?: unknown };
 	const mutationOutcome = value.mutationOutcome === "unknown" ? "unknown" : "none";
-	const diagnostics = error instanceof NativeReviewCliError ? error.diagnostics : undefined;
+	const diagnostics = error instanceof NativeReviewCliError
+		? error.diagnostics
+		: operation === REVIEW_CONTROLLER_OPERATION.START && error instanceof CandidateViewError && value.candidateViewPreNative === true
+			? { code: error.reason, message: "candidate view rejected before native START" }
+			: undefined;
 	return {
 		operation,
 		status: "blocked",
@@ -4892,8 +4896,10 @@ async function executeReviewControllerOperation(
 			}
 			const replayKey = JSON.stringify({ cwd: defaultCwd, lineageId: parameters.lineageId ?? null, input: parameters.input ?? null, inputPath: parameters.inputPath ?? null });
 			let candidateView: ReturnType<CandidateViewRegistry["create"]> | undefined;
+			let nativeStartAttempted = false;
 			try {
 				candidateView = candidateViews?.createOrReuse({ contributorRoot: defaultCwd, replayKey, ...(canonicalBaseRef === undefined ? {} : { baseRef: canonicalBaseRef, committedOnly: true }) });
+				nativeStartAttempted = true;
 				const result = await nativeReviewCli.start({
 					cwd: candidateView?.root ?? defaultCwd,
 					...(canonicalBaseRef === undefined
@@ -4914,13 +4920,16 @@ async function executeReviewControllerOperation(
 				if (error instanceof CandidateViewError && (error.reason === "base-ref-ambiguous" || error.reason === "base-ref-unresolvable" || error.reason === "base-ref-moved")) return nativeStartRejection(error.reason);
 				const value = error as { mutationOutcome?: unknown; nextAction?: unknown };
 				const provenNoMutation = value.mutationOutcome === "none";
-				if (candidateView && candidateViews && provenNoMutation) candidateViews.cleanup(candidateView.token);
+				const preNativeCandidateFailure = !nativeStartAttempted && error instanceof CandidateViewError;
+				if (candidateView && candidateViews && (provenNoMutation || preNativeCandidateFailure)) candidateViews.cleanup(candidateView.token);
 				const failure = provenNoMutation
 					? error
-					: Object.assign(error instanceof Error ? error : new Error(String(error)), {
-						mutationOutcome: "unknown",
-						nextAction: "replay-exact-native-operation",
-					});
+					: preNativeCandidateFailure
+						? Object.assign(error, { candidateViewPreNative: true })
+						: Object.assign(error instanceof Error ? error : new Error(String(error)), {
+							mutationOutcome: "unknown",
+							nextAction: "replay-exact-native-operation",
+						});
 				return nativeOperationFailure(parameters.operation, failure);
 			}
 		}

package/lib/native-review-cli.ts

@@ -35,7 +35,7 @@ export const NATIVE_REVIEW_ERROR_CODE = {
 } as const;
 export type NativeReviewErrorCode = (typeof NATIVE_REVIEW_ERROR_CODE)[keyof typeof NATIVE_REVIEW_ERROR_CODE];
 
-export interface ExecFileRequest { file: string; arguments: readonly string[]; cwd: string; timeoutMs: number; maxBufferBytes: number; signal?: AbortSignal; }
+export interface ExecFileRequest { file: string; arguments: readonly string[]; cwd: string; timeoutMs: number | undefined; maxBufferBytes: number; signal?: AbortSignal; }
 export interface ExecFileResult { stdout: string; stderr: string; exitCode: number; signal: NodeJS.Signals | null; timedOut: boolean; outputLimitExceeded: boolean; }
 export type ExecFileAdapter = (request: ExecFileRequest) => Promise<ExecFileResult>;
 
@@ -622,7 +622,7 @@ export class NativeReviewCliV214 {
 
 	private async execute(operation: NativeReviewOperation, cwd: string, arguments_: readonly string[], mutating: boolean, signal?: AbortSignal): Promise<NativeJsonExecution> {
 		let result: ExecFileResult;
-		try { result = await this.adapter({ file: this.executablePath(operation, mutating), arguments: arguments_, cwd, timeoutMs: this.timeoutMs, maxBufferBytes: this.maxBufferBytes, signal }); }
+		try { result = await this.adapter({ file: this.executablePath(operation, mutating), arguments: arguments_, cwd, timeoutMs: mutating ? undefined : this.timeoutMs, maxBufferBytes: this.maxBufferBytes, signal }); }
 		catch (error) {
 			if (error instanceof NativeReviewCliError) throw nativeError(error.code, operation, mutating, error.message, undefined, error.launchAttempted);
 			if (error instanceof Error && error.name === "AbortError") throw nativeError(NATIVE_REVIEW_ERROR_CODE.CANCELLED, operation, mutating, "native process was cancelled");

package/lib/review-candidate-view.ts

@@ -147,6 +147,26 @@ function decodeCanonicalPath(value: Buffer): string {
 	return path;
 }
 
+function assertSafeSymlinkTarget(root: string, entryPath: string, value: Buffer): void {
+	const target = value.toString("utf8");
+	if (
+		!Buffer.from(target, "utf8").equals(value) ||
+		target.length === 0 ||
+		isAbsolute(target) ||
+		/^[A-Za-z]:\//.test(target) ||
+		target.includes("\\") ||
+		/[\u0000-\u001f\u007f]/.test(target) ||
+		target.split("/").some((segment) => segment.length === 0 || segment === ".")
+	) {
+		throw new CandidateViewError("candidate view symlink target is unsafe");
+	}
+	const resolvedTarget = resolve(dirname(join(root, entryPath)), target);
+	const metadata = join(root, ".git");
+	if (!isWithin(root, resolvedTarget) || resolvedTarget === metadata || isWithin(metadata, resolvedTarget)) {
+		throw new CandidateViewError("candidate view symlink target escapes its frozen root or enters metadata");
+	}
+}
+
 function splitNulTerminated(raw: Buffer, errorMessage: string): Buffer[] {
 	if (raw.length === 0) return [];
 	if (raw.at(-1) !== 0) throw new CandidateViewError(errorMessage);
@@ -221,7 +241,7 @@ function entryContentHash(root: string, entry: CandidateViewEntry): string {
 		if (!item.isSymbolicLink()) throw new CandidateViewError("candidate view symlink does not match its frozen tree");
 		const target = readlinkSync(path, "buffer");
 		const bytes = Buffer.isBuffer(target) ? target : Buffer.from(target);
-		decodeCanonicalPath(bytes);
+		assertSafeSymlinkTarget(root, entry.path, bytes);
 		return createHash("sha256").update(bytes).digest("hex");
 	}
 	if (!item.isFile() || item.isSymbolicLink()) throw new CandidateViewError("candidate view entry does not match its frozen tree");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",

package/tests/native-review-cli.test.ts

@@ -21,8 +21,8 @@ interface QueuedResult {
 	outputLimitExceeded?: boolean;
 }
 
-function queuedAdapter(results: QueuedResult[]): { adapter: ExecFileAdapter; calls: Array<{ file: string; arguments: readonly string[]; cwd: string }> } {
-	const calls: Array<{ file: string; arguments: readonly string[]; cwd: string }> = [];
+function queuedAdapter(results: QueuedResult[]): { adapter: ExecFileAdapter; calls: Array<{ file: string; arguments: readonly string[]; cwd: string; timeoutMs: number | undefined; maxBufferBytes: number }> } {
+	const calls: Array<{ file: string; arguments: readonly string[]; cwd: string; timeoutMs: number | undefined; maxBufferBytes: number }> = [];
 	return {
 		calls,
 		adapter: async (request) => {
@@ -236,6 +236,29 @@ test("native mutation uncertainty requires exact replay", async () => {
 	);
 });
 
+test("native mutating commands omit the automatic timeout while preserving output caps", async () => {
+	const queue = queuedAdapter([
+		VERSION,
+		START,
+		VERSION,
+		{ stdout: await fixture("finalize") },
+		VERSION,
+		{ stdout: await fixture("bind-sdd") },
+	]);
+	const client = new NativeReviewCliV213(queue.adapter, "/package/.gentle-ai/v2.1.4/gentle-ai", 321, 654);
+	await client.start({ cwd: "/repo" });
+	await client.finalize({ cwd: "/repo", lineageId: "lineage-1" });
+	await client.bindSdd({ cwd: "/repo", change: "native-review-authority-parity", lineage: "issue136-contract-runtime", expectedBindingRevision: "" });
+	assert.deepEqual(queue.calls.map((call) => call.timeoutMs), [321, undefined, 321, undefined, 321, undefined]);
+	assert.deepEqual(queue.calls.map((call) => call.maxBufferBytes), [654, 654, 654, 654, 654, 654]);
+});
+
+test("native read-only commands and version checks retain the automatic timeout", async () => {
+	const queue = queuedAdapter([VERSION, { stdout: await fixture("validate-allow") }]);
+	await new NativeReviewCliV213(queue.adapter, "/package/.gentle-ai/v2.1.4/gentle-ai", 321).validate({ cwd: "/repo", gate: "post-apply", lineageId: "issue136-contract-runtime" });
+	assert.deepEqual(queue.calls.map((call) => call.timeoutMs), [321, 321]);
+});
+
 test("native process failures retain bounded sanitized process diagnostics and parsed denial evidence", async () => {
 	const denial = JSON.parse(await fixture("validate-deny")) as Record<string, unknown>;
 	const queue = queuedAdapter([VERSION, {
@@ -877,11 +900,13 @@ test("node execFile adapter passes AbortSignal to child_process", async () => {
 	await assert.rejects(pending, (error: unknown) => error instanceof Error && error.name === "AbortError");
 });
 
-test("native adapter receives the controller AbortSignal and preserves mutating replay guidance", async () => {
+test("native adapter receives the controller AbortSignal without an automatic mutation timeout", async () => {
 	const controller = new AbortController();
 	controller.abort();
+	let mutationTimeoutMs: number | undefined;
 	const adapter: ExecFileAdapter = async (request) => {
 		if (request.arguments[0] === "version") return { stdout: "gentle-ai 2.1.4\n", stderr: "", exitCode: 0, signal: null, timedOut: false, outputLimitExceeded: false };
+		mutationTimeoutMs = request.timeoutMs;
 		if (request.signal?.aborted) {
 			const error = new Error("cancelled");
 			error.name = "AbortError";
@@ -896,4 +921,5 @@ test("native adapter receives the controller AbortSignal and preserves mutating
 			&& error.mutationOutcome === "unknown"
 			&& error.nextAction === "replay-exact-native-operation",
 	);
+	assert.equal(mutationTimeoutMs, undefined);
 });

package/tests/native-review-parity-runtime.test.ts

@@ -1,13 +1,17 @@
 import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
-import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
 import { resolveGentleAiBinary } from "../lib/gentle-ai-binary.ts";
+import { NativeReviewCliV214 } from "../lib/native-review-cli.ts";
+import { CandidateViewRegistry } from "../lib/review-candidate-view.ts";
 
 const execFileAsync = promisify(execFile);
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -25,9 +29,31 @@ interface CommandResult {
 	stderr: string;
 }
 
+interface RegisteredController {
+	execute: (toolCallId: string, params: unknown, signal: AbortSignal | undefined, onUpdate: undefined, ctx: ExtensionContext) => Promise<{ details?: unknown }>;
+}
+
 interface ReviewStart {
 	lineage_id: string;
 	selected_lenses: string[];
+	action?: string;
+	state?: string;
+}
+
+interface ReviewFinalize {
+	lineage_id: string;
+	state: string;
+	store_revision: string;
+	receipt_path: string;
+}
+
+interface ReviewAuthorityEntry {
+	version: string;
+	lineage_id: string;
+	status: string;
+	state: string;
+	revision: string;
+	problems: unknown[];
 }
 
 interface ReviewGateContext {
@@ -90,6 +116,42 @@ async function restoreCandidate(repository: string, candidateTree: string): Prom
 	await assertPublishedProjection(repository, candidateTree);
 }
 
+async function reviewStatus(repository: string): Promise<Record<string, unknown>> {
+	return JSON.parse((await run(binary, ["review", "status", "--cwd", repository], repository)).stdout) as Record<string, unknown>;
+}
+
+function authorityInventory(status: Record<string, unknown>): ReviewAuthorityEntry[] {
+	assert.ok(Array.isArray(status.entries), "review status must expose authority entries");
+	return status.entries.map((entry) => {
+		assert.ok(entry !== null && typeof entry === "object", "authority entry must be an object");
+		const candidate = entry as Record<string, unknown>;
+		for (const key of ["version", "lineage_id", "status", "state", "revision"] as const) {
+			assert.equal(typeof candidate[key], "string", `authority entry ${key} must be stable text`);
+		}
+		assert.ok(Array.isArray(candidate.problems), "authority entry problems must be an array");
+		return {
+			version: candidate.version as string,
+			lineage_id: candidate.lineage_id as string,
+			status: candidate.status as string,
+			state: candidate.state as string,
+			revision: candidate.revision as string,
+			problems: candidate.problems,
+		};
+	});
+}
+
+async function finalizeEmptyReview(repository: string, artifacts: string, started: ReviewStart, evidenceName: string): Promise<CommandResult> {
+	const evidence = join(artifacts, evidenceName);
+	await writeFile(evidence, `evidence for ${started.lineage_id}\n`);
+	const resultFiles: string[] = [];
+	for (const [index] of started.selected_lenses.entries()) {
+		const result = join(artifacts, `${evidenceName}-lens-${index}.json`);
+		await writeFile(result, JSON.stringify({ findings: [], evidence: ["reviewed frozen candidate"] }));
+		resultFiles.push(result);
+	}
+	return run(binary, ["review", "finalize", "--cwd", repository, "--lineage", started.lineage_id, ...resultFiles.flatMap((result) => ["--result", result]), "--evidence", evidence], repository);
+}
+
 test("official v2.1.5 package runtime authorizes an unchanged linked-view candidate and denies a changed staging tree", async (t) => {
 	assert.equal(createHash("sha256").update(await readFile(binary)).digest("hex"), OFFICIAL_BINARY_SHA256);
 	assert.deepEqual(await run(binary, ["version"], packageRoot), { exitCode: 0, stdout: "gentle-ai 2.1.5\n", stderr: "" });
@@ -168,3 +230,140 @@ test("official v2.1.5 package runtime authorizes an unchanged linked-view candid
 	await chmod(join(repository, "tracked.txt"), 0o644);
 	await restoreCandidate(repository, candidateTree);
 });
+
+test("official v2.1.5 package runtime keeps frozen candidate lineages and receipts isolated across replay and replacement", async (t) => {
+	const workspace = await mkdtemp(join(tmpdir(), "gentle-pi-v215-lineage-"));
+	const repository = join(workspace, "repository");
+	const artifacts = join(workspace, "artifacts");
+	t.after(async () => rm(workspace, { recursive: true, force: true }));
+
+	await mkdir(repository);
+	await mkdir(artifacts);
+	await run("git", ["init", "--initial-branch=main"], repository);
+	await run("git", ["config", "user.email", "test@example.invalid"], repository);
+	await run("git", ["config", "user.name", "Gentle Pi test"], repository);
+	await writeFile(join(repository, "tracked.txt"), "base\n");
+	await run("git", ["add", "--", "tracked.txt"], repository);
+	await run("git", ["commit", "-m", "base"], repository);
+
+	await writeFile(join(repository, "tracked.txt"), "candidate one\n");
+	const first = JSON.parse((await run(binary, ["review", "start", "--cwd", repository], repository)).stdout) as ReviewStart;
+	const firstInventory = authorityInventory(await reviewStatus(repository));
+	const firstReplay = JSON.parse((await run(binary, ["review", "start", "--cwd", repository], repository)).stdout) as ReviewStart;
+	const firstReplayInventory = authorityInventory(await reviewStatus(repository));
+	assert.equal(firstReplay.lineage_id, first.lineage_id, "replaying an exact START must reuse the frozen lineage");
+	assert.deepEqual(firstReplayInventory, firstInventory, "replaying an exact START must not create durable authority");
+
+	const firstFinalized = JSON.parse((await finalizeEmptyReview(repository, artifacts, first, "first-evidence.txt")).stdout) as ReviewFinalize;
+	const firstFinalizedInventory = authorityInventory(await reviewStatus(repository));
+	const firstFinalizeReplay = JSON.parse((await finalizeEmptyReview(repository, artifacts, first, "first-evidence.txt")).stdout) as ReviewFinalize;
+	const firstFinalizeReplayInventory = authorityInventory(await reviewStatus(repository));
+	assert.equal(firstFinalized.lineage_id, first.lineage_id);
+	assert.equal(firstFinalized.state, "approved");
+	assert.match(firstFinalized.store_revision, /^sha256:[a-f0-9]{64}$/);
+	assert.equal(firstFinalizeReplay.store_revision, firstFinalized.store_revision, "replaying an exact FINALIZE must reuse its receipt revision");
+	assert.equal(firstFinalizeReplay.receipt_path, firstFinalized.receipt_path, "replaying an exact FINALIZE must reuse its receipt location");
+	assert.deepEqual(firstFinalizeReplayInventory, firstFinalizedInventory, "replaying an exact FINALIZE must not create a durable receipt or authority");
+	assert.deepEqual(firstFinalizedInventory, [{ version: "compact-v2", lineage_id: first.lineage_id, status: "approved", state: "approved", revision: firstFinalized.store_revision, problems: [] }]);
+
+	await run("git", ["add", "--", "tracked.txt"], repository);
+	const firstCandidateTree = (await run("git", ["write-tree"], repository)).stdout.trim();
+	const firstAllowed = JSON.parse((await run(binary, ["review", "validate", "--gate", "pre-commit", "--cwd", repository, "--lineage", first.lineage_id], repository)).stdout) as ReviewGateResult;
+	assert.equal(firstAllowed.result, "allow");
+	assert.equal(firstAllowed.context.candidate_tree, firstCandidateTree);
+
+	await writeFile(join(repository, "tracked.txt"), "candidate two\n");
+	await run("git", ["add", "--", "tracked.txt"], repository);
+	const secondCandidateTree = (await run("git", ["write-tree"], repository)).stdout.trim();
+	assert.notEqual(secondCandidateTree, firstCandidateTree);
+	const authorityBeforeCompetingStart = authorityInventory(await reviewStatus(repository));
+	const competingStart = await run(binary, ["review", "start", "--cwd", repository, "--lineage", first.lineage_id], repository);
+	const competingStartResult = JSON.parse(competingStart.stdout) as ReviewStart;
+	const authorityAfterCompetingStart = authorityInventory(await reviewStatus(repository));
+	assert.equal(competingStartResult.action, "blocked-scope-action", "a frozen lineage must return a structured scope-action block for a competing candidate");
+	assert.equal(competingStartResult.lineage_id, first.lineage_id);
+	assert.equal(competingStartResult.state, "approved");
+	assert.deepEqual(authorityAfterCompetingStart, authorityBeforeCompetingStart, "a blocked scope action must not mutate approved authority");
+	const second = JSON.parse((await run(binary, ["review", "start", "--cwd", repository], repository)).stdout) as ReviewStart;
+	const secondInventory = authorityInventory(await reviewStatus(repository));
+	assert.equal(second.action, "created");
+	assert.equal(second.state, "reviewing");
+	assert.notEqual(second.lineage_id, first.lineage_id, "a distinct candidate must establish a distinct lineage");
+	const secondReplay = JSON.parse((await run(binary, ["review", "start", "--cwd", repository], repository)).stdout) as ReviewStart;
+	const secondReplayInventory = authorityInventory(await reviewStatus(repository));
+	assert.equal(secondReplay.lineage_id, second.lineage_id, "replaying the second START must reuse its lineage");
+	assert.deepEqual(secondReplayInventory, secondInventory, "replaying the second START must not duplicate durable authority");
+	await finalizeEmptyReview(repository, artifacts, second, "second-evidence.txt");
+
+	const secondAllowed = JSON.parse((await run(binary, ["review", "validate", "--gate", "pre-commit", "--cwd", repository, "--lineage", second.lineage_id], repository)).stdout) as ReviewGateResult;
+	assert.equal(secondAllowed.result, "allow");
+	assert.equal(secondAllowed.context.candidate_tree, secondCandidateTree);
+	await assertScopeChanged(repository, first.lineage_id);
+
+	await writeFile(join(repository, "tracked.txt"), "candidate one\n");
+	await run("git", ["add", "--", "tracked.txt"], repository);
+	assert.equal((await run("git", ["write-tree"], repository)).stdout.trim(), firstCandidateTree);
+	const firstRestored = JSON.parse((await run(binary, ["review", "validate", "--gate", "pre-commit", "--cwd", repository, "--lineage", first.lineage_id], repository)).stdout) as ReviewGateResult;
+	assert.equal(firstRestored.result, "allow", "the old receipt must remain valid for its exact frozen candidate");
+
+	await writeFile(join(repository, "tracked.txt"), "candidate two\n");
+	await run("git", ["add", "--", "tracked.txt"], repository);
+	assert.equal((await run("git", ["write-tree"], repository)).stdout.trim(), secondCandidateTree);
+	t.diagnostic("pre-push, pre-pr, and release require remote/publication evidence; their network-aware gate contracts remain covered by dedicated gate integration tests rather than this hermetic binary E2E.");
+});
+
+test("registered gentle_review START materializes a safe internal skill symlink before invoking native authority", async (t) => {
+	const workspace = await mkdtemp(join(tmpdir(), "gentle-pi-v215-symlink-candidate-"));
+	const repository = join(workspace, "repository");
+	t.after(async () => rm(workspace, { recursive: true, force: true }));
+
+	await mkdir(join(repository, ".agents", "skills", "example"), { recursive: true });
+	await mkdir(join(repository, ".agent", "skills"), { recursive: true });
+	await writeFile(join(repository, "tracked.txt"), "base\n");
+	await writeFile(join(repository, ".agents", "skills", "example", "SKILL.md"), "---\nname: example\n---\n");
+	const link = join(repository, ".agent", "skills", "example");
+	const linkTarget = "../../.agents/skills/example";
+	await symlink(linkTarget, link);
+	const lexicalTarget = resolve(dirname(link), linkTarget);
+	const lexicalRelative = relative(repository, lexicalTarget);
+	assert.ok(lexicalRelative !== "" && !lexicalRelative.startsWith("..") && !isAbsolute(lexicalRelative), "the internal symlink target must resolve lexically inside the repository");
+
+	await run("git", ["init", "--initial-branch=main"], repository);
+	await run("git", ["config", "user.email", "test@example.invalid"], repository);
+	await run("git", ["config", "user.name", "Gentle Pi test"], repository);
+	await run("git", ["add", "--", "tracked.txt", ".agents", ".agent"], repository);
+	await run("git", ["commit", "-m", "base with internal skill symlink"], repository);
+	await writeFile(join(repository, "tracked.txt"), "candidate\n");
+
+	const candidateViews = new CandidateViewRegistry();
+	let nativeStartReached = false;
+	const native = new NativeReviewCliV214(async (request) => {
+		if (request.arguments[0] === "review" && request.arguments[1] === "start") nativeStartReached = true;
+		const command = await run(binary, request.arguments, request.cwd, true);
+		return { ...command, signal: null, timedOut: false, outputLimitExceeded: false };
+	});
+	const tools = new Map<string, RegisteredController>();
+	createGentleAiExtension({ nativeReviewCli: native, candidateViews } as Parameters<typeof createGentleAiExtension>[0])({
+		on() {},
+		registerTool(definition: RegisteredController & { name: string }) { tools.set(definition.name, definition); },
+		registerCommand() {},
+	} as unknown as ExtensionAPI);
+	const controller = tools.get("gentle_review");
+	assert.ok(controller);
+
+	let returned: { details?: unknown } | undefined;
+	let thrown: unknown;
+	try {
+		returned = await controller.execute("issue-146-start", { operation: "start", input: JSON.stringify({ mode: "ordinary" }) }, undefined, undefined, { cwd: repository, hasUI: false, ui: { confirm: async () => true } } as unknown as ExtensionContext);
+	} catch (caught) {
+		thrown = caught;
+	}
+	const error = thrown instanceof Error ? { name: thrown.name, message: thrown.message } : thrown === undefined ? undefined : String(thrown);
+	t.diagnostic(JSON.stringify({ returned: returned?.details, error, nativeStartReached }));
+	assert.equal(thrown, undefined, "safe internal symlink materialization must not throw before START");
+	assert.equal(nativeStartReached, true, "safe internal symlink materialization must reach native START");
+	const result = (returned?.details as { result?: Record<string, unknown> } | undefined)?.result;
+	assert.equal(typeof result?.lineage_id, "string", "safe internal symlink materialization must return native review authority");
+	assert.equal(result?.state, "reviewing");
+	candidateViews.cleanup(candidateViews.resolveForLens(result!.lineage_id as string, "review-reliability").token);
+});

package/tests/package-manifest.test.ts

@@ -1015,9 +1015,9 @@ test("pi-pretty wrapper uses real package path resolution for pnpm symlink insta
 	assert.match(wrapper, /quietToolsEnabled/);
 });
 
-test("v1.0.5 release package and runtime stop before delivery or publication", () => {
+test("v1.0.6 release package and runtime stop before delivery or publication", () => {
 	const packageJson = readPackageJson();
-	assert.equal(packageJson.version, "1.0.5", "the release manifest must remain explicitly pinned to v1.0.5");
+	assert.equal(packageJson.version, "1.0.6", "the release manifest must remain explicitly pinned to v1.0.6");
 	assert.equal(
 		packageJson.scripts?.test,
 		"node --experimental-strip-types --test tests/*.test.ts && pnpm run test:harness",

package/tests/review-candidate-view.test.ts

@@ -404,6 +404,71 @@ test("candidate view fails closed before dispatch when the changed scope itself
 	}
 });
 
+test("candidate view accepts internal relative symlink targets and rejects unsafe lexical targets", (t) => {
+	const acceptedRoot = repository(t);
+	const acceptedTarget = "../../.agents/skills/example";
+	const acceptedLink = join(acceptedRoot, ".agent", "skills", "example");
+	mkdirSync(join(acceptedRoot, ".agents", "skills", "example"), { recursive: true });
+	mkdirSync(join(acceptedRoot, ".agent", "skills"), { recursive: true });
+	writeFileSync(join(acceptedRoot, ".agents", "skills", "example", "SKILL.md"), "example\n");
+	try {
+		symlinkSync(acceptedTarget, acceptedLink);
+	} catch {
+		t.skip("platform does not support symlinks");
+		return;
+	}
+	const accepted = createCandidateView({ contributorRoot: acceptedRoot });
+	try {
+		assert.equal(lstatSync(acceptedLink).isSymbolicLink(), true);
+		assert.equal(readFileSync(join(accepted.root, ".agent", "skills", "example", "SKILL.md"), "utf8"), "example\n");
+		accepted.verify();
+	} finally {
+		accepted.cleanup();
+	}
+
+	for (const [name, target] of [
+		["escape", "../escape"],
+		["absolute", "/absolute-target"],
+		["Windows drive absolute", "C:/absolute-target"],
+		["lowercase Windows drive absolute", "c:/absolute-target"],
+		["metadata", ".git"],
+		["control", "unsafe\ntarget"],
+		["backslash", "unsafe\\target"],
+		["empty segment", "unsafe//target"],
+	] as const) {
+		const contributorRoot = repository(t);
+		try {
+			symlinkSync(target, join(contributorRoot, "candidate-link"));
+		} catch {
+			t.skip("platform does not support symlinks");
+			return;
+		}
+		assert.throws(() => createCandidateView({ contributorRoot }), (error: unknown) => error instanceof CandidateViewError, name);
+	}
+});
+
+test("candidate view detects symlink target-byte tampering after materialization", (t) => {
+	const contributorRoot = repository(t);
+	const link = join(contributorRoot, "candidate-link");
+	try {
+		symlinkSync("safe-target", link);
+	} catch {
+		t.skip("platform does not support symlinks");
+		return;
+	}
+	const view = createCandidateView({ contributorRoot });
+	try {
+		const frozenLink = join(view.root, "candidate-link");
+		chmodSync(view.root, 0o755);
+		rmSync(frozenLink);
+		symlinkSync("other-target", frozenLink);
+		chmodSync(view.root, 0o555);
+		assert.throws(() => view.verify(), CandidateViewError);
+	} finally {
+		view.cleanup();
+	}
+});
+
 test("candidate view retains a valid dangling symlink through bind and finalize resolution", (t) => {
 	const contributorRoot = repository(t);
 	try {

package/tests/review-controller-native-routing.test.ts

@@ -702,6 +702,30 @@ test("native error has no compact fallback and ambiguous mutation demands exact
 	assert.deepEqual(result.details, { operation: "start", status: "blocked", outcome: "native-operation-failed", mutation_performed: false, mutation_outcome: "unknown", next_action: "replay-exact-native-operation" });
 });
 
+test("native START preserves a candidate-view diagnostic before native invocation", async (t) => {
+	const cwd = repository(t);
+	try {
+		symlinkSync("../escape", join(cwd, "unsafe-link"));
+	} catch {
+		t.skip("platform does not support symlinks");
+		return;
+	}
+	let starts = 0;
+	const { controller } = runtime(fakeNative({
+		start: async () => {
+			starts += 1;
+			return { lineageId: "must-not-start", state: "reviewing", riskLevel: "medium", selectedLenses: ["review-reliability"], changedFiles: 1, changedLines: 1, correctionBudget: 1, action: "created", lensesRequired: true };
+		},
+	}), undefined, undefined, undefined, new CandidateViewRegistry());
+	const result = await controller.execute("unsafe-symlink-start", { operation: "start", input: JSON.stringify({ mode: "ordinary" }) }, undefined, undefined, context(cwd));
+	const details = result.details as Record<string, unknown>;
+	assert.equal(details.outcome, "native-operation-failed");
+	assert.equal(details.mutation_outcome, "none");
+	assert.equal(details.next_action, "resolve-native-operation-failure");
+	assert.deepEqual(details.diagnostics, { code: "candidate-view-invalid", message: "candidate view rejected before native START" });
+	assert.equal(starts, 0);
+});
+
 test("native START uses the default policy or a canonical safe policy path, and rejects unsafe policy inputs before native calls", async (t) => {
 	const cwd = repository(t);
 	const policyDirectory = join(cwd, ".gentle-ai", "policies");