@astrosheep/keiyaku 4.5.11 → 4.5.13

package/build/src/git/private-state-seat.js

@@ -1,8 +1,19 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { join } from "node:path";
-import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
+import { acquireSqliteTransactionLock, SqliteTransactionLockError } from "../coordination/sqlite-transaction-lock.js";
 const PRIVATE_STATE_SEAT = "private-state.sqlite";
+const PRIVATE_STATE_SEAT_ACQUIRE_TIMEOUT_MS = 5_000;
 const privateStateSeat = Symbol("private-state-seat");
 const confirmedPublications = new WeakSet();
+const heldPrivateStateSeats = new AsyncLocalStorage();
+/** Timed-out wait for the private-state publication seat. The holder and lock are unchanged. */
+export class GitPrivateStateSeatContentionError extends Error {
+    reason = "timeout";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "GitPrivateStateSeatContentionError";
+    }
+}
 /** Record a known or exact-read-back-proven private-root publication. */
 export function confirmPrivateStatePublication(seat) {
     confirmedPublications.add(seat);
@@ -10,30 +21,84 @@ export function confirmPrivateStatePublication(seat) {
 export function privateStatePublicationSeatPath(repository) {
     return join(repository.commonDirectory, "keiyaku", "locks", PRIVATE_STATE_SEAT);
 }
-/** Serialize cooperating writers of the one private Git state root. */
-export async function withPrivateStatePublicationSeat(repository, action) {
-    const held = await acquireSqliteTransactionLock({
-        path: privateStatePublicationSeatPath(repository),
-        mode: "immediate",
-        ...(repository.signal === undefined ? {} : { signal: repository.signal }),
-        ...(repository.onPrivateStateSeatContention === undefined
-            ? {}
-            : { onContended: repository.onPrivateStateSeatContention }),
-    });
+export function privateStateSeatCloseLag(error) {
+    return {
+        kind: "private-state-seat-close-failed",
+        diagnostic: error instanceof Error ? error.message : String(error),
+    };
+}
+export function concatenatePrivateStateSeatClose(current, next) {
+    const lags = [...(current ?? []), ...(next ?? [])];
+    return lags.length === 0 ? undefined : lags;
+}
+export function appendPrivateStateSeatClose(current, closeLag) {
+    return current === undefined ? [closeLag] : [...current, closeLag];
+}
+/** Unwrap a seat outcome that has no typed lag surface; confirmed close lag throws. */
+export function requireClosedPrivateStateSeat(outcome) {
+    if (outcome.closeLag !== undefined)
+        throw new Error(outcome.closeLag.diagnostic);
+    return outcome.value;
+}
+/** Unwrap a seat outcome through an owner-typed merge of confirmed close lag. */
+export function mergePrivateStateSeatClose(outcome, merge) {
+    return outcome.closeLag === undefined ? outcome.value : merge(outcome.value, outcome.closeLag);
+}
+export function isPrivateStateSeatContention(error) {
+    return error instanceof GitPrivateStateSeatContentionError;
+}
+function acquireTimeoutMs(timeoutMs) {
+    return timeoutMs ?? PRIVATE_STATE_SEAT_ACQUIRE_TIMEOUT_MS;
+}
+async function acquirePrivateStateSeatLock(repository, path, timeoutMs) {
+    try {
+        return await acquireSqliteTransactionLock({
+            path,
+            mode: "immediate",
+            timeoutMs: acquireTimeoutMs(timeoutMs),
+            ...(repository.signal === undefined ? {} : { signal: repository.signal }),
+            ...(repository.onPrivateStateSeatContention === undefined
+                ? {}
+                : { onContended: repository.onPrivateStateSeatContention }),
+        });
+    }
+    catch (error) {
+        if (error instanceof SqliteTransactionLockError && error.reason === "timeout") {
+            throw new GitPrivateStateSeatContentionError(error.message, { cause: error });
+        }
+        throw error;
+    }
+}
+async function runPrivateStateSeatAction(repository, held, action) {
     const seat = { [privateStateSeat]: true };
     let completed = false;
+    let value;
     try {
-        const result = await action(seat);
+        value = await action(seat);
         completed = true;
-        return result;
+        return { value };
     }
     finally {
         try {
             held.close();
+            repository.onPrivateStateSeatClose?.();
         }
         catch (error) {
             if (!(completed && confirmedPublications.has(seat)))
                 throw error;
+            return { value: value, closeLag: privateStateSeatCloseLag(error) };
         }
     }
 }
+/** Serialize cooperating writers of the one private Git state root. */
+export async function withPrivateStatePublicationSeat(repository, action, options) {
+    const path = privateStatePublicationSeatPath(repository);
+    const heldPaths = heldPrivateStateSeats.getStore();
+    if (heldPaths?.has(path) === true) {
+        throw new Error(`private-state publication seat reentered: ${path}`);
+    }
+    const held = await acquirePrivateStateSeatLock(repository, path, options?.timeoutMs);
+    const nested = new Set(heldPaths);
+    nested.add(path);
+    return await heldPrivateStateSeats.run(nested, () => runPrivateStateSeatAction(repository, held, action));
+}

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

@@ -13,6 +13,8 @@ export type GitRepository = Readonly<{
     readonly signal?: AbortSignal;
     /** Test-only observation that this capability is waiting for the private-state seat. */
     readonly onPrivateStateSeatContention?: () => void;
+    /** Test-only hook after the private-state seat close attempt. */
+    readonly onPrivateStateSeatClose?: () => void;
 }>;
 /** Give one caller's Git capability view its cancellation boundary. */
 export declare function withGitAbortSignal(repository: GitRepository, signal: AbortSignal | undefined): GitRepository;

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

@@ -4,7 +4,6 @@ import type { ContractId, ContractState, SnapshotId } from "../core/facts/types.
 import type { GitDecodeChannel } from "./read-observation.js";
 import { type TargetCheckoutEffect, type TargetCheckoutLag } from "./target-placement.js";
 import { type WorktreeHookLag, type WorktreeHooks } from "./hooks.js";
-import { type RefMigrationConflict } from "./ref-migration.js";
 import type { UnsealedBytes } from "./terminal-seal.js";
 export type Effect = Readonly<{
     kind: "worktree";
@@ -54,7 +53,7 @@ export type ReconcileFailure = Readonly<{
     stage: "observation" | "effect";
     diagnostic: string;
 }>;
-export type ReconcileLag = WorktreeRetained | WorktreeFollowRetained | UnsealedBytes | TargetCheckoutLag | WorktreeHookLag | RefMigrationConflict | ReconcileFailure;
+export type ReconcileLag = WorktreeRetained | WorktreeFollowRetained | UnsealedBytes | TargetCheckoutLag | WorktreeHookLag | ReconcileFailure;
 export type ReconcileResult = Readonly<{
     effects: readonly Effect[];
     lag: readonly ReconcileLag[];

package/build/src/git/reconcile.js

@@ -10,7 +10,6 @@ import { acquireTargetPlacementFence, recoverTargetPlacement, } from "./target-p
 import { runCreateHooks } from "./hooks.js";
 import { followDependentManagedWorktree, retireConflictHandoff, worktreePath } from "./workspace.js";
 import { removeCollectableScratchWorktrees } from "./scratch.js";
-import { migrateContractCustodyRefs } from "./ref-migration.js";
 import { reconcileTerminalManagedWorktree, removeRef, updateRef } from "./terminal-reconcile.js";
 const pathExists = (path) => access(path).then(() => true, () => false);
 function deliveryRefFor(contract) {
@@ -174,11 +173,6 @@ async function reconcileWithTopology(input, state, topology) {
         await removeCollectableScratch(repository, topology, effects, lag);
         if (!state)
             return complete(effects, lag);
-        const migration = await migrateContractCustodyRefs(repository, state.id);
-        effects.push(...migration.effects);
-        lag.push(...migration.lag);
-        if (migration.lag.length > 0)
-            return complete(effects, lag);
         const targetCheckouts = await reconcileTargetCheckouts(repository, state);
         effects.push(...targetCheckouts.effects);
         lag.push(...targetCheckouts.lag);

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

@@ -5,8 +5,6 @@ export declare const GIT_REF = "refs/heads/keiyaku-state";
 export declare const DELIVERY_REF_NAMESPACE = "refs/keiyaku/delivery";
 export declare const CANDIDATE_PIN_REF_NAMESPACE = "refs/keiyaku/candidate";
 export declare const HANDOFF_RECEIPT_REF_NAMESPACE = "refs/keiyaku/handoff";
-export declare const LEGACY_DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
-export declare const LEGACY_CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
 export declare const GIT_FORMAT_PATH = "meta/format.json";
 export declare const GIT_FORMAT_BYTES = "{\"version\":4}\n";
 export declare const STATE_COMMIT_SUBJECT = "keiyaku authority - do not delete or rewrite";

package/build/src/git/repository.js

@@ -1,5 +1,5 @@
-/* eslint-disable max-lines */
 import { isAbsolute, resolve } from "node:path";
+import { realpath } from "node:fs/promises";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { gitObjectId } from "./identity.js";
 import { GitPlumbingError, runGit, runGitWithEnvironment } from "./process.js";
@@ -8,8 +8,6 @@ export const GIT_REF = "refs/heads/keiyaku-state";
 export const DELIVERY_REF_NAMESPACE = "refs/keiyaku/delivery";
 export const CANDIDATE_PIN_REF_NAMESPACE = "refs/keiyaku/candidate";
 export const HANDOFF_RECEIPT_REF_NAMESPACE = "refs/keiyaku/handoff";
-export const LEGACY_DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
-export const LEGACY_CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
 export const GIT_FORMAT_PATH = "meta/format.json";
 const CURRENT_FORMAT_VERSION = 4;
 export const GIT_FORMAT_BYTES = `{"version":${CURRENT_FORMAT_VERSION}}\n`;
@@ -21,11 +19,7 @@ export function isKeiyakuOwnedRef(ref) {
         ref === CANDIDATE_PIN_REF_NAMESPACE ||
         ref.startsWith(`${CANDIDATE_PIN_REF_NAMESPACE}/`) ||
         ref === HANDOFF_RECEIPT_REF_NAMESPACE ||
-        ref.startsWith(`${HANDOFF_RECEIPT_REF_NAMESPACE}/`) ||
-        ref === LEGACY_DELIVERY_REF_NAMESPACE ||
-        ref.startsWith(`${LEGACY_DELIVERY_REF_NAMESPACE}/`) ||
-        ref === LEGACY_CANDIDATE_PIN_REF_NAMESPACE ||
-        ref.startsWith(`${LEGACY_CANDIDATE_PIN_REF_NAMESPACE}/`));
+        ref.startsWith(`${HANDOFF_RECEIPT_REF_NAMESPACE}/`));
 }
 export class NoGitWorldError extends Error {
     path;
@@ -53,7 +47,11 @@ function worktreesFromPorcelain(output) {
         const branch = branchField === undefined ? null : branchField.slice("branch ".length);
         if (branch !== null && !branch.startsWith("refs/"))
             throw new Error("Git worktree porcelain output has an invalid branch");
-        worktrees.push({ path: resolve(path), branch });
+        worktrees.push({
+            path: resolve(path),
+            branch,
+            prunable: record.some((field) => field.startsWith("prunable ")),
+        });
         record = [];
     };
     for (const field of fields) {
@@ -69,7 +67,17 @@ function worktreesFromPorcelain(output) {
     return worktrees;
 }
 export async function registeredWorktrees(repository) {
-    return worktreesFromPorcelain(await runGit(repository, ["worktree", "list", "--porcelain", "-z"]));
+    return await Promise.all(worktreesFromPorcelain(await runGit(repository, ["worktree", "list", "--porcelain", "-z"])).map(async (worktree) => {
+        const { prunable, ...registered } = worktree;
+        try {
+            return { ...registered, path: await realpath(registered.path) };
+        }
+        catch (error) {
+            if (prunable || error.code === "ENOENT")
+                return registered;
+            throw error;
+        }
+    }));
 }
 export async function registeredWorktreePaths(repository) {
     return (await registeredWorktrees(repository)).map((worktree) => worktree.path);
@@ -106,7 +114,7 @@ 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));
+    return await realpath(resolve(isAbsolute(value) ? value : resolve(repository.effectiveCwd, value)));
 }
 export function commonGitDirectory(repository) {
     return repository.commonDirectory;
@@ -329,10 +337,7 @@ async function writePreparedTrees(repository, prepared) {
         }
     }
 }
-/** Copy only the changed paths' tree ancestors, preserving untouched subtrees by object ID. */
-export async function updateGitTree(repository, baseTree, changes) {
-    const update = treeUpdate(changes);
-    const bases = await baseTreeEntries(repository, baseTree, [...changes.keys()], update.nodePaths);
+async function writeTreeUpdate(repository, baseTree, changes, update, bases) {
     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");
@@ -340,19 +345,16 @@ export async function updateGitTree(repository, baseTree, changes) {
     await writePreparedTrees(repository, prepared.trees);
     return prepared.root;
 }
+/** Copy only the changed paths' tree ancestors, preserving untouched subtrees by object ID. */
+export async function updateGitTree(repository, baseTree, changes) {
+    const update = treeUpdate(changes);
+    const bases = await baseTreeEntries(repository, baseTree, [...changes.keys()], update.nodePaths);
+    return writeTreeUpdate(repository, baseTree, changes, update, bases);
+}
 /** Write a tree update from directory entries frozen with the admitted base tree. */
 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)
-        throw new Error("cannot write an empty Git tree without an object format");
-    const prepared = prepareTreeUpdate({
-        update,
-        bases: directories,
-        oidBytes: representativeOid.length / 2,
-    });
-    await writePreparedTrees(repository, prepared.trees);
-    return prepared.root;
+    return writeTreeUpdate(repository, baseTree, changes, update, directories);
 }
 async function writeCommitObject(input) {
     const { repository, tree, parents, message, actor, email, at } = input;

package/build/src/git/result-codec.d.ts

@@ -0,0 +1,29 @@
+import { type ContractId } from "../core/facts/types.js";
+import type { PublicationFailed } from "./admission.js";
+import type { HookFailure } from "./hooks.js";
+import type { IntegrationPreparationRefusal } from "./integration.js";
+import type { PrivateStateSeatCloseLag } from "./private-state-seat.js";
+import type { ReconcileLag } from "./reconcile.js";
+import type { WorktreeLeak } from "./scratch.js";
+import type { AuditTargetAnswer, CheckoutNotFollowableRefusal } from "./target-placement.js";
+import type { DirtyWorkspaceRefusal, WorkspaceDirtyDelta, WorktreeMissingRefusal } from "./tender.js";
+export declare function decodeHookFailure(value: unknown): HookFailure;
+export declare function decodeWorktreeLeak(value: unknown): WorktreeLeak;
+export declare function decodePrivateStateSeatCloseLag(value: unknown): PrivateStateSeatCloseLag;
+export declare function decodePublicationFailed(value: unknown): PublicationFailed;
+export declare function decodeWorktreeWorkspace(value: unknown): Readonly<{
+    kind: "worktree";
+    path: string;
+}>;
+export declare function decodeWorkspaceDirtyDelta(value: unknown): WorkspaceDirtyDelta;
+export declare function decodeWorktreeMissingRefusal(value: unknown): WorktreeMissingRefusal;
+export declare function decodeUnmergedPathsRefusal(value: unknown): Readonly<{
+    kind: "unmerged-paths";
+    contractId: ContractId;
+    paths: readonly string[];
+}>;
+export declare function decodeDirtyWorkspaceRefusal(value: unknown): DirtyWorkspaceRefusal;
+export declare function decodeIntegrationPreparationRefusal(value: unknown): IntegrationPreparationRefusal;
+export declare function decodeCheckoutNotFollowableRefusal(value: unknown): CheckoutNotFollowableRefusal;
+export declare function decodeAuditTargetAnswer(value: unknown): AuditTargetAnswer;
+export declare function decodeGitReconcileLag(value: unknown): ReconcileLag;

package/build/src/git/result-codec.js

@@ -0,0 +1,306 @@
+import { contractId, snapshotId } from "../core/facts/types.js";
+import { mintSnapshotId } from "./identity.js";
+function fail(message = "malformed git result") {
+    throw new Error(message);
+}
+function record(value, required, optional = []) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail();
+    const object = value;
+    const allowed = new Set([...required, ...optional]);
+    for (const key of Object.keys(object))
+        if (!allowed.has(key))
+            fail();
+    for (const key of required)
+        if (!(key in object))
+            fail();
+    return object;
+}
+function nonblank(value) {
+    if (typeof value !== "string" || value.trim() === "")
+        fail();
+    return value;
+}
+function integer(value) {
+    if (typeof value !== "number" || !Number.isInteger(value))
+        fail();
+    return value;
+}
+function nonnegativeInteger(value) {
+    const n = integer(value);
+    if (n < 0)
+        fail();
+    return n;
+}
+function boolean(value) {
+    if (typeof value !== "boolean")
+        fail();
+    return value;
+}
+function strings(value) {
+    if (!Array.isArray(value))
+        fail();
+    return value.map(nonblank);
+}
+function decodeContractId(value) {
+    try {
+        return contractId(nonblank(value));
+    }
+    catch {
+        fail();
+    }
+}
+function decodeSnapshotId(value) {
+    try {
+        return snapshotId(nonblank(value));
+    }
+    catch {
+        fail();
+    }
+}
+function decodeGitSnapshotId(value) {
+    try {
+        return mintSnapshotId(nonblank(value));
+    }
+    catch {
+        fail();
+    }
+}
+export function decodeHookFailure(value) {
+    const object = record(value, ["kind"], ["code", "stdout", "stderr", "truncated", "diagnostic"]);
+    if (object.kind === "timeout" || object.kind === "unknown-exit") {
+        if ("code" in object || "stdout" in object || "stderr" in object || "truncated" in object || "diagnostic" in object)
+            fail();
+        return { kind: object.kind };
+    }
+    if (object.kind === "spawn-error") {
+        if ("code" in object || "stdout" in object || "stderr" in object || "truncated" in object)
+            fail();
+        return { kind: "spawn-error", diagnostic: nonblank(object.diagnostic) };
+    }
+    if (object.kind !== "exit")
+        fail();
+    if ("diagnostic" in object)
+        fail();
+    return {
+        kind: "exit",
+        code: integer(object.code),
+        stdout: typeof object.stdout === "string" ? object.stdout : fail(),
+        stderr: typeof object.stderr === "string" ? object.stderr : fail(),
+        truncated: boolean(object.truncated),
+    };
+}
+export function decodeWorktreeLeak(value) {
+    const object = record(value, ["path", "diagnostic"]);
+    if (typeof object.path !== "string" || typeof object.diagnostic !== "string")
+        fail();
+    return { path: object.path, diagnostic: object.diagnostic };
+}
+export function decodePrivateStateSeatCloseLag(value) {
+    const object = record(value, ["kind", "diagnostic"]);
+    if (object.kind !== "private-state-seat-close-failed")
+        fail();
+    return { kind: "private-state-seat-close-failed", diagnostic: nonblank(object.diagnostic) };
+}
+export function decodePublicationFailed(value) {
+    const object = record(value, ["kind", "diagnostic"]);
+    if (object.kind !== "publication-failed")
+        fail();
+    if (typeof object.diagnostic !== "string")
+        fail();
+    return { kind: "publication-failed", diagnostic: object.diagnostic };
+}
+export function decodeWorktreeWorkspace(value) {
+    const object = record(value, ["kind", "path"]);
+    if (object.kind !== "worktree")
+        fail();
+    return { kind: "worktree", path: nonblank(object.path) };
+}
+export function decodeWorkspaceDirtyDelta(value) {
+    const object = record(value, ["staged", "unstaged", "untracked", "shortStat"]);
+    const shortStat = record(object.shortStat, ["filesChanged", "insertions", "deletions"]);
+    return {
+        staged: Array.isArray(object.staged)
+            ? object.staged.map((path) => (typeof path === "string" ? path : fail()))
+            : fail(),
+        unstaged: Array.isArray(object.unstaged)
+            ? object.unstaged.map((path) => (typeof path === "string" ? path : fail()))
+            : fail(),
+        untracked: Array.isArray(object.untracked)
+            ? object.untracked.map((path) => (typeof path === "string" ? path : fail()))
+            : fail(),
+        shortStat: {
+            filesChanged: integer(shortStat.filesChanged),
+            insertions: integer(shortStat.insertions),
+            deletions: integer(shortStat.deletions),
+        },
+    };
+}
+export function decodeWorktreeMissingRefusal(value) {
+    const object = record(value, ["kind", "contractId"]);
+    if (object.kind !== "worktree-missing")
+        fail();
+    return { kind: "worktree-missing", contractId: decodeContractId(object.contractId) };
+}
+export function decodeUnmergedPathsRefusal(value) {
+    const object = record(value, ["kind", "contractId", "paths"]);
+    if (object.kind !== "unmerged-paths")
+        fail();
+    return { kind: "unmerged-paths", contractId: decodeContractId(object.contractId), paths: strings(object.paths) };
+}
+export function decodeDirtyWorkspaceRefusal(value) {
+    const object = record(value, ["kind", "contractId", "staged", "unstaged", "untracked", "submodules", "shortStat"]);
+    if (object.kind !== "dirty-workspace")
+        fail();
+    const shortStat = record(object.shortStat, ["filesChanged", "insertions", "deletions"]);
+    return {
+        kind: "dirty-workspace",
+        contractId: decodeContractId(object.contractId),
+        staged: strings(object.staged),
+        unstaged: strings(object.unstaged),
+        untracked: strings(object.untracked),
+        submodules: strings(object.submodules),
+        shortStat: {
+            filesChanged: nonnegativeInteger(shortStat.filesChanged),
+            insertions: nonnegativeInteger(shortStat.insertions),
+            deletions: nonnegativeInteger(shortStat.deletions),
+        },
+    };
+}
+export function decodeIntegrationPreparationRefusal(value) {
+    const object = record(value, ["kind", "contractId"], ["reason", "targetHead", "conflictPaths", "requiredGit"]);
+    if (object.kind === "integration-unsupported") {
+        if (object.requiredGit !== "2.38")
+            fail();
+        if ("reason" in object || "targetHead" in object || "conflictPaths" in object)
+            fail();
+        return { kind: "integration-unsupported", contractId: decodeContractId(object.contractId), requiredGit: "2.38" };
+    }
+    if (object.kind !== "integration-failed")
+        fail();
+    if ("requiredGit" in object)
+        fail();
+    if (object.reason !== "not-based-on-target" &&
+        object.reason !== "unrelated-histories" &&
+        object.reason !== "conflict")
+        fail();
+    return {
+        kind: "integration-failed",
+        contractId: decodeContractId(object.contractId),
+        reason: object.reason,
+        targetHead: decodeSnapshotId(object.targetHead),
+        ...(object.conflictPaths === undefined ? {} : { conflictPaths: strings(object.conflictPaths) }),
+    };
+}
+export function decodeCheckoutNotFollowableRefusal(value) {
+    const object = record(value, ["kind", "contractId", "target", "path", "reason", "paths"]);
+    if (object.kind !== "checkout-not-followable")
+        fail();
+    if (object.reason !== "staged" && object.reason !== "conflict" && object.reason !== "untracked")
+        fail();
+    return {
+        kind: "checkout-not-followable",
+        contractId: decodeContractId(object.contractId),
+        target: nonblank(object.target),
+        path: nonblank(object.path),
+        reason: object.reason,
+        paths: strings(object.paths),
+    };
+}
+export function decodeAuditTargetAnswer(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail();
+    const kind = value.kind;
+    if (kind === "placeable") {
+        const object = record(value, ["kind", "ref", "head"]);
+        return { kind: "placeable", ref: nonblank(object.ref), head: decodeSnapshotId(object.head) };
+    }
+    if (kind === "moved") {
+        const object = record(value, ["kind", "ref", "expected", "observed"]);
+        return {
+            kind: "moved",
+            ref: nonblank(object.ref),
+            expected: decodeSnapshotId(object.expected),
+            observed: object.observed === null ? null : decodeSnapshotId(object.observed),
+        };
+    }
+    if (kind === "refused") {
+        const object = record(value, ["kind", "refusal"]);
+        return { kind: "refused", refusal: decodeCheckoutNotFollowableRefusal(object.refusal) };
+    }
+    const object = record(value, ["kind", "diagnostic"]);
+    if (object.kind !== "failed")
+        fail();
+    return { kind: "failed", diagnostic: nonblank(object.diagnostic) };
+}
+export function decodeGitReconcileLag(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail();
+    const kind = value.kind;
+    if (kind === "worktree-retained") {
+        const object = record(value, ["kind", "path"]);
+        return { kind: "worktree-retained", path: nonblank(object.path) };
+    }
+    if (kind === "worktree-follow-retained") {
+        const object = record(value, ["kind", "path", "tender", "head", "reason"], ["paths"]);
+        if (object.reason !== "head-moved" &&
+            object.reason !== "head-attached" &&
+            object.reason !== "operation-in-progress" &&
+            object.reason !== "unsupported-parent-shape")
+            fail();
+        const lag = {
+            kind: "worktree-follow-retained",
+            path: nonblank(object.path),
+            tender: decodeGitSnapshotId(object.tender),
+            head: decodeGitSnapshotId(object.head),
+            reason: object.reason,
+            ...(object.paths === undefined ? {} : { paths: strings(object.paths) }),
+        };
+        return lag;
+    }
+    if (kind === "unsealed-bytes") {
+        const object = record(value, ["kind", "path", "paths"], ["head"]);
+        const lag = {
+            kind: "unsealed-bytes",
+            path: nonblank(object.path),
+            paths: strings(object.paths),
+            ...(object.head === undefined ? {} : { head: decodeGitSnapshotId(object.head) }),
+        };
+        return lag;
+    }
+    if (kind === "target-checkout-retained") {
+        const object = record(value, ["kind", "path", "target", "diagnostic"]);
+        const lag = {
+            kind: "target-checkout-retained",
+            path: nonblank(object.path),
+            target: nonblank(object.target),
+            diagnostic: nonblank(object.diagnostic),
+        };
+        return lag;
+    }
+    if (kind === "reconcile-failed") {
+        const object = record(value, ["kind", "stage", "diagnostic"]);
+        if (object.stage !== "observation" && object.stage !== "effect")
+            fail();
+        const lag = {
+            kind: "reconcile-failed",
+            stage: object.stage,
+            diagnostic: nonblank(object.diagnostic),
+        };
+        return lag;
+    }
+    const object = record(value, ["kind", "phase", "path", "command", "name", "failure"]);
+    if (object.kind !== "worktree-hook-failed")
+        fail();
+    if (object.phase !== "create" && object.phase !== "destroy")
+        fail();
+    const lag = {
+        kind: "worktree-hook-failed",
+        phase: object.phase,
+        path: nonblank(object.path),
+        command: nonnegativeInteger(object.command),
+        name: nonblank(object.name),
+        failure: decodeHookFailure(object.failure),
+    };
+    return lag;
+}

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

@@ -2,7 +2,7 @@ import { lstat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { acquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
 import { gitObjectId, gitObjectIdForSnapshot, gitRefLocator, mintSnapshotId } from "./identity.js";
-import { commonGitDirectory, readRef, registeredWorktrees } from "./repository.js";
+import { commonGitDirectory, decodeGitNameOnly, readRef, registeredWorktrees } from "./repository.js";
 import { consumeGitStdout, GitPlumbingError, runGit } from "./process.js";
 import { captureWorkspaceTree } from "./workspace.js";
 export async function observeTargetHead(repository, target) {
@@ -12,14 +12,8 @@ export async function observeTargetHead(repository, target) {
 function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function nulPaths(bytes) {
-    const fields = bytes.toString("utf8").split("\0");
-    if (fields.at(-1) !== "")
-        throw new Error("Git path output is not NUL terminated");
-    return [...new Set(fields.slice(0, -1))].sort();
-}
 async function gitPaths(repository, path, args) {
-    return nulPaths(await runGit(repository, ["-C", path, ...args]));
+    return [...new Set(decodeGitNameOnly(await runGit(repository, ["-C", path, ...args])))].sort();
 }
 function literalPath(path) {
     return `:(literal)${path}`;

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

@@ -15,6 +15,8 @@ export type WorkspaceTree = Readonly<{
     changes: WorkspaceChanges;
 }>;
 export declare function worktreePath(repository: GitRepository, place: string): string;
+/** Check out a captured candidate tree in the appointed detached worktree. */
+export declare function checkoutDetachedSnapshot(repository: GitRepository, workspace: string, snapshot: SnapshotId): Promise<void>;
 export type DependentWorktreeFollow = Readonly<{
     kind: "followed";
     before: SnapshotId;

package/build/src/git/workspace.js

@@ -8,6 +8,10 @@ const WORKTREE_DIRECTORY = [".keiyaku", "wt"];
 export function worktreePath(repository, place) {
     return resolve(repository.primaryWorktree, ...WORKTREE_DIRECTORY, place);
 }
+/** Check out a captured candidate tree in the appointed detached worktree. */
+export async function checkoutDetachedSnapshot(repository, workspace, snapshot) {
+    await runGit(repository, ["-C", workspace, "checkout", "--quiet", "--force", "--detach", gitObjectId(snapshot)]);
+}
 async function workspaceRevision(repository, workspace, revision) {
     try {
         const value = (await runGit(repository, ["-C", workspace, "rev-parse", "--verify", "--quiet", revision]))