@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/core/transcripts.js

@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { parseResolvedAkumaLaunchSnapshot, } from "../agents/launch-snapshot/model.js";
 import { resolvePersistedSubagentSession } from "../agents/session.js";
+import { OutcomeErrorValidationError, parseCurrentOutcomeError, } from "../agents/harness/index.js";
 import { isErrnoException } from "../errno.js";
 import { FlowError, requireText } from "../flow-error.js";
 import { getCurrentBranch } from "../git/branches.js";
@@ -19,6 +20,7 @@ export { isResponseArtifactId, RESPONSE_ARTIFACT_ID_RE } from "./response-artifa
 const RESPONSE_HISTORY_SLUG_MAX_LENGTH = 24;
 const RESPONSE_HISTORY_SESSION_KEY = "session";
 const RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY = "launch_snapshot";
+const RESPONSE_HISTORY_TERMINAL_FAILURE_KEY = "terminal_failure";
 const RESPONSE_HISTORY_PROVENANCE_KEY = "provenance";
 const REVIEW_HISTORY_FILE_RE = /^\d{8}-\d{9}_REVIEW_(\d+)\.md$/;
 /** Artifact-owner rendering of seal receipt/diffstat facts into the durable Diff section. */
@@ -99,6 +101,7 @@ function buildMarkdown(input, iso, provenance) {
         `${RESPONSE_HISTORY_PROVENANCE_KEY}: ${yamlQuote(JSON.stringify(provenance))}`,
         ...(input.session ? [`${RESPONSE_HISTORY_SESSION_KEY}: ${yamlQuote(JSON.stringify(input.session))}`] : []),
         ...(input.launchSnapshot ? [`${RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY}: ${yamlQuote(JSON.stringify(input.launchSnapshot))}`] : []),
+        ...(input.tool === "call" && input.terminalFailure ? [`${RESPONSE_HISTORY_TERMINAL_FAILURE_KEY}: ${yamlQuote(JSON.stringify(input.terminalFailure))}`] : []),
         ...(input.subagentName?.trim() ? [`subagent_name: ${yamlQuote(input.subagentName.trim())}`] : []),
         ...(input.effectivePolicy ? [`effective_policy: ${yamlQuote(JSON.stringify(input.effectivePolicy))}`] : []),
         `time: ${yamlQuote(iso)}`,
@@ -172,6 +175,10 @@ export async function readResponseArtifact(input) {
             throw new FlowError("INVALID_RESPONSE_PATH", `Response artifact not found: '${locator}'.`);
         throw error;
     }
+    return parseResponseArtifactDocument(input, locator, absolutePath, document);
+}
+/** Parse one already-read response document without a second filesystem read. */
+async function parseResponseArtifactDocument(input, locator, absolutePath, document) {
     const ast = parseToAST(document);
     const frontmatter = ast.frontmatter?.entries;
     if (!frontmatter)
@@ -215,9 +222,94 @@ export async function readResponseArtifact(input) {
             throw artifactError(locator, RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY, `is invalid${error instanceof Error ? ` (${error.message})` : ""}`);
         }
     }
+    let terminalFailure;
+    const rawTerminalFailure = frontmatter[RESPONSE_HISTORY_TERMINAL_FAILURE_KEY];
+    if (rawTerminalFailure !== undefined) {
+        let terminalFailureValue;
+        try {
+            terminalFailureValue = JSON.parse(rawTerminalFailure);
+        }
+        catch (error) {
+            throw artifactError(locator, RESPONSE_HISTORY_TERMINAL_FAILURE_KEY, `contains malformed JSON${error instanceof Error ? ` (${error.message})` : ""}`);
+        }
+        try {
+            terminalFailure = parseCurrentOutcomeError(terminalFailureValue, RESPONSE_HISTORY_TERMINAL_FAILURE_KEY);
+        }
+        catch (error) {
+            if (error instanceof OutcomeErrorValidationError) {
+                throw artifactError(locator, RESPONSE_HISTORY_TERMINAL_FAILURE_KEY, `is invalid (${error.message})`);
+            }
+            throw error;
+        }
+    }
     const subagentName = frontmatter.subagent_name?.trim() || undefined;
     const storageRoot = await fs.realpath(path.resolve(path.dirname(absolutePath), "..", ".."));
-    return { artifactId: provenance.artifactId, responsePath: path.relative(input.cwd, absolutePath), absolutePath, storageRoot, provenance, tool, ...(session ? { session } : {}), ...(launchSnapshot ? { launchSnapshot } : {}), ...(subagentName ? { subagentName } : {}) };
+    return { artifactId: provenance.artifactId, responsePath: path.relative(input.cwd, absolutePath), absolutePath, storageRoot, provenance, tool, ...(session ? { session } : {}), ...(launchSnapshot ? { launchSnapshot } : {}), ...(terminalFailure ? { terminalFailure } : {}), ...(subagentName ? { subagentName } : {}) };
+}
+function artifactIdFromDocument(document) {
+    const encoded = parseToAST(document).frontmatter?.entries?.[RESPONSE_HISTORY_PROVENANCE_KEY];
+    if (encoded === undefined)
+        return undefined;
+    try {
+        const provenance = JSON.parse(encoded);
+        return isPlainRecord(provenance) && typeof provenance.artifactId === "string" && isResponseArtifactId(provenance.artifactId)
+            ? provenance.artifactId
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read each response artifact file at most once to build a query-local lookup. */
+export async function indexResponseArtifacts(input) {
+    let stableRoot;
+    try {
+        stableRoot = await fs.realpath(input.cwd);
+    }
+    catch (error) {
+        if (!isErrnoException(error) || error.code !== "ENOENT")
+            throw error;
+        stableRoot = path.resolve(input.cwd);
+    }
+    const historyDir = path.join(stableRoot, RESPONSE_HISTORY_DIR);
+    let names;
+    try {
+        names = await (input.readDirectory ?? fs.readdir)(historyDir);
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT")
+            return { coverage: "complete", lookup: () => undefined };
+        throw error;
+    }
+    const entries = new Map();
+    let coverage = "complete";
+    for (const name of names.filter((candidate) => candidate.endsWith(".md")).sort()) {
+        const responsePath = path.join(RESPONSE_HISTORY_DIR, name);
+        let document;
+        try {
+            document = await fs.readFile(path.join(stableRoot, responsePath), "utf8");
+            const artifact = await parseResponseArtifactDocument({ cwd: stableRoot, responsePath }, responsePath, path.join(stableRoot, responsePath), document);
+            if (!artifact)
+                continue;
+            if (entries.has(artifact.artifactId))
+                entries.set(artifact.artifactId, { state: "incompatible" });
+            else
+                entries.set(artifact.artifactId, { state: "available", artifact });
+        }
+        catch (error) {
+            const artifactId = document === undefined ? undefined : artifactIdFromDocument(document);
+            if (isErrnoException(error)) {
+                if (artifactId && error.code !== "ENOENT")
+                    entries.set(artifactId, { state: "unavailable" });
+                if (error.code !== "ENOENT")
+                    coverage = "incomplete";
+            }
+            else if (artifactId) {
+                entries.set(artifactId, { state: "incompatible" });
+            }
+        }
+    }
+    return { coverage, lookup: (artifactId) => entries.get(artifactId) };
 }
 async function findResponseArtifactAtRoot(input) {
     const physicalHistoryDir = path.join(input.stableRoot, RESPONSE_HISTORY_DIR);

package/build/core/worktree-bootstrap.js

@@ -1,5 +1,6 @@
 import { spawn as nodeSpawn } from "node:child_process";
-export const WORKTREE_BOOTSTRAP_STDERR_TAIL_BYTES = 2048;
+import { terminateProcessGroup } from "./process-group.js";
+export const WORKTREE_BOOTSTRAP_OUTPUT_TAIL_BYTES = 2048;
 export const WORKTREE_BOOTSTRAP_KILL_GRACE_MS = 10_000;
 function defaultWait(ms) {
     return new Promise((resolve) => {
@@ -8,16 +9,16 @@ function defaultWait(ms) {
     });
 }
 /** Retain the last 2048 UTF-8 bytes and decode lossily (partial leading code point → U+FFFD). */
-export function tailUtf8Bytes(bytes, maxBytes = WORKTREE_BOOTSTRAP_STDERR_TAIL_BYTES) {
+export function tailUtf8Bytes(bytes, maxBytes = WORKTREE_BOOTSTRAP_OUTPUT_TAIL_BYTES) {
     const truncated = bytes.byteLength > maxBytes;
     const slice = truncated ? bytes.subarray(bytes.byteLength - maxBytes) : bytes;
     return { text: slice.toString("utf8"), truncated };
 }
 /**
- * Rolling stderr accumulator: holds at most `maxBytes` across every chunk and
- * remembers whether any earlier prefix was dropped. Never retains unbounded stderr.
+ * Rolling output accumulator: holds at most `maxBytes` across every chunk and
+ * remembers whether any earlier prefix was dropped.
  */
-function createRollingByteTail(maxBytes = WORKTREE_BOOTSTRAP_STDERR_TAIL_BYTES) {
+function createRollingByteTail(maxBytes = WORKTREE_BOOTSTRAP_OUTPUT_TAIL_BYTES) {
     let tail = Buffer.alloc(0);
     let truncated = false;
     return {
@@ -56,17 +57,15 @@ function createRollingByteTail(maxBytes = WORKTREE_BOOTSTRAP_STDERR_TAIL_BYTES)
         },
     };
 }
-function observationFrom(result, durationMs, stderr) {
+function observationFrom(result, durationMs, output) {
     const safeDuration = Math.max(0, Math.min(Number.MAX_SAFE_INTEGER, Math.trunc(durationMs)));
-    if (!stderr || stderr.bytes.byteLength === 0) {
-        return { result, durationMs: safeDuration };
-    }
-    // Buffer is already the bounded tail; decode lossily (partial leading code point → U+FFFD).
     return {
         result,
         durationMs: safeDuration,
-        stderrTail: stderr.bytes.toString("utf8"),
-        ...(stderr.truncated ? { stderrTruncated: true } : {}),
+        ...(output.stdout ? { stdoutTail: output.stdout.bytes.toString("utf8") } : {}),
+        ...(output.stdout?.truncated ? { stdoutTruncated: true } : {}),
+        ...(output.stderr ? { stderrTail: output.stderr.bytes.toString("utf8") } : {}),
+        ...(output.stderr?.truncated ? { stderrTruncated: true } : {}),
     };
 }
 function spawnFailureObservation(message, durationMs) {
@@ -78,17 +77,10 @@ function spawnFailureObservation(message, durationMs) {
         ...(tail.truncated ? { stderrTruncated: true } : {}),
     };
 }
-function killChild(child, signal) {
-    try {
-        child.kill(signal);
-    }
-    catch {
-        // Process may have raced out between the liveness check and kill.
-    }
-}
 /**
  * Run the project-declared worktree bootstrap once.
- * argv only (shell: false), cwd = new worktree, inherited env, stdin/stdout ignored, stderr piped.
+ * argv only (shell: false), cwd = new worktree, inherited env, stdin ignored.
+ * Output capture is opt-in so bind retains its established stdio and persistence behavior.
  */
 export async function runWorktreeBootstrap(input, dependencies = {}) {
     const spawn = dependencies.spawn ?? nodeSpawn;
@@ -102,6 +94,7 @@ export async function runWorktreeBootstrap(input, dependencies = {}) {
         };
     }
     const startedAt = nowMs();
+    const stdoutTail = input.captureOutput ? createRollingByteTail() : null;
     const stderrTail = createRollingByteTail();
     let child;
     try {
@@ -109,7 +102,8 @@ export async function runWorktreeBootstrap(input, dependencies = {}) {
             cwd: input.cwd,
             env: process.env,
             shell: false,
-            stdio: ["ignore", "ignore", "pipe"],
+            detached: process.platform !== "win32",
+            stdio: ["ignore", input.captureOutput ? "pipe" : "ignore", "pipe"],
         });
     }
     catch (error) {
@@ -129,6 +123,9 @@ export async function runWorktreeBootstrap(input, dependencies = {}) {
                 clearTimeout(timeoutHandle);
             resolve(observation);
         };
+        child.stdout?.on("data", (chunk) => {
+            stdoutTail?.append(chunk);
+        });
         child.stderr?.on("data", (chunk) => {
             stderrTail.append(chunk);
         });
@@ -139,35 +136,45 @@ export async function runWorktreeBootstrap(input, dependencies = {}) {
         child.on("close", (code, signal) => {
             exited = true;
             const durationMs = Math.max(0, nowMs() - startedAt);
-            const snap = stderrTail.snapshot();
-            const stderr = snap.bytes ? { bytes: snap.bytes, truncated: snap.truncated } : null;
+            const stdoutSnapshot = stdoutTail?.snapshot();
+            const stderrSnapshot = stderrTail.snapshot();
+            const capturedOutput = {
+                stdout: stdoutSnapshot?.bytes ? { bytes: stdoutSnapshot.bytes, truncated: stdoutSnapshot.truncated } : null,
+                stderr: stderrSnapshot.bytes ? { bytes: stderrSnapshot.bytes, truncated: stderrSnapshot.truncated } : null,
+            };
+            const failureOutput = { stdout: capturedOutput.stdout, stderr: capturedOutput.stderr };
             if (timedOut) {
-                finish(observationFrom({ kind: "timeout" }, durationMs, stderr));
+                finish(observationFrom({ kind: "timeout" }, durationMs, failureOutput));
                 return;
             }
             if (signal) {
-                finish(observationFrom({ kind: "signal", signal }, durationMs, stderr));
+                finish(observationFrom({ kind: "signal", signal }, durationMs, failureOutput));
                 return;
             }
             const exitCode = typeof code === "number" ? code : 1;
             const normalized = Math.max(0, Math.min(255, exitCode));
             if (normalized === 0) {
-                // Success discards stderr but still clamps durationMs.
-                finish(observationFrom({ kind: "exit", code: 0 }, durationMs, null));
+                const successOutput = input.captureOutput ? capturedOutput : { stdout: null, stderr: null };
+                finish(observationFrom({ kind: "exit", code: 0 }, durationMs, successOutput));
                 return;
             }
-            finish(observationFrom({ kind: "exit", code: normalized }, durationMs, stderr));
+            finish(observationFrom({ kind: "exit", code: normalized }, durationMs, failureOutput));
         });
         timeoutHandle = setTimeout(() => {
             void (async () => {
                 if (settled || exited)
                     return;
                 timedOut = true;
-                killChild(child, "SIGTERM");
-                await wait(WORKTREE_BOOTSTRAP_KILL_GRACE_MS);
-                // SIGKILL only if the child has not reached a terminal close yet.
-                if (!exited && !settled) {
-                    killChild(child, "SIGKILL");
+                try {
+                    await terminateProcessGroup(child, { graceMs: WORKTREE_BOOTSTRAP_KILL_GRACE_MS, wait });
+                }
+                catch {
+                    const stdoutSnapshot = stdoutTail?.snapshot();
+                    const stderrSnapshot = stderrTail.snapshot();
+                    finish(observationFrom({ kind: "timeout" }, Math.max(0, nowMs() - startedAt), {
+                        stdout: stdoutSnapshot?.bytes ? { bytes: stdoutSnapshot.bytes, truncated: stdoutSnapshot.truncated } : null,
+                        stderr: stderrSnapshot.bytes ? { bytes: stderrSnapshot.bytes, truncated: stderrSnapshot.truncated } : null,
+                    }));
                 }
             })();
         }, input.plan.timeoutMs);
@@ -175,11 +182,12 @@ export async function runWorktreeBootstrap(input, dependencies = {}) {
     });
 }
 export function bootstrapEntryDataFromObservation(observation) {
+    const retainFailureStderr = !isBootstrapSuccess(observation);
     return {
         result: observation.result,
         durationMs: observation.durationMs,
-        ...(observation.stderrTail !== undefined ? { stderrTail: observation.stderrTail } : {}),
-        ...(observation.stderrTruncated ? { stderrTruncated: true } : {}),
+        ...(retainFailureStderr && observation.stderrTail !== undefined ? { stderrTail: observation.stderrTail } : {}),
+        ...(retainFailureStderr && observation.stderrTruncated ? { stderrTruncated: true } : {}),
     };
 }
 export function isBootstrapSuccess(observation) {

package/build/core/worktree-path.js

@@ -1,14 +1,61 @@
 import * as path from "node:path";
 import * as fs from "node:fs/promises";
 import { FlowError } from "../flow-error.js";
-import { createGit, wrapGitError } from "../git/core.js";
-import { readLedger } from "./ledger.js";
-import { readLedgerSnapshot } from "./ledger-batch.js";
-import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
+import { createGit, runGitProcess, wrapGitError } from "../git/core.js";
+import { resolveLocalBranchHead } from "../git/refs.js";
+import { readCurrentContractLifecycle } from "./repository-ledger/read-model.js";
 import { normalizeFilesystemCoordinate } from "../fs/path-coordinate.js";
 import { gitCommonRootPath, resolveGitCommonRoot } from "../git/path-coordinate.js";
-export function findBindEntry(entries) {
-    return entries.find((entry) => entry.kind === "bind");
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Reconstruct the public terminal-cleanup fact from its independent replay receipts. */
+export function terminalCleanupFacts(worktreeValue, deliveryRefValue) {
+    const worktree = record(worktreeValue);
+    const delivery = record(deliveryRefValue);
+    if (!worktree || !Array.isArray(worktree.absent) || !delivery)
+        return undefined;
+    const absent = worktree.absent.filter((item) => item === "worktree");
+    const base = {
+        absent,
+        ...(typeof worktree.removedWorktreePath === "string" ? { removedWorktreePath: worktree.removedWorktreePath } : {}),
+    };
+    const failure = record(worktree.worktreeRemoveFailure);
+    if (failure && typeof failure.path === "string" && typeof failure.reason === "string") {
+        base.worktreeRemoveFailure = { path: failure.path, reason: failure.reason };
+    }
+    if (delivery.status === "aligned"
+        && typeof delivery.ref === "string"
+        && delivery.expected === "absent"
+        && delivery.observed === "absent") {
+        return { ...base, deliveryRef: { status: "aligned", ref: delivery.ref, expected: "absent", observed: "absent" } };
+    }
+    const mismatch = record(delivery.mismatch);
+    const observed = record(mismatch?.observed);
+    if (delivery.status === "mismatch"
+        && mismatch?.kind === "projected-surface-mismatch"
+        && mismatch.surface === "delivery-ref"
+        && typeof mismatch.ref === "string"
+        && mismatch.expected === "absent"
+        && observed?.state === "present"
+        && typeof observed.head === "string") {
+        return {
+            ...base,
+            deliveryRef: {
+                status: "mismatch",
+                mismatch: {
+                    kind: "projected-surface-mismatch",
+                    surface: "delivery-ref",
+                    ref: mismatch.ref,
+                    expected: "absent",
+                    observed: { state: "present", head: observed.head },
+                },
+            },
+        };
+    }
+    return undefined;
 }
 function parseWorktreeListPorcelainZ(output) {
     const listings = [];
@@ -28,7 +75,16 @@ function parseWorktreeListPorcelainZ(output) {
         listings.push(current);
     return listings;
 }
-async function listWorktrees(cwd) {
+async function listWorktrees(cwd, signal) {
+    if (signal) {
+        const result = await runGitProcess(cwd, ["worktree", "list", "--porcelain", "-z"], { signal });
+        if (result.error || result.status !== 0) {
+            if (result.error?.name === "AbortError")
+                throw result.error;
+            throw wrapGitError("worktree list --porcelain -z", result.error ?? new Error(result.stderr || `exit ${String(result.status)}`), cwd);
+        }
+        return parseWorktreeListPorcelainZ(result.stdout);
+    }
     const git = createGit(cwd);
     try {
         return parseWorktreeListPorcelainZ(await git.raw(["worktree", "list", "--porcelain", "-z"]));
@@ -80,16 +136,19 @@ function contractWorktreePathFromStableRoot(stableRoot, contractId, bind) {
     return path.join(stableRoot, ".keiyaku", "wt", bind?.data.place ?? contractId);
 }
 export async function contractWorktreePath(cwd, contractId) {
-    const ledger = await readLedger(cwd, contractId);
-    const bind = ledger ? findBindEntry(ledger.entries) : undefined;
-    return await contractWorktreePathFromBind(cwd, contractId, bind);
+    const stableRoot = await stableRepoRoot(cwd);
+    const outcome = await readCurrentContractLifecycle(stableRoot, contractId);
+    return path.join(stableRoot, ".keiyaku", "wt", outcome.status === "healthy" || outcome.status === "diseased"
+        ? outcome.model.resources.worktree?.place ?? contractId
+        : contractId);
 }
 export async function requireContractWorktreePath(cwd, contractId) {
-    const ledger = await readLedger(cwd, contractId);
-    if (!ledger) {
+    const stableRoot = await stableRepoRoot(cwd);
+    const outcome = await readCurrentContractLifecycle(stableRoot, contractId);
+    if (outcome.status !== "healthy" || !outcome.model.resources.worktree) {
         throw new FlowError("INTERNAL_STATE", `contract ${contractId} not found`);
     }
-    return await contractWorktreePathFromBind(cwd, contractId, findBindEntry(ledger.entries));
+    return path.join(stableRoot, ".keiyaku", "wt", outcome.model.resources.worktree.place);
 }
 async function findContractWorktree(cwd, contractId) {
     const expectedBranch = `refs/heads/keiyaku/${contractId}`;
@@ -108,21 +167,53 @@ export async function findContractWorktreePath(cwd, contractId) {
 }
 export async function findRegisteredContractWorktreePath(cwd, contractId) {
     const stableRoot = await stableRepoRoot(cwd);
-    const ledger = await readLedger(stableRoot, contractId);
-    const bind = ledger ? findBindEntry(ledger.entries) : undefined;
-    if (!bind || bind.data.workspace !== "worktree")
+    const outcome = await readCurrentContractLifecycle(stableRoot, contractId);
+    if (outcome.status !== "healthy" || outcome.model.resources.worktree?.state !== "held")
         return undefined;
-    let expected;
-    try {
-        expected = await fs.realpath(contractWorktreePathFromStableRoot(stableRoot, contractId, bind));
-    }
-    catch {
+    return findRegisteredContractWorktreePathFromModel(stableRoot, outcome.model);
+}
+export async function findRegisteredContractWorktreePathFromModel(stableRoot, model) {
+    const worktree = model.resources.worktree;
+    if (!worktree)
         return undefined;
+    const expected = path.join(stableRoot, ".keiyaku", "wt", worktree.place);
+    for (const registered of await listWorktrees(stableRoot)) {
+        if (registered.branch !== model.resources.deliveryRef)
+            continue;
+        try {
+            if (normalizeFilesystemCoordinate(await fs.realpath(registered.path)) === normalizeFilesystemCoordinate(await fs.realpath(expected))) {
+                return await fs.realpath(registered.path);
+            }
+        }
+        catch { /* stale registration is not lifecycle evidence */ }
     }
+    return undefined;
+}
+async function findRegisteredContractWorktreePathFromBind(stableRoot, contractId, _bind) {
+    const expectedBranch = `refs/heads/keiyaku/${contractId}`;
     for (const worktree of await listWorktrees(stableRoot)) {
+        let ownsBranch = worktree.branch === expectedBranch;
+        if (!ownsBranch && !worktree.branch) {
+            for (const statePath of ["rebase-merge/head-name", "rebase-apply/head-name"]) {
+                try {
+                    const gitPath = (await createGit(worktree.path).raw(["rev-parse", "--git-path", statePath])).trim();
+                    if ((await fs.readFile(gitPath, "utf8")).trim() === expectedBranch) {
+                        ownsBranch = true;
+                        break;
+                    }
+                }
+                catch {
+                    // No owned rebase coordinate at this registered worktree.
+                }
+            }
+        }
+        if (!ownsBranch)
+            continue;
         try {
-            if (await fs.realpath(worktree.path) === expected)
-                return worktree.path;
+            const dotGit = await fs.stat(path.join(worktree.path, ".git"));
+            if (dotGit.isDirectory())
+                continue;
+            return await fs.realpath(worktree.path);
         }
         catch {
             // A stale Git registration is not an engine-owned worktree fact.
@@ -130,12 +221,21 @@ export async function findRegisteredContractWorktreePath(cwd, contractId) {
     }
     return undefined;
 }
-/**
- * Delivery coordinate for dirty admission and KEIYAKU.md render: the linked
- * contract worktree when Git registers one, otherwise cwd (workspace here).
- */
-export async function resolveContractDeliveryCwd(cwd, contractId) {
-    return (await findContractWorktreePath(cwd, contractId)) ?? cwd;
+/** Prove the sole carrier target from stable-root, bind, and Git registration facts. */
+export async function resolveContractCarrierTarget(stableRoot, contractId, bind) {
+    if (bind.data.workspace === "here") {
+        const root = await fs.realpath(stableRoot);
+        return { status: "available", root, path: path.join(root, ".keiyaku", "KEIYAKU.md"), workspace: "here" };
+    }
+    const root = await findRegisteredContractWorktreePathFromBind(stableRoot, contractId, bind);
+    if (!root) {
+        return {
+            status: "unavailable",
+            workspace: "worktree",
+            reason: `contract ${contractId} has no verified registered engine worktree`,
+        };
+    }
+    return { status: "available", root, path: path.join(root, ".keiyaku", "KEIYAKU.md"), workspace: "worktree" };
 }
 /**
  * Resolve the contract id for an engine-owned bound worktree containing cwd.
@@ -144,10 +244,29 @@ export async function resolveContractDeliveryCwd(cwd, contractId) {
  */
 async function contractIdForEngineOwnedWorktree(cwd, options) {
     const stableRoot = options.stableRoot ?? await stableRepoRoot(cwd);
+    const candidate = await contractIdentityFromWorktreeWitness(cwd, stableRoot);
+    if (!candidate)
+        return undefined;
+    const outcome = await readCurrentContractLifecycle(stableRoot, candidate.contractId);
+    if (outcome.status !== "healthy" || !outcome.model.resources.worktree)
+        return undefined;
+    if (options.requireActive && ["claimed", "forfeited"].includes(outcome.model.phase))
+        return undefined;
+    let expectedWorktree;
+    try {
+        expectedWorktree = await fs.realpath(path.join(stableRoot, ".keiyaku", "wt", outcome.model.resources.worktree.place));
+    }
+    catch {
+        return undefined;
+    }
+    return candidate.path === expectedWorktree ? candidate.contractId : undefined;
+}
+/** Resolve only Git's local registered-worktree witness; lifecycle facts must verify it separately. */
+export async function contractIdentityFromWorktreeWitness(cwd, stableRoot, signal) {
     const canonicalCwd = await fs.realpath(cwd);
+    const branchPrefix = "refs/heads/keiyaku/";
     const candidates = [];
-    for (const worktree of await listWorktrees(stableRoot)) {
-        const branchPrefix = "refs/heads/keiyaku/";
+    for (const worktree of await listWorktrees(stableRoot, signal)) {
         if (!worktree.branch?.startsWith(branchPrefix))
             continue;
         let canonicalWorktree;
@@ -162,27 +281,10 @@ async function contractIdForEngineOwnedWorktree(cwd, options) {
         candidates.push({
             contractId: worktree.branch.slice(branchPrefix.length),
             path: canonicalWorktree,
+            branch: worktree.branch,
         });
     }
-    const candidate = candidates.sort((left, right) => right.path.length - left.path.length)[0];
-    if (!candidate)
-        return undefined;
-    const ledger = await readLedgerSnapshot(stableRoot, candidate.contractId);
-    if (!ledger)
-        return undefined;
-    if (options.requireActive && isTerminalState(deriveContractState(ledger.entries)))
-        return undefined;
-    const bind = findBindEntry(ledger.entries);
-    if (!bind || bind.data.workspace !== "worktree")
-        return undefined;
-    let expectedWorktree;
-    try {
-        expectedWorktree = await fs.realpath(contractWorktreePathFromStableRoot(stableRoot, candidate.contractId, bind));
-    }
-    catch {
-        return undefined;
-    }
-    return candidate.path === expectedWorktree ? candidate.contractId : undefined;
+    return candidates.sort((left, right) => right.path.length - left.path.length || left.contractId.localeCompare(right.contractId))[0];
 }
 /**
  * Resolve the contract bound by an engine-owned worktree containing cwd,
@@ -196,12 +298,48 @@ export async function contractBoundByEngineWorktree(cwd, stableRoot) {
 export async function activeContractBoundByEngineWorktree(cwd, stableRoot) {
     return contractIdForEngineOwnedWorktree(cwd, { requireActive: true, stableRoot });
 }
-export async function cleanupContractWorkspace(cwd, contractId) {
+/**
+ * Verify a worktree binding against a folded current-ledger model. Git's
+ * registration is only a physical witness here; it cannot create lifecycle
+ * state or select a contract absent from the supplied read model.
+ */
+export async function currentContractBoundByWorktreeWitness(input) {
+    let canonicalCwd;
+    try {
+        canonicalCwd = await fs.realpath(input.cwd);
+    }
+    catch {
+        return undefined;
+    }
+    const registeredWorktrees = await listWorktrees(input.stableRoot);
+    const candidates = [];
+    for (const model of input.contracts) {
+        const worktree = model.resources.worktree;
+        if (!worktree || worktree.state !== "held")
+            continue;
+        const expectedPath = path.join(input.stableRoot, ".keiyaku", "wt", worktree.place);
+        let canonicalExpectedPath;
+        try {
+            canonicalExpectedPath = await fs.realpath(expectedPath);
+        }
+        catch {
+            continue;
+        }
+        if (!worktreeContainsCoordinate(canonicalExpectedPath, canonicalCwd))
+            continue;
+        const registered = registeredWorktrees.some((candidate) => candidate.branch === model.resources.deliveryRef &&
+            normalizeFilesystemCoordinate(candidate.path) === normalizeFilesystemCoordinate(canonicalExpectedPath));
+        if (registered)
+            candidates.push({ contract: model.contract, path: canonicalExpectedPath });
+    }
+    candidates.sort((left, right) => right.path.length - left.path.length || left.contract.localeCompare(right.contract));
+    return candidates[0]?.contract;
+}
+/** Remove only the derived linked worktree. Authoritative refs are outside this adapter. */
+export async function cleanupContractWorkspace(cwd, lifecycle) {
     const stableRoot = await stableRepoRoot(cwd);
     const git = createGit(stableRoot);
-    const branch = `keiyaku/${contractId}`;
-    const worktree = await findContractWorktree(stableRoot, contractId);
-    const worktreePath = worktree.path;
+    const worktreePath = await findRegisteredContractWorktreePathFromModel(stableRoot, lifecycle);
     const facts = { absent: [] };
     if (worktreePath) {
         try {
@@ -215,28 +353,23 @@ export async function cleanupContractWorkspace(cwd, contractId) {
     else {
         facts.absent.push("worktree");
     }
-    if (worktree.primary) {
-        facts.absent.push("branch");
-        return facts;
-    }
-    let branchRef;
-    try {
-        branchRef = (await git.raw(["for-each-ref", "--format=%(refname)", `refs/heads/${branch}`])).trim();
-    }
-    catch (error) {
-        throw wrapGitError(`for-each-ref refs/heads/${branch}`, error, stableRoot);
-    }
-    if (branchRef !== `refs/heads/${branch}`) {
-        facts.absent.push("branch");
-    }
-    else {
-        try {
-            await git.raw(["branch", "-D", branch]);
-            facts.deletedBranch = branch;
-        }
-        catch (error) {
-            facts.branchDeleteFailure = { name: branch, reason: wrapGitError(`branch -D ${branch}`, error, stableRoot).message };
-        }
-    }
     return facts;
 }
+/** Observe the terminal transaction's expected delivery-ref absence without reconciling it. */
+export async function observeTerminalDeliveryRef(cwd, contractId) {
+    const stableRoot = await stableRepoRoot(cwd);
+    const ref = `refs/heads/keiyaku/${contractId}`;
+    const observed = await resolveLocalBranchHead(stableRoot, ref);
+    if (!observed)
+        return { status: "aligned", ref, expected: "absent", observed: "absent" };
+    return {
+        status: "mismatch",
+        mismatch: {
+            kind: "projected-surface-mismatch",
+            surface: "delivery-ref",
+            ref,
+            expected: "absent",
+            observed: { state: "present", head: observed.head },
+        },
+    };
+}