gentle-pi 4.2.0 → 4.3.0

package/lib/orchestrator-presence.ts

@@ -263,6 +263,15 @@ export function readActivity(profile: string, selection: Header): { activity?: A
 	} catch (error) { return { unavailable: reason(error) }; }
 }
 
+/** True only when no discovery sidecar exists for this header: the publisher
+ * predates discovery publication. A present but unreadable sidecar is not absent. */
+export function discoveryAbsent(profile: string, h: Header): boolean {
+	try {
+		fs.lstatSync(join(rootFor(profile), filename(h, "discovery")));
+		return false;
+	} catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT"; }
+}
+
 /** Optional derived sidecar; failures never invalidate the schema-1 header. */
 export function readDiscovery(profile: string, h: Header): DiscoveryMetadata | undefined {
 	try {

package/lib/orchestrator-scope.ts

@@ -41,9 +41,14 @@ export function validRecordedScope(value: any): value is RecordedScope {
 /** One bounded derivative snapshot, not a registry or authority. The caller supplies
  * only admitted, unfinished, non-restored owned children and durable registry roots.
  * Membership/cwd changes invalidate even unknown facts; session replacement clears.
- * No resolution runs on a stable heartbeat/token update. */
+ * Recency reorders rebuild caller-ordered snapshots without refreshing visible facts.
+ * Resolution stays bounded to the host and first eight tasks/registered roots;
+ * newly visible paths are resolved lazily, including after a reorder. */
 export class OrchestratorScopeCache {
 	private key = "";
+	private membershipKey = "";
+	private facts = new Map<string, RepositoryFact>();
+	private resolvedAt = 0;
 	private snapshot?: RecordedScope;
 	private resolver: WorktreeResolver;
 	private now: () => number;
@@ -53,14 +58,24 @@ export class OrchestratorScopeCache {
 	}
 	clear() {
 		this.key = "";
+		this.membershipKey = "";
+		this.facts.clear();
 		this.snapshot = undefined;
 	}
 	project(cwd: string, tasks: readonly { id: string; cwd: string }[], roots: readonly string[]): RecordedScope {
 		const registered = [...new Set(roots)];
 		const key = createHash("sha256").update(JSON.stringify([cwd, tasks.map(t => [t.id, t.cwd]), registered])).digest("hex");
 		if (key === this.key && this.snapshot) return this.snapshot;
-		const resolvedAt = this.now();
-		const facts = new Map<string, RepositoryFact>();
+		const membershipKey = createHash("sha256").update(JSON.stringify([
+			cwd, tasks.map(t => JSON.stringify([t.id, t.cwd])).sort(), [...registered].sort(),
+		])).digest("hex");
+		if (membershipKey !== this.membershipKey) {
+			this.facts.clear();
+			this.resolvedAt = this.now();
+			this.membershipKey = membershipKey;
+		}
+		const resolvedAt = this.resolvedAt;
+		const facts = this.facts;
 		const fact = (path: string) => {
 			if (facts.has(path)) return facts.get(path)!;
 			const unknown: RepositoryFact = { root: null, cloneHash: null, resolvedAt, source: "recorded-workspace/git" };
@@ -74,6 +89,9 @@ export class OrchestratorScopeCache {
 		this.snapshot = { host: fact(cwd), tasks: tasks.slice(0, 8).map(t => ({ id: t.id, repository: fact(t.cwd) })),
 			registered: registered.slice(0, 8).map(fact), omittedTasks: Math.max(0, tasks.length - 8),
 			omittedRegistered: Math.max(0, registered.length - 8), complete: tasks.length <= 8 && registered.length <= 8 };
+		// Keep fact retention bounded even when an oversized task list rotates.
+		const visible = new Set([cwd, ...tasks.slice(0, 8).map(t => t.cwd), ...registered.slice(0, 8)]);
+		for (const path of facts.keys()) if (!visible.has(path)) facts.delete(path);
 		this.key = key;
 		return this.snapshot;
 	}

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"));