@astrosheep/keiyaku 4.5.9 → 4.5.11

package/build/src/cli/commands/contract.js

@@ -1,6 +1,8 @@
 import { archetypeName } from "../../akuma/identity.js";
 import { parseTaskNamespaceSelector } from "../../task/catalog.js";
-import { CliUsageError, usageLine } from "../usage.js";
+import { CliUsageError } from "../usage.js";
+import { renderContractUsage } from "./contract-help.js";
+export { CONTRACT_COMMAND_SPECS, renderContractHelp, renderContractUsage, } from "./contract-help.js";
 function parseAkumaCatalogPath(value) {
     if (value === "aku" || value === "aku/")
         return { kind: "archetypes" };
@@ -11,135 +13,6 @@ function parseAkumaCatalogPath(value) {
         return null;
     return { kind: "akuma", archetype: archetypeName(match[1]) };
 }
-export const CONTRACT_COMMAND_SPECS = {
-    bind: {
-        positional: "none",
-        stdin: "optional",
-        flags: {
-            actor: "value",
-            task: "value",
-            target: "value",
-            after: "repeat-value",
-            gates: "raw-value",
-            "fork-of": "value",
-            json: "boolean",
-        },
-        usage: "bind [--task <task/...>] [--target <ref>] [--after <kei/...> ...] [--gates <name,...>] [--actor <actor>] [--json] - | bind --fork-of <kei/...> [--target <ref>] [--actor <actor>] [--json]",
-        purpose: "Create one Contract from stdin Markdown or a sibling fork.",
-    },
-    amend: {
-        positional: "optional",
-        stdin: "optional",
-        flags: { actor: "value", after: "repeat-value", "clear-after": "boolean", gates: "raw-value", json: "boolean" },
-        usage: "amend [<contract>|@<contract>] [--after <kei/...> ... | --clear-after] [--gates <name,...>] [--actor <actor>] [--json] [-]",
-        purpose: "Amend one Contract's document operations or structured terms.",
-        details: [
-            "  ## Context|Objective|Design|Region|Criteria|Verification|<extension>  (replace, or add new extension)",
-            "  ## Replace: Context|Objective|Design|Region|Criteria|Verification|<extension>",
-            "  ## Append: Context|Objective|Design|Criteria|<extension>",
-            "  ## Add: Criteria|<new-extension-title>",
-            "  ## Update: <existing-extension-title>",
-            "  ## Remove: <existing-extension-title>",
-        ].join("\n"),
-    },
-    deliver: {
-        positional: "optional",
-        stdin: "none",
-        flags: {
-            message: "value",
-            "include-dirty": "boolean",
-            "materialize-conflict": "boolean",
-            json: "boolean",
-        },
-        usage: "deliver [<contract>|@<contract>] [--message <text>] [--include-dirty] [--materialize-conflict] [--json]",
-        purpose: "Deliver one Contract candidate from the appointed worktree.",
-        details: [
-            "  --include-dirty         Capture the complete non-ignored worktree tree as the",
-            "                          candidate; stages nothing, commits nothing, including",
-            "                          an unmerged shared index.",
-            "  --materialize-conflict  After a conflict result, project the judged targetHead",
-            "                          into the worktree as an uncommitted merge. Not a",
-            "                          delivery: resolve, then deliver with --include-dirty.",
-        ].join("\n"),
-    },
-    review: {
-        positional: "optional",
-        stdin: "optional",
-        flags: { satisfied: "boolean", unsatisfied: "boolean", summary: "value", json: "boolean" },
-        usage: "review [<contract>|@<contract>] (--satisfied | --unsatisfied) (--summary <text> | -) [--json]",
-        purpose: "Record one review verdict.",
-    },
-    arc: {
-        positional: "optional",
-        stdin: "required",
-        flags: { actor: "value", json: "boolean" },
-        usage: "arc [<contract>|@<contract>] [--actor <actor>] [--json] -",
-        purpose: "Record stdin arc Markdown for one Contract.",
-    },
-    abandon: {
-        positional: "optional",
-        stdin: "none",
-        flags: { actor: "value", note: "value", json: "boolean" },
-        usage: "abandon [<contract>|@<contract>] [--note <text>] [--actor <actor>] [--json]",
-        purpose: "Abandon one Contract with an optional note.",
-    },
-    status: {
-        positional: "optional",
-        stdin: "none",
-        flags: { json: "boolean" },
-        usage: "status [<contract>|@name|<aku/...>]... [--json]",
-        purpose: "Read the world status board or one or more Contract and Akuma projections.",
-    },
-    show: {
-        positional: "optional",
-        stdin: "none",
-        flags: { json: "boolean" },
-        usage: "show [<contract>|@<contract>] [--json]",
-        purpose: "Read one Contract guidance projection.",
-    },
-    ls: {
-        positional: "optional",
-        stdin: "none",
-        flags: { json: "boolean" },
-        usage: 'ls task[/] [--json]\nls kei[/] [--json]\nls aku[/] [--json]\nls aku/<akuma>[/] [--json]\nls "aku/*/*" [--json]',
-        purpose: "List one identity directory.",
-    },
-    audit: {
-        positional: "optional",
-        stdin: "none",
-        flags: { "include-dirty": "boolean", diff: "boolean", json: "boolean" },
-        usage: "audit [<contract>|@<contract>] [--include-dirty] [--diff] [--json]",
-        purpose: "Ask what candidate preparation, Verification, and target placement would do.",
-    },
-    reconcile: {
-        positional: "optional",
-        stdin: "none",
-        flags: { "retry-hooks": "boolean", json: "boolean" },
-        usage: "reconcile [<contract>|@<contract>] [--retry-hooks] [--json]",
-        purpose: "Reconcile one Contract or the invocation world.",
-    },
-    nuke: {
-        positional: "none",
-        stdin: "none",
-        flags: { confirm: "value", json: "boolean" },
-        usage: "nuke [--confirm <WorldRoot>] [--json]",
-        purpose: "Remove Keiyaku-owned data from one confirmed World.",
-    },
-    settings: {
-        positional: "none",
-        stdin: "none",
-        flags: { json: "boolean" },
-        usage: "settings [--json]",
-        purpose: "Show effective Settings (user + project, read-only)",
-    },
-    region: {
-        positional: "optional",
-        stdin: "none",
-        flags: { path: "repeat-value", json: "boolean" },
-        usage: "region [<contract>] [--json]\nregion --path <pattern> [--path <pattern> ...] [--json]",
-        purpose: "Read active declared Contract Regions.",
-    },
-};
 function optionalFlag(flags, name) {
     const value = flags[name];
     return typeof value === "string" ? value : undefined;
@@ -296,36 +169,6 @@ function parseLs(parts) {
         refuse("ls", error instanceof Error ? error.message : "invalid ls directory");
     }
 }
-export function renderContractHelp(command) {
-    const spec = CONTRACT_COMMAND_SPECS[command];
-    if (command === "settings") {
-        return [
-            "Show effective Settings — the merged read-only view of:",
-            "  user      ~/.keiyaku/settings.json",
-            "  project   <WorldRoot>/.keiyaku/settings.json",
-            "A project record wholly shadows the same-name user record.",
-            "",
-            "Shape: namespace -> entry -> JSON value. There is no write",
-            "command; edit the files directly.",
-            "",
-            "Recognized settings:",
-            "  gates                            gate bundles selected by bind and amend",
-            "  worktree                         commands run when worktrees are created or destroyed",
-            "  git.requireBranchesToBeUpToDate  whether deliver and audit require up-to-date target branches",
-            "  providers                        the available Akuma and how each is run",
-            "",
-            "Each entry is validated by the feature that reads it. A rejected",
-            "value's diagnostic states the expected shape.",
-            "",
-            usageLine(spec.usage),
-        ].join("\n");
-    }
-    const help = `${spec.purpose}\n\n${usageLine(spec.usage)}`;
-    return spec.details === undefined ? help : `${help}\n\n${spec.details}`;
-}
-export function renderContractUsage(command) {
-    return usageLine(CONTRACT_COMMAND_SPECS[command].usage);
-}
 export function parseContractCommand(parts) {
     switch (parts.command) {
         case "bind":

package/build/src/contract-guidance.js

@@ -19,12 +19,16 @@ export const CONTRACT_DELIVERER_SKILL = [
     "",
     "## Deliver",
     "",
+    "`deliver` creates the immutable candidate commit and prepares its integration with the target as it exists for that invocation. It runs or reuses Verification, records the candidate, and requests placement. If the target moves, run `deliver` again; Keiyaku recomputes the current-target integration. A manual rebase is optional candidate shaping, not target refresh.",
+    "",
+    "When the finished worktree itself is the candidate, use `deliver --include-dirty`; Keiyaku captures its complete non-ignored state without moving this worktree's HEAD or real index.",
+    "",
     "```bash",
     "keiyaku deliver <contract> --include-dirty",
     "keiyaku deliver <contract> --materialize-conflict",
     "```",
     "",
-    "Delivery submits the full current worktree state as the candidate for review and placement. Deliver when Verification passes and the evidence is in place; the Reviewer judges the rest.",
+    "If delivery reports an integration conflict, materialize that judged conflict, resolve it in this worktree, then deliver the resolved bytes with `--include-dirty`. Deliver when the candidate is ready and the evidence is in place; delivery records and requests placement, while the Reviewer independently judges any declared review gate.",
 ]
     .join("\n")
     .concat("\n");

package/build/src/git/reconcile.js

@@ -8,7 +8,7 @@ import { contractLocator, contractPhysicalName, gitObjectIdForSnapshot } from ".
 import { observeContractAt } from "./observe.js";
 import { acquireTargetPlacementFence, recoverTargetPlacement, } from "./target-placement.js";
 import { runCreateHooks } from "./hooks.js";
-import { followDependentManagedWorktree, followManagedWorktree, worktreePath } from "./workspace.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";
@@ -111,26 +111,19 @@ async function reconcileActiveManagedWorktree({ repository, hooks, retryHooks, p
     const desired = state.delivery?.data.tenderSnapshot ?? state.coordinates.start;
     effects.push(await updateRef(repository, deliveryRefFor(state.id), desired));
     const projection = await worktree(repository, topology, path, desired);
-    if (projection.kind === "worktree" && projection.action === "unchanged" && state.delivery !== null) {
-        const follow = await followManagedWorktree(repository, path, state.delivery.data.tenderSnapshot);
-        if (follow.kind === "followed") {
-            effects.push({ kind: "worktree", path, action: "followed", before: follow.before, after: follow.after });
-        }
-        else {
-            effects.push(projection);
-            if (follow.kind === "retained") {
-                lag.push({
-                    kind: "worktree-follow-retained",
-                    path,
-                    tender: state.delivery.data.tenderSnapshot,
-                    head: follow.head,
-                    reason: follow.reason,
-                });
-            }
-        }
-    }
-    else {
-        effects.push(projection);
+    effects.push(projection);
+    const handoff = await retireConflictHandoff(repository, {
+        contractId: state.id,
+        place,
+        workspace: path,
+        consume: state.delivery !== null,
+    });
+    if (state.delivery !== null && handoff.kind === "retained") {
+        lag.push({
+            kind: "reconcile-failed",
+            stage: "effect",
+            diagnostic: `conflict handoff retirement retained: ${handoff.reason}`,
+        });
     }
     if (projection.action === "created" || retryHooks) {
         const hookRun = await runCreateHooks(path, hooks);
@@ -143,6 +136,35 @@ async function reconcileActiveManagedWorktree({ repository, hooks, retryHooks, p
         : await removeRef(repository, candidatePinRefFor(state.id))));
     return complete(effects, lag, hookRuns);
 }
+async function terminalHandoffRetained(input, state, topology, lag) {
+    if (input.place === undefined)
+        return false;
+    const path = worktreePath(input.repository, input.place);
+    if (!topology.paths.has(path) && !(await pathExists(path)))
+        return false;
+    const handoff = await retireConflictHandoff(input.repository, {
+        contractId: state.id,
+        place: input.place,
+        workspace: path,
+        consume: state.delivery !== null,
+    });
+    if (handoff.kind === "active") {
+        lag.push({
+            kind: "reconcile-failed",
+            stage: "effect",
+            diagnostic: "conflict handoff retirement retained: active",
+        });
+        return true;
+    }
+    if (handoff.kind !== "retained")
+        return false;
+    lag.push({
+        kind: "reconcile-failed",
+        stage: "effect",
+        diagnostic: `conflict handoff retirement retained: ${handoff.reason}`,
+    });
+    return true;
+}
 async function reconcileWithTopology(input, state, topology) {
     const { repository } = input;
     const effects = [];
@@ -161,6 +183,8 @@ async function reconcileWithTopology(input, state, topology) {
         effects.push(...targetCheckouts.effects);
         lag.push(...targetCheckouts.lag);
         if (state.terminal) {
+            if (await terminalHandoffRetained(input, state, topology, lag))
+                return complete(effects, lag, hookRuns);
             return await reconcileTerminalManagedWorktree(input, state, topology, { effects, lag, hookRuns }, { ref: deliveryRefFor(state.id), pin: candidatePinRefFor(state.id) });
         }
         const result = await reconcileActiveManagedWorktree(input, state, topology, { effects, lag, hookRuns });

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

@@ -4,6 +4,7 @@ export type { TreeChange } from "./tree.js";
 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";

package/build/src/git/repository.js

@@ -7,6 +7,7 @@ import { parseTreeObject, prepareTreeUpdate, treeUpdate, validPath, } from "./tr
 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";
@@ -19,6 +20,8 @@ export function isKeiyakuOwnedRef(ref) {
         ref.startsWith(`${DELIVERY_REF_NAMESPACE}/`) ||
         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 ||

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

@@ -1,4 +1,4 @@
-import type { SnapshotId } from "../core/facts/types.js";
+import type { ContractId, SnapshotId } from "../core/facts/types.js";
 import { type GitObjectId } from "./identity.js";
 import { type GitRepository } from "./process.js";
 export type WorkspaceChanges = Readonly<{
@@ -15,17 +15,6 @@ export type WorkspaceTree = Readonly<{
     changes: WorkspaceChanges;
 }>;
 export declare function worktreePath(repository: GitRepository, place: string): string;
-export type ManagedWorktreeFollow = Readonly<{
-    kind: "followed";
-    before: SnapshotId;
-    after: SnapshotId;
-}> | Readonly<{
-    kind: "unchanged";
-}> | Readonly<{
-    kind: "retained";
-    head: SnapshotId;
-    reason: "head-moved" | "head-attached" | "operation-in-progress" | "unsupported-parent-shape";
-}>;
 export type DependentWorktreeFollow = Readonly<{
     kind: "followed";
     before: SnapshotId;
@@ -38,8 +27,6 @@ export type DependentWorktreeFollow = Readonly<{
     reason: "head-moved" | "head-attached" | "operation-in-progress";
     paths: readonly string[];
 }>;
-/** Follow an accepted tender only through the native index-and-HEAD transition. */
-export declare function followManagedWorktree(repository: GitRepository, workspace: string, tender: SnapshotId): Promise<ManagedWorktreeFollow>;
 /** Follow a dependency baseline only through a clean, detached fast-forward. */
 export declare function followDependentManagedWorktree(repository: GitRepository, workspace: string, target: SnapshotId): Promise<DependentWorktreeFollow>;
 export declare function withPrivateGitIndex<Value>(action: (environment: Readonly<{
@@ -91,3 +78,22 @@ export declare function observeWorkspace(repository: GitRepository, location: Co
 export declare function observeTargetLag(repository: GitRepository, workspace: string, head: SnapshotId | null | undefined): Promise<ContractTargetLag>;
 /** Capture tracked and untracked workspace bytes without changing its real index. */
 export declare function captureWorkspaceTree(repository: GitRepository, workspace: string): Promise<WorkspaceTree>;
+export type HandoffRetirement = Readonly<{
+    kind: "absent" | "active" | "orphan-retired" | "retired";
+}> | Readonly<{
+    kind: "retained";
+    reason: "receipt-mismatch" | "operation-in-progress";
+}>;
+export declare function recordConflictHandoff(repository: GitRepository, input: Readonly<{
+    contractId: ContractId;
+    place: string;
+    workspace: string;
+    head: SnapshotId;
+    mergeHead: SnapshotId;
+}>): Promise<void>;
+export declare function retireConflictHandoff(repository: GitRepository, input: Readonly<{
+    contractId: ContractId;
+    place: string;
+    workspace: string;
+    consume: boolean;
+}>): Promise<HandoffRetirement>;

package/build/src/git/workspace.js

@@ -1,9 +1,9 @@
 import { access, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { gitObjectId, mintSnapshotId } from "./identity.js";
+import { contractPhysicalName, gitObjectId, mintSnapshotId } from "./identity.js";
 import { GitPlumbingError, runGit, runGitWithEnvironment } from "./process.js";
-import { worktreeGitDirectory } from "./repository.js";
+import { HANDOFF_RECEIPT_REF_NAMESPACE, readBlob, readRef, worktreeGitDirectory, writeBlob } from "./repository.js";
 const WORKTREE_DIRECTORY = [".keiyaku", "wt"];
 export function worktreePath(repository, place) {
     return resolve(repository.primaryWorktree, ...WORKTREE_DIRECTORY, place);
@@ -35,41 +35,6 @@ async function workspaceOperationState(repository, workspace, gitDirectory) {
     const unmerged = (await runGit(repository, ["-C", workspace, "ls-files", "--unmerged", "-z"])).length > 0;
     return { other: other.some(Boolean), unmerged };
 }
-/** Follow an accepted tender only through the native index-and-HEAD transition. */
-export async function followManagedWorktree(repository, workspace, tender) {
-    const head = await workspaceRevision(repository, workspace, "HEAD");
-    if (head === null)
-        throw new Error("managed worktree HEAD is missing");
-    const attached = await runGit(repository, ["-C", workspace, "symbolic-ref", "--quiet", "HEAD"]).then(() => true, (error) => {
-        if (error instanceof GitPlumbingError && error.status === 1)
-            return false;
-        throw error;
-    });
-    if (attached)
-        return { kind: "retained", head, reason: "head-attached" };
-    if (head === tender)
-        return { kind: "unchanged" };
-    const parents = (await runGit(repository, ["show", "-s", "--format=%P", gitObjectId(tender)]))
-        .toString("utf8")
-        .trim()
-        .split(" ")
-        .filter((parent) => parent.length > 0)
-        .map((parent) => mintSnapshotId(parent));
-    if (parents.length > 0 && head !== parents[0])
-        return { kind: "retained", head, reason: "head-moved" };
-    if (parents.length !== 1 && parents.length !== 2)
-        return { kind: "retained", head, reason: "unsupported-parent-shape" };
-    const gitDirectory = await worktreeGitDirectory(repository, workspace);
-    const mergeHead = await workspaceRevision(repository, workspace, "MERGE_HEAD");
-    const operation = await workspaceOperationState(repository, workspace, gitDirectory);
-    const admitted = parents.length === 1
-        ? mergeHead === null && !operation.other && !operation.unmerged
-        : mergeHead === parents[1] && !operation.other && !operation.unmerged;
-    if (!admitted)
-        return { kind: "retained", head, reason: "operation-in-progress" };
-    await runGit(repository, ["-C", workspace, "reset", "--mixed", gitObjectId(tender)]);
-    return { kind: "followed", before: head, after: tender };
-}
 /** Follow a dependency baseline only through a clean, detached fast-forward. */
 export async function followDependentManagedWorktree(repository, workspace, target) {
     const head = await workspaceRevision(repository, workspace, "HEAD");
@@ -214,7 +179,11 @@ export async function workspaceMergeHead(repository, workspace) {
 }
 /** True when the appointed workspace already has Git MERGE_HEAD. */
 export async function workspaceMergeStatePresent(repository, workspace) {
-    return (await workspaceMergeHead(repository, workspace)) !== undefined;
+    if ((await workspaceMergeHead(repository, workspace)) !== undefined)
+        return true;
+    const gitDirectory = await worktreeGitDirectory(repository, workspace);
+    const operation = await workspaceOperationState(repository, workspace, gitDirectory);
+    return operation.other || operation.unmerged;
 }
 /** Sorted unique unmerged index paths from porcelain status. */
 export async function unmergedWorkspacePaths(repository, workspace) {
@@ -293,3 +262,87 @@ export async function captureWorkspaceTree(repository, workspace) {
         };
     });
 }
+const handoffRefFor = (contractId, place) => `${HANDOFF_RECEIPT_REF_NAMESPACE}/${contractPhysicalName(contractId)}/${place}`;
+function receiptFor(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("handoff receipt is malformed");
+    const record = value;
+    if (record.version !== 1 ||
+        typeof record.contractId !== "string" ||
+        typeof record.place !== "string" ||
+        typeof record.workspace !== "string" ||
+        typeof record.head !== "string" ||
+        typeof record.mergeHead !== "string") {
+        throw new Error("handoff receipt is malformed");
+    }
+    return {
+        version: 1,
+        contractId: record.contractId,
+        place: record.place,
+        workspace: resolve(record.workspace),
+        head: mintSnapshotId(record.head),
+        mergeHead: mintSnapshotId(record.mergeHead),
+    };
+}
+async function storedHandoffReceipt(repository, contractId, place) {
+    const ref = handoffRefFor(contractId, place);
+    const oid = await readRef(repository, ref);
+    if (oid === null)
+        return null;
+    const receipt = receiptFor(JSON.parse((await readBlob(repository, oid)).toString("utf8")));
+    return { receipt, ref, oid };
+}
+async function removeHandoffReceipt(repository, stored) {
+    await runGit(repository, ["update-ref", "--no-deref", "-d", stored.ref, stored.oid]);
+}
+export async function recordConflictHandoff(repository, input) {
+    const ref = handoffRefFor(input.contractId, input.place);
+    const existing = await readRef(repository, ref);
+    if (existing !== null)
+        throw new Error("a conflict handoff receipt is already active");
+    const receipt = {
+        version: 1,
+        contractId: input.contractId,
+        place: input.place,
+        workspace: resolve(input.workspace),
+        head: input.head,
+        mergeHead: input.mergeHead,
+    };
+    const oid = await writeBlob(repository, `${JSON.stringify(receipt)}\n`);
+    await runGit(repository, ["update-ref", "--no-deref", ref, oid, "0".repeat(oid.length)]);
+}
+export async function retireConflictHandoff(repository, input) {
+    const stored = await storedHandoffReceipt(repository, input.contractId, input.place);
+    if (stored === null)
+        return { kind: "absent" };
+    const { receipt } = stored;
+    if (receipt.contractId !== input.contractId ||
+        receipt.place !== input.place ||
+        receipt.workspace !== resolve(input.workspace)) {
+        return { kind: "retained", reason: "receipt-mismatch" };
+    }
+    const gitDirectory = await worktreeGitDirectory(repository, input.workspace);
+    const operation = await workspaceOperationState(repository, input.workspace, gitDirectory);
+    if (operation.other)
+        return { kind: "retained", reason: "operation-in-progress" };
+    const [head, mergeHead] = await Promise.all([
+        workspaceRevision(repository, input.workspace, "HEAD"),
+        workspaceRevision(repository, input.workspace, "MERGE_HEAD"),
+    ]);
+    if (mergeHead === null) {
+        if (operation.unmerged)
+            return { kind: "retained", reason: "operation-in-progress" };
+        await removeHandoffReceipt(repository, stored);
+        return { kind: "orphan-retired" };
+    }
+    if (head !== receipt.head)
+        return { kind: "retained", reason: "receipt-mismatch" };
+    if (mergeHead !== receipt.mergeHead) {
+        return { kind: "retained", reason: "receipt-mismatch" };
+    }
+    if (!input.consume)
+        return { kind: "active" };
+    await runGit(repository, ["-C", input.workspace, "merge", "--quit"]);
+    await removeHandoffReceipt(repository, stored);
+    return { kind: "retired" };
+}