@astrosheep/keiyaku 4.6.4 → 4.6.6

package/build/src/git/scratch.js

@@ -1,18 +1,23 @@
 import { z } from "zod";
 import { randomBytes } from "node:crypto";
-import { access, realpath, unlink } from "node:fs/promises";
+import { lstat, realpath, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
-import { tryAcquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
-import { gitObjectIdForSnapshot } from "./identity.js";
-import { runGit } from "./process.js";
+import { acquireSqliteTransactionLock, tryAcquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
+import { contractLocator, gitRefLocator, gitObjectIdForSnapshot } from "./identity.js";
+import { executeGit } from "./process.js";
 const SCRATCH_PREFIX = "keiyaku-v4-verify-";
 const SCRATCH_ROOT = await realpath(tmpdir());
-const SCRATCH_PATTERN = /^keiyaku-v4-verify-([0-9a-f]{24})$/;
-export const worktreeLeakSchema = z.object({ path: z.string(), diagnostic: z.string() }).strict();
+const SCRATCH_PATTERN = /^keiyaku-v4-verify-([0-9a-f]{24}|[0-9a-f]{64}-[0-9a-f]{64})$/;
+/** One bounded removal attempt per scratch; expiry is reported, never retried inside this call. */
+const SCRATCH_REMOVAL_TIMEOUT_MS = 120_000;
+export const worktreeLeakSchema = z.object({ path: z.string().optional(), diagnostic: z.string() }).strict();
 function scratchPath() {
     return join(SCRATCH_ROOT, `${SCRATCH_PREFIX}${randomBytes(12).toString("hex")}`);
 }
+function retainedScratchPath(repository, contract) {
+    return join(SCRATCH_ROOT, `${SCRATCH_PREFIX}${gitRefLocator(repository.commonDirectory)}-${contractLocator(contract)}`);
+}
 function ownershipLockPath(path) {
     if (dirname(path) !== SCRATCH_ROOT)
         return null;
@@ -25,69 +30,132 @@ async function removeOwnershipLock(lockPath) {
             throw error;
     });
 }
-async function collectableScratchWorktrees(paths) {
+async function collectableScratchWorktrees(paths, terminalScratch) {
     const collectable = [];
     for (const path of paths) {
         const lockPath = ownershipLockPath(path);
         if (lockPath === null)
             continue;
+        if (basename(path).length !== SCRATCH_PREFIX.length + 24 && path !== terminalScratch)
+            continue;
         const lock = await tryAcquireSqliteTransactionLock({ path: lockPath, mode: "exclusive" });
         if (lock !== null)
             collectable.push({ path, lockPath, release: () => lock.close() });
     }
     return collectable;
 }
-const pathExists = (path) => access(path).then(() => true, () => false);
+/** Absence is ENOENT on the path entry itself: a dangling symlink is present residue, not a missing path. */
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function removeScratch(repository, path) {
+    const removal = AbortSignal.timeout(SCRATCH_REMOVAL_TIMEOUT_MS);
+    try {
+        const present = await pathExists(path);
+        await executeGit({ ...repository, signal: removal }, ["worktree", "remove", ...(present ? ["--force"] : []), path]);
+        return (await pathExists(path))
+            ? { path, diagnostic: `Git reported scratch worktree removal but the path remains: ${path}` }
+            : null;
+    }
+    catch (error) {
+        const original = error instanceof Error ? error.message : String(error);
+        return {
+            path,
+            diagnostic: removal.aborted
+                ? `scratch worktree removal timed out after ${SCRATCH_REMOVAL_TIMEOUT_MS}ms: ${original}`
+                : original,
+        };
+    }
+}
 /** Remove only abandoned Verification scratch worktrees whose ownership locks are held. */
-export async function removeCollectableScratchWorktrees(repository, paths) {
+export async function removeCollectableScratchWorktrees(repository, paths, terminalContract) {
     const removals = [];
-    for (const scratch of await collectableScratchWorktrees(paths)) {
+    const terminalScratch = terminalContract === undefined ? undefined : retainedScratchPath(repository, terminalContract);
+    for (const scratch of await collectableScratchWorktrees(paths, terminalScratch)) {
         let removed = false;
         try {
-            if (!(await pathExists(scratch.path))) {
-                await runGit(repository, ["worktree", "remove", scratch.path]);
-                paths.delete(scratch.path);
-                removed = true;
-                removals.push({ path: scratch.path, action: "removed", retained: false });
+            const leak = await removeScratch(repository, scratch.path);
+            if (leak !== null) {
+                removals.push({ path: scratch.path, retained: true, diagnostic: leak.diagnostic });
                 continue;
             }
-            try {
-                await runGit(repository, ["worktree", "remove", "--force", scratch.path]);
-                paths.delete(scratch.path);
-                removed = true;
-                removals.push({ path: scratch.path, action: "removed", retained: false });
-            }
-            catch (error) {
-                removals.push({
-                    path: scratch.path,
-                    action: "unchanged",
-                    retained: true,
-                    diagnostic: error instanceof Error ? error.message : String(error),
-                });
-            }
+            paths.delete(scratch.path);
+            removed = true;
+            removals.push({ path: scratch.path, retained: false });
         }
         finally {
             scratch.release();
-            if (removed)
+            if (removed && scratch.path !== terminalScratch)
                 await removeOwnershipLock(scratch.lockPath);
         }
     }
     return removals;
 }
+async function retainScratch(repository, cwd, contract) {
+    const retained = retainedScratchPath(repository, contract);
+    const lockPath = ownershipLockPath(retained);
+    if (lockPath === null)
+        throw new Error("scratch ownership lock path is invalid");
+    const { signal: _signal, ...retirementRepository } = repository;
+    const fallback = async (reason) => {
+        const ownLeak = await removeScratch(retirementRepository, cwd);
+        return {
+            ...(ownLeak === null ? {} : { path: ownLeak.path }),
+            diagnostic: `failed Verification scratch could not be retained: ${reason}${ownLeak === null ? "" : `; ${ownLeak.diagnostic}`}`,
+        };
+    };
+    let lock;
+    try {
+        lock = await acquireSqliteTransactionLock({
+            path: lockPath,
+            mode: "exclusive",
+            timeoutMs: SCRATCH_REMOVAL_TIMEOUT_MS,
+        });
+    }
+    catch (error) {
+        return await fallback(`retained scratch busy: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        const replaced = await pathExists(retained);
+        if (replaced) {
+            const leak = await removeScratch(retirementRepository, retained);
+            if (leak !== null)
+                return await fallback(leak.diagnostic);
+        }
+        await executeGit(retirementRepository, ["worktree", "move", cwd, retained]);
+        return {
+            path: retained,
+            diagnostic: `failed Verification scratch retained for diagnosis${replaced ? " (replaced the previous retained scratch)" : ""}`,
+        };
+    }
+    catch (error) {
+        return await fallback(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        lock.close();
+    }
+}
 /** Materialize a disposable candidate worktree and own only its removal. */
-export async function materializeScratchCandidate(repository, candidate) {
+export async function materializeScratchCandidate(repository, candidate, contract) {
     const cwd = scratchPath();
     const lockPath = ownershipLockPath(cwd);
     if (lockPath === null)
         throw new Error("scratch ownership lock path is invalid");
-    const ownership = await tryAcquireSqliteTransactionLock({
+    const ownership = await acquireSqliteTransactionLock({
         path: lockPath,
         mode: "exclusive",
+        ...(repository.signal === undefined ? {} : { signal: repository.signal }),
     });
-    if (ownership === null)
-        throw new Error("new scratch ownership lock is unexpectedly held");
     try {
-        await runGit(repository, ["worktree", "add", "--detach", cwd, gitObjectIdForSnapshot(candidate)]);
+        await executeGit(repository, ["worktree", "add", "--detach", cwd, gitObjectIdForSnapshot(candidate)]);
     }
     catch (error) {
         ownership.close();
@@ -97,26 +165,22 @@ export async function materializeScratchCandidate(repository, candidate) {
     let disposed = false;
     return {
         cwd,
-        dispose: async () => {
+        dispose: async (retain = false) => {
             if (disposed)
                 return null;
             disposed = true;
-            let leak = null;
             try {
-                await runGit({ ...repository, signal: AbortSignal.timeout(5_000) }, ["worktree", "remove", "--force", cwd]);
-            }
-            catch (error) {
-                leak = {
-                    path: cwd,
-                    diagnostic: error instanceof Error ? error.message : String(error),
-                };
+                if (!retain)
+                    return await removeScratch(repository, cwd);
+                if (contract === undefined)
+                    return { path: cwd, diagnostic: "failed Verification scratch retained for diagnosis" };
+                return await retainScratch(repository, cwd, contract);
             }
             finally {
                 ownership.close();
-                if (leak === null)
+                if (!(await pathExists(cwd)))
                     await removeOwnershipLock(lockPath);
             }
-            return leak;
         },
     };
 }

package/build/src/git/target-placement.d.ts

@@ -30,7 +30,7 @@ export declare const targetCheckoutLagSchema: z.ZodObject<{
     diagnostic: z.ZodString;
 }, z.core.$strict>;
 type TargetCheckoutLag = z.infer<typeof targetCheckoutLagSchema>;
-export type TargetPlacementPhysicalResult = Readonly<{
+type TargetPlacementPhysicalResult = Readonly<{
     effects: readonly TargetCheckoutEffect[];
     lag: readonly TargetCheckoutLag[];
 }>;
@@ -42,7 +42,7 @@ export type PreparedTargetPlacement = Readonly<{
     target: RefOperation;
     arms: readonly FollowArm[];
 }>;
-export type TargetPlacementPreparation = Readonly<{
+type TargetPlacementPreparation = Readonly<{
     kind: "prepared";
     placement: PreparedTargetPlacement;
 }> | Readonly<{
@@ -63,16 +63,16 @@ export type TargetPlacementChanges = Readonly<{
 /** Only immutable commit contents are prepared outside the publication seat. */
 export declare function prepareTargetPlacementChanges(repository: GitRepository, target: RefOperation): Promise<TargetPlacementChanges>;
 export declare function acquireTargetPlacementFence(repository: GitRepository, target: string): Promise<HeldSqliteTransactionLock>;
-export type TargetedContractCoordinates = ContractState["coordinates"] & Readonly<{
+type TargetedContractCoordinates = ContractState["coordinates"] & Readonly<{
     target: string;
 }>;
-export type TargetPlacementObservationInput = Readonly<{
+type TargetPlacementObservationInput = Readonly<{
     contractId: ContractId;
     coordinates: TargetedContractCoordinates;
     predecessor: SnapshotId;
     candidate: SnapshotId;
 }>;
-export type TargetPlacementObservation = Readonly<{
+type TargetPlacementObservation = Readonly<{
     kind: "ready";
     arms: readonly FollowArm[];
 }> | Readonly<{

package/build/src/git/target-placement.js

@@ -6,7 +6,7 @@ import { resolve } from "node:path";
 import { acquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
 import { gitObjectId, gitObjectIdForSnapshot, gitRefLocator, mintSnapshotId } from "./identity.js";
 import { commonGitDirectory, decodeGitNameOnly, readRef, registeredWorktrees } from "./repository.js";
-import { consumeGitStdout, GitPlumbingError, runGit } from "./process.js";
+import { consumeGitStdout, GitPlumbingError, executeGit } from "./process.js";
 import { captureWorkspaceTree } from "./workspace.js";
 export const checkoutNotFollowableRefusalSchema = z
     .object({
@@ -42,13 +42,15 @@ function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
 }
 async function gitPaths(repository, path, args) {
-    return [...new Set(decodeGitNameOnly(await runGit(repository, ["-C", path, ...args])))].sort();
+    return [...new Set(decodeGitNameOnly(await executeGit(repository, ["-C", path, ...args])))].sort();
 }
 function literalPath(path) {
     return `:(literal)${path}`;
 }
 async function commitTree(repository, snapshot) {
-    return gitObjectId((await runGit(repository, ["show", "-s", "--format=%T", gitObjectIdForSnapshot(snapshot)])).toString("utf8").trim(), "commit tree");
+    return gitObjectId((await executeGit(repository, ["show", "-s", "--format=%T", gitObjectIdForSnapshot(snapshot)]))
+        .toString("utf8")
+        .trim(), "commit tree");
 }
 export async function observedTreeEqualsCandidate(repository, observed, snapshot) {
     if (observed === null)
@@ -60,7 +62,7 @@ function checkoutRefusal(contractId, target, path, reason, paths) {
 }
 /** Only immutable commit contents are prepared outside the publication seat. */
 export async function prepareTargetPlacementChanges(repository, target) {
-    const records = (await runGit(repository, [
+    const records = (await executeGit(repository, [
         "diff",
         "--raw",
         "--no-renames",
@@ -175,27 +177,10 @@ async function untrackedRefusalWithinScopes(input, scopes) {
     const first = directories.find((scope) => found.has(scope.path));
     return first === undefined ? null : checkoutRefusal(contractId, target, path, "untracked", [first.path]);
 }
-async function indexMatchesTreeOnPaths(repository, path, tree, paths) {
-    return ((await gitPaths(repository, path, [
-        "diff-index",
-        "--cached",
-        "--name-only",
-        "-z",
-        tree,
-        "--",
-        ...paths.map(literalPath),
-    ])).length === 0);
-}
-async function workspaceMatchesTreeOnPaths(repository, path, tree, workspaceTree, paths) {
-    return ((await gitPaths(repository, path, [
-        "diff",
-        "--name-only",
-        "-z",
-        tree,
-        workspaceTree,
-        "--",
-        ...paths.map(literalPath),
-    ])).length === 0);
+/** Compare the index or a workspace tree against another tree over the given paths. */
+async function matchesTreeOnPaths(repository, path, command, trees, paths) {
+    const args = [...command, "--name-only", "-z", ...trees, "--", ...paths.map(literalPath)];
+    return (await gitPaths(repository, path, args)).length === 0;
 }
 /**
  * A checkout that git cannot carry is judged by the physical follow, which records its own lag.
@@ -207,7 +192,7 @@ async function ordinaryPrecheck(repository, contractId, target, path, changes) {
     const candidate = gitObjectIdForSnapshot(target.newOid);
     const observation = { repository, contractId, target, path, predecessor, candidate, changes };
     try {
-        await runGit(repository, ["-C", path, "read-tree", "--dry-run", "-m", "-u", predecessor, candidate]);
+        await executeGit(repository, ["-C", path, "read-tree", "--dry-run", "-m", "-u", predecessor, candidate]);
     }
     catch (error) {
         if (!(error instanceof GitPlumbingError) || repository.signal?.aborted === true)
@@ -311,7 +296,7 @@ export async function followTargetPlacement(repository, prepared, onPhysical) {
     for (const arm of prepared.arms) {
         const beforeEffects = effects.length, beforeLag = lag.length;
         try {
-            await runGit(repository, ["-C", arm.path, "read-tree", "-m", "-u", predecessor, candidate]);
+            await executeGit(repository, ["-C", arm.path, "read-tree", "-m", "-u", predecessor, candidate]);
             effects.push({ kind: "target-checkout", path: arm.path, target: prepared.target.target, action: "followed" });
         }
         catch (error) {
@@ -337,15 +322,15 @@ async function classifyCheckout(input) {
     if (changedPaths.length === 0)
         return { kind: "complete" };
     const workspaceTree = (await captureWorkspaceTree(repository, path)).tree;
-    const candidateIndex = await indexMatchesTreeOnPaths(repository, path, candidateTree, changedPaths);
-    const candidateWorkspace = await workspaceMatchesTreeOnPaths(repository, path, candidateTree, workspaceTree, changedPaths);
+    const candidateIndex = await matchesTreeOnPaths(repository, path, ["diff-index", "--cached"], [candidateTree], changedPaths);
+    const candidateWorkspace = await matchesTreeOnPaths(repository, path, ["diff"], [candidateTree, workspaceTree], changedPaths);
     if (candidateIndex && candidateWorkspace)
         return { kind: "complete" };
-    const predecessorIndex = await indexMatchesTreeOnPaths(repository, path, predecessorTree, changedPaths);
+    const predecessorIndex = await matchesTreeOnPaths(repository, path, ["diff-index", "--cached"], [predecessorTree], changedPaths);
     if (predecessorIndex && candidateWorkspace)
         return { kind: "recoverable", action: "index-merge" };
     return !predecessorIndex ||
-        !(await workspaceMatchesTreeOnPaths(repository, path, predecessorTree, workspaceTree, changedPaths))
+        !(await matchesTreeOnPaths(repository, path, ["diff"], [predecessorTree, workspaceTree], changedPaths))
         ? { kind: "retained" }
         : { kind: "recoverable", action: "worktree-merge" };
 }
@@ -365,7 +350,7 @@ async function recoverCheckout(input) {
         return "retained";
     const { repository, path, predecessor, candidate } = input;
     if (classified.action === "index-merge") {
-        await runGit(repository, [
+        await executeGit(repository, [
             "-C",
             path,
             "read-tree",
@@ -376,7 +361,7 @@ async function recoverCheckout(input) {
         ]);
         return "recovered";
     }
-    await runGit(repository, [
+    await executeGit(repository, [
         "-C",
         path,
         "read-tree",

package/build/src/git/tender.d.ts

@@ -4,7 +4,7 @@ import type { ActorId, ContractCoordinates, ContractId, SnapshotId } from "../co
 import { type GitObjectId } from "./identity.js";
 import { type GitRepository } from "./process.js";
 import { captureWorkspaceTree } from "./workspace.js";
-export type TenderCaptureCoordinates = Readonly<{
+type TenderCaptureCoordinates = Readonly<{
     contractId: ContractId;
     coordinates: ContractCoordinates;
     place?: string;
@@ -23,7 +23,7 @@ export declare const unmergedPathsRefusalSchema: z.ZodObject<{
     contractId: z.ZodPipe<z.ZodString, z.ZodTransform<ContractId, string>>;
     paths: z.ZodReadonly<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
-export type TenderCaptureRefusal = WorktreeMissingRefusal | z.infer<typeof unmergedPathsRefusalSchema>;
+type TenderCaptureRefusal = WorktreeMissingRefusal | z.infer<typeof unmergedPathsRefusalSchema>;
 export declare const workspaceDirtyDeltaSchema: z.ZodObject<{
     staged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
     unstaged: z.ZodReadonly<z.ZodArray<z.ZodString>>;
@@ -81,6 +81,10 @@ export declare function prepareDeliveryCommitMetadata(repository: GitRepository,
     actor?: ActorId;
     message?: string;
 }>): Promise<DeliveryCommitMetadata>;
+/** The Git identity environment for one delivery snapshot commit. */
+export declare function deliveryEnvironment(commit: DeliveryCommitMetadata): NodeJS.ProcessEnv;
+/** Materialize one delivery snapshot commit over the given parents. */
+export declare function materializeSnapshotCommit(repository: GitRepository, tree: GitObjectId, parents: readonly SnapshotId[], message: string | Uint8Array, environment: NodeJS.ProcessEnv): Promise<SnapshotId>;
 /** Materialize the tender tree when it contains admitted dirty workspace bytes. */
 export declare function materializeTenderSnapshot(repository: GitRepository, tender: TenderCapture, commit: DeliveryCommitMetadata): Promise<SnapshotId>;
 export {};

package/build/src/git/tender.js

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { access } from "node:fs/promises";
 import { gitObjectIdForSnapshot, mintSnapshotId } from "./identity.js";
 import { decodeGitNumstat, registeredWorktreePaths } from "./repository.js";
-import { GitPlumbingError, runGit, runGitWithEnvironment } from "./process.js";
+import { executeGit, GitPlumbingError } from "./process.js";
 import { captureWorkspaceTree, unmergedWorkspacePaths, workspaceMergeHead, worktreePath } from "./workspace.js";
 export const worktreeMissingRefusalSchema = z
     .object({ kind: z.literal("worktree-missing"), contractId: contractIdSchema })
@@ -69,7 +69,7 @@ export async function captureTender(repository, input) {
     };
 }
 async function dirtyShortStat(repository, tender) {
-    return decodeGitNumstat(await runGit(repository, ["diff", "--numstat", "-z", gitObjectIdForSnapshot(tender.head), tender.tree]));
+    return decodeGitNumstat(await executeGit(repository, ["diff", "--numstat", "-z", gitObjectIdForSnapshot(tender.head), tender.tree]));
 }
 export async function dirtyTenderRefusal(repository, contractId, tender) {
     return {
@@ -87,7 +87,7 @@ export async function dirtyTenderDelta(repository, tender) {
 }
 async function effectiveConfig(repository, key) {
     try {
-        const value = (await runGit(repository, ["config", "--get", key])).toString("utf8").trim();
+        const value = (await executeGit(repository, ["config", "--get", key])).toString("utf8").trim();
         return value.length === 0 ? undefined : value;
     }
     catch (error) {
@@ -119,22 +119,29 @@ export async function prepareDeliveryCommitMetadata(repository, input) {
         identity,
     };
 }
-/** Materialize the tender tree when it contains admitted dirty workspace bytes. */
-export async function materializeTenderSnapshot(repository, tender, commit) {
-    if (!tender.dirty && tender.mergeHead === undefined)
-        return tender.head;
-    const parents = ["-p", gitObjectIdForSnapshot(tender.head)];
-    if (tender.mergeHead !== undefined)
-        parents.push("-p", gitObjectIdForSnapshot(tender.mergeHead));
-    const oid = (await runGitWithEnvironment(repository, ["commit-tree", tender.tree, ...parents], commit.message, {
+/** The Git identity environment for one delivery snapshot commit. */
+export function deliveryEnvironment(commit) {
+    return {
         GIT_AUTHOR_NAME: commit.identity.name,
         GIT_AUTHOR_EMAIL: commit.identity.email,
         GIT_COMMITTER_NAME: commit.identity.name,
         GIT_COMMITTER_EMAIL: commit.identity.email,
         GIT_AUTHOR_DATE: commit.at,
         GIT_COMMITTER_DATE: commit.at,
-    }))
+    };
+}
+/** Materialize one delivery snapshot commit over the given parents. */
+export async function materializeSnapshotCommit(repository, tree, parents, message, environment) {
+    const args = parents.flatMap((parent) => ["-p", gitObjectIdForSnapshot(parent)]);
+    const oid = (await executeGit(repository, ["commit-tree", tree, ...args], message, environment))
         .toString("utf8")
         .trim();
     return mintSnapshotId(oid);
 }
+/** Materialize the tender tree when it contains admitted dirty workspace bytes. */
+export async function materializeTenderSnapshot(repository, tender, commit) {
+    if (!tender.dirty && tender.mergeHead === undefined)
+        return tender.head;
+    const parents = tender.mergeHead === undefined ? [tender.head] : [tender.head, tender.mergeHead];
+    return await materializeSnapshotCommit(repository, tender.tree, parents, commit.message, deliveryEnvironment(commit));
+}

package/build/src/git/terminal-reconcile.js

@@ -3,7 +3,7 @@ import { isKeiyakuOwnedRef, readRef, writeCommit } from "./repository.js";
 import { gitObjectIdForSnapshot, mintSnapshotId } from "./identity.js";
 import { runDestroyHooks } from "./hooks.js";
 import { terminalSealExpectations as decodeTerminalSealExpectations, terminalSealSnapshots, observeTerminalWorkspace, } from "./terminal-seal.js";
-import { GitPlumbingError, runGit } from "./process.js";
+import { GitPlumbingError, executeGit } from "./process.js";
 import { worktreePath } from "./workspace.js";
 async function pathExists(path) {
     try {
@@ -16,29 +16,38 @@ async function pathExists(path) {
         throw error;
     }
 }
+/** Attempt removal once. Retention is a lag carrying its reason; no effect claims the worktree state after it. */
 async function removeTerminalWorktree(repository, topology, path) {
     const registered = topology.paths.has(path);
     if (!registered) {
-        return { retained: await pathExists(path) };
+        return (await pathExists(path)) ? { retainedLag: { kind: "worktree-retained", path } } : {};
     }
     const present = await pathExists(path);
     try {
-        await runGit(repository, ["worktree", "remove", ...(present ? ["--force"] : []), path]);
+        await executeGit(repository, ["worktree", "remove", ...(present ? ["--force"] : []), path]);
     }
     catch (error) {
         if (!(error instanceof GitPlumbingError))
             throw error;
-        return { effect: { kind: "worktree", path, action: "unchanged" }, retained: true };
+        return { retainedLag: { kind: "worktree-retained", path, diagnostic: error.message } };
     }
     topology.paths.delete(path);
-    const retained = await pathExists(path);
-    return { effect: { kind: "worktree", path, action: retained ? "unchanged" : "removed" }, retained };
+    if (await pathExists(path)) {
+        return {
+            retainedLag: {
+                kind: "worktree-retained",
+                path,
+                diagnostic: `Git reported worktree removal but the path remains: ${path}`,
+            },
+        };
+    }
+    return { effect: { kind: "worktree", path, action: "removed" } };
 }
 export async function updateRef(repository, ref, desired) {
     const before = await readRef(repository, ref);
     if (before === desired)
         return { kind: "ref", name: ref, action: "unchanged", before, after: desired };
-    await runGit(repository, [
+    await executeGit(repository, [
         "update-ref",
         "--no-deref",
         ref,
@@ -51,7 +60,7 @@ export async function removeRef(repository, ref) {
     const before = await readRef(repository, ref);
     if (before === null)
         return { kind: "ref", name: ref, action: "unchanged", before: null, after: null };
-    await runGit(repository, ["update-ref", "--no-deref", "-d", ref, before]);
+    await executeGit(repository, ["update-ref", "--no-deref", "-d", ref, before]);
     return { kind: "ref", name: ref, action: "removed", before, after: null };
 }
 async function removeRefWithCustody(repository, ref, custodian, expectedCustodian) {
@@ -61,7 +70,7 @@ async function removeRefWithCustody(repository, ref, custodian, expectedCustodia
     if ((await readRef(repository, custodian)) !== expectedCustodian) {
         return { kind: "ref", name: ref, action: "unchanged", before, after: before };
     }
-    await runGit(repository, ["update-ref", "--stdin", "--no-deref"], [
+    await executeGit(repository, ["update-ref", "--stdin", "--no-deref"], [
         "start",
         `verify ${custodian} ${gitObjectIdForSnapshot(expectedCustodian)}`,
         `delete ${ref} ${before}`,
@@ -75,7 +84,7 @@ function retainedRefEffect(ref, snapshot) {
     return { kind: "ref", name: ref, action: "unchanged", before: snapshot, after: snapshot };
 }
 async function refRows(repository) {
-    const output = (await runGit(repository, ["for-each-ref", "--format=%(refname)%00%(objectname)"])).toString("utf8");
+    const output = (await executeGit(repository, ["for-each-ref", "--format=%(refname)%00%(objectname)"])).toString("utf8");
     if (output.length === 0)
         return [];
     return output
@@ -90,7 +99,7 @@ async function refRows(repository) {
 }
 async function commitIsAncestor(repository, ancestor, descendant) {
     try {
-        await runGit(repository, ["merge-base", "--is-ancestor", gitObjectIdForSnapshot(ancestor), descendant]);
+        await executeGit(repository, ["merge-base", "--is-ancestor", gitObjectIdForSnapshot(ancestor), descendant]);
         return true;
     }
     catch (error) {
@@ -181,8 +190,10 @@ async function removeSealedTerminalWorktree({ repository, topology, path, state,
         }
     }
     const removal = await removeTerminalWorktree(repository, topology, path);
-    if (removal.retained)
-        return retainTerminalWorktree(path, { kind: "worktree-retained", path }, acc);
+    if (removal.retainedLag !== undefined) {
+        acc.recordLag(removal.retainedLag);
+        return complete(acc.effects, acc.lag, acc.hookRuns);
+    }
     if (removal.effect !== undefined)
         acc.recordEffect(removal.effect);
     return null;

package/build/src/git/terminal-seal.d.ts

@@ -3,7 +3,6 @@ import type { ContractState, SnapshotId } from "../core/facts/types.js";
 import { type GitObjectId } from "./identity.js";
 import type { GitOid } from "./repository.js";
 import { type GitRepository } from "./process.js";
-import { captureWorkspaceTree } from "./workspace.js";
 export declare const unsealedBytesSchema: z.ZodObject<{
     kind: z.ZodLiteral<"unsealed-bytes">;
     path: z.ZodString;
@@ -16,25 +15,23 @@ export type TerminalSealExpectations = Readonly<{
     trees: readonly GitObjectId[];
     treeBySnapshot: ReadonlyMap<SnapshotId, GitObjectId>;
 }>;
-export type TerminalSealObject = Readonly<{
+type TerminalSealObject = Readonly<{
     kind: "present";
     type: string;
     bytes: Buffer;
 }> | Readonly<{
     kind: "missing";
 }>;
-type WorkspaceTree = Awaited<ReturnType<typeof captureWorkspaceTree>>;
 export type TerminalWorkspace = Readonly<{
     tree: GitObjectId;
     head: SnapshotId;
     submodules: readonly string[];
 }>;
-export type TerminalWorkspaceObservation = Readonly<{
+type TerminalWorkspaceObservation = Readonly<{
     workspace: TerminalWorkspace;
     unsealed: UnsealedBytes | null;
 }>;
 export declare function terminalSealSnapshots(state: ContractState): readonly SnapshotId[];
 export declare function terminalSealExpectations(state: ContractState, objects: ReadonlyMap<GitOid, TerminalSealObject>): TerminalSealExpectations;
-export declare function unsealedWorkspaceBytes(repository: GitRepository, path: string, expected: TerminalSealExpectations, workspace: WorkspaceTree): Promise<UnsealedBytes | null>;
 export declare function observeTerminalWorkspace(repository: GitRepository, path: string, expected: TerminalSealExpectations): Promise<TerminalWorkspaceObservation>;
 export {};

package/build/src/git/terminal-seal.js

@@ -1,7 +1,7 @@
 import { mintedSnapshotInputSchema } from "./identity.js";
 import { z } from "zod";
 import { gitObjectId, gitObjectIdForSnapshot, mintSnapshotId } from "./identity.js";
-import { runGit } from "./process.js";
+import { executeGit } from "./process.js";
 import { captureWorkspaceTree } from "./workspace.js";
 export const unsealedBytesSchema = z
     .object({
@@ -71,12 +71,14 @@ export function terminalSealExpectations(state, objects) {
     };
 }
 async function changedPaths(repository, left, right) {
-    const fields = (await runGit(repository, ["diff", "--name-only", "-z", left, right])).toString("utf8").split("\0");
+    const fields = (await executeGit(repository, ["diff", "--name-only", "-z", left, right]))
+        .toString("utf8")
+        .split("\0");
     if (fields.at(-1) !== "")
         throw new Error("Git tree diff paths are not NUL terminated");
     return fields.slice(0, -1).sort();
 }
-export async function unsealedWorkspaceBytes(repository, path, expected, workspace) {
+async function unsealedWorkspaceBytes(repository, path, expected, workspace) {
     const headIsSealed = expected.heads.includes(workspace.head);
     if (workspace.changes.submodules.length > 0) {
         return {