@astrosheep/keiyaku 1.0.0 → 1.0.2

package/build/core/amend.js

@@ -6,15 +6,10 @@ import { KEIYAKU_FILE } from "../keiyaku.js";
 import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
 import { renderContractView } from "./render.js";
 import { deriveContractState, isTerminalState } from "./status.js";
-import { resolveCurrentContractId } from "./context.js";
+import { resolveContractAddress, withResolvedAddress } from "./addressing.js";
 import { resolveDefaultBranch } from "./status.js";
 import { assertCleanWorkingTree } from "./arc.js";
-function requireText(name, value) {
-    const normalized = value.trim();
-    if (!normalized)
-        throw new FlowError("EMPTY_PARAM", `${name} cannot be empty`);
-    return normalized;
-}
+import { normalizeScopePattern } from "./scope.js";
 function requireAmendment(value) {
     if (!value.trim())
         throw new FlowError("EMPTY_PARAM", "amendment cannot be empty");
@@ -39,15 +34,11 @@ async function renderUpdatedContract(cwd, contractId) {
 function normalizeScopeDelta(scopeDelta) {
     if (!scopeDelta)
         return undefined;
-    const add = [...new Set(scopeDelta.add.map((pattern) => requireText("scope add", pattern)))];
-    const remove = [...new Set(scopeDelta.remove.map((pattern) => requireText("scope remove", pattern)))];
-    const conflict = add.find((pattern) => remove.includes(pattern));
-    if (conflict) {
-        throw new FlowError("INVALID_KEIYAKU_DRAFT", `amend scope pattern appears in both ## Scope Add and ## Scope Remove: ${conflict}`);
-    }
-    if (add.length === 0 && remove.length === 0)
+    // Scope patterns are gitignore text; do not requireText/trim, or escaped trailing spaces die.
+    const add = scopeDelta.add.map((pattern) => normalizeScopePattern(pattern));
+    if (add.length === 0)
         return undefined;
-    return { add, remove };
+    return { add };
 }
 export async function amendContract(input) {
     const amendment = requireAmendment(input.amendment);
@@ -84,37 +75,29 @@ export async function amendKeiyaku(input) {
     if (!isRepo) {
         throw new FlowError("NOT_GIT_REPO", `${input.cwd} is not a git repository`);
     }
-    let contractId;
-    try {
-        const resolution = await resolveCurrentContractId(input.cwd);
-        if (resolution.status === "none")
-            throw new FlowError("EMPTY_PARAM", "no active contract found");
-        contractId = resolution.contractId;
-    }
-    catch (error) {
-        if (!(error instanceof FlowError) || error.code !== "EMPTY_PARAM") {
-            throw error;
-        }
-        throw new FlowError("NOT_ACTIVE_KEIYAKU_BRANCH", "Current workspace is not addressing an active Keiyaku contract.", { hints: ["keiyaku bind — opens a new contract"] });
-    }
-    await assertCleanWorkingTree(input.cwd, []);
-    const amendment = requireAmendment(input.amendment);
-    const currentBranch = await getCurrentBranch(input.cwd);
-    const baseBranch = (await resolveDefaultBranch(input.cwd))?.branch ?? currentBranch;
-    const amended = await amendContract({
-        cwd: input.cwd,
-        contractId,
-        actor: "keiyaku",
-        nowMs: Date.now(),
-        amendment,
-        scopeDelta: input.scopeDelta,
+    const address = await resolveContractAddress(input.cwd, input.contractId, input.contractAddressSource);
+    return await withResolvedAddress(address, async () => {
+        const contractId = address.binding.commissionId;
+        await assertCleanWorkingTree(input.cwd, []);
+        const amendment = requireAmendment(input.amendment);
+        const currentBranch = await getCurrentBranch(input.cwd);
+        const baseBranch = (await resolveDefaultBranch(input.cwd))?.branch ?? currentBranch;
+        const amended = await amendContract({
+            cwd: input.cwd,
+            contractId,
+            actor: "keiyaku",
+            nowMs: Date.now(),
+            amendment,
+            scopeDelta: input.scopeDelta,
+        });
+        return {
+            status: "success",
+            amendmentNumber: amended.amendmentNumber,
+            currentBranch,
+            baseBranch,
+            ledgerCommit: amended.ledgerHead,
+            summary: `Appended Amendment ${amended.amendmentNumber} to contract ledger ${contractId}.`,
+            address,
+        };
     });
-    return {
-        status: "success",
-        amendmentNumber: amended.amendmentNumber,
-        currentBranch,
-        baseBranch,
-        ledgerCommit: amended.ledgerHead,
-        summary: `Appended Amendment ${amended.amendmentNumber} to contract ledger ${contractId}.`,
-    };
 }

package/build/core/arc.js

@@ -6,8 +6,8 @@ import { DIRTY_FILE_CATEGORY, getDirtyFiles, renderDirtyFileStatusLine } from ".
 import { KEIYAKU_FILE, ACTOR_IDENTITY } from "../keiyaku.js";
 import { buildDirtyWorktreeArtifactHint } from "./hints.js";
 import { normalizeInlineTitle } from "./markdown/titles.js";
-import { assertKnownMarkdownSections, parseCommandMarkdown, requireMarkdownTextSection, requireMarkdownTitle, } from "./command-io.js";
-import { resolveCurrentContractId } from "./context.js";
+import { parseCommandMarkdown, requireMarkdownTextSection, requireMarkdownTitle, } from "./command-io.js";
+import { resolveContractAddress, withResolvedAddress } from "./addressing.js";
 import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
 import { renderContractView } from "./render.js";
 import { findOpenArc, getMaxArc, sealOpenArc } from "./seal.js";
@@ -117,6 +117,7 @@ export async function openArc(input) {
         contractId: input.contractId,
         sealedBy: "arc",
         nowMs: input.nowMs,
+        waivePaths: input.waivePaths,
     });
     const at = new Date(input.nowMs).toISOString();
     let arcNumber = 0;
@@ -141,14 +142,16 @@ export async function openArc(input) {
     await renderUpdatedContract(input.cwd, input.contractId);
     return { contractId: input.contractId, arc: arcNumber, ledgerHead: result.head, sealed };
 }
-export function buildArcInput(content, cwd) {
+export function buildArcInput(content, cwd, waivePaths = [], contractId, contractAddressSource) {
     const parts = parseCommandMarkdown(content);
-    assertKnownMarkdownSections(parts, "arc", ["Objective", "Brief"]);
     return {
         cwd,
+        ...(contractId ? { contractId } : {}),
+        ...(contractAddressSource ? { contractAddressSource } : {}),
         title: requireMarkdownTitle(parts),
         objective: requireMarkdownTextSection(parts, "Objective"),
         brief: requireMarkdownTextSection(parts, "Brief"),
+        waivePaths,
     };
 }
 async function readBranchLabels(cwd) {
@@ -160,66 +163,71 @@ export async function arcKeiyaku(input) {
     if (!(await isGitRepo(input.cwd))) {
         throw new FlowError("NOT_GIT_REPO", `${input.cwd} is not a git repository`);
     }
-    await assertCleanWorkingTree(input.cwd, []);
-    try {
-        await fs.access(path.join(input.cwd, KEIYAKU_FILE));
-    }
-    catch {
-        throw new FlowError("MISSING_PROTOCOL_FILES", `missing protocol file for current keiyaku (${KEIYAKU_FILE})`);
-    }
-    const title = normalizeInlineTitle(requireText("title", input.title));
-    const objective = requireText("objective", input.objective);
-    const brief = requireText("brief", input.brief);
-    const resolution = await resolveCurrentContractId(input.cwd);
-    if (resolution.status === "none")
-        throw new FlowError("EMPTY_PARAM", "no active contract found");
-    const contractId = resolution.contractId;
-    const opened = await openArc({
-        cwd: input.cwd,
-        contractId,
-        actor: ACTOR_IDENTITY,
-        nowMs: Date.now(),
-        title,
-        objective,
-        brief,
-    });
-    const { currentBranch, baseBranch } = await readBranchLabels(input.cwd);
-    const summary = opened.sealed
-        ? `a${opened.sealed.arc} sealed; a${opened.arc} open: ${title}.`
-        : `a${opened.arc} open: ${title}.`;
-    const diff = opened.sealed?.incrementalDiff ?? "working tree untouched";
-    let responsePath;
-    try {
-        responsePath = await persistResponseHistory({
+    const address = await resolveContractAddress(input.cwd, input.contractId, input.contractAddressSource);
+    return await withResolvedAddress(address, async () => {
+        await assertCleanWorkingTree(input.cwd, []);
+        try {
+            await fs.access(path.join(input.cwd, KEIYAKU_FILE));
+        }
+        catch {
+            throw new FlowError("MISSING_PROTOCOL_FILES", `missing protocol file for current keiyaku (${KEIYAKU_FILE})`);
+        }
+        const title = normalizeInlineTitle(requireText("title", input.title));
+        const objective = requireText("objective", input.objective);
+        const brief = requireText("brief", input.brief);
+        const contractId = address.binding.commissionId;
+        const opened = await openArc({
             cwd: input.cwd,
-            tool: "arc",
+            contractId,
+            actor: ACTOR_IDENTITY,
+            nowMs: Date.now(),
             title,
-            branch: currentBranch,
+            objective,
+            brief,
+            waivePaths: input.waivePaths,
+        });
+        const { currentBranch, baseBranch } = await readBranchLabels(input.cwd);
+        const summary = opened.sealed
+            ? `a${opened.sealed.arc} sealed; a${opened.arc} open: ${title}.`
+            : `a${opened.arc} open: ${title}.`;
+        const diff = opened.sealed?.incrementalDiff ?? "working tree untouched";
+        let responsePath;
+        let artifactId;
+        try {
+            const persisted = await persistResponseHistory({
+                cwd: input.cwd,
+                tool: "arc",
+                provenance: { authority: { kind: "repository" }, binding: address.binding, evidenceCwd: input.cwd },
+                title,
+                objective,
+                brief,
+                ledgerCommit: opened.ledgerHead,
+                summary,
+                diff,
+                ...(opened.sealed ? { sealed: opened.sealed } : {}),
+            });
+            responsePath = persisted.responsePath;
+            artifactId = persisted.artifactId;
+        }
+        catch {
+            responsePath = undefined;
+        }
+        return {
+            status: "success",
+            arc: opened.arc,
+            currentBranch,
+            baseBranch,
             commit: opened.ledgerHead,
+            diff,
+            summary,
+            title,
             objective,
             brief,
             ledgerCommit: opened.ledgerHead,
-            summary,
-            diff,
-            ...(opened.sealed ? { sealed: opened.sealed } : {}),
-        });
-    }
-    catch {
-        responsePath = undefined;
-    }
-    return {
-        status: "success",
-        arc: opened.arc,
-        currentBranch,
-        baseBranch,
-        commit: opened.ledgerHead,
-        diff,
-        summary,
-        title,
-        objective,
-        brief,
-        ledgerCommit: opened.ledgerHead,
-        sealed: opened.sealed ?? undefined,
-        responsePath,
-    };
+            sealed: opened.sealed ?? undefined,
+            responsePath,
+            artifactId,
+            address,
+        };
+    });
 }

package/build/core/bind.js

@@ -1,17 +1,19 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { assertSettingsKnobUsable, loadKeiyakuSettings } from "../config/settings.js";
 import { FlowError } from "../flow-error.js";
 import { KEIYAKU_FILE } from "../keiyaku.js";
 import { createGit, wrapGitError } from "../git/core.js";
-import { activeLedgerRef, appendEntry, appendWithRetry, readLedger } from "./ledger.js";
+import { activeLedgerRef, appendEntry, appendWithRetry, listContractIds, readLedger } from "./ledger.js";
 import { parseBindDraft } from "./draft.js";
 import { assertValidContractId, buildContractId } from "./ids.js";
 import { CONTRACT_PLACES } from "./places.js";
 import { renderContractView } from "./render.js";
 import { registerScope, releaseScope } from "./registry.js";
-import { deriveContractState, isTerminalState, listContractIds } from "./status.js";
-import { contractWorktreePathFromBind, findBindEntry, stableRepoRoot } from "./worktree-path.js";
+import { deriveContractState, isTerminalState, normalizeTargetRef, resolveDefaultBranch } from "./status.js";
+import { bootstrapEntryDataFromObservation, isBootstrapSuccess, runWorktreeBootstrap, } from "./worktree-bootstrap.js";
+import { contractWorktreePathFromBind, findBindEntry } from "./worktree-path.js";
 function randomBytesDefault() {
     return [...crypto.randomBytes(10)];
 }
@@ -112,25 +114,50 @@ async function appendBindFailedForfeit(cwd, id, actor, at) {
         throw new FlowError("INTERNAL_STATE", `BIND_FAILURE_FORFEIT_FAILED: failed to append bind-failed forfeit for ${id}: ${result.reason}`);
     }
 }
-async function occupiedWorktreePlaces(cwd) {
-    const occupied = new Set();
-    const stableRoot = await stableRepoRoot(cwd);
-    try {
-        const dirents = await fs.readdir(path.join(stableRoot, ".keiyaku", "wt"), { withFileTypes: true });
-        for (const dirent of dirents) {
-            if (dirent.isDirectory())
-                occupied.add(dirent.name);
+async function appendBootstrapEntry(cwd, id, actor, at, data) {
+    const entry = {
+        v: 1,
+        kind: "bootstrap",
+        contract: id,
+        at,
+        actor,
+        data,
+    };
+    // Bootstrap is legal only at index 1 immediately after the planned bind.
+    // If another entry advanced during bootstrap execution, abort rather than
+    // CAS-retrying into a late (corrupt) position.
+    const result = await appendWithRetry(cwd, activeLedgerRef(id), (_currentHead, currentEntries) => {
+        if (currentEntries.length !== 1)
+            return null;
+        const only = currentEntries[0];
+        if (!only || only.kind !== "bind" || only.contract !== id || !only.data.bootstrap) {
+            return null;
         }
+        return entry;
+    });
+    if (!result.ok) {
+        throw new FlowError("INTERNAL_STATE", `BIND_BOOTSTRAP_APPEND_FAILED: failed to append bootstrap entry for ${id}: ${result.reason}`);
     }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
-    }
+    return result.head;
+}
+function resolvedBootstrapPlan(settings) {
+    if (!settings)
+        return undefined;
+    return {
+        command: [...settings.command],
+        timeoutMs: settings.timeoutMs,
+    };
+}
+function bootstrapProgressLine(command) {
+    return `bootstrap » ${command.join(" ")}`;
+}
+async function occupiedWorktreePlaces(cwd) {
+    const occupied = new Set();
     for (const id of await listContractIds(cwd)) {
         const ledger = await readLedger(cwd, id);
         if (!ledger || isTerminalState(deriveContractState(ledger.entries)))
             continue;
-        const place = ledger ? findBindEntry(ledger.entries)?.data.place : undefined;
+        const place = findBindEntry(ledger.entries)?.data.place;
         if (place)
             occupied.add(place);
     }
@@ -143,12 +170,21 @@ function randomIndex(randomBytes, size) {
     }
     return value;
 }
+function nextGenerationPlace(base, occupied) {
+    for (let generation = 2;; generation += 1) {
+        const candidate = `${base}${generation}`;
+        if (!occupied.has(candidate))
+            return candidate;
+    }
+}
 async function allocateWorktreePlace(cwd, randomBytes) {
     const occupied = await occupiedWorktreePlaces(cwd);
     const candidates = CONTRACT_PLACES.filter((place) => !occupied.has(place));
-    if (candidates.length === 0)
-        return null;
-    return candidates[randomIndex(randomBytes, candidates.length)];
+    if (candidates.length > 0) {
+        return candidates[randomIndex(randomBytes, candidates.length)];
+    }
+    const base = CONTRACT_PLACES[randomIndex(randomBytes, CONTRACT_PLACES.length)];
+    return nextGenerationPlace(base, occupied);
 }
 function makeBindEntry(input) {
     return {
@@ -162,9 +198,11 @@ function makeBindEntry(input) {
             objective: input.draft.objective,
             scope: input.draft.scope,
             base: input.base,
+            target: input.target,
             workspace: input.workspace,
             after: input.after,
             ...(input.workspace === "worktree" ? { place: input.place ?? null } : {}),
+            ...(input.bootstrap ? { bootstrap: input.bootstrap } : {}),
         },
     };
 }
@@ -173,6 +211,17 @@ export async function bindContract(input) {
     const workspace = input.workspace ?? "here";
     const at = new Date(input.nowMs).toISOString();
     const base = await getHead(input.cwd);
+    const defaultBranch = await resolveDefaultBranch(input.cwd);
+    if (!defaultBranch) {
+        throw new FlowError("INTERNAL_STATE", "cannot bind: no default branch");
+    }
+    const target = normalizeTargetRef(defaultBranch.branch);
+    const loadedSettings = await loadKeiyakuSettings(input.cwd);
+    let bootstrapPlan;
+    if (workspace === "worktree") {
+        assertSettingsKnobUsable(loadedSettings, "worktreeBootstrap");
+        bootstrapPlan = resolvedBootstrapPlan(loadedSettings.knobs?.worktreeBootstrap);
+    }
     const collidedIds = [];
     for (let attempt = 0; attempt < 2; attempt += 1) {
         const randomBytes = input.randomBytes?.(attempt) ?? randomBytesDefault();
@@ -189,9 +238,11 @@ export async function bindContract(input) {
             actor: input.actor,
             draft,
             base,
+            target,
             after: input.after ?? [],
             workspace,
             place,
+            bootstrap: bootstrapPlan,
         });
         const ref = activeLedgerRef(id);
         const appended = await appendEntry(input.cwd, ref, entry, null);
@@ -203,6 +254,8 @@ export async function bindContract(input) {
         const branch = `keiyaku/${id}`;
         const worktreePath = await contractWorktreePathFromBind(input.cwd, id, entry);
         const targetRoot = workspace === "here" ? input.cwd : worktreePath;
+        let ledgerHead = appended.head;
+        let bootstrapRecorded = false;
         try {
             const tree = await resolveTreeRoot(input.cwd, workspace, id, entry);
             const registration = await registerScope(input.cwd, {
@@ -226,6 +279,16 @@ export async function bindContract(input) {
                 });
                 resources.worktreePath = worktreePath;
             }
+            if (bootstrapPlan) {
+                input.onProgress?.(bootstrapProgressLine(bootstrapPlan.command));
+                const runner = input.bootstrapRunner ?? runWorktreeBootstrap;
+                const observation = await runner({ cwd: worktreePath, plan: bootstrapPlan }, input.bootstrapDependencies);
+                ledgerHead = await appendBootstrapEntry(input.cwd, id, input.actor, at, bootstrapEntryDataFromObservation(observation));
+                bootstrapRecorded = true;
+                if (!isBootstrapSuccess(observation)) {
+                    throw new FlowError("INTERNAL_STATE", `BIND_BOOTSTRAP_FAILED: worktree bootstrap failed with ${observation.result.kind}`);
+                }
+            }
             const ledger = await readLedger(input.cwd, id);
             if (!ledger)
                 throw new FlowError("INTERNAL_STATE", `LEDGER_MISSING: ledger missing immediately after bind for ${id}`);
@@ -239,17 +302,34 @@ export async function bindContract(input) {
                 branch: workspace === "worktree" ? branch : undefined,
                 worktreePath: targetRoot,
                 workspace,
-                ledgerHead: appended.head,
+                ledgerHead,
                 warnings: registration.warnings,
             };
         }
         catch (error) {
-            const cleanupFailures = await cleanupCreatedResources(input.cwd, resources);
-            try {
-                await appendBindFailedForfeit(input.cwd, id, input.actor, at);
+            // Bootstrap failure order is strict: bootstrap entry (already appended) →
+            // forfeit(bind-failed) → cleanup. Cleanup cold facts cannot convert success.
+            const cleanupFailures = [];
+            if (!bootstrapRecorded) {
+                // Non-bootstrap failure: cleanup first remains compatible with prior path,
+                // then forfeit. When bootstrap already recorded its failed fact, forfeit
+                // must precede cleanup.
+                cleanupFailures.push(...(await cleanupCreatedResources(input.cwd, resources)));
+                try {
+                    await appendBindFailedForfeit(input.cwd, id, input.actor, at);
+                }
+                catch (forfeitError) {
+                    cleanupFailures.push(forfeitError instanceof Error ? forfeitError.message : String(forfeitError));
+                }
             }
-            catch (forfeitError) {
-                cleanupFailures.push(forfeitError instanceof Error ? forfeitError.message : String(forfeitError));
+            else {
+                try {
+                    await appendBindFailedForfeit(input.cwd, id, input.actor, at);
+                }
+                catch (forfeitError) {
+                    cleanupFailures.push(forfeitError instanceof Error ? forfeitError.message : String(forfeitError));
+                }
+                cleanupFailures.push(...(await cleanupCreatedResources(input.cwd, resources)));
             }
             if (resources.registry) {
                 try {

package/build/core/call-persist.js

@@ -0,0 +1,69 @@
+import { appendDebugLog } from "../telemetry/debug-log.js";
+import { logWarn } from "../telemetry/logger.js";
+import { runCall } from "./call.js";
+import { persistResponseHistory } from "./transcripts.js";
+import { isGitRepo } from "../git/branches.js";
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import { stableRepoRoot } from "./worktree-path.js";
+function responsePathFromPrintingCwd(historyStorageCwd, responsePath) {
+    const printingCwd = process.cwd();
+    const absoluteHistoryCwd = path.resolve(printingCwd, historyStorageCwd);
+    return path.relative(printingCwd, path.resolve(absoluteHistoryCwd, responsePath));
+}
+export async function runCallAndPersist(input) {
+    const historyCandidate = input.repo ?? input.cwd;
+    const canonicalHistoryCandidate = await fs.realpath(historyCandidate);
+    const historyStorageCwd = (await isGitRepo(historyCandidate))
+        ? await stableRepoRoot(historyCandidate)
+        : canonicalHistoryCandidate;
+    const historyDisplayCwd = path.resolve(historyCandidate, path.relative(canonicalHistoryCandidate, historyStorageCwd));
+    const result = await runCall(input);
+    if (input.incognito) {
+        return { result };
+    }
+    if (result.projectionOwnsResponsePersistence === true) {
+        return {
+            result,
+            ...(result.responsePath ? { responsePath: responsePathFromPrintingCwd(historyDisplayCwd, result.responsePath) } : {}),
+            ...(result.artifactId ? { artifactId: result.artifactId } : {}),
+        };
+    }
+    let responsePath;
+    let artifactId;
+    try {
+        if (!result.evidenceCwd)
+            throw new Error("call response persistence is missing evidenceCwd");
+        const authority = result.address.repo.kind === "repository"
+            ? { kind: "repository" }
+            : { kind: "user" };
+        const persisted = await persistResponseHistory({
+            cwd: historyStorageCwd,
+            tool: "call",
+            provenance: { authority, binding: result.address.binding, evidenceCwd: result.evidenceCwd },
+            title: input.title,
+            task: input.task,
+            context: input.context,
+            response: result.summary,
+            session: result.session,
+            subagentName: result.agent,
+            launchSnapshot: result.launchSnapshot,
+            effectivePolicy: result.meta?.effectivePolicy,
+        });
+        responsePath = persisted.responsePath;
+        artifactId = persisted.artifactId;
+    }
+    catch (historyError) {
+        const historyErrorMessage = historyError instanceof Error ? historyError.message : String(historyError);
+        logWarn(`Failed to persist call response: ${historyErrorMessage}`, { cwd: historyStorageCwd, section: "script" });
+        appendDebugLog(`tool call response persistence failed: ${historyErrorMessage}`, {
+            cwd: historyStorageCwd,
+            section: "script",
+        });
+    }
+    return {
+        result: artifactId ? { ...result, artifactId } : result,
+        ...(responsePath ? { responsePath: responsePathFromPrintingCwd(historyDisplayCwd, responsePath) } : {}),
+        ...(artifactId ? { artifactId } : {}),
+    };
+}