@astrosheep/keiyaku 4.0.1 → 4.0.2

package/build/src/git/repository.js

@@ -1,6 +1,7 @@
-import { execFileSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { isAbsolute, resolve } from "node:path";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { consumeProcessStdout } from "../runtime/proc/run.js";
 import { gitObjectId } from "./identity.js";
 import { parseTreeObject, prepareTreeUpdate, treeUpdate, validPath, } from "./tree.js";
 export const GIT_REF = "refs/heads/keiyaku-state";
@@ -38,6 +39,7 @@ export class GitPlumbingError extends Error {
         this.pid = input.pid ?? null;
     }
 }
+const GIT_STDERR_BYTES = 16 * 1024;
 function worktreesFromPorcelain(output) {
     const fields = output.toString("utf8").split("\0");
     const worktrees = [];
@@ -71,11 +73,13 @@ function worktreesFromPorcelain(output) {
         throw new Error("Git worktree porcelain output has no worktrees");
     return worktrees;
 }
-export function registeredWorktrees(repository) {
-    return worktreesFromPorcelain(runGit(repository, ["worktree", "list", "--porcelain", "-z"]));
+export async function registeredWorktrees(repository) {
+    return worktreesFromPorcelain(await runGit(repository, ["worktree", "list", "--porcelain", "-z"]));
 }
-export function registeredWorktreePaths(repository) { return registeredWorktrees(repository).map((worktree) => worktree.path); }
-export function repositoryAt(cwd) {
+export async function registeredWorktreePaths(repository) {
+    return (await registeredWorktrees(repository)).map((worktree) => worktree.path);
+}
+export async function repositoryAt(cwd) {
     if (typeof cwd !== "string" || cwd.length === 0) {
         throw new Error("repository path must be a nonempty string");
     }
@@ -88,8 +92,8 @@ export function repositoryAt(cwd) {
     let primaryWorktree;
     let commonDirectory;
     try {
-        primaryWorktree = registeredWorktreePaths(provisional)[0];
-        commonDirectory = absoluteGitPath(provisional, ["--git-common-dir"], "common Git directory");
+        primaryWorktree = (await registeredWorktreePaths(provisional))[0];
+        commonDirectory = await absoluteGitPath(provisional, ["--git-common-dir"], "common Git directory");
     }
     catch (error) {
         if (error instanceof GitPlumbingError && error.status === 128) {
@@ -99,8 +103,8 @@ export function repositoryAt(cwd) {
     }
     return { effectiveCwd, primaryWorktree, commonDirectory };
 }
-function absoluteGitPath(repository, args, label) {
-    const value = runGit(repository, ["rev-parse", "--path-format=absolute", ...args]).toString("utf8").trim();
+async function absoluteGitPath(repository, args, label) {
+    const value = (await runGit(repository, ["rev-parse", "--path-format=absolute", ...args])).toString("utf8").trim();
     if (value.length === 0)
         throw new Error(`${label} is empty`);
     return resolve(isAbsolute(value) ? value : resolve(repository.effectiveCwd, value));
@@ -108,12 +112,12 @@ function absoluteGitPath(repository, args, label) {
 export function commonGitDirectory(repository) {
     return repository.commonDirectory;
 }
-export function worktreeGitDirectory(repository, worktree) {
+export async function worktreeGitDirectory(repository, worktree) {
     const scoped = { ...repository, effectiveCwd: worktree };
-    return absoluteGitPath(scoped, ["--git-dir"], "worktree Git directory");
+    return await absoluteGitPath(scoped, ["--git-dir"], "worktree Git directory");
 }
-export function worktreeRoot(repository) {
-    return absoluteGitPath(repository, ["--show-toplevel"], "worktree root");
+export async function worktreeRoot(repository) {
+    return await absoluteGitPath(repository, ["--show-toplevel"], "worktree root");
 }
 function commandError(command, error) {
     const candidate = error;
@@ -128,32 +132,69 @@ function commandError(command, error) {
         pid: candidate.pid ?? null,
     });
 }
-export function runGit(repository, args, input) {
-    try {
-        const output = execFileSync("git", [...args], {
-            cwd: repository.effectiveCwd,
-            input,
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        return Buffer.isBuffer(output) ? output : Buffer.from(output);
-    }
-    catch (error) {
-        throw commandError(args, error);
-    }
+async function executeGit(repository, args, input, environment) {
+    const stdout = [];
+    const stderr = [];
+    let stderrBytes = 0;
+    let inputError;
+    const child = spawn("git", [...args], {
+        cwd: repository.effectiveCwd,
+        ...(environment === undefined ? {} : { env: { ...process.env, ...environment } }),
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => {
+        if (stderrBytes >= GIT_STDERR_BYTES)
+            return;
+        const retained = chunk.subarray(0, GIT_STDERR_BYTES - stderrBytes);
+        stderr.push(retained);
+        stderrBytes += retained.length;
+    });
+    child.stdin.on("error", (error) => { inputError = error; });
+    child.stdin.end(input);
+    const terminal = await new Promise((resolveTerminal) => {
+        child.once("error", (error) => resolveTerminal({ code: null, error }));
+        child.once("close", (code) => resolveTerminal({ code }));
+    });
+    const output = Buffer.concat(stdout);
+    if (terminal.code === 0 && inputError === undefined)
+        return output;
+    throw commandError(args, {
+        message: terminal.error?.message ?? inputError?.message ?? `git exited with status ${terminal.code ?? "unknown"}`,
+        stdout: output,
+        stderr: Buffer.concat(stderr),
+        status: terminal.code,
+        pid: child.pid,
+    });
 }
-export function runGitWithEnvironment(repository, args, input, environment) {
-    try {
-        const output = execFileSync("git", [...args], {
-            cwd: repository.effectiveCwd,
-            input,
-            env: { ...process.env, ...environment },
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        return Buffer.isBuffer(output) ? output : Buffer.from(output);
-    }
-    catch (error) {
-        throw commandError(args, error);
-    }
+export async function runGit(repository, args, input) {
+    return await executeGit(repository, args, input);
+}
+export async function consumeGitStdout(repository, args, consume) {
+    const result = await consumeProcessStdout({
+        argv: ["git", ...args],
+        cwd: repository.effectiveCwd,
+    }, consume);
+    const { outcome } = result;
+    if (outcome.kind === "terminal" && outcome.code === 0)
+        return;
+    const status = outcome.kind === "terminal" ? outcome.code : null;
+    const stderr = outcome.kind === "terminal" ? outcome.stderr : "";
+    const message = outcome.kind === "terminal"
+        ? `git exited with status ${outcome.code}`
+        : outcome.kind === "spawn-error" || outcome.kind === "stream-error"
+            ? outcome.diagnostic
+            : `git process ended with ${outcome.kind}`;
+    throw commandError(args, {
+        message,
+        stderr,
+        status,
+        pid: result.pid ?? undefined,
+    });
+}
+export async function runGitWithEnvironment(repository, args, input, environment) {
+    return await executeGit(repository, args, input, environment);
 }
 function assertOid(oid, label) {
     gitObjectId(oid, label);
@@ -167,10 +208,10 @@ function assertAssertionRef(ref) {
     if (ref !== "HEAD")
         assertRef(ref);
 }
-export function readRef(repository, ref) {
+export async function readRef(repository, ref) {
     assertAssertionRef(ref);
     try {
-        const oid = runGit(repository, ["rev-parse", "--verify", "--quiet", ref]).toString("utf8").trim();
+        const oid = (await runGit(repository, ["rev-parse", "--verify", "--quiet", ref])).toString("utf8").trim();
         if (oid.length === 0)
             return null;
         assertOid(oid, `ref ${ref}`);
@@ -182,9 +223,9 @@ export function readRef(repository, ref) {
         throw error;
     }
 }
-function readTreeForCommit(repository, commit) {
+async function readTreeForCommit(repository, commit) {
     assertOid(commit, "Git commit");
-    const tree = runGit(repository, ["show", "-s", "--format=%T", commit]).toString("utf8").trim();
+    const tree = (await runGit(repository, ["show", "-s", "--format=%T", commit])).toString("utf8").trim();
     assertOid(tree, "Git tree");
     return tree;
 }
@@ -206,30 +247,30 @@ function parseTreeEntries(output) {
     }
     return entries;
 }
-export function readTreeEntries(repository, tree) {
+export async function readTreeEntries(repository, tree) {
     assertOid(tree, "tree");
-    const output = runGit(repository, ["ls-tree", "-r", "-z", "--full-tree", tree]);
+    const output = await runGit(repository, ["ls-tree", "-r", "-z", "--full-tree", tree]);
     return parseTreeEntries(output);
 }
-export function readGit(repository) {
-    const commit = readRef(repository, GIT_REF);
+export async function readGit(repository) {
+    const commit = await readRef(repository, GIT_REF);
     if (commit === null) {
         return { commit: null, tree: null, paths: new Map() };
     }
-    const tree = readTreeForCommit(repository, commit);
-    const paths = readTreeEntries(repository, tree);
-    validateGitFormat(repository, paths);
+    const tree = await readTreeForCommit(repository, commit);
+    const paths = await readTreeEntries(repository, tree);
+    await validateGitFormat(repository, paths);
     return { commit, tree, paths };
 }
 /** Read only the requested private Git paths from one immutable Git tree. */
-export function readGitPaths(repository, requestedPaths) {
+export async function readGitPaths(repository, requestedPaths) {
     for (const path of requestedPaths)
         validPath(path);
-    const commit = readRef(repository, GIT_REF);
+    const commit = await readRef(repository, GIT_REF);
     if (commit === null)
         return { commit: null, tree: null, paths: new Map() };
-    const tree = readTreeForCommit(repository, commit);
-    const paths = parseTreeEntries(runGit(repository, [
+    const tree = await readTreeForCommit(repository, commit);
+    const paths = parseTreeEntries(await runGit(repository, [
         "ls-tree",
         "-z",
         "--full-tree",
@@ -238,16 +279,16 @@ export function readGitPaths(repository, requestedPaths) {
         GIT_FORMAT_PATH,
         ...requestedPaths,
     ]));
-    validateGitFormat(repository, paths);
+    await validateGitFormat(repository, paths);
     return { commit, tree, paths };
 }
 /** Add paths from the same immutable Git tree without rereading its ref. */
-export function extendGitPaths(repository, snapshot, requestedPaths) {
+export async function extendGitPaths(repository, snapshot, requestedPaths) {
     for (const path of requestedPaths)
         validPath(path);
     if (snapshot.tree === null || requestedPaths.length === 0)
         return snapshot;
-    const additions = parseTreeEntries(runGit(repository, [
+    const additions = parseTreeEntries(await runGit(repository, [
         "ls-tree",
         "-z",
         "--full-tree",
@@ -258,19 +299,19 @@ export function extendGitPaths(repository, snapshot, requestedPaths) {
     return { ...snapshot, paths: new Map([...snapshot.paths, ...additions]) };
 }
 /** Expand a targeted immutable snapshot to its complete already-pinned tree. */
-export function expandGitSnapshot(repository, snapshot) {
+export async function expandGitSnapshot(repository, snapshot) {
     if (snapshot.tree === null)
         return snapshot;
-    return { ...snapshot, paths: readTreeEntries(repository, snapshot.tree) };
+    return { ...snapshot, paths: await readTreeEntries(repository, snapshot.tree) };
 }
-export function writeBlob(repository, bytes) {
-    const oid = runGit(repository, ["hash-object", "-w", "--stdin"], bytes).toString("utf8").trim();
+export async function writeBlob(repository, bytes) {
+    const oid = (await runGit(repository, ["hash-object", "-w", "--stdin"], bytes)).toString("utf8").trim();
     assertOid(oid, "written blob");
     return oid;
 }
-export function readBlob(repository, oid) {
+export async function readBlob(repository, oid) {
     assertOid(oid, "blob");
-    return runGit(repository, ["cat-file", "blob", oid]);
+    return await runGit(repository, ["cat-file", "blob", oid]);
 }
 function malformedBatchOutput(detail) {
     throw new GitPlumbingError({
@@ -279,13 +320,13 @@ function malformedBatchOutput(detail) {
         message: `malformed cat-file --batch output: ${detail}`,
     });
 }
-function readObjects(repository, oids) {
+async function readObjects(repository, oids) {
     const unique = [...new Set(oids)];
     for (const oid of unique)
         assertOid(oid, "Git object");
     if (unique.length === 0)
         return new Map();
-    const output = runGit(repository, ["cat-file", "--batch"], `${unique.join("\n")}\n`);
+    const output = await runGit(repository, ["cat-file", "--batch"], `${unique.join("\n")}\n`);
     const objects = new Map();
     let offset = 0;
     for (const oid of unique) {
@@ -321,22 +362,22 @@ function readObjects(repository, oids) {
         malformedBatchOutput("trailing bytes");
     return objects;
 }
-function validateGitFormat(repository, paths) {
+async function validateGitFormat(repository, paths) {
     const format = paths.get(GIT_FORMAT_PATH);
     if (format === undefined)
         throw new AuthorityCorruptionError(`Git is missing ${GIT_FORMAT_PATH}`);
     if (format.type !== "blob")
         throw new AuthorityCorruptionError(`Git format is not a blob: ${GIT_FORMAT_PATH}`);
-    const bytes = readBlob(repository, format.oid);
+    const bytes = await readBlob(repository, format.oid);
     if (bytes.toString("utf8") !== GIT_FORMAT_BYTES) {
         throw new AuthorityCorruptionError(`Git format is not current: ${GIT_FORMAT_PATH}`);
     }
 }
-function baseTreeEntries(repository, baseTree, changedPaths, nodePaths) {
+async function baseTreeEntries(repository, baseTree, changedPaths, nodePaths) {
     const byPath = new Map();
     if (baseTree === null)
         return byPath;
-    const ancestry = parseTreeEntries(runGit(repository, [
+    const ancestry = parseTreeEntries(await runGit(repository, [
         "ls-tree",
         "-z",
         "-t",
@@ -357,7 +398,7 @@ function baseTreeEntries(repository, baseTree, changedPaths, nodePaths) {
             throw new Error(`Git path is both file and directory: ${path}`);
         treeByPath.set(path, entry.oid);
     }
-    const objects = readObjects(repository, [...treeByPath.values()]);
+    const objects = await readObjects(repository, [...treeByPath.values()]);
     const oidBytes = baseTree.length / 2;
     for (const [path, oid] of treeByPath) {
         const object = objects.get(oid);
@@ -368,8 +409,8 @@ function baseTreeEntries(repository, baseTree, changedPaths, nodePaths) {
     }
     return byPath;
 }
-function writePreparedTrees(repository, prepared) {
-    const output = runGit(repository, ["mktree", "--batch"], prepared.map(({ records }) => `${records}\n`).join(""));
+async function writePreparedTrees(repository, prepared) {
+    const output = await runGit(repository, ["mktree", "--batch"], prepared.map(({ records }) => `${records}\n`).join(""));
     const written = output.toString("ascii").trimEnd().split("\n");
     if (written.length !== prepared.length) {
         throw new GitPlumbingError({ stderr: output, status: null, message: "malformed mktree --batch output" });
@@ -384,18 +425,18 @@ function writePreparedTrees(repository, prepared) {
     }
 }
 /** Copy only the changed paths' tree ancestors, preserving untouched subtrees by object ID. */
-export function updateGitTree(repository, baseTree, changes) {
+export async function updateGitTree(repository, baseTree, changes) {
     const update = treeUpdate(changes);
-    const bases = baseTreeEntries(repository, baseTree, [...changes.keys()], update.nodePaths);
+    const bases = await baseTreeEntries(repository, baseTree, [...changes.keys()], update.nodePaths);
     const representativeOid = baseTree ?? [...changes.values()].find((change) => change !== null)?.oid;
     if (representativeOid === undefined)
         throw new Error("cannot write an empty Git tree without an object format");
     const prepared = prepareTreeUpdate({ update, bases, oidBytes: representativeOid.length / 2 });
-    writePreparedTrees(repository, prepared.trees);
+    await writePreparedTrees(repository, prepared.trees);
     return prepared.root;
 }
 /** Write a tree update from directory entries frozen with the admitted base tree. */
-export function updateGitTreeFromFrozenDirectories(repository, baseTree, directories, changes) {
+export async function updateGitTreeFromFrozenDirectories(repository, baseTree, directories, changes) {
     const update = treeUpdate(changes);
     const representativeOid = baseTree ?? [...changes.values()].find((change) => change !== null)?.oid;
     if (representativeOid === undefined)
@@ -405,10 +446,10 @@ export function updateGitTreeFromFrozenDirectories(repository, baseTree, directo
         bases: directories,
         oidBytes: representativeOid.length / 2,
     });
-    writePreparedTrees(repository, prepared.trees);
+    await writePreparedTrees(repository, prepared.trees);
     return prepared.root;
 }
-function writeCommitObject(input) {
+async function writeCommitObject(input) {
     const { repository, tree, parents, message, actor, email, at } = input;
     assertOid(tree, "commit tree");
     for (const parent of parents)
@@ -416,20 +457,20 @@ function writeCommitObject(input) {
     const args = ["commit-tree", tree];
     for (const parent of parents)
         args.push("-p", parent);
-    const commit = runGitWithEnvironment(repository, args, `${message}\n`, {
+    const commit = (await runGitWithEnvironment(repository, args, `${message}\n`, {
         GIT_AUTHOR_NAME: actor,
         GIT_AUTHOR_EMAIL: email,
         GIT_COMMITTER_NAME: actor,
         GIT_COMMITTER_EMAIL: email,
         ...(at === undefined ? {} : { GIT_AUTHOR_DATE: at, GIT_COMMITTER_DATE: at }),
-    })
+    }))
         .toString("utf8")
         .trim();
     assertOid(commit, "written Git commit");
     return commit;
 }
-export function writeCommit(input) {
-    return writeCommitObject({
+export async function writeCommit(input) {
+    return await writeCommitObject({
         repository: input.repository,
         tree: input.tree,
         parents: input.parent === null ? [] : [input.parent],
@@ -455,7 +496,7 @@ function refUpdateLine(update, index) {
         assertOid(update.expectedOid, `expected oid for ${update.ref}`);
     return `option no-deref\nupdate ${update.ref} ${update.newOid} ${update.expectedOid ?? "0".repeat(update.newOid.length)}`;
 }
-export function updateRefsAtomically(repository, updates, assertions = []) {
+export async function updateRefsAtomically(repository, updates, assertions = []) {
     if (updates.length === 0)
         throw new Error("an atomic ref transaction needs a Git update");
     if (updates.length > 2)
@@ -473,7 +514,7 @@ export function updateRefsAtomically(repository, updates, assertions = []) {
         "",
     ];
     try {
-        runGit(repository, ["update-ref", "--stdin"], lines.join("\n"));
+        await runGit(repository, ["update-ref", "--stdin"], lines.join("\n"));
         return { kind: "published" };
     }
     catch (error) {
@@ -488,3 +529,34 @@ export function updateRefsAtomically(repository, updates, assertions = []) {
         throw error;
     }
 }
+export function decodeGitNumstat(output) {
+    const fields = output.toString("utf8").split("\0");
+    if (fields.at(-1) !== "")
+        throw new Error("Git numstat output is not NUL terminated");
+    let filesChanged = 0;
+    let insertions = 0;
+    let deletions = 0;
+    for (let index = 0; index < fields.length - 1; index += 1) {
+        const field = fields[index];
+        const [added, deleted, path, extra] = field.split("\t");
+        if (added === undefined || deleted === undefined || path === undefined || extra !== undefined) {
+            throw new Error("Git numstat output is malformed");
+        }
+        if (path.length === 0) {
+            if (fields[index + 1] === undefined || fields[index + 2] === undefined) {
+                throw new Error("Git rename numstat output is missing paths");
+            }
+            index += 2;
+        }
+        filesChanged += 1;
+        insertions += added === "-" ? 0 : Number.parseInt(added, 10);
+        deletions += deleted === "-" ? 0 : Number.parseInt(deleted, 10);
+    }
+    return { filesChanged, insertions, deletions };
+}
+export function decodeGitNameOnly(output) {
+    const names = output.toString("utf8").split("\0");
+    if (names.at(-1) !== "")
+        throw new Error("Git name-only output is not NUL terminated");
+    return names.slice(0, -1);
+}

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

@@ -2,12 +2,16 @@ import type { SnapshotId } from "../core/facts/types.js";
 import { type GitRepository } from "./repository.js";
 export type MaterializedScratchCandidate = Readonly<{
     cwd: string;
-    dispose: () => WorktreeLeak | null;
+    dispose: () => Promise<WorktreeLeak | null>;
+}>;
+export type CollectableScratchWorktree = Readonly<{
+    path: string;
+    release(): void;
 }>;
 export type WorktreeLeak = Readonly<{
     path: string;
     diagnostic: string;
 }>;
-export declare function orphanedScratchWorktrees(paths: Iterable<string>): readonly string[];
+export declare function collectableScratchWorktrees(paths: Iterable<string>): Promise<readonly CollectableScratchWorktree[]>;
 /** Materialize a disposable candidate worktree and own only its removal. */
-export declare function materializeScratchCandidate(repository: GitRepository, candidate: SnapshotId): MaterializedScratchCandidate;
+export declare function materializeScratchCandidate(repository: GitRepository, candidate: SnapshotId): Promise<MaterializedScratchCandidate>;

package/build/src/git/scratch.js

@@ -1,58 +1,62 @@
 import { randomBytes } from "node:crypto";
-import { realpathSync } from "node:fs";
+import { realpath } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, dirname, join } from "node:path";
+import { tryAcquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
 import { gitObjectIdForSnapshot } from "./identity.js";
 import { runGit } from "./repository.js";
-import { currentProcessIdentity, probeProcessIdentity, } from "../runtime/proc/run.js";
 const SCRATCH_PREFIX = "keiyaku-v4-verify-";
-const SCRATCH_ROOT = realpathSync(tmpdir());
+const SCRATCH_ROOT = await realpath(tmpdir());
+const SCRATCH_PATTERN = /^keiyaku-v4-verify-([0-9a-f]{24})$/;
 function scratchPath() {
-    const owner = currentProcessIdentity();
-    const identity = Buffer.from(owner.spawnedAt, "utf8").toString("base64url");
-    return join(SCRATCH_ROOT, `${SCRATCH_PREFIX}${owner.pid}-${identity}-${randomBytes(12).toString("hex")}`);
+    return join(SCRATCH_ROOT, `${SCRATCH_PREFIX}${randomBytes(12).toString("hex")}`);
 }
-function scratchOwner(path) {
-    const prefix = join(SCRATCH_ROOT, SCRATCH_PREFIX);
-    if (!path.startsWith(prefix))
+function ownershipLockPath(path) {
+    if (dirname(path) !== SCRATCH_ROOT)
         return null;
-    const suffix = path.slice(prefix.length);
-    const match = /^([1-9][0-9]*)-([A-Za-z0-9_-]+)-([0-9a-f]{24})$/.exec(suffix);
-    if (match === null)
-        return null;
-    const pid = Number(match[1]);
-    if (!Number.isSafeInteger(pid))
-        return null;
-    let spawnedAt;
-    try {
-        spawnedAt = Buffer.from(match[2], "base64url").toString("utf8");
-    }
-    catch {
-        return null;
-    }
-    return spawnedAt.length === 0 ? null : { pid, spawnedAt };
+    const match = SCRATCH_PATTERN.exec(basename(path));
+    return match === null ? null : join(SCRATCH_ROOT, `.${SCRATCH_PREFIX}${match[1]}.owner.sqlite`);
 }
-export function orphanedScratchWorktrees(paths) {
-    const orphaned = [];
+export async function collectableScratchWorktrees(paths) {
+    const collectable = [];
     for (const path of paths) {
-        const owner = scratchOwner(path);
-        if (owner === null)
+        const lockPath = ownershipLockPath(path);
+        if (lockPath === null)
             continue;
-        const state = probeProcessIdentity(owner);
-        if (state.kind === "gone" || state.kind === "replaced")
-            orphaned.push(path);
+        const lock = await tryAcquireSqliteTransactionLock({ path: lockPath, mode: "exclusive" });
+        if (lock !== null)
+            collectable.push({ path, release: () => lock.close() });
     }
-    return orphaned;
+    return collectable;
 }
 /** Materialize a disposable candidate worktree and own only its removal. */
-export function materializeScratchCandidate(repository, candidate) {
+export async function materializeScratchCandidate(repository, candidate) {
     const cwd = scratchPath();
-    runGit(repository, ["worktree", "add", "--detach", cwd, gitObjectIdForSnapshot(candidate)]);
+    const lockPath = ownershipLockPath(cwd);
+    if (lockPath === null)
+        throw new Error("scratch ownership lock path is invalid");
+    const ownership = await tryAcquireSqliteTransactionLock({
+        path: lockPath,
+        mode: "exclusive",
+    });
+    if (ownership === null)
+        throw new Error("new scratch ownership lock is unexpectedly held");
+    try {
+        await runGit(repository, ["worktree", "add", "--detach", cwd, gitObjectIdForSnapshot(candidate)]);
+    }
+    catch (error) {
+        ownership.close();
+        throw error;
+    }
+    let disposed = false;
     return {
         cwd,
-        dispose: () => {
+        dispose: async () => {
+            if (disposed)
+                return null;
+            disposed = true;
             try {
-                runGit(repository, ["worktree", "remove", "--force", cwd]);
+                await runGit(repository, ["worktree", "remove", "--force", cwd]);
                 return null;
             }
             catch (error) {
@@ -61,6 +65,9 @@ export function materializeScratchCandidate(repository, candidate) {
                     diagnostic: error instanceof Error ? error.message : String(error),
                 };
             }
+            finally {
+                ownership.close();
+            }
         },
     };
 }

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

@@ -48,9 +48,45 @@ export type TargetPlacementPreparation = Readonly<{
     kind: "refused";
     refusal: TargetPlacementRefusal;
 }>;
-export declare function observeTargetHead(repository: GitRepository, target: string): SnapshotId | null;
+export declare function observeTargetHead(repository: GitRepository, target: string): Promise<SnapshotId | null>;
 export declare function acquireTargetPlacementFence(repository: GitRepository, target: string): Promise<HeldSqliteTransactionLock>;
-export declare function prepareTargetPlacement(repository: GitRepository, state: ContractState, target: RefOperation): TargetPlacementPreparation;
-export declare function followTargetPlacement(repository: GitRepository, prepared: PreparedTargetPlacement): TargetPlacementPhysicalResult;
-export declare function recoverTargetPlacement(repository: GitRepository, state: ContractState): TargetPlacementPhysicalResult;
+export type TargetedContractCoordinates = ContractState["coordinates"] & Readonly<{
+    target: string;
+}>;
+export type TargetPlacementObservationInput = Readonly<{
+    contractId: ContractId;
+    coordinates: TargetedContractCoordinates;
+    predecessor: SnapshotId;
+    candidate: SnapshotId;
+}>;
+export type TargetPlacementObservation = Readonly<{
+    kind: "ready";
+    arms: readonly FollowArm[];
+}> | Readonly<{
+    kind: "refused";
+    refusal: TargetPlacementRefusal;
+}>;
+/** Observe whether registered target checkouts can follow a predecessor-to-candidate movement. */
+export declare function observeTargetPlacement(repository: GitRepository, input: TargetPlacementObservationInput): Promise<TargetPlacementObservation>;
+export type AuditTargetAnswer = Readonly<{
+    kind: "placeable";
+    ref: string;
+    head: SnapshotId;
+}> | Readonly<{
+    kind: "moved";
+    ref: string;
+    expected: SnapshotId;
+    observed: SnapshotId | null;
+}> | Readonly<{
+    kind: "refused";
+    refusal: TargetPlacementRefusal;
+}> | Readonly<{
+    kind: "failed";
+    diagnostic: string;
+}>;
+/** Adjudicate the complete post-Verification audit target answer without placing. */
+export declare function adjudicateAuditTarget(repository: GitRepository, input: TargetPlacementObservationInput): Promise<AuditTargetAnswer>;
+export declare function prepareTargetPlacement(repository: GitRepository, state: ContractState, target: RefOperation): Promise<TargetPlacementPreparation>;
+export declare function followTargetPlacement(repository: GitRepository, prepared: PreparedTargetPlacement): Promise<TargetPlacementPhysicalResult>;
+export declare function recoverTargetPlacement(repository: GitRepository, state: ContractState): Promise<TargetPlacementPhysicalResult>;
 export {};