gentle-pi 3.2.0 → 3.3.0

package/tests/review-integration-v2-forward.test.ts

@@ -440,6 +440,67 @@ test("capabilities/v2.5 negotiates the v2.6.0 advertisement and status/v7 decode
 	assert.throws(() => decodeReviewStatusV3(v6WithDigest), /eligible_untracked_inventory/);
 });
 
+test("capabilities/v2.6 negotiates the v3.4.0 advertisement on the same v2.5 requirement floor", () => {
+	// gentle-ai v3.4.0 advertises capabilities/v2.6: the v2.5 surface plus
+	// status/v8 (status/v6 and status/v7 stay advertised for compatibility).
+	// The `review assess` review_due/review_due_reason/next_transition
+	// additions are a separate schema (gentle-ai.review-assessment/v1),
+	// unrelated to this negotiated capabilities surface.
+	const v26 = clone(fixture(DEV_FIXTURES, "capabilities-v2.2.captured.json") as JsonObject);
+	v26.schema = "gentle-ai.review-integration.capabilities/v2.6";
+	(v26.protocol as JsonObject).minor = 6;
+	const features = v26.features as JsonObject;
+	features.mandatory = (features.mandatory as JsonObject[]).filter((feature) =>
+		!["exact_receipt_replay", "five_delivery_gates", "sdd_receipt_binding"].includes(feature.name as string));
+	v26.schemas = [
+		...(v26.schemas as string[]).map((schema) => schema
+			.replace("capabilities/v2.2", "capabilities/v2.6")
+			.replace("start/v3", "start/v4")
+			.replace("status/v5", "status/v6")),
+		"gentle-ai.review-intended-untracked-selection/v1",
+		"gentle-ai.review-integration.status/v7",
+		"gentle-ai.review-integration.status/v8",
+	];
+	const decoded = decodeReviewCapabilitiesV2(v26, CAPTURED_DIGEST);
+	assert.equal(decoded.schemas.has("gentle-ai.review-integration.status/v6"), true);
+	// The negotiated set is the v2.5 requirement floor unchanged; status/v7
+	// and status/v8 are additive and never required, so an advertisement
+	// without either still negotiates.
+	const withoutV7V8 = clone(v26);
+	withoutV7V8.schemas = (withoutV7V8.schemas as string[]).filter((schema) => !["gentle-ai.review-integration.status/v7", "gentle-ai.review-integration.status/v8"].includes(schema as string));
+	assert.equal(decodeReviewCapabilitiesV2(withoutV7V8, CAPTURED_DIGEST).schemas.has("gentle-ai.review-integration.status/v6"), true);
+
+	// status/v6 stays required: v7/v8 are additive extensions, not a replacement.
+	const missingStatusV6 = clone(v26);
+	missingStatusV6.schemas = (missingStatusV6.schemas as string[]).filter((schema) => schema !== "gentle-ai.review-integration.status/v6");
+	assert.throws(() => decodeReviewCapabilitiesV2(missingStatusV6, CAPTURED_DIGEST), /status\/v6/);
+});
+
+// status/v8 (gentle-ai main, PR #4765; the current released contract) only
+// extended the reviewer-result transition for OpenCode provider tasks -- no
+// new top-level key -- so it decodes on the exact v7 surface: same optional
+// eligible_untracked_inventory digest, same rejection of a v6 envelope
+// carrying it. status/v9 (the sibling gentle-ai branch's contract, ahead of
+// the released v8) adds nothing new at the top level either; its one
+// addition -- the host-mediated role submission -- lives in
+// next_transition.collect.inputs and is covered by
+// tests/review-integration-v2.test.ts's "v9 host-mediated" tests.
+test("status/v8 and status/v9 decode with their exact identity on the v7 surface", () => {
+	const v8 = initialIntendedUntrackedStatusV6();
+	v8.schema = "gentle-ai.review-integration.status/v8";
+	v8.eligible_untracked_inventory = sha("e");
+	const decodedV8 = decodeReviewStatusV3(v8);
+	assert.equal(decodedV8.raw.schema, "gentle-ai.review-integration.status/v8");
+	assert.equal(decodedV8.eligibleUntrackedInventory, sha("e"));
+
+	const v9 = initialIntendedUntrackedStatusV6();
+	v9.schema = "gentle-ai.review-integration.status/v9";
+	v9.eligible_untracked_inventory = sha("e");
+	const decodedV9 = decodeReviewStatusV3(v9);
+	assert.equal(decodedV9.raw.schema, "gentle-ai.review-integration.status/v9");
+	assert.equal(decodedV9.eligibleUntrackedInventory, sha("e"));
+});
+
 test("status/v6 decodes and enforces the intended-untracked selection submission", () => {
 	const decoded = decodeReviewStatusV3(initialIntendedUntrackedStatusV6());
 	const input = decoded.nextTransition?.collect?.inputs[0];

package/tests/review-integration-v2.test.ts

@@ -818,11 +818,14 @@ test("next_transition decodes the self-contained provider role capture vectors s
 		() => decodeRoleTransition(roleInput("provider_refuter", "review.capture-refuter", "https://gentle-ai.dev/schema/review/reviewer/v1")),
 		/schema must be https:\/\/gentle-ai\.dev\/schema\/review\/refuter\/v1/,
 	);
+	// This fixture decodes on the v5 surface only (no v9): a submission
+	// descriptor on a role input is rejected for lacking the v9 provider
+	// contract, before the materialize/execute discriminator is even read.
 	assert.throws(
 		() => decodeRoleTransition(roleInput("provider_refuter", "review.capture-refuter", "https://gentle-ai.dev/schema/review/refuter/v1", {
 			submission: { operation_token: "capture-refuter", argument_tokens: ["--input={{value}}"], values: [{ slot: "{{value}}", domain: "artifact-path", substitution_location: 0 }] },
 		})),
-		/submission is not allowed on the self-contained/,
+		/submission requires the v9 provider contract/,
 	);
 
 	const validator = roleInput("provider_targeted_validator", "review.capture-validation", "https://gentle-ai.dev/schema/review/validator/v1");
@@ -837,6 +840,87 @@ test("next_transition decodes the self-contained provider role capture vectors s
 	);
 });
 
+// gentle-ai's v9 contract makes the same two role operations host-mediated
+// exactly like a lens materialize slot: the input carries a submission
+// descriptor alongside --materialize=true (never --execute), and the host
+// completes the frozen prompt in-process and submits through that
+// descriptor instead of executing a Go-owned pi subprocess.
+test("next_transition decodes the v9 host-mediated provider role submission form", () => {
+	const materializeArguments = [
+		{ name: "lineage", value: "review-fixture", token: "--lineage=review-fixture" },
+		{ name: "expected-revision", value: digest, token: `--expected-revision=${digest}` },
+		{ name: "target", value: digest, token: `--target=${digest}` },
+		{ name: "repository-context", value: `rctx1_${"c".repeat(64)}`, token: `--repository-context=rctx1_${"c".repeat(64)}` },
+		{ name: "agent", value: "pi", token: "--agent=pi" },
+		{ name: "materialize", value: "true", token: "--materialize=true" },
+	];
+	const roleInput = (name: string, captureOperation: string, schema: string, extra: Record<string, unknown> = {}) => ({
+		kind: "collect",
+		reason_code: "provider_refuter_required",
+		collect: { inputs: [{ name, schema, capture_operation: captureOperation, arguments: materializeArguments, ...extra }] },
+	});
+	// This decoder path is gated on v9 specifically -- the sibling gentle-ai
+	// branch's contract, ahead of the currently-released v8 -- not on v5,
+	// which v8 (and v6/v7) already satisfy.
+	const decodeRoleTransition = (value: unknown) => decodeReviewNextTransitionV3(value, { v9: true });
+	const refuterSubmission = {
+		operation_token: "capture-refuter",
+		argument_tokens: [...materializeArguments.map((argument) => argument.token), "--input={{value}}"],
+		value: { slot: "provider_refuter", domain: "artifact_path_or_stdin", schema: "https://gentle-ai.dev/schema/review/refuter/v1", substitution_location: materializeArguments.length },
+	};
+
+	const refuter = roleInput("provider_refuter", "review.capture-refuter", "https://gentle-ai.dev/schema/review/refuter/v1", { submission: refuterSubmission });
+	const decodedSubmission = decodeRoleTransition(refuter).collect?.inputs[0]?.submission;
+	assert.equal(decodedSubmission?.operationToken, "capture-refuter");
+	assert.equal(decodedSubmission?.argumentTokens.length, materializeArguments.length + 1);
+	assert.deepEqual(decodedSubmission?.values, [{
+		slot: "provider_refuter",
+		domain: "artifact_path_or_stdin",
+		schema: "https://gentle-ai.dev/schema/review/refuter/v1",
+		substitutionLocation: materializeArguments.length,
+	}]);
+
+	// The exact same payload under v8 (or any earlier non-v9 rung) is
+	// rejected: v8 only extended the reviewer-result transition for OpenCode
+	// provider tasks and never renders a role submission descriptor.
+	assert.throws(
+		() => decodeReviewNextTransitionV3(refuter, { v6: true }),
+		/submission requires the v9 provider contract/,
+	);
+
+	// A submission descriptor with no --materialize=true (and no --execute
+	// either) matches neither wire form.
+	assert.throws(
+		() => decodeRoleTransition(roleInput("provider_refuter", "review.capture-refuter", "https://gentle-ai.dev/schema/review/refuter/v1", {
+			submission: refuterSubmission,
+			arguments: materializeArguments.filter((argument) => argument.name !== "materialize"),
+		})),
+		/submission requires --materialize=true/,
+	);
+
+	// --execute alongside a submission descriptor mixes both wire forms on
+	// one input, which is never valid.
+	assert.throws(
+		() => decodeRoleTransition(roleInput("provider_refuter", "review.capture-refuter", "https://gentle-ai.dev/schema/review/refuter/v1", {
+			submission: refuterSubmission,
+			arguments: [...materializeArguments, { name: "execute", value: "true", token: "--execute=true" }],
+		})),
+		/must not carry --execute alongside a submission descriptor/,
+	);
+
+	// The targeted-validator's host-mediated form still requires its
+	// validation_request, exactly like the self-contained vector.
+	const validatorSubmission = {
+		operation_token: "capture-validation",
+		argument_tokens: [...materializeArguments.map((argument) => argument.token), "--input={{value}}"],
+		value: { slot: "provider_targeted_validator", domain: "artifact_path_or_stdin", schema: "https://gentle-ai.dev/schema/review/validator/v1", substitution_location: materializeArguments.length },
+	};
+	assert.throws(
+		() => decodeRoleTransition(roleInput("provider_targeted_validator", "review.capture-validation", "https://gentle-ai.dev/schema/review/validator/v1", { submission: validatorSubmission })),
+		/validation_request is required/,
+	);
+});
+
 test("v5 targeted-validator collect inputs carry the exact provider-owned validation request", () => {
 	const requestHash = `sha256:${"a".repeat(64)}`;
 	const expectedRevision = `sha256:${"b".repeat(64)}`;
@@ -913,6 +997,37 @@ test("v5 targeted-validator collect inputs carry the exact provider-owned valida
 	}]);
 	assert.deepEqual(decoded.collect?.inputs[0]?.arguments, input.arguments, "provider-rendered arguments must remain unchanged");
 
+	// The same validation_request rides the v9 host-mediated form too: swap
+	// --execute=true for --materialize=true and add the provider-owned
+	// submission descriptor.
+	const materializeArguments = input.arguments.map((argument) => argument.name === "execute" ? { name: "materialize", value: "true", token: "--materialize=true" } : argument);
+	const hostMediatedInput = {
+		...input,
+		arguments: materializeArguments,
+		submission: {
+			operation_token: "capture-validation",
+			argument_tokens: [...materializeArguments.map((argument) => argument.token), "--input={{value}}"],
+			value: { slot: "provider_targeted_validator", domain: "artifact_path_or_stdin", schema: "https://gentle-ai.dev/schema/review/validator/v1", substitution_location: materializeArguments.length },
+		},
+	};
+	const hostMediatedTransition = { kind: "collect" as const, reason_code: "targeted_validation_required", collect: { inputs: [hostMediatedInput] } };
+	const decodedHostMediated = decodeReviewNextTransitionV3(hostMediatedTransition, { v9: true });
+	assert.equal(decodedHostMediated.collect?.inputs[0]?.submission?.operationToken, "capture-validation");
+	assert.deepEqual(decodedHostMediated.collect?.inputs[0]?.submission?.values, [{
+		slot: "provider_targeted_validator",
+		domain: "artifact_path_or_stdin",
+		schema: "https://gentle-ai.dev/schema/review/validator/v1",
+		substitutionLocation: materializeArguments.length,
+	}]);
+	assert.equal(decodedHostMediated.collect?.inputs[0]?.validationRequest?.requestHash, requestHash);
+
+	// The identical v8 surface (v6/v7/v8 all decode collect inputs alike)
+	// rejects the same host-mediated submission: only v9 renders it.
+	assert.throws(
+		() => decodeReviewNextTransitionV3(hostMediatedTransition, { v6: true }),
+		/submission requires the v9 provider contract/,
+	);
+
 	const missingRequest = clone(transition);
 	delete (missingRequest.collect.inputs[0] as JsonObject).validation_request;
 	assert.throws(() => decodeReviewNextTransitionV3(missingRequest, { v5: true }), /validation_request is required/);

package/tests/review-relay-transport-agent.test.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 { REVIEW_HOST_RELAY_FAILURE, ReviewHostRelayError } from "../lib/review-host-relay.ts";
 import { NativeReviewIntegrationError, type NativeReviewCli } from "../lib/native-review-cli.ts";
 import { CandidateViewRegistry } from "../lib/review-candidate-view.ts";
 import type { ReviewCollectInputV3, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
@@ -186,6 +187,88 @@ test("the negotiated status asks for the pi agent so the provider offers its mat
 	assert.equal(hostRelay.transport, "pi_host_relay");
 });
 
+// gentle-pi#311 P2 (superseding gentle-shell#1136 / #1158): the lens's
+// user-owned completion selection (agent model routing config) rides the
+// relay request alongside the live model registry; there is no extension
+// allowlist and no ambient default model to fall back to.
+test("capture forwards the lens's user-owned selection and thinking level to the relay request", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const configHome = mkdtempSync(join(tmpdir(), "gentle-pi-relay-config-"));
+	const cwd = repository(t);
+	t.after(() => rmSync(configHome, { recursive: true, force: true }));
+	writeFileSync(join(configHome, "models.json"), JSON.stringify({ "review-reliability": { model: "minimax/MiniMax-M3", thinking: "high" } }), "utf8");
+	const previousConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
+	process.env.GENTLE_PI_CONFIG_HOME = configHome;
+	t.after(() => {
+		if (previousConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousConfigHome;
+	});
+	const { native } = transportAwareNative();
+	const relayed: ReviewHostRelayRequest[] = [];
+	__testing.setReviewHostRelayRunnerForTesting(async (request: ReviewHostRelayRequest) => {
+		relayed.push(request);
+		return { promptByteLength: 128, resultByteLength: 64, submission: '{"admission_decision":"completed"}' };
+	});
+
+	await runCapture(cwd, native, "selection-lineage");
+	assert.equal(relayed.length, 1);
+	assert.equal(relayed[0]!.selection, "minimax/MiniMax-M3", "the lens's routing entry must name the completion's selection");
+	assert.equal(relayed[0]!.thinking, "high");
+	assert.equal(relayed[0]!.routingKey, "review-reliability");
+});
+
+// gentle-pi#311 P2 decision (flagged for confirmation): the in-process path
+// has no ambient default model. A routing entry with no configured model used
+// to launch the child selection-free (inheriting pi's own default); the real
+// relay now refuses it typed instead, since there is no child to inherit a
+// default from (lib/review-host-relay.ts's own tests exercise that refusal
+// through the real, unfaked runner). This extension layer only forwards
+// whatever the routing config yields — it never validates the selection
+// itself — so with the runner faked here the request still reaches it, and
+// its `selection` field is simply absent.
+test("capture forwards no selection when the lens has no configured model, leaving the missing-model refusal to the relay", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const configHome = mkdtempSync(join(tmpdir(), "gentle-pi-relay-config-empty-"));
+	const cwd = repository(t);
+	t.after(() => rmSync(configHome, { recursive: true, force: true }));
+	const previousConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
+	process.env.GENTLE_PI_CONFIG_HOME = configHome;
+	t.after(() => {
+		if (previousConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previousConfigHome;
+	});
+	const { native } = transportAwareNative();
+	const relayed: ReviewHostRelayRequest[] = [];
+	__testing.setReviewHostRelayRunnerForTesting(async (request: ReviewHostRelayRequest) => {
+		relayed.push(request);
+		return { promptByteLength: 128, resultByteLength: 64, submission: '{"admission_decision":"completed"}' };
+	});
+
+	await runCapture(cwd, native, "default-lineage");
+	assert.equal(relayed.length, 1);
+	assert.equal(relayed[0]!.selection, undefined);
+	assert.equal(relayed[0]!.routingKey, "review-reliability");
+});
+
+test("a relayed empty-output failure carries the child's own evidence in the failure report", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const { native } = transportAwareNative();
+	__testing.setReviewHostRelayRunnerForTesting(async () => {
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.PI_EMPTY_OUTPUT, "pi", "pi subprocess produced no assistant text (stdout kind: no-assistant-text; a tool call was attempted)", {
+			reviewerEvidence: { stdoutKind: "no-assistant-text", reviewerModel: "nan/deepseek-v4-flash", toolCallAttempted: true },
+		});
+	});
+
+	const result = await runCapture(cwd, native, "evidence-lineage");
+	assert.equal(result.outcome, "pi-host-relay-transport-failure");
+	const failure = result.failure as { reviewer?: { stdoutKind?: string; reviewerModel?: string; toolCallAttempted?: boolean } } | undefined;
+	assert.ok(failure !== undefined, "the envelope carries the failure report");
+	assert.equal(failure.reviewer?.stdoutKind, "no-assistant-text");
+	assert.equal(failure.reviewer?.reviewerModel, "nan/deepseek-v4-flash");
+	assert.equal(failure.reviewer?.toolCallAttempted, true);
+});
+
 test("capture forecasts the reviewer model run once and spends nothing until it is acknowledged", async (t) => {
 	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
 	const cwd = repository(t);

package/tests/runtime-harness.mjs

@@ -524,7 +524,18 @@ async function run() {
 
 	const toolCwd = await tempWorkspace();
 	try {
+		execFileSync("git", ["init"], { cwd: toolCwd, stdio: "ignore" });
 		const toolHook = hooks.get("tool_call")[0];
+		const toolResultHook = hooks.get("tool_result")[0];
+		const promptHook = hooks.get("before_agent_start")[0];
+		const oddCtx = createCtx(toolCwd, false, "odd-runtime-gate");
+		await promptHook({ systemPrompt: "primary" }, oddCtx);
+		const firstOddPath = join(toolCwd, "first.ts");
+		assert.equal(await toolHook({ toolName: "write", input: { path: firstOddPath } }, oddCtx), undefined);
+		await toolResultHook({ toolName: "write", toolCallId: "odd-first", input: { path: firstOddPath }, isError: false }, oddCtx);
+		const secondOdd = await toolHook({ toolName: "edit", input: { path: join(toolCwd, "second.ts") } }, oddCtx);
+		assert.equal(secondOdd?.block, true, "the real primary hook must stop a second distinct direct file");
+		assert.match(secondOdd?.reason ?? "", /subagent_run/);
 		const ghPrCwd = await tempWorkspace();
 		try {
 			execFileSync("git", ["init"], { cwd: ghPrCwd, stdio: "ignore" });

package/tests/session-changes-shell.test.ts

@@ -36,3 +36,30 @@ test("reload and new evidence refresh Changes without Git or live file reads",as
 	assert.equal(typeof f.widgets.get("gentle-shell-changes"),"function");
 	await f.fire("session_shutdown");
 });
+test("the changes overlay labels each session tree with its root's branch instead of detached",async()=>{
+	const evidence=(root:string,id:string)=>({type:"custom",customType:SESSION_CHANGE_ENTRY,data:{sessionId:"session",evidence:{id,root,path:"own.ts",before:{kind:"absent"},after:{kind:"text",text:"own\n"}}}});
+	const entries=[evidence("/repo","child:1"),evidence("/other","child:2")];
+	const handlers=new Map<string,Function[]>();
+	const commands=new Map<string,any>();
+	const gitRoots:string[]=[];
+	const pi:any={on:(key,fn)=>handlers.set(key,[...(handlers.get(key)??[]),fn]),events:{on:()=>()=>{},emit(){}},appendEntry(){},registerTool(){},registerShortcut(){},registerMessageRenderer(){},registerCommand:(key,registration)=>commands.set(key,registration)};
+	let view:any; let renders=0;
+	const ctx:any={hasUI:true,cwd:"/repo",sessionManager:{getSessionId:()=>"session",getEntries:()=>entries},
+		ui:{setFooter(){},getEditorComponent:()=>({}),setWorkingVisible(){},setWidget(){},notify(){},
+			custom:async(factory:any)=>{view=factory({terminal:{rows:40,columns:120},requestRender:()=>renders++},{fg:(_c:string,t:string)=>t,bold:(t:string)=>t},{},()=>{});return new Promise(()=>{});}}};
+	shell(pi,{},{resolveWorktree:()=>({root:"/repo",commonDir:"/git"}),devBinary:()=>undefined,
+		gitRunner:(root:string)=>async(args:string[])=>{gitRoots.push(root);await new Promise(r=>setImmediate(r));
+			if(args[0]==="symbolic-ref")return root==="/repo"?{stdout:"feature\n",code:0}:{stdout:"",code:1};
+			return {stdout:"deadbeef\n",code:0};}});
+	for(const fn of handlers.get("session_start")??[])await fn({},ctx);
+	void commands.get("gentle:changes").handler("",ctx);
+	await new Promise(r=>setImmediate(r));
+	assert.ok(view,"the overlay opened");
+	for(let i=0;i<6;i++)await new Promise(r=>setImmediate(r));
+	const rendered=view.render(120).join("\n");
+	assert.match(rendered,/feature · repo/,"the repo tree carries its branch");
+	assert.match(rendered,/detached · other/,"a genuinely detached root still reads detached");
+	assert.deepEqual([...new Set(gitRoots)].sort(),["/other","/repo"],"git is asked once per root, only while the overlay is open");
+	assert.ok(renders>0,"a resolved label asks the overlay to repaint");
+	for(const fn of handlers.get("session_shutdown")??[])await fn({},ctx);
+});

package/tests/session-worktree-registry.test.ts

@@ -133,3 +133,44 @@ test("only standard path-bearing calls have registration candidates; shell and p
 	for (const name of ["bash", "powershell", "custom", "subagent_run"]) assert.equal(toolWorktreePath(name, { path: "/linked", command: "cd /linked", task: "/linked" }), undefined);
 	assert.equal(toolWorktreePath("read", { path: 42 }), undefined);
 });
+
+// C2 (odd/tasks/usage-click-and-changes-attribution.md): a repo nested inside
+// another repo (the live session's ~/work/NaN-builders inside ~/work) must
+// resolve to the INNER repo, never the outer one, because Git itself walks
+// up from the file's own directory and stops at the first .git it finds.
+function nestedFixture(t: test.TestContext) {
+	const dir = realpathSync(mkdtempSync(join(tmpdir(), "session-worktrees-nested-")));
+	t.after(() => rmSync(dir, { recursive: true, force: true }));
+	const outer = join(dir, "work");
+	const inner = join(outer, "NaN-builders");
+	const empty = join(dir, "empty");
+	mkdirSync(empty);
+	const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_")));
+	Object.assign(env, { GIT_CONFIG_GLOBAL: join(empty, "config"), GIT_CONFIG_NOSYSTEM: "1", GIT_ATTR_NOSYSTEM: "1" });
+	writeFileSync(join(empty, "config"), "");
+	const git = (cwd: string, args: string[]) => execFileSync("git", ["-C", cwd, "-c", `core.hooksPath=${empty}`, "-c", "commit.gpgsign=false", ...args], { env, stdio: ["ignore", "pipe", "pipe"] });
+	// Outer repo: no commits, matching the live evidence's `~/work` exactly.
+	git(dir, ["init", "--initial-branch=main", `--template=${empty}`, outer]);
+	// Inner repo: its own .git, a real branch and a commit.
+	git(dir, ["init", "--initial-branch=feature", `--template=${empty}`, inner]);
+	git(inner, ["-c", "user.name=Test", "-c", "user.email=test@example.invalid", "commit", "--allow-empty", "-m", "Fixture"]);
+	mkdirSync(join(inner, "odd", "tasks"), { recursive: true });
+	writeFileSync(join(inner, "odd", "tasks", "jpg-png-converter.md"), "converted\n");
+	return { dir, outer, inner };
+}
+
+test("nearest-repository resolution: an inner repo's files never resolve to an outer ancestor repo", (t) => {
+	const f = nestedFixture(t);
+	const forFile = resolveSessionWorktree(join("NaN-builders", "odd", "tasks", "jpg-png-converter.md"), f.outer);
+	assert.equal(forFile?.root, f.inner, "the file's own nearest repository must win, not the outer ~/work repo");
+	// The inner repo's own root and files resolve to itself too, whether
+	// addressed from the outer cwd or the inner cwd directly.
+	const forRoot = resolveSessionWorktree("NaN-builders", f.outer);
+	assert.equal(forRoot?.root, f.inner);
+	const fromInnerCwd = resolveSessionWorktree(join("odd", "tasks", "jpg-png-converter.md"), f.inner);
+	assert.equal(fromInnerCwd?.root, f.inner);
+	// The outer repo is still resolvable for its own files.
+	const outerFile = join(f.outer, "README.md");
+	writeFileSync(outerFile, "outer\n");
+	assert.equal(resolveSessionWorktree("README.md", f.outer)?.root, f.outer);
+});