gentle-pi 2.4.0 → 2.5.0

package/lib/native-pointer-region.ts

@@ -0,0 +1,164 @@
+import {
+	MouseRegion,
+	type Component,
+	type TuiMouseEvent,
+	type TuiMouseEventResult,
+} from "@earendil-works/pi-tui";
+
+export type NativePointerCallback = (event: TuiMouseEvent) => TuiMouseEventResult | undefined;
+
+export interface NativePointerRegionCallbacks {
+	onHover?: NativePointerCallback;
+	onLeave?: (event?: TuiMouseEvent) => void;
+	onPress?: NativePointerCallback;
+	onClick?: NativePointerCallback;
+	onWheel?: NativePointerCallback;
+}
+
+export interface NativePointerMouseObserver {
+	beforeMouse(event: TuiMouseEvent): void;
+	afterMouse(event: TuiMouseEvent): void;
+}
+
+/**
+ * A composable adapter around the public MouseRegion component.
+ * Child dispatch stays first, so an already handled child result is unchanged.
+ */
+export class NativePointerRegion implements Component {
+	private readonly adapter: MouseRegion;
+	private readonly callbacks: NativePointerRegionCallbacks;
+	private readonly scope: NativePointerScope | undefined;
+	private hovered = false;
+	private disabled = false;
+	private disposed = false;
+	private renderedWidth: number | undefined;
+
+	constructor(child: Component, callbacks: NativePointerRegionCallbacks, scope?: NativePointerScope) {
+		this.callbacks = callbacks;
+		this.scope = scope;
+		this.adapter = new MouseRegion(child, (event) => this.handlePointer(event));
+		this.scope?.register(this);
+	}
+
+	render(width: number): string[] {
+		if (this.renderedWidth !== undefined && this.renderedWidth !== width) this.clearHover();
+		this.renderedWidth = width;
+		return this.adapter.render(width);
+	}
+
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		if (this.disposed) return undefined;
+		return this.adapter.handleMouse(event);
+	}
+
+	invalidate(): void {
+		this.renderedWidth = undefined;
+		this.clearHover();
+		this.adapter.invalidate();
+	}
+
+	setDisabled(disabled: boolean): void {
+		if (this.disabled === disabled) return;
+		this.disabled = disabled;
+		if (disabled) this.clearHover();
+	}
+
+	clearHover(event?: TuiMouseEvent): boolean {
+		if (!this.hovered) return false;
+		this.hovered = false;
+		this.callbacks.onLeave?.(event);
+		return true;
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.clearHover();
+		this.scope?.unregister(this);
+	}
+
+	private handlePointer(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		if (this.disabled || this.disposed) return undefined;
+		if (event.type === "move" && event.button === "none") {
+			this.scope?.markMove(this, event);
+			this.hovered = true;
+			return this.callbacks.onHover?.(event);
+		}
+		if (event.type === "press") return this.callbacks.onPress?.(event);
+		if (event.type === "click") return this.callbacks.onClick?.(event);
+		if (event.type === "wheel") return this.callbacks.onWheel?.(event);
+		return undefined;
+	}
+}
+
+/** Coordinates pointer regions with a root-compatible native mouse observer. */
+export class NativePointerScope {
+	private readonly regions = new Set<NativePointerRegion>();
+	private moved = false;
+	private disabled = false;
+	private disposed = false;
+
+	wrap(child: Component, callbacks: NativePointerRegionCallbacks): NativePointerRegion {
+		const region = new NativePointerRegion(child, callbacks, this);
+		region.setDisabled(this.disabled);
+		if (this.disposed) region.dispose();
+		return region;
+	}
+
+	createMouseObserver(requestRender?: () => void): NativePointerMouseObserver {
+		return {
+			beforeMouse: (event) => {
+				if (!this.disposed && event.type === "move" && event.button === "none") this.moved = false;
+			},
+			afterMouse: (event) => {
+				if (!this.isInRoot(event) || this.moved) return;
+				if (this.clearHover(event)) requestRender?.();
+			},
+		};
+	}
+
+	setDisabled(disabled: boolean): void {
+		this.disabled = disabled;
+		for (const region of this.regions) region.setDisabled(disabled);
+	}
+
+	invalidate(): void {
+		this.clearHover();
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		for (const region of [...this.regions]) region.dispose();
+	}
+
+	register(region: NativePointerRegion): void {
+		if (!this.disposed) this.regions.add(region);
+	}
+
+	unregister(region: NativePointerRegion): void {
+		this.regions.delete(region);
+	}
+
+	markMove(region: NativePointerRegion, event: TuiMouseEvent): void {
+		this.moved = true;
+		for (const candidate of this.regions) {
+			if (candidate !== region) candidate.clearHover(event);
+		}
+	}
+
+	private clearHover(event?: TuiMouseEvent): boolean {
+		let changed = false;
+		for (const region of this.regions) changed = region.clearHover(event) || changed;
+		return changed;
+	}
+
+	private isInRoot(event: TuiMouseEvent): boolean {
+		return !this.disposed && event.type === "move" && event.button === "none" &&
+			event.x >= 0 && event.x < event.width && event.y >= 0 && event.y < event.height;
+	}
+}
+
+export function createNativePointerScope(): NativePointerScope {
+	return new NativePointerScope();
+}

package/lib/native-review-cli.ts

@@ -5,6 +5,7 @@ import { dirname, isAbsolute, join, posix, win32 } from "node:path";
 import { promisify } from "node:util";
 import { PackageLocalGentleAiBinaryMissingError, resolveGentleAiBinary } from "./gentle-ai-binary.ts";
 import { GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV } from "./review-relay-contract.ts";
+import { decodeReviewAssessmentV1, type ReviewAssessmentV1 } from "./review-risk-assessment.ts";
 import {
 	REVIEW_INTEGRATION_CONTRACT,
 	decodeReviewAcknowledgedV1,
@@ -59,6 +60,7 @@ export const NATIVE_REVIEW_OPERATION = {
 	RECONCILE_AUTHORITY: "review/reconcile-authority",
 	REPAIR_LEGACY_ALIAS: "review/repair-legacy-alias",
 	MODE: "review/mode",
+	ASSESS: "review/assess",
 	REPAIR: "review/repair",
 	CAPTURE_RESULT: "review/capture-result",
 	CAPTURE_CORRECTION_PLAN: "review/capture-correction-plan",
@@ -109,6 +111,11 @@ export interface NativeReviewCli {
 	// outside the negotiated review-integration protocol — same shape as
 	// reviewStatus/reclaim above.
 	reviewMode?(request: NativeReviewModeRequest): Promise<NativeReviewModeResult>;
+	// Read-only risk assessment (gentle-ai#4295, landing in parallel with
+	// gentle-pi#662). Same plain-versioned shape as reviewMode/reviewStatus:
+	// an older binary without the verb, or any other process/decode failure,
+	// rejects the returned promise -- callers fail closed to `high` risk.
+	assess?(request: NativeReviewAssessRequest): Promise<ReviewAssessmentV1>;
 }
 
 export const NATIVE_REVIEW_MODE_OPERATION = {
@@ -151,6 +158,17 @@ export interface NativeReviewModeRequest {
 	signal?: AbortSignal;
 }
 
+// Read-only risk assessment request (gentle-pi#662). `baseRef` requires
+// explicit `committedOnly` acknowledgement, exactly like Native START's
+// baseRef/committedOnly pairing, because both select a committed range
+// instead of the ambient working tree.
+export interface NativeReviewAssessRequest {
+	cwd: string;
+	baseRef?: string;
+	committedOnly?: boolean;
+	signal?: AbortSignal;
+}
+
 export interface NativeReviewModeStatus {
 	global: NativeReviewModeValue;
 	cloneLocal: NativeReviewModeValue;
@@ -261,7 +279,6 @@ export interface NativeReviewAbandonRequest {
 	snapshotIdentity: string;
 	capturedLensResults: readonly string[];
 	findingsPresent: boolean;
-	evidenceRecordsPresent: boolean;
 	actor: string;
 	reason: string;
 	maintainerAuthorization: string;
@@ -498,8 +515,13 @@ export const NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION = {
 } as const;
 export type NativeReviewAuthorityEntryVersion = (typeof NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION)[keyof typeof NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION];
 
-export const NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS = NATIVE_REVIEW_AUTHORITY_STATUS;
-export type NativeReviewAuthorityEntryStatus = NativeReviewAuthorityStatus;
+export const NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS = {
+	...NATIVE_REVIEW_AUTHORITY_STATUS,
+	INCOMPLETE_STORE_ENTRY: "incomplete-store-entry",
+	HISTORICAL_PRE_RECEIPT: "historical-pre-receipt",
+	INVALIDATED: "invalidated",
+} as const;
+export type NativeReviewAuthorityEntryStatus = (typeof NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS)[keyof typeof NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS];
 
 export const NATIVE_REVIEW_LOCK_STATUS = {
 	OWNED: "owned",
@@ -541,6 +563,10 @@ export interface NativeReviewRecovery {
 	recoveredAt: string;
 	maintainerAuthorization?: string;
 }
+export interface NativeReviewDiscardedWorkSummary {
+	capturedLensResults: readonly string[];
+	findingsPresent: boolean;
+}
 export interface NativeReviewAuthorityEntry {
 	version: NativeReviewAuthorityEntryVersion;
 	lineageId?: string;
@@ -551,6 +577,7 @@ export interface NativeReviewAuthorityEntry {
 	snapshotIdentity?: string;
 	chainIdentity?: string;
 	recovery?: NativeReviewRecovery;
+	discardedWork?: NativeReviewDiscardedWorkSummary;
 	problems: readonly string[];
 }
 export interface NativeReviewAuthorityLock {
@@ -804,6 +831,18 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// consumes did not change between 2.5.0 and 2.6.0, so the columns match
 	// the 2.5.0 row.
 	"2.6.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// Ground-truthed against the published v2.7.0 binary installed from its
+	// signed archive: `review capabilities` on the v2 lane still advertises
+	// capabilities/v2.5 (protocol minor 5) and answers status/v7, consent/v3,
+	// and the `start/v4` continuation, all of which the decoders already read.
+	// `review mode status --json` still answers `gentle-ai.rdd-mode-status/v1`
+	// and `review validate --gate pre-commit` still answers
+	// `gentle-ai.review-gate-result/v1` carrying `delivery`, both verified
+	// against the binary. riskEvidence and hint stay dark for the same reason
+	// they have on every row since 2.2.0: still not proven to reach the
+	// negotiated START path Pi reads. The closed fields Pi consumes did not
+	// change between 2.6.0 and 2.7.0, so the columns match the 2.6.0 row.
+	"2.7.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 export interface NativeReviewProcessDiagnostics {
@@ -1046,8 +1085,15 @@ function decodeNativeReviewRecovery(value: unknown): NativeReviewRecovery {
 		...(recovery.maintainer_authorization === undefined ? {} : { maintainerAuthorization: requiredString(recovery.maintainer_authorization) }),
 	};
 }
+function decodeNativeReviewDiscardedWorkSummary(value: unknown): NativeReviewDiscardedWorkSummary {
+	const discardedWork = exactObject(value, ["captured_lens_results", "findings_present"]);
+	return {
+		capturedLensResults: stringArray(discardedWork.captured_lens_results),
+		findingsPresent: booleanValue(discardedWork.findings_present),
+	};
+}
 function decodeNativeReviewStatusEntry(value: unknown): NativeReviewAuthorityEntry {
-	const entry = exactObject(value, ["version", "path", "status", "problems"], ["lineage_id", "state", "revision", "snapshot_identity", "chain_identity", "recovery"]);
+	const entry = exactObject(value, ["version", "path", "status", "problems"], ["lineage_id", "state", "revision", "snapshot_identity", "chain_identity", "recovery", "discarded_work"]);
 	return {
 		version: enumString(entry.version, Object.values(NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION)) as NativeReviewAuthorityEntryVersion,
 		...(entry.lineage_id === undefined ? {} : { lineageId: requiredString(entry.lineage_id) }),
@@ -1058,6 +1104,7 @@ function decodeNativeReviewStatusEntry(value: unknown): NativeReviewAuthorityEnt
 		...(entry.snapshot_identity === undefined ? {} : { snapshotIdentity: sha256Identity(entry.snapshot_identity) }),
 		...(entry.chain_identity === undefined ? {} : { chainIdentity: requiredString(entry.chain_identity) }),
 		...(entry.recovery === undefined ? {} : { recovery: decodeNativeReviewRecovery(entry.recovery) }),
+		...(entry.discarded_work === undefined ? {} : { discardedWork: decodeNativeReviewDiscardedWorkSummary(entry.discarded_work) }),
 		problems: stringArray(entry.problems),
 	};
 }
@@ -1372,9 +1419,7 @@ class NativeReviewPlainCli {
 			if (!isCanonicalProcessString(value)) throw new TypeError(`Native ABANDON ${name} must be a non-empty, trimmed, NUL-free string`);
 		}
 		if (!Array.isArray(request.capturedLensResults) || request.capturedLensResults.some((entry) => !isCanonicalProcessString(entry))) throw new TypeError("Native ABANDON capturedLensResults must be an array of non-empty, trimmed, NUL-free strings");
-		for (const [name, value] of [["findingsPresent", request.findingsPresent], ["evidenceRecordsPresent", request.evidenceRecordsPresent]] as const) {
-			if (typeof value !== "boolean") throw new TypeError(`Native ABANDON ${name} must be a boolean`);
-		}
+		if (typeof request.findingsPresent !== "boolean") throw new TypeError("Native ABANDON findingsPresent must be a boolean");
 		if (request.maintainerAuthorization !== nativeReviewAbandonAuthorization(request)) throw new TypeError("Native ABANDON maintainerAuthorization must match the exact lineage, revision, snapshot, reason, discarded-work, and actor binding");
 		const execution = await this.execute(NATIVE_REVIEW_OPERATION.ABANDON, request.cwd, [
 			"review", "abandon", "--cwd", request.cwd,
@@ -1463,7 +1508,11 @@ class NativeReviewPlainCli {
 	}
 }
 
-export function nativeReviewAbandonAuthorization(request: Pick<NativeReviewAbandonRequest, "lineage" | "expectedRevision" | "snapshotIdentity" | "capturedLensResults" | "findingsPresent" | "evidenceRecordsPresent" | "actor" | "reason">): string {
+export function nativeReviewAbandonAuthorization(request: Pick<NativeReviewAbandonRequest, "lineage" | "expectedRevision" | "snapshotIdentity" | "capturedLensResults" | "findingsPresent" | "actor" | "reason">): string {
+	// gentle-ai 0ed9225f removed evidence records from the discarded-work summary,
+	// so the native v2 gate verifies an exact eight-line binding (schema, lineage,
+	// revision, snapshot_identity, reason, captured_lens_results, findings_present,
+	// actor) — there is no evidence_records_present line to derive or relay.
 	return [
 		"gentle-ai.review-abandon-authorization/v2",
 		`lineage=${request.lineage}`,
@@ -1472,7 +1521,6 @@ export function nativeReviewAbandonAuthorization(request: Pick<NativeReviewAband
 		`reason=${request.reason}`,
 		`captured_lens_results=${request.capturedLensResults.join(",")}`,
 		`findings_present=${request.findingsPresent}`,
-		`evidence_records_present=${request.evidenceRecordsPresent}`,
 		`actor=${request.actor.trim()}`,
 	].join("\n");
 }
@@ -1595,14 +1643,20 @@ function splitNativeConsentInvocation(invocation: string): readonly string[] {
 	let quote: "'" | '"' | undefined;
 	let escaping = false;
 	let started = false;
-	for (const character of invocation.trim()) {
+	const source = invocation.trim();
+	for (let index = 0; index < source.length; index += 1) {
+		const character = source[index]!;
 		if (escaping) {
 			current += character;
 			escaping = false;
 			started = true;
 			continue;
 		}
-		if (character === "\\" && quote !== "'") {
+		// Provider invocations are not shell commands. Keep every path backslash
+		// verbatim, including quoted UNC and drive-root paths. Outside quotes,
+		// only a backslash before whitespace joins a space-containing token.
+		const next = source[index + 1];
+		if (character === "\\" && quote === undefined && next !== undefined && /\s/.test(next)) {
 			escaping = true;
 			started = true;
 			continue;
@@ -1693,7 +1747,9 @@ function consentInvocationArguments(request: NativeReviewConsentAnswerRequest):
 	if (words[0] !== "gentle-ai" || words[1] !== "review" || words[2] !== "start") throw new NativeReviewConsentBindingError("consent-invocation-not-start", "Native consent invocation is not a provider review START");
 	const arguments_ = words.slice(1);
 	if (exactConsentOption(arguments_, "--contract") !== REVIEW_INTEGRATION_CONTRACT) throw new NativeReviewConsentBindingError("consent-invocation-contract-changed", "Native consent invocation contract changed");
-	if (exactConsentOption(arguments_, "--cwd") !== request.cwd) throw new NativeReviewConsentBindingError("consent-invocation-cwd-changed", "Native consent invocation repository binding changed");
+	const providerCwd = exactConsentOption(arguments_, "--cwd");
+	const requestedCwd = normalizeNativeReviewCwd(request.cwd);
+	if (normalizeNativeReviewCwd(providerCwd) !== requestedCwd) throw new NativeReviewConsentBindingError("consent-invocation-cwd-changed", "Native consent invocation repository binding changed");
 	if (exactConsentOption(arguments_, "--target") !== request.consent.targetIdentity) throw new NativeReviewConsentBindingError("consent-invocation-target-changed", "Native consent invocation target binding changed");
 	if (exactConsentOption(arguments_, "--projection") !== request.consent.projection) throw new NativeReviewConsentBindingError("consent-invocation-projection-changed", "Native consent invocation projection binding changed");
 	const lineageId = optionalConsentLineageOption(arguments_);
@@ -2193,6 +2249,26 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 		return decode(NATIVE_REVIEW_OPERATION.MODE, mutating, () => decodeNativeReviewMode(execution.body, request.operation));
 	}
 
+	// Read-only risk assessment (gentle-ai#4295, gentle-pi#662). Never mutates;
+	// an older binary without the verb, or any other process/decode failure,
+	// rejects -- callers (the `gentle_review` tool's `assess` operation) fail
+	// closed to `high`.
+	async assess(request: NativeReviewAssessRequest): Promise<ReviewAssessmentV1> {
+		if (request.baseRef !== undefined && !isCanonicalProcessString(request.baseRef)) throw new TypeError("Native ASSESS baseRef must be a non-empty, trimmed, NUL-free string");
+		if (request.baseRef !== undefined && request.committedOnly !== true) throw new TypeError("Native ASSESS baseRef requires explicit committedOnly acknowledgement");
+		if (request.baseRef === undefined && request.committedOnly !== undefined) throw new TypeError("Native ASSESS committedOnly requires an explicit baseRef");
+		const cwd = await canonicalNativeReviewCwd(request.cwd);
+		const execution = await this.invoke(
+			NATIVE_REVIEW_OPERATION.ASSESS,
+			cwd,
+			["review", "assess", "--cwd", cwd, ...(request.baseRef === undefined ? [] : ["--base-ref", request.baseRef, "--committed-only"]), "--json"],
+			false,
+			request.signal,
+			this.executablePath(NATIVE_REVIEW_OPERATION.ASSESS, false),
+		);
+		return decode(NATIVE_REVIEW_OPERATION.ASSESS, false, () => decodeReviewAssessmentV1(execution.body));
+	}
+
 	// Recovery commands are version-gated plain CLI operations outside the
 	// negotiated integration-v1 contract, exactly like reviewStatus.
 	reclaim(request: NativeReviewReclaimRequest): Promise<NativeReviewRecoveryResult> {

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

@@ -0,0 +1,177 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, lstatSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { conservativeOwnerDeathProofV1 } from "./review-lock.ts";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const BOOT_UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+export interface CandidateViewOwner {
+	version: 1;
+	uuid: string;
+	token: string;
+	pid: number;
+	host: string | null;
+	root: string;
+	commonDir: string;
+}
+type Git = (args: readonly string[]) => string;
+
+// A hostname or a repository-local nonce cannot prove that a PID is local.
+// Bind to the kernel boot and, on Linux, its PID namespace. Unsupported or
+// unavailable provenance disables reclamation (including across reboots).
+function localHost(): string | null {
+	try {
+		if (process.platform === "darwin") {
+			const boot = execFileSync("/usr/sbin/sysctl", ["-n", "kern.bootsessionuuid"], { encoding: "utf8", timeout: 1000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"] }).trim();
+			if (BOOT_UUID.test(boot)) return `darwin:${boot.toLowerCase()}`;
+		}
+		if (process.platform === "linux") {
+			const boot = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+			const namespace = readlinkSync("/proc/self/ns/pid");
+			if (BOOT_UUID.test(boot) && /^pid:\[\d+\]$/.test(namespace)) return `linux:${boot}:${namespace}`;
+		}
+	} catch { /* No remote/PID-only fallback. */ }
+	return null;
+}
+
+function directory(path: string, privateMode = false): string {
+	const stat = lstatSync(path);
+	if (!stat.isDirectory() || stat.isSymbolicLink() || realpathSync(path) !== path ||
+		(privateMode && (stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0))) throw new Error("Unsafe candidate owner directory");
+	return `${stat.dev}:${stat.ino}`;
+}
+
+export function assertCandidateOwnerParent(commonDir: string): string {
+	directory(commonDir);
+	directory(join(commonDir, "gentle-ai"));
+	const parent = join(commonDir, "gentle-ai", "candidate-views");
+	directory(parent, true);
+	return parent;
+}
+
+function regular(path: string, privateMode = false): string {
+	const stat = lstatSync(path);
+	if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || realpathSync(path) !== path || stat.size > 16384 ||
+		(privateMode && (stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600))) throw new Error("Unsafe candidate owner file");
+	return `${stat.dev}:${stat.ino}`;
+}
+
+function syncDirectory(path: string): void {
+	const fd = openSync(path, "r");
+	try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function exclusiveFile(path: string, content: string): void {
+	const fd = openSync(path, "wx", 0o600);
+	try { writeFileSync(fd, content); fsyncSync(fd); } finally { closeSync(fd); }
+	syncDirectory(dirname(path));
+}
+
+function markerPath(root: string): string { return `${root}.owner.json`; }
+
+export function createCandidateOwner(commonDir: string, root: string): CandidateViewOwner {
+	const parent = assertCandidateOwnerParent(commonDir);
+	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 };
+	// Any write/fsync failure aborts creation BEFORE Git can register the view.
+	// An incomplete marker is retained, never guessed into ownership.
+	exclusiveFile(markerPath(root), JSON.stringify(owner));
+	syncDirectory(dirname(parent));
+	syncDirectory(commonDir);
+	return Object.freeze(owner);
+}
+
+function readOwner(commonDir: string, root: string): CandidateViewOwner {
+	const parent = assertCandidateOwnerParent(commonDir);
+	if (!UUID.test(basename(root)) || root !== join(parent, basename(root))) throw new Error("Candidate owner escaped parent");
+	regular(markerPath(root), true);
+	const owner = JSON.parse(readFileSync(markerPath(root), "utf8")) as CandidateViewOwner;
+	if (!owner || Object.keys(owner).sort().join(",") !== "commonDir,host,pid,root,token,uuid,version" || owner.version !== 1 ||
+		owner.uuid !== basename(root) || !UUID.test(owner.token) || !Number.isSafeInteger(owner.pid) || owner.pid <= 0 ||
+		owner.root !== root || owner.commonDir !== commonDir || !(owner.host === null || typeof owner.host === "string")) throw new Error("Malformed candidate owner");
+	return owner;
+}
+
+function dead(owner: CandidateViewOwner): boolean {
+	return owner.host !== null && owner.host === localHost() && conservativeOwnerDeathProofV1({
+		pid: owner.pid, token: owner.token, owner_hash: "", repository_id: owner.commonDir, authority_id: owner.uuid,
+	});
+}
+
+function registration(root: string, commonDir: string, git: Git): string {
+	const rows = git(["worktree", "list", "--porcelain", "-z"]).split("\0\0");
+	const matching = rows.filter((row) => row.split("\0")[0] === `worktree ${root}`);
+	if (matching.length !== 1 || matching[0]!.split("\0").some((field) => /^(locked|prunable)( |$)/.test(field))) throw new Error("Candidate registration is ambiguous");
+	const gitFile = join(root, ".git");
+	regular(gitFile);
+	const pointer = readFileSync(gitFile, "utf8");
+	if (!pointer.startsWith("gitdir: ") || !pointer.endsWith("\n")) throw new Error("Unsafe candidate Git pointer");
+	const admin = pointer.slice(8, -1);
+	if (dirname(admin) !== join(commonDir, "worktrees")) throw new Error("Candidate admin escaped common directory");
+	directory(join(commonDir, "worktrees"));
+	directory(admin);
+	regular(join(admin, "gitdir"));
+	regular(join(admin, "commondir"));
+	if (readFileSync(join(admin, "gitdir"), "utf8") !== `${gitFile}\n` ||
+		resolve(admin, readFileSync(join(admin, "commondir"), "utf8").trim()) !== commonDir) throw new Error("Candidate Git backlinks changed");
+	return matching[0]! + pointer;
+}
+
+export function removeCandidateOwner(owner: CandidateViewOwner, git: Git, makeWritable: (root: string) => void, orphan = false): void {
+	const { root, commonDir } = owner;
+	const parent = assertCandidateOwnerParent(commonDir);
+	const expected = JSON.stringify(owner);
+	const parentIdentity = directory(parent, true);
+	const markerIdentity = regular(markerPath(root), true);
+	const checkOwner = (): void => {
+		if (directory(parent, true) !== parentIdentity || regular(markerPath(root), true) !== markerIdentity ||
+			JSON.stringify(readOwner(commonDir, root)) !== expected || (orphan ? !dead(owner) : owner.pid !== process.pid)) throw new Error("Candidate ownership changed");
+	};
+	checkOwner();
+	const lock = `${root}.reaper-lock`;
+	const token = randomUUID();
+	exclusiveFile(lock, token); // EEXIST is final; unknown/stale locks are never stolen.
+	const lockIdentity = regular(lock, true);
+	const checkLock = (): void => {
+		if (regular(lock, true) !== lockIdentity || readFileSync(lock, "utf8") !== token) throw new Error("Candidate reaper lock changed");
+	};
+	try {
+		checkOwner();
+		const identity = [directory(parent, true), directory(root), regular(markerPath(root), true)];
+		const registered = registration(root, commonDir, git);
+		checkOwner();
+		checkLock();
+		makeWritable(root);
+		// Git and chmod are race boundaries: repeat path, owner, lock, and exact
+		// registration proofs immediately before asking Git to remove this root.
+		if (registration(root, commonDir, git) !== registered ||
+			JSON.stringify([directory(parent, true), directory(root), regular(markerPath(root), true)]) !== JSON.stringify(identity)) throw new Error("Candidate cleanup identity changed");
+		checkOwner();
+		checkLock();
+		git(["worktree", "remove", "--force", root]);
+		// Git failure or incomplete removal must never trigger recursive rm.
+		if (lstatSync(root, { throwIfNoEntry: false }) || git(["worktree", "list", "--porcelain", "-z"]).split("\0").includes(`worktree ${root}`)) throw new Error("Candidate removal is incomplete");
+		checkOwner();
+		checkLock();
+		unlinkSync(markerPath(root));
+		syncDirectory(parent);
+	} finally {
+		// Only release this exact lock, even when the deletion itself failed.
+		try { assertCandidateOwnerParent(commonDir); checkLock(); unlinkSync(lock); syncDirectory(parent); } catch {}
+	}
+}
+
+export function sweepCandidateOwners(commonDir: string, git: Git, makeWritable: (root: string) => void): void {
+	try {
+		const parent = assertCandidateOwnerParent(commonDir);
+		for (const name of readdirSync(parent)) {
+			if (!name.endsWith(".owner.json")) continue;
+			try {
+				const owner = readOwner(commonDir, join(parent, name.slice(0, -11)));
+				if (dead(owner)) removeCandidateOwner(owner, git, makeWritable, true);
+			} catch { /* Unknown, legacy, unsafe, unregistered, and contended entries survive. */ }
+		}
+	} catch { /* Startup/materialization sweeps are best-effort; never create a store. */ }
+}