gentle-pi 4.1.0 → 4.3.0

package/lib/provider-contract-bundle.ts

@@ -4,7 +4,9 @@
 // release bundle (or its extracted tree) and verifies it fail-closed before
 // any layout, role, schema, or capability inside it is trusted:
 //
-// - exact eight-entry inventory (README.md, manifest.json, 3 schemas, 3 vectors);
+// - exact inventory: eight base entries (README.md, manifest.json, 3 schemas,
+//   3 vectors) plus one `orchestration/<runtime>.md` (>= 1.2.0) and one
+//   `routing/<runtime>.md` (>= 1.4.0) per runtime the manifest lists;
 // - strict manifest decode: single JSON object, no duplicate keys, no unknown fields;
 // - per-file SHA-256 agreement between the manifest and the actual bytes;
 // - pinned transport capability and supported contract major (1);
@@ -33,6 +35,8 @@ export const SUPPORTED_PROVIDER_CONTRACT_MAJOR = 1;
 export const RUNTIMES_REQUIRED_SINCE_MINOR = 1;
 // `orchestration` became part of the manifest in contract 1.2.0.
 export const ORCHESTRATION_REQUIRED_SINCE_MINOR = 2;
+// `routing` became part of the manifest in contract 1.4.0.
+export const ROUTING_REQUIRED_SINCE_MINOR = 4;
 // Exactly the provider roles gentle-pi supports, in the manifest's strict order.
 export const PROVIDER_CONTRACT_ROLE_IDS = ["lens", "refuter", "targeted-validator"] as const;
 // Every mandatory capability a role may declare. An unknown mandatory
@@ -46,11 +50,11 @@ const MAX_MANIFEST_BYTES = 64 * 1024;
 const BUNDLE_ENTRY_COUNT = 8;
 // Generous fixed safety bound on raw archive/tree entries read BEFORE the
 // manifest itself is parsed (the exact expected count, base entries plus one
-// per `orchestration` runtime, is known only after manifest decode). Real
-// contracts register a handful of runtimes; this bound only rules out an
-// absurd smuggled inventory, it is not the exact-count check.
-const MAX_ORCHESTRATION_ENTRIES = 64;
-const MAX_RAW_BUNDLE_ENTRIES = BUNDLE_ENTRY_COUNT + MAX_ORCHESTRATION_ENTRIES;
+// per `orchestration` and one per `routing` runtime, is known only after
+// manifest decode). Real contracts register a handful of runtimes; this bound
+// only rules out an absurd smuggled inventory, it is not the exact-count check.
+const MAX_RUNTIME_FILE_ENTRIES = 64;
+const MAX_RAW_BUNDLE_ENTRIES = BUNDLE_ENTRY_COUNT + 2 * MAX_RUNTIME_FILE_ENTRIES;
 // setuid/setgid/sticky, any execute bit, or world-writable content is never
 // acceptable for a data-only contract bundle.
 const FORBIDDEN_MODE_BITS = 0o7113;
@@ -99,7 +103,13 @@ export interface VerifiedProviderContractBundle {
 	 * 1.2.0, where `orchestration` does not exist in the manifest.
 	 */
 	readonly orchestration: ReadonlyMap<string, string>;
-	/** Canonical path -> exact verified bytes for all entries (base eight plus one per orchestration runtime). */
+	/**
+	 * Verified ODD implementation-routing block, runtime identity -> UTF-8
+	 * `routing/<runtime>.md` contents. Empty before contract 1.4.0, where
+	 * `routing` does not exist in the manifest.
+	 */
+	readonly routing: ReadonlyMap<string, string>;
+	/** Canonical path -> exact verified bytes for all entries (base eight plus one per orchestration and routing runtime). */
 	readonly entries: ReadonlyMap<string, Buffer>;
 	/** Canonical path -> SHA-256 of the exact verified bytes. */
 	readonly entrySha256: ReadonlyMap<string, string>;
@@ -321,23 +331,65 @@ function parseManifestRole(value: unknown, index: number): ManifestRole {
 	};
 }
 
-interface ManifestOrchestrationEntry {
+// One entry of a runtime-file inventory: `orchestration` (>= 1.2.0) or
+// `routing` (>= 1.4.0). Both share the shape `{ runtime, file }` with the file
+// at `<inventory>/<runtime>.md`.
+interface ManifestRuntimeFileEntry {
 	readonly runtime: string;
 	readonly file: ManifestFileReference;
 }
 
-function parseOrchestrationEntry(value: unknown, index: number): ManifestOrchestrationEntry {
-	const where = `manifest.orchestration[${index}]`;
+type RuntimeFileInventory = "orchestration" | "routing";
+
+function parseRuntimeFileEntry(inventory: RuntimeFileInventory, value: unknown, index: number): ManifestRuntimeFileEntry {
+	const where = `manifest.${inventory}[${index}]`;
 	const object = requireObject(value, where);
 	requireExactKeys(object, ["runtime", "file"], ["runtime", "file"], where);
 	const runtime = requireString(object.runtime, `${where}.runtime`);
 	if (!RUNTIME_IDENTITY_PATTERN.test(runtime)) invalid(`${where}.runtime ${JSON.stringify(runtime)} is not a runtime identity`);
 	const file = parseFileReference(object.file, `${where}.file`);
-	const expectedPath = `orchestration/${runtime}.md`;
+	const expectedPath = `${inventory}/${runtime}.md`;
 	if (file.path !== expectedPath) invalid(`${where}.file.path must be ${JSON.stringify(expectedPath)}`);
 	return { runtime, file };
 }
 
+// Decodes one runtime-file inventory: absent before the contract minor that
+// introduced it, required from it on, strictly sorted, every runtime
+// registered in manifest.runtimes, and `pi` always present.
+function parseRuntimeFileInventory(
+	object: Record<string, unknown>,
+	inventory: RuntimeFileInventory,
+	requiredSinceMinor: number,
+	contractSemver: string,
+	minor: number,
+	runtimes: readonly string[] | undefined,
+): readonly ManifestRuntimeFileEntry[] {
+	const required = minor >= requiredSinceMinor;
+	if (!Object.prototype.hasOwnProperty.call(object, inventory)) {
+		if (required) invalid(`manifest.${inventory} is required from contract 1.${requiredSinceMinor}.0 (got ${contractSemver} without it)`);
+		return [];
+	}
+	if (!required) {
+		invalid(`manifest.${inventory} is not part of contract ${contractSemver}; it exists from 1.${requiredSinceMinor}.0`);
+	}
+	const value = object[inventory];
+	if (!Array.isArray(value) || value.length === 0) invalid(`manifest.${inventory} must be a non-empty array`);
+	const entries = value.map((entry, index) => parseRuntimeFileEntry(inventory, entry, index));
+	for (let position = 0; position < entries.length; position += 1) {
+		const entry = entries[position] as ManifestRuntimeFileEntry;
+		if (position > 0 && (entries[position - 1] as ManifestRuntimeFileEntry).runtime >= entry.runtime) {
+			invalid(`manifest.${inventory} must be strictly sorted by runtime and unique`);
+		}
+		if (runtimes === undefined || !runtimes.includes(entry.runtime)) {
+			invalid(`manifest.${inventory}[${position}].runtime ${JSON.stringify(entry.runtime)} is not registered in manifest.runtimes`);
+		}
+	}
+	if (!entries.some((entry) => entry.runtime === PI_RUNTIME_IDENTITY)) {
+		invalid(`manifest.${inventory} does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
+	}
+	return entries;
+}
+
 interface ParsedManifest {
 	readonly contractSemver: string;
 	readonly major: number;
@@ -347,14 +399,15 @@ interface ParsedManifest {
 	readonly runtimes: readonly string[] | undefined;
 	readonly readme: ManifestFileReference;
 	readonly roles: readonly ManifestRole[];
-	readonly orchestration: readonly ManifestOrchestrationEntry[];
+	readonly orchestration: readonly ManifestRuntimeFileEntry[];
+	readonly routing: readonly ManifestRuntimeFileEntry[];
 }
 
 function parseManifest(payload: Buffer): ParsedManifest {
 	const object = decodeStrictManifestObject(payload);
 	requireExactKeys(
 		object,
-		["schema", "contract_semver", "transport_capability", "runtimes", "readme", "roles", "orchestration"],
+		["schema", "contract_semver", "transport_capability", "runtimes", "readme", "roles", "orchestration", "routing"],
 		["schema", "contract_semver", "transport_capability", "readme", "roles"],
 		"manifest",
 	);
@@ -398,32 +451,8 @@ function parseManifest(payload: Buffer): ParsedManifest {
 		invalid(`manifest.runtimes does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
 	}
 
-	const orchestrationRequired = minor >= ORCHESTRATION_REQUIRED_SINCE_MINOR;
-	let orchestration: readonly ManifestOrchestrationEntry[] = [];
-	if (Object.prototype.hasOwnProperty.call(object, "orchestration")) {
-		if (!orchestrationRequired) {
-			invalid(`manifest.orchestration is not part of contract ${contractSemver}; it exists from 1.${ORCHESTRATION_REQUIRED_SINCE_MINOR}.0`);
-		}
-		if (!Array.isArray(object.orchestration) || object.orchestration.length === 0) {
-			invalid("manifest.orchestration must be a non-empty array");
-		}
-		const parsedOrchestration = object.orchestration.map((entry, index) => parseOrchestrationEntry(entry, index));
-		for (let position = 0; position < parsedOrchestration.length; position += 1) {
-			const entry = parsedOrchestration[position] as ManifestOrchestrationEntry;
-			if (position > 0 && (parsedOrchestration[position - 1] as ManifestOrchestrationEntry).runtime >= entry.runtime) {
-				invalid("manifest.orchestration must be strictly sorted by runtime and unique");
-			}
-			if (runtimes === undefined || !runtimes.includes(entry.runtime)) {
-				invalid(`manifest.orchestration[${position}].runtime ${JSON.stringify(entry.runtime)} is not registered in manifest.runtimes`);
-			}
-		}
-		if (!parsedOrchestration.some((entry) => entry.runtime === PI_RUNTIME_IDENTITY)) {
-			invalid(`manifest.orchestration does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
-		}
-		orchestration = parsedOrchestration;
-	} else if (orchestrationRequired) {
-		invalid(`manifest.orchestration is required from contract 1.${ORCHESTRATION_REQUIRED_SINCE_MINOR}.0 (got ${contractSemver} without it)`);
-	}
+	const orchestration = parseRuntimeFileInventory(object, "orchestration", ORCHESTRATION_REQUIRED_SINCE_MINOR, contractSemver, minor, runtimes);
+	const routing = parseRuntimeFileInventory(object, "routing", ROUTING_REQUIRED_SINCE_MINOR, contractSemver, minor, runtimes);
 
 	if (!Array.isArray(object.roles)) invalid("manifest.roles must be an array");
 	const roles = object.roles.map((role, index) => parseManifestRole(role, index));
@@ -446,6 +475,7 @@ function parseManifest(payload: Buffer): ParsedManifest {
 		readme: parseFileReference(object.readme, "manifest.readme"),
 		roles,
 		orchestration,
+		routing,
 	};
 }
 
@@ -541,8 +571,9 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 
 	// The exact expected inventory size is only known once the manifest is
 	// decoded: base entries plus exactly one `orchestration/<runtime>.md` per
-	// registered orchestration runtime.
-	const expectedEntryCount = BUNDLE_ENTRY_COUNT + manifest.orchestration.length;
+	// registered orchestration runtime and one `routing/<runtime>.md` per
+	// registered routing runtime.
+	const expectedEntryCount = BUNDLE_ENTRY_COUNT + manifest.orchestration.length + manifest.routing.length;
 	if (rawEntries.size !== expectedEntryCount) {
 		invalid(`bundle inventory has ${rawEntries.size} files; exactly ${expectedEntryCount} are expected`);
 	}
@@ -554,13 +585,18 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 		expected.add(`schemas/${role.id}.schema.json`);
 		expected.add(`vectors/${role.id}.json`);
 	}
-	const orchestration = new Map<string, string>();
-	for (const entry of manifest.orchestration) {
-		const path = `orchestration/${entry.runtime}.md`;
-		const payload = verifyFileReference(rawEntries, entry.file, path);
-		orchestration.set(entry.runtime, payload.toString("utf8"));
-		expected.add(path);
-	}
+	const verifyRuntimeFiles = (inventory: RuntimeFileInventory, manifestEntries: readonly ManifestRuntimeFileEntry[]): Map<string, string> => {
+		const texts = new Map<string, string>();
+		for (const entry of manifestEntries) {
+			const path = `${inventory}/${entry.runtime}.md`;
+			const payload = verifyFileReference(rawEntries, entry.file, path);
+			texts.set(entry.runtime, payload.toString("utf8"));
+			expected.add(path);
+		}
+		return texts;
+	};
+	const orchestration = verifyRuntimeFiles("orchestration", manifest.orchestration);
+	const routing = verifyRuntimeFiles("routing", manifest.routing);
 	for (const name of rawEntries.keys()) {
 		if (!expected.has(name)) invalid(`bundle has unexpected file ${JSON.stringify(name)}`);
 	}
@@ -591,6 +627,7 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 			vectorSha256: role.vector.sha256,
 		})),
 		orchestration,
+		routing,
 		entries,
 		entrySha256,
 		treeSha256: bundleTreeSha256(entrySha256),
@@ -745,6 +782,18 @@ export const PROVIDER_CAPABILITIES_BASELINE_SCHEMA = "gentle-pi.provider-contrac
 export const PROVIDER_ROLES_BASELINE_FILE = "provider-roles.baseline.json";
 export const PROVIDER_CAPABILITIES_BASELINE_FILE = "provider-capabilities.baseline.json";
 
+function runtimeFileBaseline(
+	bundle: VerifiedProviderContractBundle,
+	inventory: RuntimeFileInventory,
+	texts: ReadonlyMap<string, string>,
+): { runtime: string; path: string; sha256: string | undefined }[] {
+	return [...texts.keys()].sort().map((runtime) => ({
+		runtime,
+		path: `${inventory}/${runtime}.md`,
+		sha256: bundle.entrySha256.get(`${inventory}/${runtime}.md`),
+	}));
+}
+
 /**
  * Deterministically derives the provider-owned consumer contract surface from
  * a verified bundle. Pi overlays never live in these files; they are pure
@@ -773,11 +822,8 @@ export function generateProviderContractBaselines(bundle: VerifiedProviderContra
 		mandatory_capabilities: mandatory,
 		runtimes: bundle.runtimes === undefined ? null : [...bundle.runtimes],
 		pi_registered: piRuntimeRegistration(bundle).registered,
-		orchestration: [...bundle.orchestration.keys()].sort().map((runtime) => ({
-			runtime,
-			path: `orchestration/${runtime}.md`,
-			sha256: bundle.entrySha256.get(`orchestration/${runtime}.md`),
-		})),
+		orchestration: runtimeFileBaseline(bundle, "orchestration", bundle.orchestration),
+		routing: runtimeFileBaseline(bundle, "routing", bundle.routing),
 	};
 	return new Map([
 		[PROVIDER_ROLES_BASELINE_FILE, `${JSON.stringify(roles, null, 2)}\n`],

package/lib/review-candidate-view-owner.ts

@@ -208,19 +208,19 @@ function enforcePrivateWindowsDacl(path: string, identity: WindowsAclIdentity =
 	assertPrivateWindowsDacl(path, "directory", true, identity);
 }
 
-function privateWindowsDacl(path: string, kind: WindowsObjectKind, protectedDacl: boolean, enforce = false): void {
+function privateWindowsDacl(path: string, kind: WindowsObjectKind, protectedDacl: boolean, enforce = false, windowsIdentity?: WindowsAclIdentity): void {
 	if (testingWindowsAclAuthority !== undefined) return testingWindowsAclAuthority(path);
-	if (enforce) enforcePrivateWindowsDacl(path);
-	else assertPrivateWindowsDacl(path, kind, protectedDacl);
+	if (enforce) enforcePrivateWindowsDacl(path, windowsIdentity);
+	else assertPrivateWindowsDacl(path, kind, protectedDacl, windowsIdentity);
 }
 
-function privateWindowsCandidateOwnerBoundary(commonDir: string, enforce = false): void {
+function privateWindowsCandidateOwnerBoundary(commonDir: string, enforce = false, windowsIdentity?: WindowsAclIdentity): void {
 	const boundary = [commonDir, join(commonDir, "gentle-ai"), join(commonDir, "gentle-ai", "candidate-views")];
 	if (testingWindowsAclAuthority !== undefined) {
 		for (const path of boundary) testingWindowsAclAuthority(path);
 		return;
 	}
-	const identity = windowsAclIdentity();
+	const identity = windowsIdentity ?? windowsAclIdentity();
 	if (enforce) {
 		for (const path of boundary) validatePrivateWindowsOwner(windowsOwnerSid(path, "directory"), identity.user);
 		for (const path of boundary) enforcePrivateWindowsDacl(path, identity);
@@ -304,16 +304,23 @@ function directory(path: string, privateMode = false, platform: NodeJS.Platform
 	return `${stat.dev}:${stat.ino}`;
 }
 
-export function assertCandidateOwnerParent(commonDir: string, platform: NodeJS.Platform = process.platform): string {
+function checkedCandidateOwnerParent(commonDir: string, platform: NodeJS.Platform): { parent: string; windowsIdentity?: WindowsAclIdentity } {
 	directory(commonDir, false, platform);
 	const control = join(commonDir, "gentle-ai");
 	directory(control, false, platform);
 	const parent = join(commonDir, "gentle-ai", "candidate-views");
 	if (platform === "win32") {
 		directory(parent, false, platform);
-		privateWindowsCandidateOwnerBoundary(commonDir);
-	} else directory(parent, true, platform, true);
-	return parent;
+		const windowsIdentity = testingWindowsAclAuthority === undefined ? windowsAclIdentity() : undefined;
+		privateWindowsCandidateOwnerBoundary(commonDir, false, windowsIdentity);
+		return { parent, windowsIdentity };
+	}
+	directory(parent, true, platform, true);
+	return { parent };
+}
+
+export function assertCandidateOwnerParent(commonDir: string, platform: NodeJS.Platform = process.platform): string {
+	return checkedCandidateOwnerParent(commonDir, platform).parent;
 }
 
 export function prepareCandidateOwnerParent(commonDir: string, platform: NodeJS.Platform = process.platform): string {
@@ -329,13 +336,13 @@ export function prepareCandidateOwnerParent(commonDir: string, platform: NodeJS.
 	return assertCandidateOwnerParent(commonDir, platform);
 }
 
-function regular(path: string, privateMode = false, platform: NodeJS.Platform = process.platform): string {
+function regular(path: string, privateMode = false, platform: NodeJS.Platform = process.platform, windowsIdentity?: WindowsAclIdentity): string {
 	// Keep 64-bit identity exact without a second stat lookup racing the privacy checks.
 	const stat = lstatSync(path, { bigint: true });
 	const uid = process.getuid?.();
 	if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1n || !samePath(realpathSync(path), path, platform) || stat.size > 16384n ||
 		(privateMode && platform !== "win32" && (uid === undefined || stat.uid !== BigInt(uid) || (stat.mode & 0o777n) !== 0o600n))) throw new Error("Unsafe candidate owner file");
-	if (privateMode && platform === "win32") privateWindowsDacl(path, "file", false);
+	if (privateMode && platform === "win32") privateWindowsDacl(path, "file", false, false, windowsIdentity);
 	return `${stat.dev}:${stat.ino}`;
 }
 
@@ -347,27 +354,27 @@ function syncDirectory(path: string): void {
 	try { fsyncSync(fd); } finally { closeSync(fd); }
 }
 
-function removeExactPrivateFile(path: string, identity: string, platform: NodeJS.Platform): void {
+function removeExactPrivateFile(path: string, identity: string, platform: NodeJS.Platform, windowsIdentity?: WindowsAclIdentity): void {
 	try {
-		if (regular(path, true, platform) !== identity) return;
+		if (regular(path, true, platform, windowsIdentity) !== identity) return;
 		unlinkSync(path);
 		syncDirectory(dirname(path));
 	} catch { /* An unproven or replaced file survives. */ }
 }
 
-function exclusiveFile(path: string, content: string, platform: NodeJS.Platform = process.platform, rollbackOnFailure = false): string {
+function exclusiveFile(path: string, content: string, platform: NodeJS.Platform = process.platform, rollbackOnFailure = false, windowsIdentity?: WindowsAclIdentity): string {
 	let identity: string | undefined;
 	try {
 		const fd = openSync(path, "wx", 0o600);
 		try {
-			identity = regular(path, true, platform);
+			identity = regular(path, true, platform, windowsIdentity);
 			writeFileSync(fd, content);
 			fsyncSync(fd);
 		} finally { closeSync(fd); }
 		syncDirectory(dirname(path));
 		return identity;
 	} catch (error) {
-		if (rollbackOnFailure && identity !== undefined) removeExactPrivateFile(path, identity, platform);
+		if (rollbackOnFailure && identity !== undefined) removeExactPrivateFile(path, identity, platform, windowsIdentity);
 		throw error;
 	}
 }
@@ -375,7 +382,10 @@ function exclusiveFile(path: string, content: string, platform: NodeJS.Platform
 function markerPath(root: string): string { return `${root}.owner.json`; }
 
 export function createCandidateOwner(commonDir: string, root: string, platform: NodeJS.Platform = process.platform): CandidateViewOwner {
-	const parent = assertCandidateOwnerParent(commonDir, platform);
+	// Reuse only identity within this module-controlled synchronous creation.
+	// Owner/DACL observations stay fresh, including rollback. Nothing is retained
+	// across calls or passed into callback-based removal/sweeping operations.
+	const { parent, windowsIdentity } = checkedCandidateOwnerParent(commonDir, platform);
 	const uuid = basename(root);
 	if (!UUID.test(uuid) || root !== join(parent, uuid) || lstatSync(root, { throwIfNoEntry: false })) throw new Error("Unsafe candidate owner root");
 	const owner: CandidateViewOwner = { version: 1, uuid, token: randomUUID(), pid: process.pid, host: localHost(), root, commonDir };
@@ -383,11 +393,11 @@ export function createCandidateOwner(commonDir: string, root: string, platform:
 	const marker = markerPath(root);
 	let markerIdentity: string | undefined;
 	try {
-		markerIdentity = exclusiveFile(marker, JSON.stringify(owner), platform, true);
+		markerIdentity = exclusiveFile(marker, JSON.stringify(owner), platform, true, windowsIdentity);
 		syncDirectory(dirname(parent));
 		syncDirectory(commonDir);
 	} catch (error) {
-		if (markerIdentity !== undefined) removeExactPrivateFile(marker, markerIdentity, platform);
+		if (markerIdentity !== undefined) removeExactPrivateFile(marker, markerIdentity, platform, windowsIdentity);
 		throw error;
 	}
 	return Object.freeze(owner);

package/lib/review-candidate-view.ts

@@ -1,6 +1,6 @@
 import { execFileSync, type ExecFileSyncOptions } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, symlinkSync, utimesSync } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, symlinkSync, utimesSync, type Stats } from "node:fs";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -650,6 +650,32 @@ function makeReadonly(root: string, entries: readonly CandidateViewEntry[]): voi
 	for (const directory of candidateDirectories(root, entries)) chmodSync(directory, 0o555);
 }
 
+// macOS File Provider (iCloud-synced Desktop/Documents) asynchronously resets
+// directory modes to exactly 0700 while leaving file modes intact, so a view
+// made read-only at creation later reads as writable. Only that exact shape on
+// a directory this user owns is re-tightened; any group or other bit still
+// refuses. Owner-only write grants nothing a same-user process could not do by
+// chmod anyway, and the caller then proves the directory holds exactly the
+// frozen children, closing the ignored-file injection the untracked scan misses.
+function repairFileProviderDirectoryMode(directory: string, metadata: Stats, platform: NodeJS.Platform): boolean {
+	if (platform === "win32" || !metadata.isDirectory() || metadata.isSymbolicLink() || (metadata.mode & 0o7777) !== 0o700) return false;
+	if (typeof process.getuid !== "function" || metadata.uid !== process.getuid()) return false;
+	chmodSync(directory, 0o555);
+	return true;
+}
+
+function expectedDirectoryChildren(root: string, entries: readonly CandidateViewEntry[]): ReadonlyMap<string, ReadonlySet<string>> {
+	const children = new Map<string, Set<string>>([[root, new Set([".git"])]]);
+	for (const entry of entries) {
+		for (let path = join(root, entry.path); path !== root && isWithin(root, path); path = dirname(path)) {
+			const parent = dirname(path);
+			if (!children.has(parent)) children.set(parent, new Set());
+			children.get(parent)!.add(basename(path));
+		}
+	}
+	return children;
+}
+
 function makeWritableForCleanup(path: string): void {
 	const entry = lstatSync(path, { throwIfNoEntry: false });
 	if (!entry || entry.isSymbolicLink()) return;
@@ -1050,8 +1076,16 @@ function assertRecordSafe(record: CandidateViewRecord, platform: NodeJS.Platform
 	if (!isWithin(record.parent, root) || !existsSync(root)) throw new CandidateViewError("candidate view is missing or moved");
 	const rootStat = lstatSync(root);
 	if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || realpathSync(root) !== root) throw new CandidateViewError("candidate view root is unsafe");
+	let expectedChildren: ReadonlyMap<string, ReadonlySet<string>> | undefined;
 	for (const directory of candidateDirectories(root, record.entries)) {
-		const metadata = lstatSync(directory);
+		let metadata = lstatSync(directory);
+		if (repairFileProviderDirectoryMode(directory, metadata, platform)) {
+			expectedChildren ??= expectedDirectoryChildren(root, record.entries);
+			const expected = expectedChildren.get(directory) ?? new Set<string>();
+			const actual = readdirSync(directory);
+			if (actual.length !== expected.size || actual.some((name) => !expected.has(name))) throw new CandidateViewError("candidate view directory contains unexpected entries");
+			metadata = lstatSync(directory);
+		}
 		if (!metadata.isDirectory() || metadata.isSymbolicLink() || (metadata.mode & 0o222) !== 0) throw new CandidateViewError("candidate view directory is unsafe or writable");
 	}
 	const gitFile = lstatSync(join(root, ".git"));

package/lib/review-risk-assessment.ts

@@ -267,8 +267,9 @@ export type VerificationTier = (typeof VERIFICATION_TIER)[keyof typeof VERIFICAT
 // ---------------------------------------------------------------------------
 // Agent-raised risk (gentle-shell#1494). The agent that made the change may
 // raise its risk to high by citing one item of the high-risk list in the
-// always-on Task Size section; it can never lower a tier. Lowering stays with
-// the deterministic native assessment.
+// always-on Task Size section; it can never lower a tier. That escalation is
+// the only way a plan gets an independent verifier: a native high or a failed
+// assessment informs but never adds one by itself.
 // ---------------------------------------------------------------------------
 
 export const HIGH_RISK_ITEMS = Object.freeze({
@@ -305,10 +306,17 @@ export function decodeAgentRiskEscalation(value: unknown): AgentRiskEscalation {
 	return Object.freeze({ item: item as HighRiskItem, reason });
 }
 
-/** Raises passive or medium to high when the agent escalated; never lowers. */
-export function escalatedRisk(risk: VerificationTier, escalation: AgentRiskEscalation | undefined): VerificationTier {
-	if (escalation === undefined) return risk;
-	return risk === VERIFICATION_TIER.PASSIVE || risk === VERIFICATION_TIER.MEDIUM ? VERIFICATION_TIER.HIGH : risk;
+/**
+ * The risk tier the verification plan follows. The independent verifier is
+ * for concrete occasions only: the plan is high only when the agent escalated
+ * a named Task Size high-risk item. Without an escalation a native passive
+ * stays passive, and every other native tier -- medium, high, or unassessable
+ * (a failed or unavailable assessment) -- is medium: it informs, but adds no
+ * verifier by itself. The native tier stays visible to callers as `nativeRisk`.
+ */
+export function verificationRisk(nativeRisk: VerificationTier, escalation: AgentRiskEscalation | undefined): VerificationTier {
+	if (escalation !== undefined) return VERIFICATION_TIER.HIGH;
+	return nativeRisk === VERIFICATION_TIER.PASSIVE ? VERIFICATION_TIER.PASSIVE : VERIFICATION_TIER.MEDIUM;
 }
 
 export const RDD_LINE = {
@@ -342,7 +350,9 @@ export type NativeReviewOutcome = (typeof NATIVE_REVIEW_OUTCOME)[keyof typeof NA
 
 export interface VerificationPlanInput {
 	readonly rddLine: RddLine;
+	/** The plan risk from `verificationRisk`, not the raw native tier. */
 	readonly risk: VerificationTier;
+	/** Reported context only: the writer's model or effort never changes the plan. */
 	readonly writerProfile: WriterProfile;
 	/**
 	 * Native review outcome for the current candidate. Only consulted when
@@ -366,7 +376,7 @@ export interface VerificationPlan {
  * naming which branch fired, up to and including the word "and"; the
  * tier-specific clause is appended after it.
  */
-function riskGatedPlan(gatePrefix: string, risk: VerificationTier, writerProfile: WriterProfile): VerificationPlan {
+function riskGatedPlan(gatePrefix: string, risk: VerificationTier): VerificationPlan {
 	if (risk === VERIFICATION_TIER.PASSIVE) {
 		return Object.freeze({
 			writerSelfVerification: false,
@@ -376,26 +386,22 @@ function riskGatedPlan(gatePrefix: string, risk: VerificationTier, writerProfile
 		});
 	}
 
-	if (risk === VERIFICATION_TIER.MEDIUM) {
-		const smallModelBias = writerProfile === WRITER_PROFILE.SMALL;
+	if (risk === VERIFICATION_TIER.HIGH) {
 		return Object.freeze({
 			writerSelfVerification: true,
 			structuralReadbackOnly: false,
-			independentVerifier: smallModelBias,
-			reason: smallModelBias
-				? `${gatePrefix} the native assessment reports medium risk, but the small-model bias raises it one tier to high for verification purposes: the writer self-verifies and a separate independent verifier also runs.`
-				: `${gatePrefix} the native assessment reports medium risk with a large writer profile: the writer's self-verification stands and no separate verifier is required.`,
+			independentVerifier: true,
+			reason: `${gatePrefix} an agent escalation names a Task Size high-risk item: the writer self-verifies and a separate independent verifier runs.`,
 		});
 	}
 
-	// high or unassessable.
+	// medium, or an unassessable tier that did not go through verificationRisk:
+	// both inform only.
 	return Object.freeze({
 		writerSelfVerification: true,
 		structuralReadbackOnly: false,
-		independentVerifier: true,
-		reason: risk === VERIFICATION_TIER.UNASSESSABLE
-			? `${gatePrefix} the native risk assessment could not be produced, so the candidate is treated as high risk: the writer self-verifies and a separate independent verifier always runs.`
-			: `${gatePrefix} the native assessment reports high risk: the writer self-verifies and a separate independent verifier always runs.`,
+		independentVerifier: false,
+		reason: `${gatePrefix} no Task Size high-risk item was escalated: the writer's self-verification stands and no separate verifier runs, whatever the native tier or the model that wrote the change.`,
 	});
 }
 
@@ -416,24 +422,23 @@ function nonClosedOutcomeClause(outcome: NativeReviewOutcome): string {
 
 /**
  * Computes who verifies a delegated writer's change. Verification follows the
- * native risk tier whatever the RDD line and native review outcome
+ * plan risk tier whatever the RDD line and native review outcome
  * (verify-always-rdd-high S1, superseding the gentle-pi#662/#668 on-path): the
  * native review is an additional outside view and never replaces or skips the
  * tier's verification. `nativeReviewOutcome` only shapes the reason text.
  *
+ * `risk` is the plan risk from `verificationRisk`; `writerProfile` is never
+ * consulted, so the model or effort that wrote the change never adds a
+ * verifier.
+ *
  * - `passive`: structural readback by the parent only; no verifier, no tests.
- * - `medium`: the writer self-verifies; a separate independent verifier runs
- *   only when `writerProfile` is `"small"` -- the small-model bias raises the
- *   tier by one for verification purposes (medium -> high). An unknown or
- *   omitted writer profile resolves to `"small"` before it reaches this
- *   function (see `resolveWriterProfile`), so an unrecognized profile never
- *   lowers a tier below what a known small model would get.
- * - `high` or `unassessable` (a failed or unrecognized native assessment is
- *   always treated as high): the writer self-verifies and an independent
- *   verifier always runs.
+ * - `medium` (also an `unassessable` tier passed directly): the writer
+ *   self-verifies; no separate verifier.
+ * - `high` (only through an agent escalation naming a Task Size high-risk
+ *   item): the writer self-verifies and an independent verifier runs.
  */
 export function verificationPlan(input: VerificationPlanInput): VerificationPlan {
-	const { rddLine, risk, writerProfile } = input;
+	const { rddLine, risk } = input;
 
 	if (rddLine === RDD_LINE.ON) {
 		const outcome = input.nativeReviewOutcome ?? NATIVE_REVIEW_OUTCOME.UNKNOWN;
@@ -443,14 +448,13 @@ export function verificationPlan(input: VerificationPlanInput): VerificationPlan
 		return riskGatedPlan(
 			`receipt-driven development is on and ${clause}; the native review is an additional outside view that never replaces verification, so the risk-gated path applies exactly as receipt-driven development off, and`,
 			risk,
-			writerProfile,
 		);
 	}
 
 	// rddLine is "off" or "unknown" here -- both gate on the native risk
 	// assessment identically, so an unknown RDD line never lowers a tier, and
 	// neither line ever consults nativeReviewOutcome.
-	return riskGatedPlan(`receipt-driven development is ${rddLine} and`, risk, writerProfile);
+	return riskGatedPlan(`receipt-driven development is ${rddLine} and`, risk);
 }
 
 // ---------------------------------------------------------------------------
@@ -475,15 +479,16 @@ export interface WriterModelProfileLike {
 const SMALL_MODEL_ID_TOKEN = /(?:^|[-_./:\s])mini(?:$|[-_./:\s])/i;
 
 /**
- * A writer profile counts as a "small model" for the medium-risk bias when:
+ * A writer profile counts as a "small model" (reported by ASSESS as
+ * `writerProfile`; it never changes the verification plan) when:
  * - its resolved effort is `low`, or
  * - its resolved model id carries `mini` as a whole token (see
  *   `SMALL_MODEL_ID_TOKEN`), or
  * - it carries NO signal at all -- no profile object, or a profile with
  *   neither a model id nor a resolved effort. An unknown or omitted writer
- *   profile fails closed to small rather than defaulting to large, so a
- *   caller that cannot resolve the writer's profile never gets a weaker
- *   verification plan than a known small model would (gentle-pi#662).
+ *   profile fails closed to small rather than defaulting to large. The
+ *   result is reported in the assessment only: the verification plan never
+ *   reads the writer profile, so it cannot add or remove a verifier.
  *
  * A profile that carries a model id or an effort, just not a matching one
  * (for example `{model: {id: "claude-sonnet-5"}, thinking: "high"}`), is
@@ -501,9 +506,9 @@ export function isSmallWriterProfile(profile: WriterModelProfileLike | undefined
 }
 
 /**
- * Maps a resolved writer profile to the `writerProfile` input `verificationPlan`
- * expects. An unknown or omitted profile never lowers a tier: it resolves to
- * `"small"`, exactly like `isSmallWriterProfile` (gentle-pi#662).
+ * Maps a resolved writer profile to the reported `writerProfile`. An unknown
+ * or omitted profile resolves to `"small"`, exactly like
+ * `isSmallWriterProfile` (gentle-pi#662).
  */
 export function resolveWriterProfile(profile: WriterModelProfileLike | undefined): WriterProfile {
 	return isSmallWriterProfile(profile) ? WRITER_PROFILE.SMALL : WRITER_PROFILE.LARGE;

package/lib/review-session-standing-permission.ts

@@ -15,6 +15,7 @@ export interface GitCommandOptions {
 	timeout: number;
 	maxBuffer: number;
 	windowsHide?: boolean;
+	stdio?: ["ignore", "pipe", "pipe"];
 }
 
 export type GitAsyncRunner = (command: string, args: readonly string[], options: GitCommandOptions) => Promise<{ stdout: string }>;
@@ -133,7 +134,8 @@ export function resolveCanonicalGitRepositoryIdentitySync(
 	run: GitSyncRunner = execFileSync as unknown as GitSyncRunner,
 ): string | undefined {
 	try {
-		const output = run("git", ["-C", cwd, "rev-parse", "--git-common-dir"], { encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024, windowsHide: true }).trim();
+		// execFileSync otherwise echoes stderr on failure, even when caught below.
+		const output = run("git", ["-C", cwd, "rev-parse", "--git-common-dir"], { encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] }).trim();
 		if (output.length === 0 || output.includes("\n") || output.includes("\r")) return undefined;
 		return canonicalRepositoryIdentity(realpathSync(resolve(cwd, output)));
 	} catch {