harnery 0.42.0 → 0.44.0

package/dist/core/workflow/workspaces/local-git.js

@@ -2,12 +2,16 @@ import { randomBytes } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { stateDirMode, stateFileMode } from "../../storage/modes.js";
+import { acquireWorkflowResumeLease } from "../run-state.js";
 import { WorkspaceAttestationError } from "./attestation-error.js";
+import { cleanupWorkspace } from "./cleanup.js";
 import { git, gitMaybe, gitMaybeWithDirectoryDescriptor, gitOperations, isAncestor, nulEntries, overwriteRiskPaths, parseWorktreeInventory, worktreeInventory, } from "./git.js";
 import { acquireNoClobberLease } from "./leases.js";
+import { claimOverlapsWorkspace, reserveWorkspaceReclaim, } from "./ownership.js";
 import { assertContainedExisting, assertPathIdentity, candidateUnderRoot, containsPath, createContainedDirectories, descriptorBackedPathsSupported, descriptorPath, filesystemIdentity, openContainedDirectory, sameFilesystemIdentity, validateConfiguredRoot, } from "./paths.js";
+import { prepareReclaim, WorkflowReclaimError, } from "./reclaim.js";
 import { readWorkflowLiveness } from "./recovery.js";
-import { appendWorkspaceEvent, fileSha256, readWorkflowSupplement, readWorkspaceBinding, readWorkspaceClaim, readWorkspaceEvents, stableDigest, workspaceClaimPath, workspaceLockPath, writeWorkspaceBinding, writeWorkspaceClaim, } from "./state.js";
+import { appendWorkspaceEvent, fileSha256, readWorkflowSupplement, readWorkspaceBinding, readWorkspaceClaim, readWorkspaceClaims, readWorkspaceEvents, stableDigest, workspaceClaimPath, workspaceLockPath, writeWorkspaceBinding, writeWorkspaceClaim, } from "./state.js";
 import { isWorkspaceAttestation } from "./validate.js";
 const PROVIDER_ID = "local-git-worktree";
 const PROVIDER_VERSION = "1";
@@ -17,7 +21,7 @@ const OBJECT_FORMAT = /^[a-f0-9]{40,64}$/;
 const REF_FORMAT = /^refs\/heads\/[A-Za-z0-9][A-Za-z0-9._/-]{0,180}$/;
 export function createLocalGitWorktreeProvider(options) {
     const coordRoot = resolve(options.coordRoot);
-    return {
+    const provider = {
         probe: (input) => probe(input, options.descriptorPathsSupported),
         allocate: (request) => allocate(coordRoot, request),
         readBinding: async (binding) => {
@@ -30,7 +34,9 @@ export function createLocalGitWorktreeProvider(options) {
         previewIntegration: (input) => previewIntegration(coordRoot, input),
         applyAuthorizedIntegration: (input) => applyAuthorizedIntegration(coordRoot, input),
         cleanup: (binding, intent) => cleanup(coordRoot, binding, intent),
+        reclaim: (binding, reclaimOptions) => reclaim(coordRoot, provider, binding, reclaimOptions),
     };
+    return provider;
 }
 export async function probe(input, descriptorPathsSupported = descriptorBackedPathsSupported) {
     const unsupported = [];
@@ -585,6 +591,239 @@ function cancelUnderLease(coordRoot, binding, claim) {
     appendWorkspaceEvent(coordRoot, claim, "cancellation_outcome", { status: "cancelled" });
     return { ...base, status: "cancelled" };
 }
+function reclaimPreview(coordRoot, binding, mode) {
+    const preview = {
+        action: "preview",
+        run_id: binding.run_id,
+        mode,
+        liveness: readWorkflowLiveness(coordRoot, binding.run_id),
+        ownership: "unproven",
+        dirty_paths: null,
+        lease_holder: reclaimLeaseHolders(coordRoot, binding),
+    };
+    try {
+        const current = attestSync(coordRoot, binding);
+        if (current.status === "ok") {
+            preview.ownership = "ok";
+            preview.dirty_paths = [...(current.repository?.dirty_paths ?? [])];
+        }
+        else {
+            preview.ownership_detail =
+                current.provider_drift.join("; ") || "ownership attestation failed";
+        }
+    }
+    catch (error) {
+        preview.ownership_detail = error.message;
+    }
+    return preview;
+}
+function assertReclaimLiveness(coordRoot, binding) {
+    const liveness = readWorkflowLiveness(coordRoot, binding.run_id);
+    if (liveness === "inactive")
+        return;
+    throw new WorkflowReclaimError(liveness === "active" ? "workflow_reclaim_run_live" : "workflow_reclaim_liveness_unknown", liveness === "active"
+        ? `run ${binding.run_id} is active; its workspace was left untouched`
+        : `run ${binding.run_id} has missing, corrupt, or ambiguous liveness evidence; its workspace was left untouched`);
+}
+function assertReclaimOwnership(coordRoot, binding) {
+    try {
+        const claim = requiredClaim(coordRoot, binding);
+        const current = attestSync(coordRoot, binding);
+        if (current.status !== "ok") {
+            throw new Error(current.provider_drift.join("; ") || "ownership attestation failed");
+        }
+        return claim;
+    }
+    catch (error) {
+        throw new WorkflowReclaimError("workflow_reclaim_ownership_unproven", error.message);
+    }
+}
+function assertPeerWorkspaceAuthority(coordRoot, claim) {
+    try {
+        for (const peer of readWorkspaceClaims(coordRoot, PROVIDER_ID)) {
+            if (peer.binding_id === claim.binding_id)
+                continue;
+            const binding = readWorkspaceBinding(coordRoot, PROVIDER_ID, peer.binding_id);
+            const events = readWorkspaceEvents(coordRoot, PROVIDER_ID, peer.binding_id);
+            if (binding)
+                requiredClaim(coordRoot, binding);
+            else if (events.some((event) => event.event === "bound")) {
+                throw new Error("retained peer binding authority is missing");
+            }
+            if (!claimOverlapsWorkspace(peer, claim.workspace_root))
+                continue;
+            // Process termination, archival and an expired reservation do not release
+            // a resource. Require the provider's release record AND current absence.
+            if (binding && events.some((event) => event.event === "released")) {
+                const current = attestSync(coordRoot, binding);
+                if (current.status === "ok" && current.resource_state === "released")
+                    continue;
+            }
+            throw new Error(`retained peer workspace ${peer.binding_id} overlaps the reclaim path`);
+        }
+    }
+    catch (error) {
+        throw new WorkflowReclaimError("workflow_reclaim_ownership_unproven", error.message);
+    }
+}
+function reclaimAuthorityGuard(coordRoot, binding, claim, reservation) {
+    try {
+        reservation.assertCurrent();
+        assertReclaimLiveness(coordRoot, binding);
+        assertReclaimOwnership(coordRoot, binding);
+        assertPeerWorkspaceAuthority(coordRoot, claim);
+    }
+    catch (error) {
+        if (error instanceof WorkflowReclaimError)
+            throw error;
+        throw new WorkflowReclaimError("workflow_reclaim_ownership_unproven", error.message);
+    }
+}
+async function reclaim(coordRoot, provider, binding, options) {
+    if (options.mode !== "salvage" && options.mode !== "discard") {
+        throw new Error("unsupported workspace reclaim mode");
+    }
+    if (!options.yes)
+        return reclaimPreview(coordRoot, binding, options.mode);
+    // Liveness comes before terminal-proof cleanup helpers. A live run may not
+    // have a proof yet, and a missing proof must never be discovered after reset.
+    assertReclaimLiveness(coordRoot, binding);
+    const claim = assertReclaimOwnership(coordRoot, binding);
+    let reservation;
+    try {
+        reservation = reserveWorkspaceReclaim(coordRoot, claim);
+    }
+    catch (error) {
+        throw new WorkflowReclaimError("workflow_reclaim_lease_held", error.message);
+    }
+    try {
+        reclaimAuthorityGuard(coordRoot, binding, claim, reservation);
+        let releaseResume;
+        try {
+            releaseResume = acquireWorkflowResumeLease(coordRoot, binding.run_id);
+        }
+        catch (error) {
+            throw new WorkflowReclaimError("workflow_reclaim_lease_held", error.message);
+        }
+        try {
+            let releaseBinding;
+            try {
+                releaseBinding = acquireLease(coordRoot, workspaceLockPath(coordRoot, PROVIDER_ID, binding.binding_id), claim, "binding");
+            }
+            catch (error) {
+                throw new WorkflowReclaimError("workflow_reclaim_lease_held", error.message);
+            }
+            try {
+                let releaseRepository;
+                try {
+                    releaseRepository = acquireRepositoryLease(coordRoot, claim);
+                }
+                catch (error) {
+                    throw new WorkflowReclaimError("workflow_reclaim_lease_held", error.message);
+                }
+                try {
+                    assertReclaimLiveness(coordRoot, binding);
+                    assertReclaimOwnership(coordRoot, binding);
+                    const preview = reclaimPreview(coordRoot, binding, options.mode);
+                    let preparation;
+                    // Keep ordinary cleanup's terminal-evidence checks, intent and receipts.
+                    // Its provider callback uses the leases already held here instead of
+                    // trying to acquire them again. Preparation occurs only after all of
+                    // cleanup's path, ownership, ref and registration checks have succeeded.
+                    const cleanupResult = await cleanupWorkspace({
+                        coordRoot,
+                        runId: binding.run_id,
+                        provider: {
+                            ...provider,
+                            cleanup: async (candidate, intent) => {
+                                assertReclaimLiveness(coordRoot, candidate);
+                                assertReclaimOwnership(coordRoot, candidate);
+                                return cleanupUnderLease(coordRoot, candidate, claim, intent, {
+                                    mode: options.mode,
+                                    beforeEffect: () => reclaimAuthorityGuard(coordRoot, candidate, claim, reservation),
+                                    prepared: (value) => {
+                                        preparation = value;
+                                    },
+                                });
+                            },
+                        },
+                    });
+                    if (!preparation &&
+                        cleanupResult.status !== "released" &&
+                        cleanupResult.status !== "already_released") {
+                        throw new WorkflowReclaimError("workflow_reclaim_ownership_unproven", ("reason" in cleanupResult ? cleanupResult.reason : undefined) ??
+                            "workspace cleanup preconditions could not be proved");
+                    }
+                    return {
+                        ...preview,
+                        action: "reclaimed",
+                        lease_holder: [],
+                        preparation: preparation ?? {
+                            action: "already_gone",
+                            detail: "the workspace is already released",
+                        },
+                        cleanup: cleanupResult,
+                    };
+                }
+                finally {
+                    releaseRepository();
+                }
+            }
+            finally {
+                releaseBinding();
+            }
+        }
+        finally {
+            releaseResume();
+        }
+    }
+    finally {
+        reservation.release();
+    }
+}
+function reclaimLeaseHolders(coordRoot, binding) {
+    const paths = [
+        ["binding", workspaceLockPath(coordRoot, PROVIDER_ID, binding.binding_id)],
+    ];
+    if (binding.repository) {
+        const key = stableDigest({ common: binding.repository.common_dir.identity });
+        paths.push([
+            "repository",
+            join(coordRoot, ".harnery", "workspaces", PROVIDER_ID, ".leases", `repository-${key}.lock`),
+        ]);
+    }
+    const holders = [];
+    try {
+        const owner = JSON.parse(readFileSync(join(coordRoot, ".harnery", "workflows", binding.run_id, "resume.lock"), "utf8"));
+        holders.push({
+            scope: "resume",
+            pid: typeof owner.pid === "number" ? owner.pid : undefined,
+            host: typeof owner.host === "string" ? owner.host : undefined,
+        });
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            holders.push({ scope: "resume", detail: "lease holder could not be read" });
+        }
+    }
+    for (const [scope, path] of paths) {
+        try {
+            const owner = JSON.parse(readFileSync(join(path, "current"), "utf8"));
+            holders.push({
+                scope,
+                owner_id: typeof owner.owner_id === "string" ? owner.owner_id : undefined,
+                pid: typeof owner.pid === "number" ? owner.pid : undefined,
+                host: typeof owner.host === "string" ? owner.host : undefined,
+            });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                holders.push({ scope, detail: "lease holder could not be read" });
+            }
+        }
+    }
+    return holders;
+}
 async function cleanup(coordRoot, binding, intent) {
     if (intent.mode !== "normal")
         throw new Error("unsupported workspace cleanup mode");
@@ -593,7 +832,18 @@ async function cleanup(coordRoot, binding, intent) {
     try {
         const releaseRepository = acquireRepositoryLease(coordRoot, claim);
         try {
-            return cleanupUnderLease(coordRoot, binding, claim, intent);
+            const reservation = reserveWorkspaceReclaim(coordRoot, claim);
+            try {
+                const authorityGuard = () => {
+                    reservation.assertCurrent();
+                    assertPeerWorkspaceAuthority(coordRoot, claim);
+                };
+                authorityGuard();
+                return cleanupUnderLease(coordRoot, binding, claim, intent, undefined, authorityGuard);
+            }
+            finally {
+                reservation.release();
+            }
         }
         finally {
             releaseRepository();
@@ -603,7 +853,7 @@ async function cleanup(coordRoot, binding, intent) {
         releaseBinding();
     }
 }
-function cleanupUnderLease(coordRoot, binding, claim, intent) {
+function cleanupUnderLease(coordRoot, binding, claim, intent, reclaimRequest, beforeRemoval) {
     const repository = binding.repository;
     if (!repository ||
         intent.schema_version !== 1 ||
@@ -653,10 +903,11 @@ function cleanupUnderLease(coordRoot, binding, claim, intent) {
     if (before.workspace_exists && before.status !== "ok") {
         return { ...base, status: "blocked", reason: "ownership attestation failed" };
     }
-    if ((before.repository?.dirty_paths.length ?? 0) > 0 ||
+    if ((!reclaimRequest && (before.repository?.dirty_paths.length ?? 0) > 0) ||
         (before.repository?.conflicts.length ?? 0) > 0 ||
         (before.repository?.operation_in_progress.length ?? 0) > 0) {
-        appendWorkspaceEvent(coordRoot, claim, "preserved_dirty");
+        if (!reclaimRequest)
+            appendWorkspaceEvent(coordRoot, claim, "preserved_dirty");
         return {
             ...base,
             status: "preserved_dirty",
@@ -710,6 +961,17 @@ function cleanupUnderLease(coordRoot, binding, claim, intent) {
             reason: "missing worktree still has ambiguous Git registration",
         };
     }
+    if (reclaimRequest) {
+        assertReclaimLiveness(coordRoot, binding);
+        assertReclaimOwnership(coordRoot, binding);
+        revalidateClaimResources(claim, root);
+        reclaimRequest.prepared(prepareReclaim({
+            worktreePath: binding.workspace_root,
+            mode: reclaimRequest.mode,
+            runId: binding.run_id,
+            beforeEffect: reclaimRequest.beforeEffect,
+        }));
+    }
     appendWorkspaceEvent(coordRoot, claim, "cleanup_pending", {
         worktree_path: binding.workspace_root,
         gitdir: repository.gitdir,
@@ -719,6 +981,8 @@ function cleanupUnderLease(coordRoot, binding, claim, intent) {
         target_ref_oid: targetRef.out,
     });
     if (before.workspace_exists) {
+        reclaimRequest?.beforeEffect();
+        beforeRemoval?.();
         revalidateClaimResources(claim, root);
         assertContainedExisting(root, binding.workspace_root, "workspace cleanup path");
         git(repository.source_root.realpath, ["worktree", "remove", binding.workspace_root]);

package/dist/core/workflow/workspaces/ownership.d.ts

@@ -0,0 +1,11 @@
+import type { WorkspaceClaim } from "./state.js";
+export interface WorkspaceReclaimReservation {
+    assertCurrent(): void;
+    release(): void;
+}
+/** The immutable claim is the authority; the lease reserves its destructive path. */
+export declare function reserveWorkspaceReclaim(coordRoot: string, claim: WorkspaceClaim): WorkspaceReclaimReservation;
+export declare function publishWorkspaceClaim<T>(coordRoot: string, claim: WorkspaceClaim, publish: () => T): T;
+export declare function assertClaimAuthority(claim: WorkspaceClaim, providerId: string, id: string): void;
+export declare function claimOverlapsWorkspace(claim: WorkspaceClaim, workspaceRoot: string): boolean;
+//# sourceMappingURL=ownership.d.ts.map

package/dist/core/workflow/workspaces/ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership.d.ts","sourceRoot":"","sources":["../../../../src/core/workflow/workspaces/ownership.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA8CjD,MAAM,WAAW,2BAA2B;IAC1C,aAAa,IAAI,IAAI,CAAC;IACtB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,cAAc,GACpB,2BAA2B,CAgC7B;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,CAAC,GACf,CAAC,CA8DH;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAwBhG;AAmCD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAU5F"}

package/dist/core/workflow/workspaces/ownership.js

@@ -0,0 +1,194 @@
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { readJsonRecord, stableDigest } from "../durable-record.js";
+import { acquireNoClobberLease } from "./leases.js";
+import { containsPath } from "./paths.js";
+import { isWorkspaceAllocationRequest } from "./validate.js";
+const STALE_MS = 5 * 60 * 1_000;
+const RESERVATION_SCOPE = "workspace-reclaim";
+function leaseRoot(coordRoot, providerId) {
+    return join(resolve(coordRoot), ".harnery", "workspaces", providerId, ".leases");
+}
+/** Serialize only publication and reservation registration, never Git work. */
+function withPublicationGate(coordRoot, providerId, operation) {
+    const authority = stableDigest({ provider_id: providerId, scope: "workspace-publication" });
+    const gate = acquireNoClobberLease({
+        path: join(leaseRoot(coordRoot, providerId), "publication.lock"),
+        scope: "workspace-publication",
+        authoritySha256: authority,
+        staleAfterMs: STALE_MS,
+        validateStaleOwner: (owner) => owner.authority_sha256 === authority,
+    });
+    try {
+        return operation();
+    }
+    finally {
+        gate.release();
+    }
+}
+function reservationPath(coordRoot, claim) {
+    return join(leaseRoot(coordRoot, claim.provider_id), `reclaim-${claim.binding_id}.lock`);
+}
+function acquireReservation(coordRoot, claim) {
+    const authority = stableDigest(claim);
+    return acquireNoClobberLease({
+        path: reservationPath(coordRoot, claim),
+        scope: RESERVATION_SCOPE,
+        authoritySha256: authority,
+        staleAfterMs: STALE_MS,
+        metadata: { binding_id: claim.binding_id, request_sha256: claim.request_sha256 },
+        validateStaleOwner: (owner) => owner.authority_sha256 === authority &&
+            owner.metadata?.binding_id === claim.binding_id &&
+            owner.metadata?.request_sha256 === claim.request_sha256,
+    });
+}
+/** The immutable claim is the authority; the lease reserves its destructive path. */
+export function reserveWorkspaceReclaim(coordRoot, claim) {
+    assertClaimAuthority(claim, claim.provider_id, claim.binding_id);
+    const lease = withPublicationGate(coordRoot, claim.provider_id, () => acquireReservation(coordRoot, claim));
+    return {
+        assertCurrent() {
+            const path = reservationPath(coordRoot, claim);
+            const current = join(path, "current");
+            const pin = join(path, lease.owner.owner_file);
+            const a = lstatSync(current, { bigint: true });
+            const b = lstatSync(pin, { bigint: true });
+            if (!a.isFile() ||
+                !b.isFile() ||
+                a.dev !== b.dev ||
+                a.ino !== b.ino ||
+                readFileSync(current, "utf8") !== readFileSync(pin, "utf8") ||
+                stableDigest(readJsonRecord(current, "reclaim reservation")) !== stableDigest(lease.owner)) {
+                throw new Error("workspace reclaim reservation owner changed");
+            }
+            const persisted = readJsonRecord(join(dirname(dirname(path)), claim.binding_id, "claim.json"), "reserved workspace claim");
+            if (stableDigest(persisted) !== stableDigest(claim)) {
+                throw new Error("workspace reclaim reservation claim changed");
+            }
+        },
+        release: () => lease.release(),
+    };
+}
+export function publishWorkspaceClaim(coordRoot, claim, publish) {
+    assertClaimAuthority(claim, claim.provider_id, claim.binding_id);
+    return withPublicationGate(coordRoot, claim.provider_id, () => {
+        for (const entry of readdirSync(leaseRoot(coordRoot, claim.provider_id), {
+            withFileTypes: true,
+        })) {
+            if (!entry.name.startsWith("reclaim-") || !entry.name.endsWith(".lock"))
+                continue;
+            if (!entry.isDirectory())
+                throw new Error("workspace reclaim reservation is not a directory");
+            const path = join(leaseRoot(coordRoot, claim.provider_id), entry.name);
+            const current = join(path, "current");
+            try {
+                lstatSync(current);
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+            const id = entry.name.slice("reclaim-".length, -".lock".length);
+            const reserved = readJsonRecord(join(dirname(leaseRoot(coordRoot, claim.provider_id)), id, "claim.json"), "reserved workspace claim");
+            assertClaimAuthority(reserved, claim.provider_id, id);
+            // Unknown reservation authority is never interpreted as an unrelated owner.
+            const owner = readJsonRecord(current, "reclaim reservation");
+            if (owner.schema_version !== 1 ||
+                typeof owner.owner_id !== "string" ||
+                !/^[a-f0-9-]{36}$/.test(owner.owner_id) ||
+                owner.owner_file !== `owner-${owner.owner_id}.json` ||
+                !Number.isSafeInteger(owner.pid) ||
+                owner.pid <= 0 ||
+                typeof owner.host !== "string" ||
+                owner.host.length === 0 ||
+                !Number.isFinite(Date.parse(owner.created_at)) ||
+                !Number.isFinite(Date.parse(owner.expires_at)) ||
+                Date.parse(owner.expires_at) < Date.parse(owner.created_at) ||
+                owner.scope !== RESERVATION_SCOPE ||
+                owner.authority_sha256 !== stableDigest(reserved) ||
+                owner.metadata?.binding_id !== id ||
+                owner.metadata?.request_sha256 !== reserved.request_sha256) {
+                throw new Error("workspace reclaim reservation authority is unproven");
+            }
+            const a = lstatSync(current, { bigint: true });
+            const pin = join(path, owner.owner_file);
+            const b = lstatSync(pin, { bigint: true });
+            if (!a.isFile() ||
+                !b.isFile() ||
+                a.dev !== b.dev ||
+                a.ino !== b.ino ||
+                readFileSync(current, "utf8") !== readFileSync(pin, "utf8"))
+                throw new Error("workspace reclaim reservation owner is unproven");
+            if (!claimOverlapsWorkspace(claim, reserved.workspace_root))
+                continue;
+            // This succeeds only for an expired, provably dead, exact prior owner.
+            // It retires the reservation, never the immutable claim or resource.
+            const recovered = acquireReservation(coordRoot, reserved);
+            recovered.release();
+        }
+        return publish();
+    });
+}
+export function assertClaimAuthority(claim, providerId, id) {
+    if (claim?.schema_version !== 1 ||
+        !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(providerId) ||
+        claim.provider_id !== providerId ||
+        claim.provider_version !== "1" ||
+        claim.binding_id !== id ||
+        !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(id) ||
+        !isWorkspaceAllocationRequest(claim.request) ||
+        claim.request.provider_id !== providerId ||
+        stableDigest(claim.request) !== claim.request_sha256 ||
+        !/^[a-f0-9]{64}$/.test(claim.recovery_token) ||
+        stableDigest(claim.writable_root) !== stableDigest(claim.request.selected_writable_root)) {
+        throw new Error("retained workspace claim authority is unproven");
+    }
+    for (const path of claimPaths(claim)) {
+        if (typeof path !== "string" || !isAbsolute(path) || resolve(path) !== path) {
+            throw new Error("retained workspace claim path is unproven");
+        }
+    }
+    if (!containsPath(claim.workspace_root, claim.active_root)) {
+        throw new Error("retained workspace active root escapes its claim");
+    }
+}
+function claimPaths(claim) {
+    return [
+        claim.workspace_root,
+        claim.active_root,
+        claim.repository?.source_root?.realpath,
+        claim.repository?.common_dir?.realpath,
+    ];
+}
+/** Include absent descendants without losing aliases in an existing ancestor. */
+function physicalPath(path) {
+    const tail = [];
+    let cursor = path;
+    for (;;) {
+        try {
+            lstatSync(cursor);
+            return resolve(realpathSync(cursor), ...tail);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" || dirname(cursor) === cursor) {
+                throw error;
+            }
+            // A dangling symlink must fail, rather than be treated as an absent directory.
+            try {
+                if (lstatSync(cursor).isSymbolicLink())
+                    throw new Error("unresolved workspace alias");
+            }
+            catch (missing) {
+                if (missing.code !== "ENOENT")
+                    throw missing;
+            }
+            tail.unshift(basename(cursor));
+            cursor = dirname(cursor);
+        }
+    }
+}
+export function claimOverlapsWorkspace(claim, workspaceRoot) {
+    const targets = [workspaceRoot, physicalPath(workspaceRoot)];
+    return claimPaths(claim).some((path, index) => [path, physicalPath(path)].some((candidate) => targets.some((target) => containsPath(target, candidate) || (index < 2 && containsPath(candidate, target)))));
+}

package/dist/core/workflow/workspaces/reclaim.d.ts

@@ -14,7 +14,40 @@
  * always has. So reclaim adds no second removal path that could diverge from the
  * audited one, and a force-delete of live work exists nowhere in the codebase.
  */
+import type { WorkflowLiveness } from "./recovery.js";
+import type { WorkspaceCleanupAttempt, WorkspaceCleanupReceipt } from "./types.js";
 export type ReclaimMode = "salvage" | "discard";
+export type WorkflowReclaimRefusalCode = "workflow_reclaim_run_live" | "workflow_reclaim_liveness_unknown" | "workflow_reclaim_ownership_unproven" | "workflow_reclaim_lease_held";
+export declare class WorkflowReclaimError extends Error {
+    readonly code: WorkflowReclaimRefusalCode;
+    constructor(code: WorkflowReclaimRefusalCode, message: string);
+}
+export interface WorkspaceReclaimOptions {
+    mode: ReclaimMode;
+    yes?: boolean;
+}
+export interface ReclaimLeaseHolder {
+    scope: "binding" | "repository" | "resume";
+    owner_id?: string;
+    pid?: number;
+    host?: string;
+    detail?: string;
+}
+export interface WorkspaceReclaimPreview {
+    action: "preview";
+    run_id: string;
+    mode: ReclaimMode;
+    liveness: WorkflowLiveness;
+    ownership: "ok" | "unproven";
+    ownership_detail?: string;
+    dirty_paths: string[] | null;
+    lease_holder: ReclaimLeaseHolder[];
+}
+export type WorkspaceReclaimResult = WorkspaceReclaimPreview | (Omit<WorkspaceReclaimPreview, "action"> & {
+    action: "reclaimed";
+    preparation: ReclaimPreparation;
+    cleanup: WorkspaceCleanupAttempt | WorkspaceCleanupReceipt;
+});
 export type ReclaimPreparation = {
     action: "salvaged";
     branch: string;
@@ -34,6 +67,8 @@ export interface PrepareReclaimInput {
     worktreePath: string;
     mode: ReclaimMode;
     runId: string;
+    /** Revalidate the held reservation and peer authority immediately before effects. */
+    beforeEffect?: () => void;
 }
 /**
  * Bring the worktree to a clean state so ordinary cleanup can release it.

package/dist/core/workflow/workspaces/reclaim.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reclaim.d.ts","sourceRoot":"","sources":["../../../../src/core/workflow/workspaces/reclaim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhD,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,kBAAkB,CAkD7E;AAYD;qEACqE;AACrE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD"}
+{"version":3,"file":"reclaim.d.ts","sourceRoot":"","sources":["../../../../src/core/workflow/workspaces/reclaim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEnF,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhD,MAAM,MAAM,0BAA0B,GAClC,2BAA2B,GAC3B,mCAAmC,GACnC,qCAAqC,GACrC,6BAA6B,CAAC;AAElC,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,IAAI,EAAE,0BAA0B;gBAAhC,IAAI,EAAE,0BAA0B,EACzC,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,IAAI,GAAG,UAAU,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,sBAAsB,GAC9B,uBAAuB,GACvB,CAAC,IAAI,CAAC,uBAAuB,EAAE,QAAQ,CAAC,GAAG;IACzC,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,kBAAkB,CAAC;IAChC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CAAC;CAC5D,CAAC,CAAC;AAEP,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,kBAAkB,CAwD7E;AAYD;qEACqE;AACrE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/core/workflow/workspaces/reclaim.js

@@ -16,6 +16,14 @@
  */
 import { existsSync } from "node:fs";
 import { git, gitMaybe } from "./git.js";
+export class WorkflowReclaimError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "WorkflowReclaimError";
+    }
+}
 /**
  * Bring the worktree to a clean state so ordinary cleanup can release it.
  *
@@ -41,7 +49,9 @@ export function prepareReclaim(input) {
     if (input.mode === "discard") {
         // Ordered: reset drops tracked modifications, clean removes what reset
         // cannot see. Running clean first would leave staged deletions behind.
+        input.beforeEffect?.();
         git(input.worktreePath, ["reset", "--hard"]);
+        input.beforeEffect?.();
         git(input.worktreePath, ["clean", "-fd"]);
         return { action: "discarded", detail: "uncommitted changes were discarded on request" };
     }
@@ -59,11 +69,15 @@ export function prepareReclaim(input) {
     // ref ends untouched, and the work lives on a ref cleanup has no reason to
     // touch.
     const before = git(input.worktreePath, ["rev-parse", "HEAD"]).trim();
+    input.beforeEffect?.();
     git(input.worktreePath, ["add", "-A"]);
+    input.beforeEffect?.();
     git(input.worktreePath, ["commit", "--no-verify", "-m", salvageMessage(input.runId)]);
     const commit = git(input.worktreePath, ["rev-parse", "HEAD"]).trim();
     const branch = salvageBranch(input.runId);
+    input.beforeEffect?.();
     git(input.worktreePath, ["branch", "--force", branch, commit]);
+    input.beforeEffect?.();
     git(input.worktreePath, ["reset", "--hard", before]);
     return {
         action: "salvaged",

package/dist/core/workflow/workspaces/recovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../../../src/core/workflow/workspaces/recovery.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjE,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAiDvF"}
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../../../src/core/workflow/workspaces/recovery.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjE,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,CA6DvF"}