@astrosheep/keiyaku 2.9.5 → 2.9.6

package/build/agents/harness/outcome.js

@@ -3,13 +3,17 @@ import { SUBAGENT_SESSION_VERSION, } from "../session.js";
 import { OUTCOME_ERROR_VERSION, SubagentFailure, } from "../types.js";
 import { isProviderTerminalError, } from "./provider-adapter.js";
 import { renderCapturedText } from "./runtime.js";
-export function createOutcomeState(maxCaptureChars) {
+export function createOutcomeState(maxCaptureChars, admittedSession) {
     return {
         outputBuffer: new StringTailBuffer(maxCaptureChars),
         diagnosticsBuffer: new StringTailBuffer(maxCaptureChars),
         warnings: [],
+        ...(admittedSession ? { session: admittedSession } : {}),
     };
 }
+export function recordSessionAdmission(state, session) {
+    state.session = session;
+}
 function mintOutcome(draft) {
     return draft;
 }
@@ -29,7 +33,6 @@ export function processEvent(state, event) {
             return;
         case "done":
             state.doneEvent = event;
-            state.session = event.session;
             if (event.finalMessage !== undefined) {
                 state.finalMessageCandidate = event.finalMessage;
             }
@@ -173,13 +176,16 @@ export function failWithError(shared, state, error, finalMessage, diagnostics =
         warnings: [...state.warnings],
     });
 }
-export function completeOutcome(shared, state, finalMessage, session) {
+export function completeOutcome(state, finalMessage) {
+    if (!state.session) {
+        throw new Error("Cannot complete an outcome before session admission");
+    }
     return mintOutcome({
         status: "completed",
         finalMessage,
         output: renderCapturedText(state.outputBuffer),
         diagnostics: renderCapturedText(state.diagnosticsBuffer),
-        session,
+        session: state.session,
         warnings: [...state.warnings],
     });
 }

package/build/agents/harness/projection.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { FlowError } from "../../flow-error.js";
 import { createEventChannel } from "./event-channel.js";
 import { overflowMarkerFromDropped, prepareAgentEventForPersistence, } from "./execution-handle.js";
-import { classifyFailure, classifySettlementFailure, completeOutcome, createOutcomeState, failFromFailEvent, failWithError, processEvent, renderOutcomeCapturedText, } from "./outcome.js";
+import { classifyFailure, classifySettlementFailure, completeOutcome, createOutcomeState, failFromFailEvent, failWithError, processEvent, recordSessionAdmission, renderOutcomeCapturedText, } from "./outcome.js";
 import { startLiveProjection } from "./router.js";
 import { createAbortError } from "./runtime.js";
 const POLICY_BUDGET_CLEANUP_GRACE_MS = 5_000;
@@ -198,7 +198,7 @@ function deliverDriverEvent(shared, state, live, event, refreshIdleTimeout, know
     processEvent(state, event);
 }
 async function settleProjection(shared) {
-    const state = createOutcomeState(shared.terms.maxCaptureChars);
+    const state = createOutcomeState(shared.terms.maxCaptureChars, shared.reviveTerms?.session);
     let idleTimedOut = false;
     let transportFailure;
     let policyBudgetExceeded = false;
@@ -245,7 +245,6 @@ async function settleProjection(shared) {
         resolvePolicyBudget();
     }, shared.terms.executionTimeoutMs);
     executionTimeout.unref?.();
-    refreshIdleTimeout();
     const requestLiveAbort = () => {
         if (shared.explicitlyAborted)
             return;
@@ -257,7 +256,10 @@ async function settleProjection(shared) {
     shared.lifecycleAbort.signal.addEventListener("abort", requestLiveAbort, { once: true });
     const providerSettlement = (async () => {
         try {
-            const live = await startLiveProjection(shared.terms, shared.lifecycleAbort.signal, shared.reviveTerms, refreshIdleTimeout, shared.observer);
+            const live = await startLiveProjection(shared.terms, shared.lifecycleAbort.signal, shared.reviveTerms, refreshIdleTimeout, shared.observer, (admission) => {
+                recordSessionAdmission(state, admission.session);
+                refreshIdleTimeout();
+            });
             liveDriver = live;
             shared.onLive(live);
             resolveForceWaiters(shared, live);
@@ -324,8 +326,7 @@ async function settleProjection(shared) {
                 completionOutcome?.finalMessage ??
                 state.finalMessageCandidate ??
                 renderOutcomeCapturedText(state.outputBuffer).trim();
-            const session = state.doneEvent?.session ?? completionOutcome?.session;
-            if (!session) {
+            if (!state.session) {
                 return failWithError(shared, state, {
                     code: "SUBAGENT_EXEC_ERROR",
                     message: `${shared.terms.provider} exec ended without a session handle`,
@@ -333,7 +334,7 @@ async function settleProjection(shared) {
                     exitCode: null,
                 }, finalMessage);
             }
-            return completeOutcome(shared, state, finalMessage, session);
+            return completeOutcome(state, finalMessage);
         }
         catch (error) {
             if (error instanceof FlowError) {

package/build/agents/harness/router.js

@@ -1,5 +1,5 @@
 import { getProviderRegistration } from "../providers/registry.js";
-export async function startLiveProjection(terms, signal, reviveTerms, onIngress, observer) {
+export async function startLiveProjection(terms, signal, reviveTerms, onIngress, observer, onSessionAdmission) {
     const onSyncCheckpoint = observer
         ? (control, checkpoint) => {
             observer.onCheckpoint(control, checkpoint);
@@ -19,6 +19,7 @@ export async function startLiveProjection(terms, signal, reviveTerms, onIngress,
         reviveTerms,
         onSyncCheckpoint,
         onDeliveryOpportunity,
+        onSessionAdmission,
         onIngress,
         observer,
     });

package/build/agents/providers/claude-agent-sdk/adapter.js

@@ -198,6 +198,7 @@ export async function startClaudeAgentSdk(prompt, cwd, options) {
                 queryActive = true;
                 notifyActive();
                 let resumedSessionId = sessionId;
+                let admittedSessionId;
                 let finalMessage;
                 let latestAssistantMessageModel;
                 // Provider acceptance / pre-terminal retry evidence for no-turn classification.
@@ -207,7 +208,18 @@ export async function startClaudeAgentSdk(prompt, cwd, options) {
                 const seenToolUses = new Map();
                 for await (const event of query) {
                     builder.ingress(CLAUDE_AGENT_SDK_PROVIDER, event.type, event, claudeIngressDisposition(event.type), () => {
-                        resumedSessionId = extractResumeToken(event) ?? resumedSessionId;
+                        const providerSessionId = extractResumeToken(event);
+                        resumedSessionId = providerSessionId ?? resumedSessionId;
+                        if (providerSessionId && providerSessionId !== admittedSessionId) {
+                            admittedSessionId = providerSessionId;
+                            options.onSessionAdmission?.({
+                                session: {
+                                    provider: CLAUDE_AGENT_SDK_PROVIDER,
+                                    version: SUBAGENT_SESSION_VERSION,
+                                    handle: { sessionId: providerSessionId },
+                                },
+                            });
+                        }
                         if (isClaudeApiRetryEvent(event)) {
                             lastPreTerminalEvidenceWasRetry = true;
                             builder.emit({ type: "warning", warning: mapClaudeApiRetryWarning(event) });

package/build/agents/providers/claude-agent-sdk/registration.js

@@ -179,7 +179,7 @@ export const claudeAgentSdkRegistration = {
         return loader ? { ...terms, loader } : terms;
     },
     nativePolicyOwnership: () => null,
-    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onIngress }) => {
+    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onSessionAdmission, onIngress }) => {
         if (terms.provider !== CLAUDE_AGENT_SDK_PROVIDER) {
             throw new Error(`startLive expected ${CLAUDE_AGENT_SDK_PROVIDER}`);
         }
@@ -197,6 +197,7 @@ export const claudeAgentSdkRegistration = {
             systemPrompt: claudeTerms.systemPrompt,
             onSyncCheckpoint,
             onEvidence: claudeTerms.onEvidence,
+            onSessionAdmission,
             onIngress,
             initialTurn: claudeTerms.initialTurn,
             loader: claudeTerms.loader,

package/build/agents/providers/codex-app-server/adapter.js

@@ -304,6 +304,15 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
                     builder.emit({ type: "fail", message });
                     throw createProviderFailure(message);
                 }
+                const admittedSession = {
+                    provider: "codex-app-server",
+                    version: SUBAGENT_SESSION_VERSION,
+                    handle: {
+                        threadId: activeThreadId,
+                        ...(serverCodexHome ? { codexHome: serverCodexHome } : {}),
+                    },
+                };
+                options.onSessionAdmission?.({ session: admittedSession });
                 if (options.onEvidence)
                     emitProviderEvidence(options.onEvidence, { type: "session", provider: CODEX_APP_SERVER_PROVIDER, threadId: activeThreadId }, builderDiagnostic);
                 // Policy A defaults, but omit when config.* already owns that surface (thread/start config wins).
@@ -351,17 +360,9 @@ export async function startCodexAppServer(prompt, cwd, options = {}) {
                     throw createProviderFailure(message);
                 }
                 // Successful turn/completed is consumption evidence; interrupt ack alone is not terminal proof.
-                const session = {
-                    provider: "codex-app-server",
-                    version: SUBAGENT_SESSION_VERSION,
-                    handle: {
-                        threadId: activeThreadId,
-                        ...(serverCodexHome ? { codexHome: serverCodexHome } : {}),
-                    },
-                };
                 const finalMessage = turnState.lastAgentMessage;
-                builder.emit({ type: "done", finalMessage, session });
-                return { finalMessage, session };
+                builder.emit({ type: "done", finalMessage, session: admittedSession });
+                return { finalMessage, session: admittedSession };
             }
             finally {
                 activeTurnCompletion = undefined;

package/build/agents/providers/codex-app-server/registration.js

@@ -212,7 +212,7 @@ export const codexAppServerRegistration = {
             webSearch: Object.freeze(webSearch),
         });
     },
-    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onDeliveryOpportunity, onIngress, }) => {
+    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onDeliveryOpportunity, onSessionAdmission, onIngress, }) => {
         if (terms.provider !== CODEX_APP_SERVER_PROVIDER) {
             throw new Error(`startLive expected ${CODEX_APP_SERVER_PROVIDER}`);
         }
@@ -231,6 +231,7 @@ export const codexAppServerRegistration = {
             onSyncCheckpoint,
             onDeliveryOpportunity,
             onEvidence: codexTerms.onEvidence,
+            onSessionAdmission,
             onIngress,
             initialTurn: codexTerms.initialTurn,
         };

package/build/agents/providers/opencode-sdk/adapter.js

@@ -264,6 +264,13 @@ export async function startOpencode(prompt, cwd, options = {}) {
                     builder.emit({ type: "fail", message });
                     throw createProviderFailure(message);
                 }
+                options.onSessionAdmission?.({
+                    session: {
+                        provider: OPENCODE_SDK_PROVIDER,
+                        version: SUBAGENT_SESSION_VERSION,
+                        handle: { sessionId: activeSessionId },
+                    },
+                });
                 idleMonitor = new OpencodeIdleMonitor(sdk.client.v2.session, activeSessionId, combined.signal);
                 eventController = createOpencodeEventController({
                     builder,

package/build/agents/providers/opencode-sdk/registration.js

@@ -104,7 +104,7 @@ export const opencodeSdkRegistration = {
         return loader ? { ...terms, loader } : terms;
     },
     nativePolicyOwnership: () => null,
-    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onDeliveryOpportunity, onIngress, }) => {
+    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onDeliveryOpportunity, onSessionAdmission, onIngress, }) => {
         if (terms.provider !== OPENCODE_SDK_PROVIDER) {
             throw new Error(`startLive expected ${OPENCODE_SDK_PROVIDER}`);
         }
@@ -118,6 +118,7 @@ export const opencodeSdkRegistration = {
             onSyncCheckpoint,
             onDeliveryOpportunity,
             onEvidence: opencodeTerms.onEvidence,
+            onSessionAdmission,
             onIngress,
             initialTurn: opencodeTerms.initialTurn,
             loader: opencodeTerms.loader,

package/build/agents/providers/pi/adapter.js

@@ -1,5 +1,6 @@
 import { FlowError } from "../../../flow-error.js";
 import { appendDebugLog } from "../../../telemetry/debug-log.js";
+import { SUBAGENT_SESSION_VERSION, } from "../../session.js";
 import { createProjectionDriver } from "../../harness/execution-handle.js";
 import { createProviderFailure, toProviderTerminalError, } from "../../harness/provider-adapter.js";
 import { createAbortError, emitProviderEvidence, sha256Utf8 } from "../../harness/runtime.js";
@@ -103,6 +104,15 @@ async function openPiProjectionDriver(prompt, cwd, options) {
         ...(resourceLoader ? { resourceLoader } : {}),
     });
     const session = created.session;
+    if (session.sessionFile) {
+        options.onSessionAdmission?.({
+            session: {
+                provider: PI_PROVIDER,
+                version: SUBAGENT_SESSION_VERSION,
+                handle: { sessionId: session.sessionId, sessionFile: session.sessionFile },
+            },
+        });
+    }
     if (options.onEvidence)
         emitProviderEvidence(options.onEvidence, { type: "session", provider: PI_PROVIDER, sessionId: session.sessionId, ...(session.sessionFile ? { sessionFile: session.sessionFile } : {}) }, reportEvidenceDiagnostic);
     session.setSteeringMode("one-at-a-time");

package/build/agents/providers/pi/registration.js

@@ -109,7 +109,7 @@ export const piRegistration = {
         return loader ? { ...terms, loader } : terms;
     },
     nativePolicyOwnership: () => null,
-    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onIngress }) => {
+    startLive: async ({ terms, signal, reviveTerms, onSyncCheckpoint, onSessionAdmission, onIngress }) => {
         if (terms.provider !== PI_PROVIDER) {
             throw new Error(`startLive expected ${PI_PROVIDER}`);
         }
@@ -125,6 +125,7 @@ export const piRegistration = {
                 appendSystemPromptOverride: piTerms.appendSystemPromptOverride,
                 onSyncCheckpoint,
                 onEvidence: piTerms.onEvidence,
+                onSessionAdmission,
                 onIngress,
                 initialTurn: piTerms.initialTurn,
                 loader: piTerms.loader,
@@ -137,6 +138,7 @@ export const piRegistration = {
             appendSystemPromptOverride: piTerms.appendSystemPromptOverride,
             onSyncCheckpoint,
             onEvidence: piTerms.onEvidence,
+            onSessionAdmission,
             onIngress,
             initialTurn: piTerms.initialTurn,
             loader: piTerms.loader,

package/build/cli/completion.js

@@ -2,6 +2,7 @@ import { assertSettingsKnobUsable } from "../config/settings/disease.js";
 import { loadKeiyakuSettings } from "../config/settings/loader.js";
 import { loadAkumaCatalog } from "../config/akuma-loader.js";
 import { listContractIds } from "../core/ledger.js";
+import { TASK_FILTER_COMPLETION } from "../core/task/query.js";
 import { allCommandMetadata, getCommandMetadata } from "./commands/metadata.js";
 function topLevelCommands() {
     return allCommandMetadata()
@@ -46,6 +47,9 @@ export async function renderCompletionCandidates(input) {
     if (input.previous === "task") {
         return filterPrefix(subcommandsFor("task"), word).join("\n");
     }
+    if (input.previous === "--filter") {
+        return filterPrefix([TASK_FILTER_COMPLETION], word).join("\n");
+    }
     return filterPrefix(topLevelCommands(), word).join("\n");
 }
 export function renderCompletionScript(shell = "bash") {
@@ -54,7 +58,7 @@ export function renderCompletionScript(shell = "bash") {
             "#compdef keiyaku",
             "_keiyaku() {",
             "  local -a candidates",
-            "  candidates=(${(f)\"$(keiyaku completion --complete --word \"${words[CURRENT]}\" --previous \"${words[CURRENT-1]}\" 2>/dev/null)\"})",
+            "  candidates=(${(f)\"$(keiyaku completion --complete --word=\"${words[CURRENT]}\" --previous=\"${words[CURRENT-1]}\" 2>/dev/null)\"})",
             "  compadd -- $candidates",
             "}",
             "_keiyaku \"$@\"",
@@ -65,7 +69,10 @@ export function renderCompletionScript(shell = "bash") {
         "  local cur prev",
         "  cur=\"${COMP_WORDS[COMP_CWORD]}\"",
         "  prev=\"${COMP_WORDS[COMP_CWORD-1]}\"",
-        "  COMPREPLY=( $(compgen -W \"$(keiyaku completion --complete --word \"$cur\" --previous \"$prev\" 2>/dev/null)\" -- \"$cur\") )",
+        "  COMPREPLY=()",
+        "  while IFS= read -r candidate; do",
+        "    COMPREPLY+=(\"$candidate\")",
+        "  done < <(keiyaku completion --complete --word=\"$cur\" --previous=\"$prev\" 2>/dev/null)",
         "}",
         "complete -F _keiyaku_completion keiyaku",
     ].join("\n");

package/build/cli/flags.js

@@ -1,4 +1,5 @@
 import { ACTOR_IDENTITY } from "../keiyaku.js";
+import { TASK_FILTER_GRAMMAR } from "../core/task/query.js";
 export const HELP_FLAGS = new Set(["--help", "-h"]);
 export const FLAG_SPECS = {
     cwd: {
@@ -178,8 +179,8 @@ export const FLAG_SPECS = {
     },
     filter: {
         kind: "value",
-        placeholder: "FIELD OP VALUE",
-        description: "Filter structured task facts. Repeat for AND; comma-separated values are OR.",
+        placeholder: TASK_FILTER_GRAMMAR,
+        description: "Filter structured task facts. Repeat --filter for AND; comma values or | terms are OR.",
     },
     sort: {
         kind: "value",

package/build/cli/render/errors.js

@@ -1,4 +1,4 @@
-import { asMessage, isFlowError, pickHintsFromError } from "../../flow-error.js";
+import { asMessage, isFlowError, pickHintsFromError, } from "../../flow-error.js";
 import { assertSettingsKnobUsable } from "../../config/settings/disease.js";
 import { loadKeiyakuSettings } from "../../config/settings/loader.js";
 import { loadAkumaCatalog } from "../../config/akuma-loader.js";
@@ -6,6 +6,20 @@ import { appendDebugLog } from "../../telemetry/debug-log.js";
 import { ACTOR_IDENTITY, TOOL_NAMES, BUILTIN_AGENT_NAMES } from "../../keiyaku.js";
 import { buildErrorResponse } from "./misc.js";
 import { addressCarrierFromError } from "../../core/addressing.js";
+import { shellQuote } from "./format.js";
+const TASK_FILTER_GRAMMAR_EXAMPLE = "title~audit,scope";
+function formatTaskFilterExpression(terms) {
+    return terms.map((term) => `${term.field}${term.operator}${term.values.join(",")}`).join("|");
+}
+function renderInvalidTaskFilterMessage(facts) {
+    const guidance = facts.recoveredTerms.length === 0
+        ? `Grammar example: keiyaku task ls --filter ${shellQuote(TASK_FILTER_GRAMMAR_EXAMPLE)}`
+        : `Paste-ready equivalent for parsed terms: keiyaku task ls --filter ${shellQuote(formatTaskFilterExpression(facts.recoveredTerms))}`;
+    return `invalid task filter: ${facts.detail}. Valid fields: ${facts.fields.join(", ")}. `
+        + `Valid operators: ${facts.operators.join(", ")}. `
+        + `Repeat --filter for AND; use commas for same-field OR or | between complete filters. `
+        + guidance;
+}
 function renderScopeViolation(evidence) {
     if (evidence.outcome === "no-positive-match") {
         return `  ${evidence.path}\n    no positive pattern matched`;
@@ -35,6 +49,9 @@ export function renderScopeAuditMessage(scope, evidence) {
     ].join("\n");
 }
 function renderErrorMessage(error) {
+    if (isFlowError(error) && error.facts?.kind === "invalid_task_filter") {
+        return renderInvalidTaskFilterMessage(error.facts);
+    }
     if (isFlowError(error) && error.facts?.kind === "scope_violation") {
         return renderScopeAuditMessage(error.facts.scope, error.facts.violations);
     }

package/build/cli/render/format.js

@@ -1,10 +1,13 @@
 import { getConfig } from "../../config/env.js";
 import { SECTION_ICONS } from "./response-style.js";
-/** Quote a shell argument only when the token is not already a single safe word. */
+// Command-copy output is POSIX shell syntax: close the quote, emit a literal
+// apostrophe, then reopen the quote. Other shell dialects are not supported.
+const POSIX_SINGLE_QUOTE_ESCAPE = "'\\''";
+/** Quote a POSIX shell argument only when the token is not already a single safe word. */
 export function shellQuote(value) {
     if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
         return value;
-    return `'${value.replace(/'/g, "'\\''")}'`;
+    return `'${value.replace(/'/g, POSIX_SINGLE_QUOTE_ESCAPE)}'`;
 }
 export function formatAgeMs(ms) {
     if (ms === undefined)

package/build/core/audit/candidate.js

@@ -0,0 +1,48 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { FlowError, asMessage } from "../../flow-error.js";
+import { createGit, wrapGitError } from "../../git/core.js";
+import { readStructuredDiff } from "../../git/diff/structured.js";
+import { rewriteRenewBranch } from "../renew.js";
+async function resolveObject(cwd, revision, kind) {
+    try {
+        return (await createGit(cwd).raw(["rev-parse", "--verify", `${revision}^{${kind}}`])).trim();
+    }
+    catch (error) {
+        throw wrapGitError(`rev-parse ${revision}^{${kind}}`, error, cwd);
+    }
+}
+export async function createAuditCandidate(input) {
+    const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "keiyaku-audit-"));
+    const git = createGit(input.root);
+    try {
+        await git.raw(["clone", "--quiet", "--no-hardlinks", "--no-checkout", input.root, cwd]);
+        const candidateGit = createGit(cwd);
+        await candidateGit.raw(["config", "user.name", "Keiyaku Audit"]);
+        await candidateGit.raw(["config", "user.email", "audit@keiyaku.invalid"]);
+        await candidateGit.raw(["checkout", "--quiet", "-B", `keiyaku/${input.contractId}`, input.frozen.coordinates.delivery.head]);
+        if (input.frozen.base === input.frozen.coordinates.target.head)
+            return { cwd, rehearsal: { status: "fresh" }, candidate: { base: input.frozen.coordinates.target.head, head: input.frozen.coordinates.delivery.head, tree: input.frozen.coordinates.delivery.tree, rewritten: false } };
+        try {
+            await rewriteRenewBranch({ cwd, contractId: input.contractId, oldHead: input.frozen.coordinates.delivery.head, recoveryRef: "refs/keiyaku/audit/disposable", newBase: input.frozen.coordinates.target.head, oldBase: input.frozen.base });
+        }
+        catch (error) {
+            if (error instanceof FlowError && error.code === "CLOSE_MERGE_CONFLICT" && error.facts?.kind === "renew_conflict")
+                return { cwd, rehearsal: { status: "conflict", paths: [...error.facts.conflictPaths], pathCapture: error.facts.conflictPathCapture.status === "captured" ? "captured" : "failed", ...(error.facts.conflictPathCapture.status === "failed" ? { diagnostic: error.facts.conflictPathCapture.diagnostic } : {}) }, candidate: null };
+            return { cwd, rehearsal: { status: "unknown", cause: { code: error instanceof FlowError ? error.code : "INTERNAL_STATE", message: asMessage(error) } }, candidate: null };
+        }
+        const [head, tree] = await Promise.all([resolveObject(cwd, "HEAD", "commit"), resolveObject(cwd, "HEAD", "tree")]);
+        return { cwd, rehearsal: { status: "clean", oldBase: input.frozen.base, newBase: input.frozen.coordinates.target.head, oldHead: input.frozen.coordinates.delivery.head }, candidate: { base: input.frozen.coordinates.target.head, head, tree, rewritten: true } };
+    }
+    catch (error) {
+        return { cwd, rehearsal: { status: "unknown", cause: { code: error instanceof FlowError ? error.code : "INTERNAL_STATE", message: asMessage(error) } }, candidate: null };
+    }
+}
+export async function disposeAuditCandidate(candidate) { await fs.rm(candidate.cwd, { recursive: true, force: true }); }
+export async function readAuditCandidateDiff(candidateResult) {
+    const candidate = candidateResult.candidate;
+    if (!candidate)
+        return null;
+    return readStructuredDiff(candidateResult.cwd, candidate.base, candidate.head, { excludePaths: [".keiyaku/KEIYAKU.md"] });
+}

package/build/core/audit/coordinates.js

@@ -0,0 +1,180 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { FlowError, asMessage } from "../../flow-error.js";
+import { createGit, wrapGitError } from "../../git/core.js";
+import { readLedger } from "../ledger.js";
+import { hasStrandableProjectionGeneration } from "../projection/index.js";
+import { readRenewRecoverySession } from "../renew-session.js";
+import { effectiveScope, findOpenArc, getFence, getMaxArc, receiptsAfterFence } from "../seal.js";
+import { queueMembership, readQueueReadModel } from "../settlement/queue.js";
+import { markdownSourceSections } from "../scope.js";
+import { normalizeSectionTitle } from "../markdown/titles.js";
+import { commissionTarget, latestBase } from "../status/drift.js";
+import { deriveContractState, isTerminalState } from "../status/lifecycle.js";
+import { resolveContractDeliveryCwd } from "../worktree-path.js";
+import { KEIYAKU_FILE } from "../../keiyaku.js";
+async function resolveObject(cwd, revision, kind) {
+    const git = createGit(cwd);
+    try {
+        return (await git.raw(["rev-parse", "--verify", `${revision}^{${kind}}`])).trim();
+    }
+    catch (error) {
+        throw wrapGitError(`rev-parse ${revision}^{${kind}}`, error, cwd);
+    }
+}
+export function appendedScopeTerms(entries) {
+    return entries.flatMap((entry) => entry.kind === "amend" && entry.data.scopeDelta ? entry.data.scopeDelta.add : []);
+}
+export function effectiveCriteria(entries) {
+    const bind = entries.find((entry) => entry.kind === "bind");
+    if (!bind)
+        return [];
+    const criteria = [...bind.data.checks];
+    for (const entry of entries) {
+        if (entry.kind !== "amend")
+            continue;
+        for (const section of markdownSourceSections(entry.data.amendment)) {
+            if (section.level !== 2 || normalizeSectionTitle(section.title) !== "checks")
+                continue;
+            for (const line of entry.data.amendment.slice(section.contentStart, section.end).split(/\r?\n/)) {
+                const match = line.match(/^\s*-\s+(.+)$/);
+                if (match)
+                    criteria.push(match[1].trim());
+            }
+        }
+    }
+    return criteria;
+}
+async function pinLedgerCoordinates(input) {
+    const ledger = await readLedger(input.root, input.contractId);
+    if (!ledger)
+        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} not found or not active`);
+    const bind = ledger.entries.find((entry) => entry.kind === "bind");
+    const target = commissionTarget(ledger.entries);
+    const base = latestBase(ledger.entries);
+    if (!bind || !target || !base)
+        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} is missing pinned audit coordinates`);
+    const [deliveryHead, deliveryTree, targetHead, targetTree] = await Promise.all([
+        resolveObject(input.root, input.deliveryRef, "commit"), resolveObject(input.root, input.deliveryRef, "tree"),
+        resolveObject(input.root, target.ref, "commit"), resolveObject(input.root, target.ref, "tree"),
+    ]);
+    return {
+        criteria: effectiveCriteria(ledger.entries), scope: effectiveScope(ledger.entries), appendScope: appendedScopeTerms(ledger.entries), base, entries: ledger.entries,
+        coordinates: { ledger: { head: ledger.head }, delivery: { ref: input.deliveryRef, head: deliveryHead, tree: deliveryTree }, target: { ref: target.ref, head: targetHead, tree: targetTree } },
+    };
+}
+async function deliveryResidue(cwd) {
+    const fields = (await createGit(cwd).raw(["status", "--porcelain=v1", "-z", "--untracked-files=all"])).split("\0");
+    const staged = new Set();
+    const unstaged = new Set();
+    const untracked = new Set();
+    for (let index = 0; index < fields.length; index += 1) {
+        const field = fields[index];
+        if (!field)
+            continue;
+        const xy = field.slice(0, 2);
+        const filePath = field.slice(3);
+        if (filePath === KEIYAKU_FILE || filePath.startsWith(".keiyaku/recovery/")) {
+            if (xy[0] === "R" || xy[0] === "C")
+                index += 1;
+            continue;
+        }
+        if (xy === "??")
+            untracked.add(filePath);
+        else {
+            if (xy[0] !== " ")
+                staged.add(filePath);
+            if (xy[1] !== " ")
+                unstaged.add(filePath);
+            if (xy[0] === "R" || xy[0] === "C")
+                index += 1;
+        }
+    }
+    const tracked = new Set([...staged, ...unstaged]);
+    return { tracked: [...tracked], staged: [...staged], unstaged: [...unstaged], untracked: [...untracked] };
+}
+function residueKey(residue) {
+    return JSON.stringify({ tracked: [...residue.tracked].sort(), staged: [...residue.staged].sort(), unstaged: [...residue.unstaged].sort(), untracked: [...residue.untracked].sort() });
+}
+async function residueFingerprint(cwd, residue) {
+    const git = createGit(cwd);
+    const digest = createHash("sha256").update(residueKey(residue));
+    const tracked = [...residue.tracked].sort();
+    if (tracked.length > 0)
+        digest.update(await git.raw(["diff", "--no-color", "--no-ext-diff", "--binary", "HEAD", "--", ...tracked]));
+    for (const pathname of [...residue.untracked].sort()) {
+        const absolute = path.join(cwd, pathname);
+        const stat = await fs.lstat(absolute);
+        digest.update(pathname).update("\0").update(String(stat.mode)).update("\0");
+        if (stat.isSymbolicLink())
+            digest.update(await fs.readlink(absolute));
+        else
+            digest.update(await fs.readFile(absolute));
+        digest.update("\0");
+    }
+    return digest.digest("hex");
+}
+async function deliveryCoordinate(cwd) {
+    const [head, tree, residue] = await Promise.all([resolveObject(cwd, "HEAD", "commit"), resolveObject(cwd, "HEAD", "tree"), deliveryResidue(cwd)]);
+    return { head, tree, residue, residueFingerprint: await residueFingerprint(cwd, residue) };
+}
+async function readReadiness(input) {
+    const bind = input.frozen.entries.find((entry) => entry.kind === "bind");
+    const lifecycle = deriveContractState(input.frozen.entries);
+    const [residue, looseCommits, session, queue, liveProjection, dependencies] = await Promise.all([
+        deliveryResidue(input.deliveryCwd), receiptsAfterFence(input.root, input.frozen.entries, input.frozen.coordinates.delivery.head), readRenewRecoverySession(input.root, input.contractId), readQueueReadModel(input.root),
+        hasStrandableProjectionGeneration({ cwd: input.root, commissionId: input.contractId, deliveryWorktree: input.deliveryCwd, nowMs: Date.now() }),
+        Promise.all((bind.data.after ?? []).map(async (id) => { const ledger = await readLedger(input.root, id); const state = ledger ? deriveContractState(ledger.entries) : { state: "missing" }; return { id, satisfied: ledger !== null && isTerminalState(state), state: state.state }; })),
+    ]);
+    const membership = queueMembership(queue, input.contractId);
+    return { deliveryResidue: residue, arc: { open: findOpenArc(input.frozen.entries)?.data.arc ?? (getMaxArc(input.frozen.entries) === 0 ? 0 : null), max: getMaxArc(input.frozen.entries), fence: getFence(input.frozen.entries), looseCommits }, renewSession: { open: session !== null }, rewriteGuard: { liveProjection }, dependencies, petition: { state: lifecycle.state, queue: membership ? { position: membership.position, length: membership.queueLength, head: membership.queueHead, diagnostics: membership.diagnostics.map((item) => item.kind) } : null } };
+}
+export async function pinAuditSnapshot(input) {
+    const contractId = input.address.binding.commissionId;
+    const root = input.address.repo.stableRoot;
+    const deliveryRef = `refs/heads/keiyaku/${contractId}`;
+    return pinLedgerCoordinates({ root, contractId, deliveryRef });
+}
+export function initialCoordinateRace(input) {
+    return { which: "delivery-worktree", pinned: input.frozen.coordinates.delivery, observed: input.observed };
+}
+export async function pinAuditCoordinates(input) {
+    const contractId = input.address.binding.commissionId;
+    const root = input.address.repo.stableRoot;
+    const frozen = await pinAuditSnapshot({ address: input.address });
+    const deliveryCwd = await resolveContractDeliveryCwd(input.cwd, contractId);
+    const coordinate = await deliveryCoordinate(deliveryCwd);
+    if (coordinate.head !== frozen.coordinates.delivery.head || coordinate.tree !== frozen.coordinates.delivery.tree)
+        throw new Error(`registered delivery worktree ${coordinate.head}/${coordinate.tree} does not match pinned delivery ref ${frozen.coordinates.delivery.head}/${frozen.coordinates.delivery.tree}`);
+    const readiness = await readReadiness({ root, deliveryCwd, contractId, frozen });
+    return { ...frozen, deliveryCwd, deliveryCoordinate: coordinate, readiness };
+}
+export async function rereadCoordinateRace(input) {
+    const contractId = input.address.binding.commissionId;
+    const root = input.address.repo.stableRoot;
+    const deliveryRef = `refs/heads/keiyaku/${contractId}`;
+    let after;
+    try {
+        after = await pinLedgerCoordinates({ root, contractId, deliveryRef });
+    }
+    catch (error) {
+        return { which: "ledger", pinned: input.frozen.coordinates.ledger, observed: asMessage(error) };
+    }
+    if (after.coordinates.ledger.head !== input.frozen.coordinates.ledger.head)
+        return { which: "ledger", pinned: input.frozen.coordinates.ledger, observed: after.coordinates.ledger };
+    if (after.coordinates.delivery.head !== input.frozen.coordinates.delivery.head || after.coordinates.delivery.tree !== input.frozen.coordinates.delivery.tree)
+        return { which: "delivery", pinned: input.frozen.coordinates.delivery, observed: after.coordinates.delivery };
+    if (after.coordinates.target.head !== input.frozen.coordinates.target.head || after.coordinates.target.tree !== input.frozen.coordinates.target.tree)
+        return { which: "target", pinned: input.frozen.coordinates.target, observed: after.coordinates.target };
+    try {
+        const deliveryCwd = await resolveContractDeliveryCwd(input.cwd, contractId);
+        const observed = await deliveryCoordinate(deliveryCwd);
+        if (path.resolve(deliveryCwd) !== path.resolve(input.frozen.deliveryCwd) || observed.head !== input.frozen.deliveryCoordinate.head || observed.tree !== input.frozen.deliveryCoordinate.tree || observed.residueFingerprint !== input.frozen.deliveryCoordinate.residueFingerprint)
+            return { which: "delivery-worktree", pinned: { cwd: input.frozen.deliveryCwd, ...input.frozen.deliveryCoordinate }, observed: { cwd: deliveryCwd, ...observed } };
+    }
+    catch (error) {
+        return { which: "delivery-worktree", pinned: { cwd: input.frozen.deliveryCwd, ...input.frozen.deliveryCoordinate }, observed: asMessage(error) };
+    }
+    return null;
+}