@caupulican/pi-adaptative 0.81.41 → 0.81.42

package/dist/core/delegation/worker-write-reservation-coordinator.d.ts

@@ -0,0 +1,38 @@
+import type { AttemptRuntimeState } from "../orchestration/task-runtime.ts";
+import type { WorkerExecutionPlan } from "./worker-execution-policy.ts";
+export type WorkerWriteReservationAdmission = {
+    kind: "granted";
+} | {
+    kind: "blocked";
+} | {
+    kind: "denied";
+    reasonCode: "write_reservation_scope_invalid" | "write_reservation_unavailable";
+};
+export interface WorkerWriteReservationCoordinatorOptions {
+    agentDir: string;
+    getCwd(): string;
+    getParentSessionId(): string;
+    ownerId: string;
+    drainQueuedWorkers(): void;
+    warn(message: string): void;
+    isProcessAlive?(pid: number): boolean;
+}
+/**
+ * Owns one controller process's write-reservation lifecycle: admission, exact-fence release,
+ * event-driven queue wakeup, and fail-closed recovery of positively dead owners.
+ */
+export declare class WorkerWriteReservationCoordinator {
+    private readonly options;
+    private readonly store;
+    private readonly leases;
+    private watchDispose;
+    constructor(options: WorkerWriteReservationCoordinatorOptions);
+    acquire(laneId: string, attempt: Pick<AttemptRuntimeState, "attemptId" | "lease">, plan: Pick<WorkerExecutionPlan, "writeEnabled" | "writePaths">): WorkerWriteReservationAdmission;
+    hasFenceMismatch(laneId: string, attemptId: string, fencingToken: number): boolean;
+    release(laneId: string, expectedAttemptId?: string, expectedFencingToken?: number): void;
+    recoverProvenStale(): void;
+    dispose(): void;
+    private workspace;
+    private ensureWatch;
+}
+//# sourceMappingURL=worker-write-reservation-coordinator.d.ts.map

package/dist/core/delegation/worker-write-reservation-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-write-reservation-coordinator.d.ts","sourceRoot":"","sources":["../../../src/core/delegation/worker-write-reservation-coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAIxE,MAAM,MAAM,+BAA+B,GACxC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,UAAU,EAAE,iCAAiC,GAAG,+BAA+B,CAAA;CAAE,CAAC;AAEvG,MAAM,WAAW,wCAAwC;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,IAAI,MAAM,CAAC;IACjB,kBAAkB,IAAI,MAAM,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,IAAI,IAAI,CAAC;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACtC;AAED;;;GAGG;AACH,qBAAa,iCAAiC;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2C;IACnE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkD;IACzE,OAAO,CAAC,YAAY,CAA2B;IAE/C,YAAY,OAAO,EAAE,wCAAwC,EAG5D;IAED,OAAO,CACN,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,GAAG,OAAO,CAAC,EACzD,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,cAAc,GAAG,YAAY,CAAC,GAC5D,+BAA+B,CAkCjC;IAED,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAGjF;IAED,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAcvF;IAED,kBAAkB,IAAI,IAAI,CAqBzB;IAED,OAAO,IAAI,IAAI,CAGd;IAED,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,WAAW;CAInB","sourcesContent":["import type { AttemptRuntimeState } from \"../orchestration/task-runtime.ts\";\nimport type { WorkerExecutionPlan } from \"./worker-execution-policy.ts\";\nimport { isLocalProcessAlive, localWorkerProcessOwnerLiveness } from \"./worker-process-owner.ts\";\nimport { type WorkerWriteReservationLease, WorkerWriteReservationStore } from \"./worker-write-reservation.ts\";\n\nexport type WorkerWriteReservationAdmission =\n\t| { kind: \"granted\" }\n\t| { kind: \"blocked\" }\n\t| { kind: \"denied\"; reasonCode: \"write_reservation_scope_invalid\" | \"write_reservation_unavailable\" };\n\nexport interface WorkerWriteReservationCoordinatorOptions {\n\tagentDir: string;\n\tgetCwd(): string;\n\tgetParentSessionId(): string;\n\townerId: string;\n\tdrainQueuedWorkers(): void;\n\twarn(message: string): void;\n\tisProcessAlive?(pid: number): boolean;\n}\n\n/**\n * Owns one controller process's write-reservation lifecycle: admission, exact-fence release,\n * event-driven queue wakeup, and fail-closed recovery of positively dead owners.\n */\nexport class WorkerWriteReservationCoordinator {\n\tprivate readonly options: WorkerWriteReservationCoordinatorOptions;\n\tprivate readonly store: WorkerWriteReservationStore;\n\tprivate readonly leases = new Map<string, WorkerWriteReservationLease>();\n\tprivate watchDispose: (() => void) | undefined;\n\n\tconstructor(options: WorkerWriteReservationCoordinatorOptions) {\n\t\tthis.options = options;\n\t\tthis.store = new WorkerWriteReservationStore({ agentDir: options.agentDir });\n\t}\n\n\tacquire(\n\t\tlaneId: string,\n\t\tattempt: Pick<AttemptRuntimeState, \"attemptId\" | \"lease\">,\n\t\tplan: Pick<WorkerExecutionPlan, \"writeEnabled\" | \"writePaths\">,\n\t): WorkerWriteReservationAdmission {\n\t\tif (!plan.writeEnabled || plan.writePaths.length === 0) return { kind: \"granted\" };\n\t\tconst fencingToken = (attempt.lease?.fencingToken ?? 0) + 1;\n\t\tconst current = this.leases.get(laneId);\n\t\tif (current && current.attemptId === attempt.attemptId && current.fencingToken === fencingToken) {\n\t\t\treturn { kind: \"granted\" };\n\t\t}\n\t\ttry {\n\t\t\tconst result = this.store.acquire({\n\t\t\t\tparentSessionId: this.options.getParentSessionId(),\n\t\t\t\townerId: this.options.ownerId,\n\t\t\t\ttaskId: laneId,\n\t\t\t\tattemptId: attempt.attemptId,\n\t\t\t\tfencingToken,\n\t\t\t\taccess: \"write\",\n\t\t\t\tworkspace: this.workspace(),\n\t\t\t\twriteScopes: plan.writePaths,\n\t\t\t});\n\t\t\tif (result.kind !== \"granted\" || !result.lease) {\n\t\t\t\tthis.ensureWatch();\n\t\t\t\treturn { kind: \"blocked\" };\n\t\t\t}\n\t\t\tthis.leases.set(laneId, result.lease);\n\t\t\treturn { kind: \"granted\" };\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\tthis.options.warn(`Worker write reservation denied: ${message}`);\n\t\t\treturn {\n\t\t\t\tkind: \"denied\",\n\t\t\t\treasonCode: message.includes(\"within the execution root\")\n\t\t\t\t\t? \"write_reservation_scope_invalid\"\n\t\t\t\t\t: \"write_reservation_unavailable\",\n\t\t\t};\n\t\t}\n\t}\n\n\thasFenceMismatch(laneId: string, attemptId: string, fencingToken: number): boolean {\n\t\tconst lease = this.leases.get(laneId);\n\t\treturn lease !== undefined && (lease.attemptId !== attemptId || lease.fencingToken !== fencingToken);\n\t}\n\n\trelease(laneId: string, expectedAttemptId?: string, expectedFencingToken?: number): void {\n\t\tconst held = this.leases.get(laneId);\n\t\tif (!held) return;\n\t\tif (expectedAttemptId !== undefined && held.attemptId !== expectedAttemptId) return;\n\t\tif (expectedFencingToken !== undefined && held.fencingToken !== expectedFencingToken) return;\n\t\ttry {\n\t\t\tthis.store.release(held);\n\t\t} catch (error) {\n\t\t\tthis.options.warn(\n\t\t\t\t`Failed to release worker write reservation ${laneId}: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t} finally {\n\t\t\tif (this.leases.get(laneId) === held) this.leases.delete(laneId);\n\t\t}\n\t}\n\n\trecoverProvenStale(): void {\n\t\tconst discovered = this.store.recover({ workspace: this.workspace(), evidence: [] });\n\t\tconst evidence = discovered.outcomes.map((outcome) => ({\n\t\t\treservationId: outcome.reservationId,\n\t\t\tstate:\n\t\t\t\tlocalWorkerProcessOwnerLiveness(\n\t\t\t\t\toutcome.lease.ownerId,\n\t\t\t\t\tthis.options.isProcessAlive ?? isLocalProcessAlive,\n\t\t\t\t) === \"dead\"\n\t\t\t\t\t? (\"not_live\" as const)\n\t\t\t\t\t: (\"unknown\" as const),\n\t\t}));\n\t\tfor (const outcome of this.store.recover({ workspace: this.workspace(), evidence }).outcomes) {\n\t\t\tif (outcome.kind !== \"stale\") continue;\n\t\t\tconst released = this.store.release(outcome.lease);\n\t\t\tif (released.kind !== \"released\" && released.kind !== \"not_found\") {\n\t\t\t\tthis.options.warn(\n\t\t\t\t\t`Stale worker write reservation ${outcome.reservationId} was not released (${released.kind}).`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\tdispose(): void {\n\t\tthis.watchDispose?.();\n\t\tthis.watchDispose = undefined;\n\t}\n\n\tprivate workspace() {\n\t\tconst cwd = this.options.getCwd();\n\t\treturn { repositoryRoot: cwd, executionRoot: cwd };\n\t}\n\n\tprivate ensureWatch(): void {\n\t\tif (this.watchDispose) return;\n\t\tthis.watchDispose = this.store.watchAvailability(this.workspace(), () => this.options.drainQueuedWorkers());\n\t}\n}\n"]}

package/dist/core/delegation/worker-write-reservation-coordinator.js

@@ -0,0 +1,107 @@
+import { isLocalProcessAlive, localWorkerProcessOwnerLiveness } from "./worker-process-owner.js";
+import { WorkerWriteReservationStore } from "./worker-write-reservation.js";
+/**
+ * Owns one controller process's write-reservation lifecycle: admission, exact-fence release,
+ * event-driven queue wakeup, and fail-closed recovery of positively dead owners.
+ */
+export class WorkerWriteReservationCoordinator {
+    options;
+    store;
+    leases = new Map();
+    watchDispose;
+    constructor(options) {
+        this.options = options;
+        this.store = new WorkerWriteReservationStore({ agentDir: options.agentDir });
+    }
+    acquire(laneId, attempt, plan) {
+        if (!plan.writeEnabled || plan.writePaths.length === 0)
+            return { kind: "granted" };
+        const fencingToken = (attempt.lease?.fencingToken ?? 0) + 1;
+        const current = this.leases.get(laneId);
+        if (current && current.attemptId === attempt.attemptId && current.fencingToken === fencingToken) {
+            return { kind: "granted" };
+        }
+        try {
+            const result = this.store.acquire({
+                parentSessionId: this.options.getParentSessionId(),
+                ownerId: this.options.ownerId,
+                taskId: laneId,
+                attemptId: attempt.attemptId,
+                fencingToken,
+                access: "write",
+                workspace: this.workspace(),
+                writeScopes: plan.writePaths,
+            });
+            if (result.kind !== "granted" || !result.lease) {
+                this.ensureWatch();
+                return { kind: "blocked" };
+            }
+            this.leases.set(laneId, result.lease);
+            return { kind: "granted" };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.options.warn(`Worker write reservation denied: ${message}`);
+            return {
+                kind: "denied",
+                reasonCode: message.includes("within the execution root")
+                    ? "write_reservation_scope_invalid"
+                    : "write_reservation_unavailable",
+            };
+        }
+    }
+    hasFenceMismatch(laneId, attemptId, fencingToken) {
+        const lease = this.leases.get(laneId);
+        return lease !== undefined && (lease.attemptId !== attemptId || lease.fencingToken !== fencingToken);
+    }
+    release(laneId, expectedAttemptId, expectedFencingToken) {
+        const held = this.leases.get(laneId);
+        if (!held)
+            return;
+        if (expectedAttemptId !== undefined && held.attemptId !== expectedAttemptId)
+            return;
+        if (expectedFencingToken !== undefined && held.fencingToken !== expectedFencingToken)
+            return;
+        try {
+            this.store.release(held);
+        }
+        catch (error) {
+            this.options.warn(`Failed to release worker write reservation ${laneId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            if (this.leases.get(laneId) === held)
+                this.leases.delete(laneId);
+        }
+    }
+    recoverProvenStale() {
+        const discovered = this.store.recover({ workspace: this.workspace(), evidence: [] });
+        const evidence = discovered.outcomes.map((outcome) => ({
+            reservationId: outcome.reservationId,
+            state: localWorkerProcessOwnerLiveness(outcome.lease.ownerId, this.options.isProcessAlive ?? isLocalProcessAlive) === "dead"
+                ? "not_live"
+                : "unknown",
+        }));
+        for (const outcome of this.store.recover({ workspace: this.workspace(), evidence }).outcomes) {
+            if (outcome.kind !== "stale")
+                continue;
+            const released = this.store.release(outcome.lease);
+            if (released.kind !== "released" && released.kind !== "not_found") {
+                this.options.warn(`Stale worker write reservation ${outcome.reservationId} was not released (${released.kind}).`);
+            }
+        }
+    }
+    dispose() {
+        this.watchDispose?.();
+        this.watchDispose = undefined;
+    }
+    workspace() {
+        const cwd = this.options.getCwd();
+        return { repositoryRoot: cwd, executionRoot: cwd };
+    }
+    ensureWatch() {
+        if (this.watchDispose)
+            return;
+        this.watchDispose = this.store.watchAvailability(this.workspace(), () => this.options.drainQueuedWorkers());
+    }
+}
+//# sourceMappingURL=worker-write-reservation-coordinator.js.map

package/dist/core/delegation/worker-write-reservation-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-write-reservation-coordinator.js","sourceRoot":"","sources":["../../../src/core/delegation/worker-write-reservation-coordinator.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AttemptRuntimeState } from \"../orchestration/task-runtime.ts\";\nimport type { WorkerExecutionPlan } from \"./worker-execution-policy.ts\";\nimport { isLocalProcessAlive, localWorkerProcessOwnerLiveness } from \"./worker-process-owner.ts\";\nimport { type WorkerWriteReservationLease, WorkerWriteReservationStore } from \"./worker-write-reservation.ts\";\n\nexport type WorkerWriteReservationAdmission =\n\t| { kind: \"granted\" }\n\t| { kind: \"blocked\" }\n\t| { kind: \"denied\"; reasonCode: \"write_reservation_scope_invalid\" | \"write_reservation_unavailable\" };\n\nexport interface WorkerWriteReservationCoordinatorOptions {\n\tagentDir: string;\n\tgetCwd(): string;\n\tgetParentSessionId(): string;\n\townerId: string;\n\tdrainQueuedWorkers(): void;\n\twarn(message: string): void;\n\tisProcessAlive?(pid: number): boolean;\n}\n\n/**\n * Owns one controller process's write-reservation lifecycle: admission, exact-fence release,\n * event-driven queue wakeup, and fail-closed recovery of positively dead owners.\n */\nexport class WorkerWriteReservationCoordinator {\n\tprivate readonly options: WorkerWriteReservationCoordinatorOptions;\n\tprivate readonly store: WorkerWriteReservationStore;\n\tprivate readonly leases = new Map<string, WorkerWriteReservationLease>();\n\tprivate watchDispose: (() => void) | undefined;\n\n\tconstructor(options: WorkerWriteReservationCoordinatorOptions) {\n\t\tthis.options = options;\n\t\tthis.store = new WorkerWriteReservationStore({ agentDir: options.agentDir });\n\t}\n\n\tacquire(\n\t\tlaneId: string,\n\t\tattempt: Pick<AttemptRuntimeState, \"attemptId\" | \"lease\">,\n\t\tplan: Pick<WorkerExecutionPlan, \"writeEnabled\" | \"writePaths\">,\n\t): WorkerWriteReservationAdmission {\n\t\tif (!plan.writeEnabled || plan.writePaths.length === 0) return { kind: \"granted\" };\n\t\tconst fencingToken = (attempt.lease?.fencingToken ?? 0) + 1;\n\t\tconst current = this.leases.get(laneId);\n\t\tif (current && current.attemptId === attempt.attemptId && current.fencingToken === fencingToken) {\n\t\t\treturn { kind: \"granted\" };\n\t\t}\n\t\ttry {\n\t\t\tconst result = this.store.acquire({\n\t\t\t\tparentSessionId: this.options.getParentSessionId(),\n\t\t\t\townerId: this.options.ownerId,\n\t\t\t\ttaskId: laneId,\n\t\t\t\tattemptId: attempt.attemptId,\n\t\t\t\tfencingToken,\n\t\t\t\taccess: \"write\",\n\t\t\t\tworkspace: this.workspace(),\n\t\t\t\twriteScopes: plan.writePaths,\n\t\t\t});\n\t\t\tif (result.kind !== \"granted\" || !result.lease) {\n\t\t\t\tthis.ensureWatch();\n\t\t\t\treturn { kind: \"blocked\" };\n\t\t\t}\n\t\t\tthis.leases.set(laneId, result.lease);\n\t\t\treturn { kind: \"granted\" };\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\tthis.options.warn(`Worker write reservation denied: ${message}`);\n\t\t\treturn {\n\t\t\t\tkind: \"denied\",\n\t\t\t\treasonCode: message.includes(\"within the execution root\")\n\t\t\t\t\t? \"write_reservation_scope_invalid\"\n\t\t\t\t\t: \"write_reservation_unavailable\",\n\t\t\t};\n\t\t}\n\t}\n\n\thasFenceMismatch(laneId: string, attemptId: string, fencingToken: number): boolean {\n\t\tconst lease = this.leases.get(laneId);\n\t\treturn lease !== undefined && (lease.attemptId !== attemptId || lease.fencingToken !== fencingToken);\n\t}\n\n\trelease(laneId: string, expectedAttemptId?: string, expectedFencingToken?: number): void {\n\t\tconst held = this.leases.get(laneId);\n\t\tif (!held) return;\n\t\tif (expectedAttemptId !== undefined && held.attemptId !== expectedAttemptId) return;\n\t\tif (expectedFencingToken !== undefined && held.fencingToken !== expectedFencingToken) return;\n\t\ttry {\n\t\t\tthis.store.release(held);\n\t\t} catch (error) {\n\t\t\tthis.options.warn(\n\t\t\t\t`Failed to release worker write reservation ${laneId}: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t} finally {\n\t\t\tif (this.leases.get(laneId) === held) this.leases.delete(laneId);\n\t\t}\n\t}\n\n\trecoverProvenStale(): void {\n\t\tconst discovered = this.store.recover({ workspace: this.workspace(), evidence: [] });\n\t\tconst evidence = discovered.outcomes.map((outcome) => ({\n\t\t\treservationId: outcome.reservationId,\n\t\t\tstate:\n\t\t\t\tlocalWorkerProcessOwnerLiveness(\n\t\t\t\t\toutcome.lease.ownerId,\n\t\t\t\t\tthis.options.isProcessAlive ?? isLocalProcessAlive,\n\t\t\t\t) === \"dead\"\n\t\t\t\t\t? (\"not_live\" as const)\n\t\t\t\t\t: (\"unknown\" as const),\n\t\t}));\n\t\tfor (const outcome of this.store.recover({ workspace: this.workspace(), evidence }).outcomes) {\n\t\t\tif (outcome.kind !== \"stale\") continue;\n\t\t\tconst released = this.store.release(outcome.lease);\n\t\t\tif (released.kind !== \"released\" && released.kind !== \"not_found\") {\n\t\t\t\tthis.options.warn(\n\t\t\t\t\t`Stale worker write reservation ${outcome.reservationId} was not released (${released.kind}).`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\tdispose(): void {\n\t\tthis.watchDispose?.();\n\t\tthis.watchDispose = undefined;\n\t}\n\n\tprivate workspace() {\n\t\tconst cwd = this.options.getCwd();\n\t\treturn { repositoryRoot: cwd, executionRoot: cwd };\n\t}\n\n\tprivate ensureWatch(): void {\n\t\tif (this.watchDispose) return;\n\t\tthis.watchDispose = this.store.watchAvailability(this.workspace(), () => this.options.drainQueuedWorkers());\n\t}\n}\n"]}

package/dist/core/delegation/worker-write-reservation.d.ts

@@ -0,0 +1,90 @@
+import { type FSWatcher } from "node:fs";
+type WatchDirectory = (directory: string, options: {
+    persistent: boolean;
+}, listener: (eventType: string, fileName: string | Buffer | null) => void) => FSWatcher;
+export interface WorkerWriteReservationWorkspace {
+    /** Canonical repository/workspace root shared by primary and isolated worktrees. */
+    repositoryRoot: string;
+    /** Actual checkout used by this attempt. A non-primary checkout requires an isolation identity. */
+    executionRoot: string;
+    /** Durable worktree identity supplied by the worktree owner, never a model-provided label. */
+    isolatedWorktreeId?: string;
+}
+export interface WorkerWriteReservationRequest {
+    parentSessionId: string;
+    /** Exact pi-owned process instance that acquired this reservation. */
+    ownerId: string;
+    taskId: string;
+    attemptId: string;
+    fencingToken: number;
+    access: "read" | "write";
+    workspace: WorkerWriteReservationWorkspace;
+    /** Absolute authorized write roots. They are resolved before persistence. */
+    writeScopes: readonly string[];
+}
+export interface WorkerWriteReservationLease {
+    filePath: string;
+    reservationId: string;
+    parentSessionId: string;
+    ownerId: string;
+    taskId: string;
+    attemptId: string;
+    fencingToken: number;
+    repositoryRoot: string;
+    executionRoot: string;
+    executionIdentity: string;
+    isolatedWorktreeId?: string;
+    writeScopes: readonly string[];
+}
+export type WorkerWriteReservationAcquireResult = {
+    kind: "granted";
+    lease?: WorkerWriteReservationLease;
+} | {
+    kind: "blocked";
+    reasonCode: "overlapping_write_scope" | "attempt_reservation_conflict" | "reservation_capacity_reached";
+    conflictingReservationIds?: readonly string[];
+};
+export type WorkerWriteReservationReleaseResult = {
+    kind: "released";
+} | {
+    kind: "stale_fence";
+} | {
+    kind: "not_found";
+};
+export type WorkerWriteReservationEvidenceState = "live" | "not_live" | "unknown";
+export interface WorkerWriteReservationRecoveryEvidence {
+    reservationId: string;
+    state: WorkerWriteReservationEvidenceState;
+}
+export interface WorkerWriteReservationRecoveryRequest {
+    workspace: WorkerWriteReservationWorkspace;
+    /** Caller-owned lease observations. This store never polls process state or worker output. */
+    evidence: readonly WorkerWriteReservationRecoveryEvidence[];
+}
+export interface WorkerWriteReservationRecoveryOutcome {
+    kind: "active" | "stale" | "inspection_required";
+    reservationId: string;
+    lease: WorkerWriteReservationLease;
+}
+/**
+ * Cross-process, agent-owned admission seam for concurrent worker mutations. It owns only
+ * reservations; lifecycle, process liveness, and terminal status remain controller concerns.
+ */
+export declare class WorkerWriteReservationStore {
+    private readonly agentDir;
+    private readonly watchDirectory;
+    constructor(options: {
+        agentDir: string;
+        watchDirectory?: WatchDirectory;
+    });
+    acquire(request: WorkerWriteReservationRequest): WorkerWriteReservationAcquireResult;
+    release(lease: WorkerWriteReservationLease): WorkerWriteReservationReleaseResult;
+    /** Event-driven cross-process wakeup for queued write admission; caller owns disposal. */
+    watchAvailability(workspace: WorkerWriteReservationWorkspace, listener: () => void): () => void;
+    recover(request: WorkerWriteReservationRecoveryRequest): {
+        outcomes: WorkerWriteReservationRecoveryOutcome[];
+    };
+    private readLocked;
+}
+export {};
+//# sourceMappingURL=worker-write-reservation.d.ts.map

package/dist/core/delegation/worker-write-reservation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-write-reservation.d.ts","sourceRoot":"","sources":["../../../src/core/delegation/worker-write-reservation.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport { existsSync, type FSWatcher, mkdirSync, unlinkSync, watch } from \"node:fs\";\nimport { basename, dirname } from \"node:path\";\nimport { stateFile } from \"../agent-paths.ts\";\nimport {\n\tcanonicalPathScopeIdentity,\n\tisPathWithinScope,\n\tpathScopesOverlap,\n\tsafeRealpathSync,\n} from \"../autonomy/path-scope.ts\";\nimport { withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\nimport { readBoundedTextFileSync } from \"../util/bounded-file.ts\";\nimport { requireBoundedTrimmedText } from \"../util/bounded-value.ts\";\nimport { parseLocalWorkerProcessOwnerId } from \"./worker-process-owner.ts\";\n\nconst SCHEMA_VERSION = 1;\nconst MAX_IDENTIFIER_CHARS = 256;\nconst MAX_PATH_CHARS = 4096;\nconst MAX_SCOPES = 32;\nconst MAX_RESERVATIONS = 64;\nconst MAX_FILE_BYTES = 128 * 1024;\nconst availabilityListeners = new Map<string, Set<() => void>>();\n\ntype WatchDirectory = (\n\tdirectory: string,\n\toptions: { persistent: boolean },\n\tlistener: (eventType: string, fileName: string | Buffer | null) => void,\n) => FSWatcher;\n\nexport interface WorkerWriteReservationWorkspace {\n\t/** Canonical repository/workspace root shared by primary and isolated worktrees. */\n\trepositoryRoot: string;\n\t/** Actual checkout used by this attempt. A non-primary checkout requires an isolation identity. */\n\texecutionRoot: string;\n\t/** Durable worktree identity supplied by the worktree owner, never a model-provided label. */\n\tisolatedWorktreeId?: string;\n}\n\nexport interface WorkerWriteReservationRequest {\n\tparentSessionId: string;\n\t/** Exact pi-owned process instance that acquired this reservation. */\n\townerId: string;\n\ttaskId: string;\n\tattemptId: string;\n\tfencingToken: number;\n\taccess: \"read\" | \"write\";\n\tworkspace: WorkerWriteReservationWorkspace;\n\t/** Absolute authorized write roots. They are resolved before persistence. */\n\twriteScopes: readonly string[];\n}\n\nexport interface WorkerWriteReservationLease {\n\tfilePath: string;\n\treservationId: string;\n\tparentSessionId: string;\n\townerId: string;\n\ttaskId: string;\n\tattemptId: string;\n\tfencingToken: number;\n\trepositoryRoot: string;\n\texecutionRoot: string;\n\texecutionIdentity: string;\n\tisolatedWorktreeId?: string;\n\twriteScopes: readonly string[];\n}\n\nexport type WorkerWriteReservationAcquireResult =\n\t| { kind: \"granted\"; lease?: WorkerWriteReservationLease }\n\t| {\n\t\t\tkind: \"blocked\";\n\t\t\treasonCode: \"overlapping_write_scope\" | \"attempt_reservation_conflict\" | \"reservation_capacity_reached\";\n\t\t\tconflictingReservationIds?: readonly string[];\n\t  };\n\nexport type WorkerWriteReservationReleaseResult =\n\t| { kind: \"released\" }\n\t| { kind: \"stale_fence\" }\n\t| { kind: \"not_found\" };\n\nexport type WorkerWriteReservationEvidenceState = \"live\" | \"not_live\" | \"unknown\";\n\nexport interface WorkerWriteReservationRecoveryEvidence {\n\treservationId: string;\n\tstate: WorkerWriteReservationEvidenceState;\n}\n\nexport interface WorkerWriteReservationRecoveryRequest {\n\tworkspace: WorkerWriteReservationWorkspace;\n\t/** Caller-owned lease observations. This store never polls process state or worker output. */\n\tevidence: readonly WorkerWriteReservationRecoveryEvidence[];\n}\n\nexport interface WorkerWriteReservationRecoveryOutcome {\n\tkind: \"active\" | \"stale\" | \"inspection_required\";\n\treservationId: string;\n\tlease: WorkerWriteReservationLease;\n}\n\ninterface PersistedReservation {\n\treservationId: string;\n\tparentSessionId: string;\n\townerId: string;\n\ttaskId: string;\n\tattemptId: string;\n\tfencingToken: number;\n\trepositoryRoot: string;\n\texecutionRoot: string;\n\texecutionIdentity: string;\n\tisolatedWorktreeId?: string;\n\twriteScopes: string[];\n\tcreatedAt: string;\n}\n\ninterface PersistedReservationStore {\n\tschemaVersion: number;\n\trepositoryRoot: string;\n\treservations: PersistedReservation[];\n}\n\ninterface CanonicalWorkspace {\n\trepositoryRoot: string;\n\texecutionRoot: string;\n\texecutionIdentity: string;\n\tisolatedWorktreeId?: string;\n}\n\nfunction positiveFencingToken(value: number): number {\n\tif (!Number.isSafeInteger(value) || value < 1) throw new TypeError(\"Fencing token must be a positive safe integer.\");\n\treturn value;\n}\n\n/**\n * Prefer a real path for filesystem-backed scopes, but preserve a foreign lexical path family\n * (for example a Windows drive path inspected from WSL) so shared path-scope helpers retain\n * their documented Windows drive/UNC comparison semantics.\n */\nfunction canonicalRealOrLexicalPath(value: string, label: string): string {\n\tconst lexical = canonicalPathScopeIdentity(requireBoundedTrimmedText(value, MAX_PATH_CHARS, label));\n\tconst resolved = safeRealpathSync(lexical);\n\treturn pathScopesOverlap(lexical, resolved) ? canonicalPathScopeIdentity(resolved) : lexical;\n}\n\nfunction canonicalWorkspace(workspace: WorkerWriteReservationWorkspace): CanonicalWorkspace {\n\tconst repositoryRoot = canonicalRealOrLexicalPath(workspace.repositoryRoot, \"Repository root\");\n\tconst executionRoot = canonicalRealOrLexicalPath(workspace.executionRoot, \"Execution root\");\n\tconst isolatedWorktreeId = workspace.isolatedWorktreeId\n\t\t? requireBoundedTrimmedText(workspace.isolatedWorktreeId, MAX_IDENTIFIER_CHARS, \"Isolated worktree id\")\n\t\t: undefined;\n\tconst isPrimaryExecutionRoot =\n\t\tisPathWithinScope(executionRoot, repositoryRoot) && isPathWithinScope(repositoryRoot, executionRoot);\n\tif (isPrimaryExecutionRoot && isolatedWorktreeId) {\n\t\tthrow new TypeError(\"An isolated worktree execution root must differ from the shared repository root.\");\n\t}\n\tif (!isPrimaryExecutionRoot && !isolatedWorktreeId) {\n\t\tthrow new TypeError(\"A non-primary execution root requires an explicit isolated worktree identity.\");\n\t}\n\treturn {\n\t\trepositoryRoot,\n\t\texecutionRoot,\n\t\texecutionIdentity: isolatedWorktreeId ? `isolated:${executionRoot}` : `shared:${repositoryRoot}`,\n\t\t...(isolatedWorktreeId ? { isolatedWorktreeId } : {}),\n\t};\n}\n\nfunction reservationFile(agentDir: string, repositoryRoot: string): string {\n\tconst digest = createHash(\"sha256\")\n\t\t.update(\"pi-worker-write-reservations-v1\")\n\t\t.update(\"\\0\")\n\t\t.update(repositoryRoot)\n\t\t.digest(\"hex\");\n\treturn stateFile(agentDir, \"orchestration\", \"worker-write-reservations\", `${digest}.json`);\n}\n\nfunction notifyAvailability(filePath: string): void {\n\tfor (const listener of availabilityListeners.get(filePath) ?? []) queueMicrotask(listener);\n}\n\nfunction leaseFromRecord(filePath: string, record: PersistedReservation): WorkerWriteReservationLease {\n\treturn {\n\t\tfilePath,\n\t\treservationId: record.reservationId,\n\t\tparentSessionId: record.parentSessionId,\n\t\townerId: record.ownerId,\n\t\ttaskId: record.taskId,\n\t\tattemptId: record.attemptId,\n\t\tfencingToken: record.fencingToken,\n\t\trepositoryRoot: record.repositoryRoot,\n\t\texecutionRoot: record.executionRoot,\n\t\texecutionIdentity: record.executionIdentity,\n\t\t...(record.isolatedWorktreeId ? { isolatedWorktreeId: record.isolatedWorktreeId } : {}),\n\t\twriteScopes: [...record.writeScopes],\n\t};\n}\n\nfunction stringField(value: unknown, label: string, maximum: number): string {\n\tif (typeof value !== \"string\") throw new Error(`Worker write reservation ${label} is invalid.`);\n\treturn requireBoundedTrimmedText(value, maximum, `Worker write reservation ${label}`);\n}\n\nfunction localOwnerId(value: unknown): string {\n\tconst ownerId = stringField(value, \"owner id\", MAX_IDENTIFIER_CHARS);\n\tif (!parseLocalWorkerProcessOwnerId(ownerId)) throw new Error(\"Worker write reservation owner id is invalid.\");\n\treturn ownerId;\n}\n\nfunction parseReservation(value: unknown, repositoryRoot: string): PersistedReservation {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value))\n\t\tthrow new Error(\"Worker write reservation entry is invalid.\");\n\tconst entry = value as Record<string, unknown>;\n\tconst fencingToken = entry.fencingToken;\n\tif (typeof fencingToken !== \"number\") throw new Error(\"Worker write reservation fencing token is invalid.\");\n\tconst parsedRepositoryRoot = stringField(entry.repositoryRoot, \"repository root\", MAX_PATH_CHARS);\n\tif (parsedRepositoryRoot !== repositoryRoot)\n\t\tthrow new Error(\"Worker write reservation repository root conflicts with its store.\");\n\tif (!Array.isArray(entry.writeScopes) || entry.writeScopes.length === 0 || entry.writeScopes.length > MAX_SCOPES) {\n\t\tthrow new Error(\"Worker write reservation scopes are invalid.\");\n\t}\n\tconst writeScopes = entry.writeScopes.map((scope) => stringField(scope, \"write scope\", MAX_PATH_CHARS));\n\tconst isolatedWorktreeId =\n\t\tentry.isolatedWorktreeId === undefined\n\t\t\t? undefined\n\t\t\t: stringField(entry.isolatedWorktreeId, \"isolated worktree id\", MAX_IDENTIFIER_CHARS);\n\treturn {\n\t\treservationId: stringField(entry.reservationId, \"id\", MAX_IDENTIFIER_CHARS),\n\t\tparentSessionId: stringField(entry.parentSessionId, \"parent session\", MAX_IDENTIFIER_CHARS),\n\t\townerId: localOwnerId(entry.ownerId),\n\t\ttaskId: stringField(entry.taskId, \"task\", MAX_IDENTIFIER_CHARS),\n\t\tattemptId: stringField(entry.attemptId, \"attempt\", MAX_IDENTIFIER_CHARS),\n\t\tfencingToken: positiveFencingToken(fencingToken),\n\t\trepositoryRoot: parsedRepositoryRoot,\n\t\texecutionRoot: stringField(entry.executionRoot, \"execution root\", MAX_PATH_CHARS),\n\t\texecutionIdentity: stringField(entry.executionIdentity, \"execution identity\", MAX_PATH_CHARS),\n\t\t...(isolatedWorktreeId ? { isolatedWorktreeId } : {}),\n\t\twriteScopes,\n\t\tcreatedAt: stringField(entry.createdAt, \"created time\", MAX_IDENTIFIER_CHARS),\n\t};\n}\n\nfunction parseStore(raw: string, repositoryRoot: string): PersistedReservationStore {\n\tif (Buffer.byteLength(raw, \"utf-8\") > MAX_FILE_BYTES)\n\t\tthrow new Error(\"Worker write reservation store exceeds its byte limit.\");\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(raw);\n\t} catch {\n\t\tthrow new Error(\"Worker write reservation store is unreadable; refusing concurrent write admission.\");\n\t}\n\tif (!value || typeof value !== \"object\" || Array.isArray(value))\n\t\tthrow new Error(\"Worker write reservation store is invalid.\");\n\tconst store = value as Record<string, unknown>;\n\tif (store.schemaVersion !== SCHEMA_VERSION) throw new Error(\"Worker write reservation store schema is unsupported.\");\n\tif (stringField(store.repositoryRoot, \"store repository root\", MAX_PATH_CHARS) !== repositoryRoot) {\n\t\tthrow new Error(\"Worker write reservation store root conflicts with the requested workspace.\");\n\t}\n\tif (!Array.isArray(store.reservations) || store.reservations.length > MAX_RESERVATIONS) {\n\t\tthrow new Error(\"Worker write reservation store entries are invalid.\");\n\t}\n\tconst reservations = store.reservations.map((entry) => parseReservation(entry, repositoryRoot));\n\tif (new Set(reservations.map((entry) => entry.reservationId)).size !== reservations.length) {\n\t\tthrow new Error(\"Worker write reservation store contains duplicate reservation identities.\");\n\t}\n\treturn { schemaVersion: SCHEMA_VERSION, repositoryRoot, reservations };\n}\n\nfunction writeStore(filePath: string, store: PersistedReservationStore): void {\n\tconst serialized = `${JSON.stringify(store)}\\n`;\n\tif (Buffer.byteLength(serialized, \"utf-8\") > MAX_FILE_BYTES) {\n\t\tthrow new Error(\"Worker write reservation store would exceed its byte limit.\");\n\t}\n\twriteFileAtomicSync(filePath, serialized, { mode: 0o600 });\n}\n\nfunction overlappingReservationIds(\n\treservations: readonly PersistedReservation[],\n\texecutionIdentity: string,\n\twriteScopes: readonly string[],\n): string[] {\n\tconst matches: string[] = [];\n\tfor (const reservation of reservations) {\n\t\tif (reservation.executionIdentity !== executionIdentity) continue;\n\t\tif (\n\t\t\treservation.writeScopes.some((reservedScope) =>\n\t\t\t\twriteScopes.some((requestedScope) => pathScopesOverlap(reservedScope, requestedScope)),\n\t\t\t)\n\t\t) {\n\t\t\tmatches.push(reservation.reservationId);\n\t\t}\n\t}\n\treturn matches;\n}\n\n/**\n * Cross-process, agent-owned admission seam for concurrent worker mutations. It owns only\n * reservations; lifecycle, process liveness, and terminal status remain controller concerns.\n */\nexport class WorkerWriteReservationStore {\n\tprivate readonly agentDir: string;\n\tprivate readonly watchDirectory: WatchDirectory;\n\n\tconstructor(options: { agentDir: string; watchDirectory?: WatchDirectory }) {\n\t\tthis.agentDir = requireBoundedTrimmedText(options.agentDir, MAX_PATH_CHARS, \"Agent directory\");\n\t\tthis.watchDirectory = options.watchDirectory ?? watch;\n\t}\n\n\tacquire(request: WorkerWriteReservationRequest): WorkerWriteReservationAcquireResult {\n\t\tif (request.access === \"read\") return { kind: \"granted\" };\n\t\tif (request.access !== \"write\") throw new TypeError(\"Worker write reservation access must be read or write.\");\n\t\tif (request.writeScopes.length === 0 || request.writeScopes.length > MAX_SCOPES) {\n\t\t\tthrow new TypeError(`Write reservations require from 1 through ${MAX_SCOPES} write scopes.`);\n\t\t}\n\t\tconst workspace = canonicalWorkspace(request.workspace);\n\t\tconst writeScopes = [\n\t\t\t...new Set(request.writeScopes.map((scope) => canonicalRealOrLexicalPath(scope, \"Write scope\"))),\n\t\t].sort();\n\t\tif (writeScopes.some((scope) => !isPathWithinScope(scope, workspace.executionRoot))) {\n\t\t\tthrow new TypeError(\"Write reservation scopes must be within the execution root.\");\n\t\t}\n\t\tconst parentSessionId = requireBoundedTrimmedText(\n\t\t\trequest.parentSessionId,\n\t\t\tMAX_IDENTIFIER_CHARS,\n\t\t\t\"Parent session id\",\n\t\t);\n\t\tconst ownerId = localOwnerId(request.ownerId);\n\t\tconst taskId = requireBoundedTrimmedText(request.taskId, MAX_IDENTIFIER_CHARS, \"Task id\");\n\t\tconst attemptId = requireBoundedTrimmedText(request.attemptId, MAX_IDENTIFIER_CHARS, \"Attempt id\");\n\t\tconst fencingToken = positiveFencingToken(request.fencingToken);\n\t\tconst filePath = reservationFile(this.agentDir, workspace.repositoryRoot);\n\n\t\treturn withFileLockSync(filePath, () => {\n\t\t\tconst store = this.readLocked(filePath, workspace.repositoryRoot);\n\t\t\tconst matchingAttempt = store.reservations.find(\n\t\t\t\t(reservation) =>\n\t\t\t\t\treservation.parentSessionId === parentSessionId &&\n\t\t\t\t\treservation.ownerId === ownerId &&\n\t\t\t\t\treservation.taskId === taskId &&\n\t\t\t\t\treservation.attemptId === attemptId &&\n\t\t\t\t\treservation.fencingToken === fencingToken,\n\t\t\t);\n\t\t\tif (matchingAttempt) {\n\t\t\t\tif (\n\t\t\t\t\tmatchingAttempt.executionIdentity !== workspace.executionIdentity ||\n\t\t\t\t\tmatchingAttempt.isolatedWorktreeId !== workspace.isolatedWorktreeId ||\n\t\t\t\t\tmatchingAttempt.writeScopes.length !== writeScopes.length ||\n\t\t\t\t\tmatchingAttempt.writeScopes.some((scope, index) => scope !== writeScopes[index])\n\t\t\t\t) {\n\t\t\t\t\treturn { kind: \"blocked\", reasonCode: \"attempt_reservation_conflict\" };\n\t\t\t\t}\n\t\t\t\treturn { kind: \"granted\", lease: leaseFromRecord(filePath, matchingAttempt) };\n\t\t\t}\n\t\t\tconst conflicts = overlappingReservationIds(store.reservations, workspace.executionIdentity, writeScopes);\n\t\t\tif (conflicts.length > 0) {\n\t\t\t\treturn { kind: \"blocked\", reasonCode: \"overlapping_write_scope\", conflictingReservationIds: conflicts };\n\t\t\t}\n\t\t\tif (store.reservations.length >= MAX_RESERVATIONS)\n\t\t\t\treturn { kind: \"blocked\", reasonCode: \"reservation_capacity_reached\" };\n\t\t\tconst record: PersistedReservation = {\n\t\t\t\treservationId: randomUUID(),\n\t\t\t\tparentSessionId,\n\t\t\t\townerId,\n\t\t\t\ttaskId,\n\t\t\t\tattemptId,\n\t\t\t\tfencingToken,\n\t\t\t\trepositoryRoot: workspace.repositoryRoot,\n\t\t\t\texecutionRoot: workspace.executionRoot,\n\t\t\t\texecutionIdentity: workspace.executionIdentity,\n\t\t\t\t...(workspace.isolatedWorktreeId ? { isolatedWorktreeId: workspace.isolatedWorktreeId } : {}),\n\t\t\t\twriteScopes,\n\t\t\t\tcreatedAt: new Date().toISOString(),\n\t\t\t};\n\t\t\tstore.reservations.push(record);\n\t\t\twriteStore(filePath, store);\n\t\t\treturn { kind: \"granted\", lease: leaseFromRecord(filePath, record) };\n\t\t});\n\t}\n\n\trelease(lease: WorkerWriteReservationLease): WorkerWriteReservationReleaseResult {\n\t\tconst repositoryRoot = requireBoundedTrimmedText(lease.repositoryRoot, MAX_PATH_CHARS, \"Lease repository root\");\n\t\tconst ownerId = localOwnerId(lease.ownerId);\n\t\tconst expectedFilePath = reservationFile(this.agentDir, repositoryRoot);\n\t\tif (lease.filePath !== expectedFilePath)\n\t\t\tthrow new TypeError(\"Worker write reservation lease does not belong to this agent state.\");\n\t\treturn withFileLockSync(expectedFilePath, () => {\n\t\t\tconst store = this.readLocked(expectedFilePath, repositoryRoot);\n\t\t\tconst index = store.reservations.findIndex((reservation) => reservation.reservationId === lease.reservationId);\n\t\t\tif (index < 0) {\n\t\t\t\tconst supersedingReservation = store.reservations.some(\n\t\t\t\t\t(reservation) =>\n\t\t\t\t\t\treservation.parentSessionId === lease.parentSessionId &&\n\t\t\t\t\t\treservation.ownerId === ownerId &&\n\t\t\t\t\t\treservation.taskId === lease.taskId &&\n\t\t\t\t\t\treservation.fencingToken > lease.fencingToken,\n\t\t\t\t);\n\t\t\t\treturn { kind: supersedingReservation ? \"stale_fence\" : \"not_found\" };\n\t\t\t}\n\t\t\tconst record = store.reservations[index];\n\t\t\tif (\n\t\t\t\trecord.parentSessionId !== lease.parentSessionId ||\n\t\t\t\trecord.ownerId !== ownerId ||\n\t\t\t\trecord.taskId !== lease.taskId ||\n\t\t\t\trecord.attemptId !== lease.attemptId ||\n\t\t\t\trecord.fencingToken !== lease.fencingToken ||\n\t\t\t\trecord.executionIdentity !== lease.executionIdentity ||\n\t\t\t\trecord.isolatedWorktreeId !== lease.isolatedWorktreeId\n\t\t\t) {\n\t\t\t\treturn { kind: \"stale_fence\" };\n\t\t\t}\n\t\t\tstore.reservations.splice(index, 1);\n\t\t\tif (store.reservations.length === 0) unlinkSync(expectedFilePath);\n\t\t\telse writeStore(expectedFilePath, store);\n\t\t\tnotifyAvailability(expectedFilePath);\n\t\t\treturn { kind: \"released\" };\n\t\t});\n\t}\n\n\t/** Event-driven cross-process wakeup for queued write admission; caller owns disposal. */\n\twatchAvailability(workspace: WorkerWriteReservationWorkspace, listener: () => void): () => void {\n\t\tconst canonical = canonicalWorkspace(workspace);\n\t\tconst filePath = reservationFile(this.agentDir, canonical.repositoryRoot);\n\t\tconst listeners = availabilityListeners.get(filePath) ?? new Set<() => void>();\n\t\tavailabilityListeners.set(filePath, listeners);\n\t\tlisteners.add(listener);\n\t\tconst directory = dirname(filePath);\n\t\tmkdirSync(directory, { recursive: true });\n\t\tlet scheduled = false;\n\t\tconst schedule = () => {\n\t\t\tif (scheduled) return;\n\t\t\tscheduled = true;\n\t\t\tqueueMicrotask(() => {\n\t\t\t\tscheduled = false;\n\t\t\t\tlistener();\n\t\t\t});\n\t\t};\n\t\tconst watcher = this.watchDirectory(directory, { persistent: false }, (_eventType, fileName) => {\n\t\t\t// Node may omit a filename (notably on Windows), or provide a Buffer when the watcher is\n\t\t\t// configured that way. An unknown filename is conservatively treated as a wake signal: the\n\t\t\t// scheduler re-evaluates durable admission, so this cannot grant access by itself.\n\t\t\tif (fileName === null) {\n\t\t\t\tschedule();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst normalizedName = Buffer.isBuffer(fileName) ? fileName.toString(\"utf-8\") : fileName;\n\t\t\tif (normalizedName === basename(filePath)) schedule();\n\t\t});\n\t\treturn () => {\n\t\t\tlisteners.delete(listener);\n\t\t\tif (listeners.size === 0) availabilityListeners.delete(filePath);\n\t\t\twatcher.close();\n\t\t};\n\t}\n\n\trecover(request: WorkerWriteReservationRecoveryRequest): { outcomes: WorkerWriteReservationRecoveryOutcome[] } {\n\t\tconst workspace = canonicalWorkspace(request.workspace);\n\t\tconst filePath = reservationFile(this.agentDir, workspace.repositoryRoot);\n\t\tconst evidence = new Map<string, WorkerWriteReservationEvidenceState>();\n\t\tfor (const observation of request.evidence) {\n\t\t\tconst reservationId = requireBoundedTrimmedText(\n\t\t\t\tobservation.reservationId,\n\t\t\t\tMAX_IDENTIFIER_CHARS,\n\t\t\t\t\"Reservation evidence id\",\n\t\t\t);\n\t\t\tif (observation.state !== \"live\" && observation.state !== \"not_live\" && observation.state !== \"unknown\") {\n\t\t\t\tthrow new TypeError(\"Reservation evidence state must be live, not_live, or unknown.\");\n\t\t\t}\n\t\t\tif (evidence.has(reservationId)) throw new TypeError(\"Reservation evidence must not repeat an identity.\");\n\t\t\tevidence.set(reservationId, observation.state);\n\t\t}\n\t\treturn withFileLockSync(filePath, () => {\n\t\t\tconst store = this.readLocked(filePath, workspace.repositoryRoot);\n\t\t\tconst outcomes = store.reservations\n\t\t\t\t.filter((reservation) => reservation.executionIdentity === workspace.executionIdentity)\n\t\t\t\t.map((reservation): WorkerWriteReservationRecoveryOutcome => {\n\t\t\t\t\tconst state = evidence.get(reservation.reservationId);\n\t\t\t\t\treturn {\n\t\t\t\t\t\tkind: state === \"live\" ? \"active\" : state === \"not_live\" ? \"stale\" : \"inspection_required\",\n\t\t\t\t\t\treservationId: reservation.reservationId,\n\t\t\t\t\t\tlease: leaseFromRecord(filePath, reservation),\n\t\t\t\t\t};\n\t\t\t\t});\n\t\t\treturn { outcomes };\n\t\t});\n\t}\n\n\tprivate readLocked(filePath: string, repositoryRoot: string): PersistedReservationStore {\n\t\tif (!existsSync(filePath)) return { schemaVersion: SCHEMA_VERSION, repositoryRoot, reservations: [] };\n\t\treturn parseStore(\n\t\t\treadBoundedTextFileSync(filePath, MAX_FILE_BYTES, \"Worker write reservation store\"),\n\t\t\trepositoryRoot,\n\t\t);\n\t}\n}\n"]}