gentle-pi 3.2.0 → 3.3.0

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/odd-runtime-delegation-gate.test.ts

@@ -0,0 +1,212 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import type { NativeReviewCli } from "../lib/native-review-cli.ts";
+
+type Handler = (event: Record<string, unknown>, ctx: ExtensionContext) => unknown;
+
+function harness(processEnv: NodeJS.ProcessEnv = {}, activeTools = ["read", "edit", "write", "subagent_run"], sddRoot?: string): Map<string, Handler> {
+	const handlers = new Map<string, Handler>();
+	const pi = {
+		on(name: string, handler: Handler) {
+			handlers.set(name, handler);
+		},
+		events: { emit() {} },
+		registerCommand() {},
+		registerTool() {},
+		getFlag: () => sddRoot ? JSON.stringify({ changeName: "isolation", workspaceRoot: sddRoot, phase: "apply" }) : undefined,
+		getActiveTools: () => activeTools,
+	} as unknown as ExtensionAPI;
+	createGentleAiExtension({
+		nativeReviewCli: sddRoot ? {
+			sddStatus: async () => ({
+				schemaName: "gentle-ai.sdd-status", schemaVersion: 2, changeName: "isolation", artifactStore: "openspec",
+				planningHome: { mode: "repo-local", path: join(sddRoot, "openspec") }, changeRoot: join(sddRoot, "openspec", "changes", "isolation"),
+				actionContext: { mode: "repo-local", workspaceRoot: sddRoot, allowedEditRoots: [sddRoot] },
+				dependencies: { proposal: "all_done", specs: "all_done", design: "all_done", tasks: "all_done", apply: "ready", verify: "blocked", archive: "blocked" },
+				phaseInstructions: { apply: [], verify: [], archive: [] }, blockedReasons: [], nextRecommended: "apply",
+			}),
+		} as unknown as NativeReviewCli : null,
+		processEnv,
+		resolveTelemetryTriggerBinary: () => "/usr/bin/true",
+		telemetryTriggerSpawn: (() => undefined) as never,
+	})(pi);
+	return handlers;
+}
+
+async function successfulMutation(handlers: Map<string, Handler>, ctx: ExtensionContext, toolName: "edit" | "write", path: string): Promise<void> {
+	assert.equal(await handlers.get("tool_call")!({ toolName, input: { path } }, ctx), undefined);
+	await handlers.get("tool_result")!({ toolName, toolCallId: `${toolName}-${path}`, input: { path }, isError: false }, ctx);
+}
+
+function context(cwd: string): ExtensionContext {
+	return {
+		cwd,
+		hasUI: false,
+		mode: "interactive",
+		ui: { notify() {} },
+		sessionManager: { getSessionId: () => "odd-runtime-delegation-red" },
+	} as unknown as ExtensionContext;
+}
+
+test("primary ODD runtime blocks the second distinct direct source write before mutation", async () => {
+	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-odd-runtime-gate-"));
+	try {
+		execFileSync("git", ["init", "--quiet"], { cwd });
+		mkdirSync(join(cwd, "src"));
+		const firstPath = join(cwd, "src", "first.ts");
+		const secondPath = join(cwd, "src", "second.ts");
+		const handlers = harness();
+		const beforeAgentStart = handlers.get("before_agent_start");
+		const toolCall = handlers.get("tool_call");
+		const toolResult = handlers.get("tool_result");
+		assert.equal(typeof beforeAgentStart, "function");
+		assert.equal(typeof toolCall, "function");
+		assert.equal(typeof toolResult, "function");
+		const ctx = context(cwd);
+
+		await beforeAgentStart!({ systemPrompt: "primary" }, ctx);
+		assert.equal(await toolCall!({ toolName: "edit", input: { path: firstPath } }, ctx), undefined);
+		await toolResult!({
+			toolName: "edit",
+			toolCallId: "first-direct-edit",
+			input: { path: firstPath },
+			isError: false,
+		}, ctx);
+
+		const second = await toolCall!({
+			toolName: "write",
+			input: { path: secondPath, content: "export const second = true;\n" },
+		}, ctx) as { block?: boolean; reason?: string } | undefined;
+		assert.equal(second?.block, true, "the second distinct direct source file must be refused before mutation");
+		assert.match(second?.reason ?? "", /subagent_run/);
+		assert.match(second?.reason ?? "", /gentle-ai-worker/);
+
+		assert.equal(await toolCall!({ toolName: "edit", input: { path: firstPath } }, ctx), undefined, "same-file edits stay direct");
+		assert.equal(await toolCall!({ toolName: "write", input: { path: join(cwd, "odd", "tasks", "feature.md") } }, ctx), undefined, "ODD bookkeeping is excluded");
+
+		await beforeAgentStart!({ systemPrompt: "fresh primary turn" }, ctx);
+		await toolResult!({ toolName: "write", toolCallId: "failed", input: { path: firstPath }, isError: true }, ctx);
+		assert.equal(await toolCall!({ toolName: "write", input: { path: secondPath } }, ctx), undefined, "failed calls do not consume the direct-file budget");
+		await successfulMutation(handlers, ctx, "write", secondPath);
+		assert.equal((await toolCall!({ toolName: "write", input: { path: firstPath } }, ctx) as { block?: boolean })?.block, true);
+
+		await beforeAgentStart!({ systemPrompt: "next primary turn" }, ctx);
+		assert.equal(await toolCall!({ toolName: "write", input: { path: firstPath } }, ctx), undefined, "a primary restart resets ephemeral state");
+
+		await beforeAgentStart!({ systemPrompt: "bookkeeping turn" }, ctx);
+		await successfulMutation(handlers, ctx, "write", join(cwd, "odd", "tasks", "feature.md"));
+		assert.equal(await toolCall!({ toolName: "write", input: { path: secondPath } }, ctx), undefined, "successful ODD bookkeeping consumes no budget");
+	} finally {
+		rmSync(cwd, { recursive: true, force: true });
+	}
+});
+
+test("the refusal stops honestly when delegation is unavailable", async () => {
+	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-odd-no-delegation-"));
+	try {
+		execFileSync("git", ["init", "--quiet"], { cwd });
+		const handlers = harness({}, ["edit", "write"]);
+		const ctx = context(cwd);
+		await handlers.get("before_agent_start")!({ systemPrompt: "primary" }, ctx);
+		await successfulMutation(handlers, ctx, "write", join(cwd, "first.ts"));
+		const refused = await handlers.get("tool_call")!({ toolName: "write", input: { path: join(cwd, "second.ts") } }, ctx) as { reason?: string };
+		assert.match(refused.reason ?? "", /Stop and report that no delegation mechanism is callable/);
+	} finally {
+		rmSync(cwd, { recursive: true, force: true });
+	}
+});
+
+test("a nested named child cannot erase its primary parent's recorded path", async () => {
+	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-odd-nested-child-"));
+	try {
+		execFileSync("git", ["init", "--quiet"], { cwd });
+		const handlers = harness();
+		const ctx = context(cwd);
+		await handlers.get("before_agent_start")!({ systemPrompt: "primary" }, ctx);
+		await successfulMutation(handlers, ctx, "write", join(cwd, "first.ts"));
+		await handlers.get("before_agent_start")!({ agentName: "gentle-ai-worker", systemPrompt: "named child" }, ctx);
+		await handlers.get("agent_end")!({}, ctx);
+		const resumed = await handlers.get("tool_call")!({ toolName: "write", input: { path: join(cwd, "second.ts") } }, ctx) as { block?: boolean } | undefined;
+		assert.equal(resumed?.block, true, "a completed child must not disable its resumed parent's gate");
+	} finally {
+		rmSync(cwd, { recursive: true, force: true });
+	}
+});
+
+test("canonical absolute targets remain inside a repository reached through a nested symlink cwd", async () => {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-odd-real-root-")));
+	const aliases = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-odd-cwd-alias-")));
+	try {
+		execFileSync("git", ["init", "--quiet"], { cwd: root });
+		mkdirSync(join(root, "workspace", "nested"), { recursive: true });
+		const linkedRoot = join(aliases, "repository");
+		symlinkSync(root, linkedRoot, "dir");
+		const ctx = context(join(linkedRoot, "workspace", "nested"));
+		const handlers = harness();
+		await handlers.get("before_agent_start")!({ systemPrompt: "primary" }, ctx);
+		await successfulMutation(handlers, ctx, "write", join(root, "workspace", "nested", "first.ts"));
+		const second = await handlers.get("tool_call")!({ toolName: "write", input: { path: join(root, "workspace", "nested", "second.ts") } }, ctx) as { block?: boolean } | undefined;
+		assert.equal(second?.block, true, "canonical absolute targets must not be rebased through the lexical symlink cwd");
+	} finally {
+		rmSync(aliases, { recursive: true, force: true });
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("canonical paths collapse aliases and cannot disguise source as ODD bookkeeping", async (t) => {
+	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-odd-canonical-path-"));
+	try {
+		execFileSync("git", ["init", "--quiet"], { cwd });
+		mkdirSync(join(cwd, "src"));
+		mkdirSync(join(cwd, "odd", "tasks"), { recursive: true });
+		const firstPath = join(cwd, "src", "first.ts");
+		const secondPath = join(cwd, "src", "second.ts");
+		writeFileSync(firstPath, "");
+		writeFileSync(secondPath, "");
+		symlinkSync("first.ts", join(cwd, "src", "alias.ts"));
+		symlinkSync("../../src/second.ts", join(cwd, "odd", "tasks", "source.ts"));
+		const handlers = harness();
+		const ctx = context(cwd);
+		await t.test("an alias of the recorded file remains the same canonical path", async () => {
+			await handlers.get("before_agent_start")!({ systemPrompt: "primary alias turn" }, ctx);
+			await successfulMutation(handlers, ctx, "write", firstPath);
+			assert.equal(await handlers.get("tool_call")!({ toolName: "edit", input: { path: join(cwd, "src", "alias.ts") } }, ctx), undefined);
+		});
+
+		await t.test("a bookkeeping symlink to source remains an eligible second file", async () => {
+			await handlers.get("before_agent_start")!({ systemPrompt: "primary bookkeeping turn" }, ctx);
+			await successfulMutation(handlers, ctx, "write", firstPath);
+			const disguised = await handlers.get("tool_call")!({ toolName: "edit", input: { path: join(cwd, "odd", "tasks", "source.ts") } }, ctx) as { block?: boolean } | undefined;
+			assert.equal(disguised?.block, true);
+		});
+	} finally {
+		rmSync(cwd, { recursive: true, force: true });
+	}
+});
+
+test("delegated child actors retain multi-file write authority", async () => {
+	for (const [label, processEnv, startEvent] of [
+		["named", {}, { agentName: "gentle-ai-worker", systemPrompt: "named child" }],
+		["SDD", {}, { agentName: "sdd-apply", systemPrompt: "SDD apply executor" }],
+		["RPC", { GENTLE_PI_AGENTS_CHILD: "1" }, { systemPrompt: "owned RPC child" }],
+	] as const) {
+		const cwd = realpathSync(mkdtempSync(join(tmpdir(), `gentle-pi-odd-${label}-`)));
+		try {
+			execFileSync("git", ["init", "--quiet"], { cwd });
+			mkdirSync(join(cwd, "src"));
+			const handlers = harness(processEnv, undefined, label === "SDD" ? cwd : undefined);
+			const ctx = context(cwd);
+			await handlers.get("before_agent_start")!(startEvent, ctx);
+			await successfulMutation(handlers, ctx, "write", join(cwd, "src", "first.ts"));
+			await successfulMutation(handlers, ctx, "edit", join(cwd, "src", "second.ts"));
+		} finally {
+			rmSync(cwd, { recursive: true, force: true });
+		}
+	}
+});

package/tests/orchestrator-rdd-ownership.test.ts

@@ -96,12 +96,12 @@ test("always-on parent prompt requires a narrow writer edit surface before launc
 	assert.match(core, /do not ask the human to author paths or globs/i);
 });
 
-test("review integration documents the opaque Pi adapter and Go-owned authority boundary", () => {
+test("review integration documents the in-process reviewer completion and Go-owned authority boundary", () => {
 	const docs = read("docs/review-integration.md");
 	for (const marker of [
-		"Buffer → Buffer/error",
+		"no child process",
 		"exact Go-issued materialize/submission tokens",
-		"typed Pi transport refusal fails closed",
+		"typed reviewer refusal fails closed",
 		"Go owns worktree, lineage, candidate freeze, lens selection, correction, validator, approval burn, and review semantics",
 		"Delivery commands remain ordinary repository-policy operations.",
 		"package has no durable receipt or policy authority",

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.4.0 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\.4\.0"/);
 	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:bQOM\+Xa3WN5\+idTagEk15rgEEQQWVhZvq8BPF\/FHtSs="/);
 	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\.4\.0/);
 });
 
 
@@ -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.3.0 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.3.0", "the release manifest must remain explicitly pinned to v3.3.0");
 	assert.equal(
 		packageJson.scripts?.test,
 		"node --experimental-strip-types --test tests/*.test.ts && pnpm run check:provider-contract && pnpm run test:harness",