@astrosheep/keiyaku 2.9.2 → 2.9.4

package/build/core/scope.js

@@ -1,8 +1,3 @@
-import { spawn } from "node:child_process";
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-import { createGit, wrapGitError } from "../git/core.js";
 export class ScopePatternError extends Error {
     code = "INVALID_SCOPE_PATTERN";
     constructor(message) {
@@ -41,9 +36,9 @@ export function isBlankScopePatternLine(line) {
     return canonicalizeScopePatternInput(line).length === 0;
 }
 /**
- * Canonicalize a scope gitignore pattern for exclude matching and persistence.
+ * Canonicalize a scope Gitignore-like pattern for matching and persistence.
  * Strips only a cosmetic leading `./` (including after `!`); preserves meaningful
- * leading `/` anchoring, gitignore backslash escapes, and escaped trailing spaces.
+ * leading `/` anchoring, supported backslash escapes, and escaped trailing spaces.
  */
 export function normalizeScopePattern(pattern) {
     if (pattern.includes("\0") || pattern.includes("\n") || pattern.includes("\r")) {
@@ -78,75 +73,157 @@ export function normalizeScopePath(filePath) {
         throw new ScopePatternError("scope path cannot contain NUL");
     return normalized;
 }
-function runCheckIgnore(gitDir, workTree, cwd, paths) {
-    return new Promise((resolve, reject) => {
-        const child = spawn("git", [
-            `--git-dir=${gitDir}`,
-            `--work-tree=${workTree}`,
-            "check-ignore",
-            "--no-index",
-            "-z",
-            "--stdin",
-        ], {
-            cwd,
-            env: {
-                ...process.env,
-                GIT_TERMINAL_PROMPT: "0",
-                GCM_INTERACTIVE: "Never",
-                GIT_CONFIG_GLOBAL: "/dev/null",
-                GIT_CONFIG_NOSYSTEM: "1",
-                LC_ALL: "C",
-            },
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        const stdout = [];
-        const stderr = [];
-        child.stdout.on("data", (chunk) => stdout.push(chunk));
-        child.stderr.on("data", (chunk) => stderr.push(chunk));
-        child.stdin.on("error", reject);
-        child.on("error", reject);
-        child.on("close", (code) => {
-            if (code !== 0 && code !== 1) {
-                reject(wrapGitError("check-ignore --no-index -z --stdin", {
-                    message: `git check-ignore exited with status ${code ?? "unknown"}`,
-                    stderr: Buffer.concat(stderr).toString("utf8"),
-                    stdout: Buffer.concat(stdout).toString("utf8"),
-                }, cwd));
-                return;
+function splitPatternComponents(pattern) {
+    const components = [];
+    let component = "";
+    let escaped = false;
+    for (const character of pattern) {
+        if (escaped) {
+            component += `\\${character}`;
+            escaped = false;
+        }
+        else if (character === "\\") {
+            escaped = true;
+        }
+        else if (character === "/") {
+            components.push(component);
+            component = "";
+        }
+        else {
+            component += character;
+        }
+    }
+    if (escaped)
+        component += "\\\\";
+    components.push(component);
+    return components;
+}
+function parseScopePattern(pattern) {
+    const normalized = normalizeScopePattern(pattern);
+    const escapedLeading = normalized.startsWith("\\!") || normalized.startsWith("\\#");
+    const negative = normalized.startsWith("!");
+    const body = negative ? normalized.slice(1) : normalized;
+    const comment = !escapedLeading && body.startsWith("#");
+    const anchored = body.startsWith("/");
+    const unanchored = anchored ? body.slice(1) : body;
+    const directory = unanchored.endsWith("/");
+    const source = directory ? unanchored.slice(0, -1) : unanchored;
+    const segments = splitPatternComponents(source);
+    return { negative, comment, directory, segments, componentOnly: !anchored && !source.includes("/") };
+}
+function componentMatches(pattern, value) {
+    let expression = "^";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        if (character === "\\") {
+            index += 1;
+            expression += escapeRegex(pattern[index] ?? "\\");
+        }
+        else if (character === "*") {
+            if (pattern[index + 1] === "*") {
+                expression += ".*";
+                index += 1;
+            }
+            else
+                expression += "[^/]*";
+        }
+        else if (character === "?")
+            expression += "[^/]";
+        else if (character === "[") {
+            const close = pattern.indexOf("]", index + 1);
+            if (close === -1)
+                expression += "\\[";
+            else {
+                const rawClass = pattern.slice(index + 1, close);
+                const classBody = rawClass.startsWith("!") ? `^${rawClass.slice(1)}` : rawClass;
+                expression += `[${classBody.replace(/\\/g, "\\\\")}]`;
+                index = close;
+            }
+        }
+        else
+            expression += escapeRegex(character);
+    }
+    return new RegExp(`${expression}$`).test(value);
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function patternMatchesPath(parsed, filePath) {
+    if (parsed.comment)
+        return false;
+    const pathSegments = filePath.split("/");
+    if (parsed.componentOnly) {
+        const lastMatchIndex = parsed.directory ? pathSegments.length - 1 : pathSegments.length;
+        return pathSegments.slice(0, lastMatchIndex).some((segment) => componentMatches(parsed.segments[0], segment));
+    }
+    const memo = new Map();
+    const matchesFrom = (patternIndex, pathIndex) => {
+        const key = `${patternIndex}:${pathIndex}`;
+        const cached = memo.get(key);
+        if (cached !== undefined)
+            return cached;
+        let matched;
+        if (patternIndex === parsed.segments.length) {
+            matched = parsed.directory ? pathIndex < pathSegments.length : pathIndex === pathSegments.length;
+            memo.set(key, matched);
+            return matched;
+        }
+        const segment = parsed.segments[patternIndex];
+        if (segment === "**") {
+            matched = false;
+            for (let nextPathIndex = pathIndex; nextPathIndex <= pathSegments.length; nextPathIndex += 1) {
+                if (matchesFrom(patternIndex + 1, nextPathIndex)) {
+                    matched = true;
+                    break;
+                }
             }
-            resolve(new Set(Buffer.concat(stdout)
-                .toString("utf8")
-                .split("\0")
-                .filter(Boolean)));
+        }
+        else {
+            matched = pathIndex < pathSegments.length
+                && componentMatches(segment, pathSegments[pathIndex])
+                && matchesFrom(patternIndex + 1, pathIndex + 1);
+        }
+        memo.set(key, matched);
+        return matched;
+    };
+    return matchesFrom(0, 0);
+}
+/**
+ * Evaluate the settled ordered Gitignore-like scope subset without invoking Git.
+ */
+export async function scopePathEvidence(_cwd, patterns, filePaths) {
+    const normalizedPatterns = patterns.map(normalizeScopePattern);
+    const normalizedPaths = filePaths.map(normalizeScopePath);
+    const parsedPatterns = normalizedPatterns.map(parseScopePattern);
+    return normalizedPaths.map((normalizedPath) => {
+        const pathDecisions = parsedPatterns.flatMap((parsed, index) => {
+            if (!patternMatchesPath(parsed, normalizedPath))
+                return [];
+            const effect = parsed.negative ? "exclude" : "include";
+            return [{ index, pattern: normalizedPatterns[index], effect, matchedAfter: effect === "include" }];
         });
-        child.stdin.end(`${paths.join("\0")}\0`);
+        const decisivePattern = pathDecisions.at(-1);
+        const hasPositiveMatch = pathDecisions.some((decision) => decision.effect === "include");
+        const matched = decisivePattern?.matchedAfter ?? false;
+        return {
+            path: normalizedPath,
+            patterns: pathDecisions,
+            matched,
+            outcome: matched ? "matched" : hasPositiveMatch ? "excluded" : "no-positive-match",
+            ...(decisivePattern ? { decisivePattern } : {}),
+        };
     });
 }
 export async function pathsMatchingScope(cwd, patterns, filePaths) {
-    const normalizedPatterns = patterns.map(normalizeScopePattern);
-    const normalizedPaths = filePaths.map(normalizeScopePath);
-    if (normalizedPatterns.length === 0 || normalizedPaths.length === 0)
-        return new Set();
-    const temporaryRoot = await fs.mkdtemp(path.join(os.tmpdir(), "keiyaku-scope-"));
-    const gitDir = path.join(temporaryRoot, "scope.git");
-    const workTree = path.join(temporaryRoot, "worktree");
-    try {
-        await Promise.all([fs.mkdir(gitDir), fs.mkdir(workTree)]);
-        await createGit(gitDir).init(true);
-        await fs.writeFile(path.join(gitDir, "info", "exclude"), `${normalizedPatterns.join("\n")}\n`, "utf8");
-        return await runCheckIgnore(gitDir, workTree, cwd, normalizedPaths);
-    }
-    finally {
-        await fs.rm(temporaryRoot, { recursive: true, force: true });
-    }
+    const evidence = await scopePathEvidence(cwd, patterns, filePaths);
+    return new Set(evidence.filter((item) => item.matched).map((item) => item.path));
 }
 export function isNegativeScopePattern(pattern) {
     return normalizeScopePattern(pattern).startsWith("!");
 }
 /**
- * Parse only the subset whose path language can be proved statically: literal
- * segments, `*` segments, and `**` segments. Anything using richer gitignore
- * syntax is left to Git and produces no advisory warning.
+ * Parse only the positive subset whose path language can be proved statically:
+ * literal segments, `*` segments, and `**` segments.
  */
 function staticScopeSegments(pattern) {
     const positive = normalizeScopePattern(pattern);

package/build/core/seal.js

@@ -1,12 +1,12 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
 import { FlowError } from "../flow-error.js";
-import { createGit, wrapGitError } from "../git/core.js";
+import { createGit, parseRevListOutput, wrapGitError } from "../git/core.js";
 import { KEIYAKU_FILE } from "../keiyaku.js";
+import { formatLedgerEntryCommitMessage } from "./entry.js";
 import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
-import { renderContractView } from "./contract-view.js";
-import { normalizeScopePath, pathsMatchingScope } from "./scope.js";
+import { refreshContractView } from "./contract-view.js";
+import { normalizeScopePath, scopePathEvidence, } from "./scope.js";
 import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
+import { casUpdateRefLog, createRefLogCommit } from "./ref-log.js";
 function findBind(entries) {
     const bind = entries.find((entry) => entry.kind === "bind");
     if (!bind)
@@ -64,10 +64,7 @@ async function resolveCommit(cwd, revision) {
 async function revList(cwd, from, to) {
     const git = createGit(cwd);
     try {
-        return (await git.raw(["rev-list", "--reverse", `${from}..${to}`]))
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .filter(Boolean);
+        return parseRevListOutput(await git.raw(["rev-list", "--reverse", `${from}..${to}`]));
     }
     catch (error) {
         throw wrapGitError(`rev-list ${from}..${to}`, error, cwd);
@@ -104,8 +101,37 @@ async function diffstat(cwd, from, to) {
 }
 async function scopeViolations(cwd, paths, scope) {
     const auditedPaths = paths.filter((changedPath) => changedPath !== KEIYAKU_FILE);
-    const matched = await pathsMatchingScope(cwd, scope, auditedPaths);
-    return auditedPaths.filter((changedPath) => !matched.has(changedPath));
+    return (await scopePathEvidence(cwd, scope, auditedPaths)).filter((evidence) => !evidence.matched);
+}
+async function auditScope(cwd, entries, paths, waivePaths) {
+    const scope = effectiveScope(entries);
+    const scopeViolationEvidence = await scopeViolations(cwd, paths, scope);
+    const waivedPaths = new Set(waivePaths.map(normalizeScopePath));
+    const unwaived = scopeViolationEvidence.filter((violation) => !waivedPaths.has(violation.path));
+    if (unwaived.length > 0) {
+        throw new ScopeAuditError(findBind(entries).contract, scope, unwaived);
+    }
+    const violations = scopeViolationEvidence.map((violation) => violation.path);
+    return {
+        scopeAudit: { violations, waived: violations.length > 0 },
+        scopeViolationEvidence,
+    };
+}
+export class ScopeAuditError extends FlowError {
+    scopeViolationEvidence;
+    constructor(_contractId, scope, evidence) {
+        const count = evidence.length;
+        const fileLabel = count === 1 ? "file" : "files";
+        super("SCOPE_VIOLATION", `scope violation — ${count} ${fileLabel} outside declared scope`, {
+            facts: {
+                kind: "scope_violation",
+                scope: [...scope],
+                violations: evidence,
+            },
+        });
+        this.name = "ScopeAuditError";
+        this.scopeViolationEvidence = evidence;
+    }
 }
 function assertOperable(contractId, entries) {
     const state = deriveContractState(entries);
@@ -127,11 +153,10 @@ export function currentSealArc(entries) {
 }
 /** Stable read-only coordinate naming the receipt source a petition would seal. */
 export function petitionSealSource(entries) {
-    const arc = currentSealArc(entries);
-    const fence = getFence(entries);
-    return arc === null
-        ? `no open arc · fence ${fence}`
-        : `a${arc} · fence ${fence}▸HEAD`;
+    return {
+        arc: currentSealArc(entries),
+        fence: getFence(entries),
+    };
 }
 /** Shared read-only owner for the seal capture and its compact changed-path evidence. */
 export async function previewSeal(cwd, entries, head = "HEAD", waivePaths = []) {
@@ -145,13 +170,7 @@ export async function previewSeal(cwd, entries, head = "HEAD", waivePaths = [])
         changedPaths(cwd, oldFence, newFence),
         diffstat(cwd, oldFence, newFence),
     ]);
-    const scope = effectiveScope(entries);
-    const violations = await scopeViolations(cwd, paths, scope);
-    const waivedPaths = new Set(waivePaths.map(normalizeScopePath));
-    const unwaived = violations.filter((violation) => !waivedPaths.has(violation));
-    if (unwaived.length > 0) {
-        throw new FlowError("INTERNAL_STATE", `scope audit failed for contract ${findBind(entries).contract}: paths ${unwaived.join(", ")} outside ${scope.join(", ")}`);
-    }
+    const scopeAudit = await auditScope(cwd, entries, paths, waivePaths);
     return {
         capture: {
             arc,
@@ -159,7 +178,7 @@ export async function previewSeal(cwd, entries, head = "HEAD", waivePaths = [])
             newFence,
             receipts,
             diffstat: stat,
-            scopeAudit: { violations, waived: violations.length > 0 },
+            ...scopeAudit,
         },
         paths,
     };
@@ -167,12 +186,30 @@ export async function previewSeal(cwd, entries, head = "HEAD", waivePaths = [])
 export async function captureSeal(cwd, entries, head = "HEAD", waivePaths = []) {
     return (await previewSeal(cwd, entries, head, waivePaths)).capture;
 }
-async function renderUpdatedContract(ledgerCwd, renderCwd, contractId) {
-    const ledger = await readLedger(ledgerCwd, contractId);
-    if (!ledger) {
-        throw new FlowError("INTERNAL_STATE", `contract ${contractId} active ledger disappeared before render`);
-    }
-    await fs.writeFile(path.join(renderCwd, KEIYAKU_FILE), renderContractView({ id: contractId, entries: ledger.entries }), "utf8");
+/** Preserve original receipt hashes while auditing the rebased delivery content. */
+export async function captureRenewSeal(input) {
+    const arc = currentSealArc(input.entries);
+    if (arc === null)
+        return null;
+    const oldFence = getFence(input.entries);
+    const [receiptHead, contentBase, contentHead] = await Promise.all([
+        resolveCommit(input.cwd, input.receiptHead),
+        resolveCommit(input.cwd, input.contentBase),
+        resolveCommit(input.cwd, input.contentHead),
+    ]);
+    const [receipts, paths, stat] = await Promise.all([
+        revList(input.cwd, oldFence, receiptHead),
+        changedPaths(input.cwd, contentBase, contentHead),
+        diffstat(input.cwd, contentBase, contentHead),
+    ]);
+    return {
+        arc,
+        oldFence,
+        newFence: receiptHead,
+        receipts,
+        diffstat: stat,
+        ...await auditScope(input.cwd, input.entries, paths, input.waivePaths ?? []),
+    };
 }
 export async function sealCurrentArc(input) {
     const ledger = await readLedger(input.cwd, input.contractId);
@@ -196,25 +233,92 @@ export async function sealCurrentArc(input) {
         if (currentArc !== capture.arc || getFence(entries) !== capture.oldFence) {
             throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} changed while sealing arc a${capture.arc}`);
         }
+        const { scopeViolationEvidence: _scopeViolationEvidence, ...durableCapture } = capture;
         return {
             v: 1,
             kind: "seal",
             contract: input.contractId,
             at,
             actor: "engine",
-            data: { ...capture, sealedBy: input.sealedBy },
+            data: { ...durableCapture, sealedBy: input.sealedBy },
         };
     });
     if (!result.ok) {
         throw new FlowError("INTERNAL_STATE", `failed to seal arc for ${input.contractId}: ${result.reason}`);
     }
-    await renderUpdatedContract(input.cwd, input.renderCwd, input.contractId);
+    await refreshContractView({
+        ledgerCwd: input.cwd,
+        renderCwd: input.renderCwd,
+        contractId: input.contractId,
+    });
     return {
         ...capture,
         sealedBy: input.sealedBy,
         ledgerHead: result.head,
-        incrementalDiff: capture.receipts.length === 0
-            ? "nothing sealed"
-            : `${capture.receipts.length} receipt${capture.receipts.length === 1 ? "" : "s"} · +${capture.diffstat.insertions} −${capture.diffstat.deletions}`,
     };
 }
+function splitLedgerMessage(entry) {
+    const message = formatLedgerEntryCommitMessage(entry);
+    const separator = message.indexOf("\n\n");
+    return { subject: message.slice(0, separator), body: message.slice(separator + 2).trimEnd() };
+}
+export async function appendRenewSettlement(input) {
+    const ledger = await readLedger(input.cwd, input.contractId);
+    if (!ledger || ledger.head !== input.expectedLedgerHead) {
+        throw new FlowError("CONCURRENT_MODIFICATION", `contract ${input.contractId} changed while renewing`);
+    }
+    assertOperable(input.contractId, ledger.entries);
+    if (input.capture && (currentSealArc(ledger.entries) !== input.capture.arc || getFence(ledger.entries) !== input.capture.oldFence)) {
+        throw new FlowError("CONCURRENT_MODIFICATION", `contract ${input.contractId} changed while renewing`);
+    }
+    const at = new Date(input.nowMs).toISOString();
+    let parentHead = ledger.head;
+    let sealHead;
+    if (input.capture) {
+        const { scopeViolationEvidence: _evidence, ...durableCapture } = input.capture;
+        const sealEntry = {
+            v: 1,
+            kind: "seal",
+            contract: input.contractId,
+            at,
+            actor: "engine",
+            data: { ...durableCapture, newFence: input.newHead, sealedBy: "renew" },
+        };
+        const message = splitLedgerMessage(sealEntry);
+        sealHead = await createRefLogCommit(input.cwd, {
+            ...message,
+            parentHead,
+            errorLabel: `ledger seal ${input.contractId}`,
+        });
+        parentHead = sealHead;
+    }
+    const renewEntry = {
+        v: 1,
+        kind: "renew",
+        contract: input.contractId,
+        at,
+        actor: input.actor,
+        data: {
+            oldBase: input.oldBase,
+            newBase: input.newBase,
+            oldHead: input.oldHead,
+            newHead: input.newHead,
+        },
+    };
+    const message = splitLedgerMessage(renewEntry);
+    const renewHead = await createRefLogCommit(input.cwd, {
+        ...message,
+        parentHead,
+        errorLabel: `ledger renew ${input.contractId}`,
+    });
+    if (!await casUpdateRefLog(input.cwd, activeLedgerRef(input.contractId), renewHead, ledger.head)) {
+        throw new FlowError("CONCURRENT_MODIFICATION", `contract ${input.contractId} changed while renewing`);
+    }
+    const sealed = input.capture ? {
+        ...input.capture,
+        newFence: input.newHead,
+        sealedBy: "renew",
+        ledgerHead: sealHead,
+    } : null;
+    return { ledgerHead: renewHead, sealed };
+}

package/build/core/{claim-delivery.js → settlement/claim-delivery.js}

@@ -1,12 +1,13 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { FlowError } from "../flow-error.js";
-import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "../git/core.js";
-import { readLedger } from "./ledger.js";
-import { shortCommitHash } from "../git/commits.js";
-import { commissionTarget, latestBase } from "./status/drift.js";
-import { settleTaskBoardForLanding } from "./task-contract.js";
-import { stableRepoRoot } from "./worktree-path.js";
+import { FlowError } from "../../flow-error.js";
+import { syncDirectory } from "../../fs/durability.js";
+import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "../../git/core.js";
+import { readLedger } from "../ledger.js";
+import { shortCommitHash } from "../../git/commits.js";
+import { commissionTarget, latestBase } from "../status/drift.js";
+import { settleTaskBoardForLanding } from "../task/index.js";
+import { stableRepoRoot } from "../worktree-path.js";
 const CLAIM_RECEIPTS_FILE = "claim-receipts.jsonl";
 async function appendClaimReceipt(cwd, receipt, restoreIfMissing = "") {
     const receiptPath = path.join(await stableRepoRoot(cwd), ".keiyaku", CLAIM_RECEIPTS_FILE);
@@ -28,13 +29,7 @@ async function appendClaimReceipt(cwd, receipt, restoreIfMissing = "") {
     finally {
         await handle.close();
     }
-    const directory = await fs.open(path.dirname(receiptPath), "r");
-    try {
-        await directory.sync();
-    }
-    finally {
-        await directory.close();
-    }
+    await syncDirectory(path.dirname(receiptPath));
 }
 export async function resolveCommit(cwd, rev) {
     const git = createGit(cwd);

package/build/core/{claim.js → settlement/claim.js}

@@ -1,10 +1,11 @@
-import { FlowError } from "../flow-error.js";
-import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
+import { FlowError } from "../../flow-error.js";
+import { assertCleanTrackedWorkingTree } from "../../git/worktree.js";
+import { activeLedgerRef, appendWithRetry, readLedger } from "../ledger.js";
 import { assertClaimQueueHead, readQueueReadModel } from "./queue.js";
-import { releaseScope } from "./registry.js";
-import { deriveContractState } from "./status/lifecycle.js";
-import { commissionTarget, latestBase } from "./status/drift.js";
-import { cleanupContractWorkspace, findContractWorktreePath, stableRepoRoot } from "./worktree-path.js";
+import { releaseScope } from "../registry.js";
+import { deriveContractState } from "../status/lifecycle.js";
+import { commissionTarget, latestBase } from "../status/drift.js";
+import { cleanupContractWorkspace, findContractWorktreePath, stableRepoRoot } from "../worktree-path.js";
 import { defaultMergeDelivery, relativeDisplayPath, resolveCommit, resolveCommitOrNull, } from "./claim-delivery.js";
 async function cleanupClaim(cwd, contractId, actor, at) {
     const stableRoot = await stableRepoRoot(cwd);
@@ -14,16 +15,37 @@ async function cleanupClaim(cwd, contractId, actor, at) {
 function findClaim(entries) {
     return entries.find((entry) => entry.kind === "claim");
 }
+/** Verdict belonging to the open petition window (after last petition, before claim). */
+function latestCurrentPetitionVerdict(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry.kind === "verdict")
+            return entry;
+        if (entry.kind === "petition")
+            return undefined;
+    }
+    return undefined;
+}
+/**
+ * Delivery requires an approved verdict for the current petition.
+ * Already-claimed cleanup retry remains legal without re-proving judgment.
+ */
 function assertClaimableFromLedger(contractId, ledger) {
     if (!ledger) {
         throw new FlowError("INTERNAL_STATE", `contract ${contractId} not found`);
     }
     const state = deriveContractState(ledger.entries);
     const claim = findClaim(ledger.entries);
-    if (state.state === "petitioned")
-        return claim;
+    // Already-claimed cleanup retry: legal head even if a prior crash left debris.
     if (claim && state.state === "claimed")
         return claim;
+    if (state.state === "petitioned") {
+        const verdict = latestCurrentPetitionVerdict(ledger.entries);
+        if (verdict?.data.result !== "approved") {
+            throw new FlowError("INTERNAL_STATE", `contract ${contractId} cannot claim without approved verdict for current petition`);
+        }
+        return claim;
+    }
     if (state.state === "forfeited") {
         throw new FlowError("INTERNAL_STATE", `contract ${contractId} forfeited`);
     }
@@ -95,6 +117,8 @@ export async function previewClaimContract(input) {
 }
 export async function claimContract(input) {
     const at = new Date(input.nowMs).toISOString();
+    const deliveryWorktree = await findContractWorktreePath(input.cwd, input.contractId);
+    await assertCleanTrackedWorkingTree(deliveryWorktree ?? input.cwd);
     const existing = await readLedger(input.cwd, input.contractId);
     const existingClaim = assertClaimableFromLedger(input.contractId, existing);
     const existingState = existing ? deriveContractState(existing.entries) : undefined;

package/build/core/settlement/index.js

@@ -0,0 +1,19 @@
+/**
+ * Public surface for the settlement package.
+ * Only symbols required by current external consumers are re-exported.
+ * Package-internal modules must import each other directly, not through this file.
+ *
+ * Orchestrator owns: gates → petition → pure verdict → claim delivery / reject publish.
+ * Foundations (queue, claim-delivery) may be depended on downward by stage modules.
+ * Stage modules (petition, verdict, claim) do not import one another.
+ */
+export { claimKeiyaku, petitionKeiyaku, } from "./settlement.js";
+export { buildPetitionClaimInput, petitionContract, loadPetitionPreflightContext, assertPetitionFresh, assertPetitionArcReady, assertPetitionable, } from "./petition.js";
+export { previewPetition, PETITION_PREVIEW_GATE_NAMES, } from "./petition-preview.js";
+export { verdictContract, } from "./verdict.js";
+export { claimContract, previewClaimContract, } from "./claim.js";
+export { defaultMergeDelivery, relativeDisplayPath, resolveCommit, resolveCommitOrNull, } from "./claim-delivery.js";
+export { allocateSettlementSeat, assertClaimQueueHead, deriveQueueReadModel, queueMembership, readQueueReadModel, seatAllocatorRef, } from "./queue.js";
+export { buildClaimGatePipeline, createAgentReviewGate, createOathGate, } from "./petition-claim-gates.js";
+export { assertHeadUnchanged } from "./petition-head-guard.js";
+export { forfeitKeiyaku } from "./petition-forfeit.js";

package/build/core/{petition-claim-gates.js → settlement/petition-claim-gates.js}

@@ -1,21 +1,20 @@
 import { spawn } from "node:child_process";
-import { getConfig } from "../config/env.js";
-import { assertSettingsKnobUsable } from "../config/settings/disease.js";
-import { resolveReviewerAgentName } from "../config/settings/knobs.js";
-import { loadKeiyakuSettings } from "../config/settings/loader.js";
-import { loadAkumaCatalog } from "../config/akuma-loader.js";
-import { formatAvailableAgentNames } from "../agents/selector.js";
-import { getDiffStats } from "../git/diff/preview.js";
-import { readDiff } from "../git/diff/read.js";
-import { getCurrentBranch } from "../git/branches.js";
-import { getLatestCommitHash } from "../git/staging.js";
-import { DIFF_PREVIEW_TEXT_MAX_CHARS } from "../keiyaku.js";
-import { FlowError } from "../flow-error.js";
-import { persistResponseHistory } from "./transcripts.js";
-import { logInfo } from "../telemetry/logger.js";
-import { execSubagent } from "./call/call.js";
-import { readContractLog } from "./log.js";
-import { buildVerificationFailureHints } from "./hints.js";
+import { getConfig } from "../../config/env.js";
+import { assertSettingsKnobUsable } from "../../config/settings/disease.js";
+import { resolveReviewerAgentName } from "../../config/settings/knobs.js";
+import { loadKeiyakuSettings } from "../../config/settings/loader.js";
+import { loadAkumaCatalog } from "../../config/akuma-loader.js";
+import { formatAvailableAgentNames } from "../../agents/selector.js";
+import { getDiffStats } from "../../git/diff/preview.js";
+import { readDiff } from "../../git/diff/read.js";
+import { getCurrentBranch } from "../../git/branches.js";
+import { getLatestCommitHash } from "../../git/staging.js";
+import { DIFF_PREVIEW_TEXT_MAX_CHARS } from "../../keiyaku.js";
+import { FlowError } from "../../flow-error.js";
+import { persistResponseHistory } from "../transcripts.js";
+import { logInfo } from "../../telemetry/logger.js";
+import { execSubagent } from "../call/call.js";
+import { readContractLog } from "../log.js";
 const CLAIM_VERIFICATION_OUTPUT_MAX_CHARS = 1200;
 const REVIEW_PASS_TOKEN = "PASS";
 const REVIEW_REJECTION_MESSAGE = "CLAIM rejected by independent reviewer.";
@@ -139,7 +138,12 @@ export function createCommandVerificationGate() {
                         pass: false,
                         code: "CLOSE_QUALITY_GATE_FAILED",
                         message: `CLAIM blocked: verification failed at '${verification.label}' (exit ${result.code}).`,
-                        hints: buildVerificationFailureHints(verification.label, clipCommandOutput(result.stdout), clipCommandOutput(result.stderr)),
+                        facts: {
+                            kind: "verification_failure",
+                            label: verification.label,
+                            stdout: clipCommandOutput(result.stdout),
+                            stderr: clipCommandOutput(result.stderr),
+                        },
                     };
                 }
             }