@astrosheep/keiyaku 2.9.11 → 2.9.13

package/build/core/task/settlement-git.js

@@ -5,6 +5,12 @@ import { runGitProcess } from "../../git/core.js";
 import { openGitStreamingBatch } from "../../git/streaming-batch.js";
 import { parseTaskDocument } from "./task.js";
 import { parseTaskCoordinate } from "./coordinate.js";
+function observePublicationEffect(observer, effect) {
+    try {
+        observer?.(effect);
+    }
+    catch { /* observation cannot participate in the Git transaction */ }
+}
 async function gitResult(cwd, args, input, env, signal) {
     return await runGitProcess(cwd, args, { input, env, signal });
 }
@@ -78,9 +84,11 @@ export async function createTaskMutationCommit(input) {
             ], undefined, env, input.signal);
         }
         const tree = (await git(input.cwd, ["write-tree"], undefined, env, input.signal)).trim();
-        const parentTree = (await git(input.cwd, ["show", "-s", "--format=%T", input.parent], undefined, undefined, input.signal)).trim();
-        if (tree === parentTree)
-            return input.parent;
+        if (!input.requireCommit) {
+            const parentTree = (await git(input.cwd, ["show", "-s", "--format=%T", input.parent], undefined, undefined, input.signal)).trim();
+            if (tree === parentTree)
+                return input.parent;
+        }
         return (await git(input.cwd, ["commit-tree", tree, "-p", input.parent, "-m", input.subject], undefined, undefined, input.signal)).trim();
     }
     finally {
@@ -88,15 +96,37 @@ export async function createTaskMutationCommit(input) {
     }
 }
 /** Stage only the mutated task paths into the real index; leave unrelated entries alone. */
-export async function reconcileTaskMutationIndex(cwd, writes, signal) {
+async function reconcileTaskMutationIndexPath(cwd, write, signal) {
+    const oid = (await git(cwd, ["hash-object", "-w", "--stdin"], write.text, undefined, signal)).trim();
+    await git(cwd, [
+        "update-index",
+        "--add",
+        "--cacheinfo",
+        `100644,${oid},${taskMutationPath(write)}`,
+    ], undefined, undefined, signal);
+}
+export async function reconcileTaskMutationIndex(cwd, writes, signal, reconcilePath = async (input) => {
+    await reconcileTaskMutationIndexPath(input.cwd, input.write, input.signal);
+}) {
     for (const write of writes) {
-        const oid = (await git(cwd, ["hash-object", "-w", "--stdin"], write.text, undefined, signal)).trim();
-        await git(cwd, [
-            "update-index",
-            "--add",
-            "--cacheinfo",
-            `100644,${oid},${taskMutationPath(write)}`,
-        ], undefined, undefined, signal);
+        await reconcilePath({ cwd, write, signal });
+    }
+}
+async function snapshotTaskMutationIndex(cwd, writes, signal) {
+    const snapshot = [];
+    for (const write of writes) {
+        const taskPath = taskMutationPath(write);
+        const output = await git(cwd, ["ls-files", "--stage", "-z", "--", taskPath], undefined, undefined, signal);
+        snapshot.push({ path: taskPath, entries: output.split("\0").filter(Boolean) });
+    }
+    return snapshot;
+}
+async function restoreTaskMutationIndex(cwd, snapshot, signal) {
+    for (const item of snapshot) {
+        await git(cwd, ["update-index", "--force-remove", "--", item.path], undefined, undefined, signal);
+        if (item.entries.length > 0) {
+            await git(cwd, ["update-index", "-z", "--index-info"], `${item.entries.join("\0")}\0`, undefined, signal);
+        }
     }
 }
 /**
@@ -114,20 +144,33 @@ export async function publishTaskMutationCommit(input, deps = {}) {
             parent: branch.head,
             writes: input.writes,
             subject: input.subject,
+            requireCommit: input.requireCommit,
             signal: input.signal,
         });
         if (commit === branch.head) {
-            input.observeEffect?.({ effect: "task-reconciliation", status: "succeeded", commit, detail: "current" });
+            const indexBefore = await snapshotTaskMutationIndex(input.cwd, input.writes, input.signal);
             try {
-                await reconcileTaskMutationIndex(input.cwd, input.writes, input.signal);
-                input.observeEffect?.({ effect: "task-index-reconciliation", status: "succeeded", commit });
+                await reconcileTaskMutationIndex(input.cwd, input.writes, input.signal, deps.reconcileIndexPath);
+                observePublicationEffect(input.observeEffect, { effect: "task-reconciliation", status: "succeeded", commit, detail: "current" });
+                observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "succeeded", commit });
+                return commit;
             }
             catch (error) {
-                input.observeEffect?.({ effect: "task-index-reconciliation", status: "failed", commit, error });
+                try {
+                    await restoreTaskMutationIndex(input.cwd, indexBefore, input.signal);
+                }
+                catch (restoreError) {
+                    observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "failed", commit, error: restoreError });
+                    throw new FlowError("INTERNAL_STATE", "cannot restore task index after reconciliation failure", { cause: restoreError });
+                }
+                observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "failed", commit, error });
+                throw error;
             }
-            return commit;
         }
+        const indexBefore = await snapshotTaskMutationIndex(input.cwd, input.writes, input.signal);
         try {
+            await reconcileTaskMutationIndex(input.cwd, input.writes, input.signal, deps.reconcileIndexPath);
+            observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "succeeded", commit });
             await updateBranch({
                 cwd: input.cwd,
                 ref: branch.ref,
@@ -135,22 +178,22 @@ export async function publishTaskMutationCommit(input, deps = {}) {
                 expected: branch.head,
                 signal: input.signal,
             }, deps);
-            input.observeEffect?.({ effect: "task-reconciliation", status: "succeeded", commit, detail: "published" });
-            try {
-                await reconcileTaskMutationIndex(input.cwd, input.writes, input.signal);
-                input.observeEffect?.({ effect: "task-index-reconciliation", status: "succeeded", commit });
-            }
-            catch (error) {
-                // Branch fact remains authoritative; index may be repaired by a later mutation.
-                input.observeEffect?.({ effect: "task-index-reconciliation", status: "failed", commit, error });
-            }
+            observePublicationEffect(input.observeEffect, { effect: "task-reconciliation", status: "succeeded", commit, detail: "published" });
             return commit;
         }
         catch (error) {
             lastError = error;
+            try {
+                await restoreTaskMutationIndex(input.cwd, indexBefore, input.signal);
+            }
+            catch (restoreError) {
+                observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "failed", commit, error: restoreError });
+                throw new FlowError("INTERNAL_STATE", "cannot restore task index after publication failure", { cause: restoreError });
+            }
+            observePublicationEffect(input.observeEffect, { effect: "task-index-reconciliation", status: "failed", commit, error });
         }
     }
-    input.observeEffect?.({ effect: "task-reconciliation", status: "failed", error: lastError });
+    observePublicationEffect(input.observeEffect, { effect: "task-reconciliation", status: "failed", error: lastError });
     throw lastError;
 }
 async function taskTreeEntries(cwd, commit) {
@@ -235,10 +278,7 @@ async function readTaskAdmissionEvidence(input, readDocument = taskDocumentAtCom
         const needs = [];
         for (const need of document.needs) {
             const prerequisite = await read(need);
-            if (prerequisite.state !== "done" && prerequisite.state !== "drop") {
-                throw new FlowError("INTERNAL_STATE", `bind base ${input.base} task ${taskId} has unsatisfied need ${need}`);
-            }
-            needs.push({ taskId: need, state: prerequisite.state });
+            needs.push({ taskId: need, state: prerequisite.state, ...(prerequisite.contractId === undefined ? {} : { contractId: prerequisite.contractId }) });
         }
         selected.push({ taskId, needs });
     }

package/build/core/task/settlement-policy.js

@@ -1,5 +1,8 @@
 import { FlowError } from "../../flow-error.js";
 import { resolveTaskReadId } from "./board.js";
+import { openTaskStore } from "./task-git-store.js";
+import { taskRepositoryFromStore } from "./task-store-repository.js";
+import { readTaskBoard } from "./commands.js";
 import { advancedTaskUpdatedAt } from "./model.js";
 export function requireHealthySettlementBoard(board) {
     if (board.diseases.length > 0) {
@@ -20,6 +23,7 @@ function settlementDocument(task, contractId, updatedAt) {
         from: [...task.from],
         supersedes: [...task.supersedes],
         relatesTo: [...task.relatesTo],
+        notes: task.notes.map((note) => ({ ...note })),
         createdAt: task.createdAt,
         updatedAt: advancedTaskUpdatedAt(task, updatedAt),
         creator: task.creator,
@@ -31,6 +35,12 @@ function settlementDocument(task, contractId, updatedAt) {
 export function contractPointerDocument(task, contractId, updatedAt) {
     return settlementDocument(task, contractId, updatedAt);
 }
+export function boundTaskDocument(task, contractId, updatedAt) {
+    const document = settlementDocument(task, contractId, updatedAt);
+    document.state = "open";
+    delete document.startedAt;
+    return document;
+}
 export function reopenedTaskDocument(task, updatedAt) {
     const document = settlementDocument(task, undefined, updatedAt);
     document.state = "open";
@@ -38,25 +48,28 @@ export function reopenedTaskDocument(task, updatedAt) {
     return document;
 }
 function validateReadyForBind(board, task) {
-    if (task.state === "in_progress") {
-        throw new FlowError("INVALID_TARGET", `task ${task.coordinate} is in_progress; stop it before bind`);
-    }
-    if (task.state !== "open") {
-        throw new FlowError("INVALID_TARGET", `task ${task.coordinate} is ${task.state}, not ready for bind`);
-    }
-    const unsatisfied = task.needs
-        .filter((need) => {
-        const dependency = board.byId.get(need);
-        return dependency.state === "open" || dependency.state === "in_progress" || dependency.state === "on_hold";
-    })
-        .sort();
-    if (unsatisfied.length > 0) {
-        throw new FlowError("INVALID_TARGET", `task ${task.coordinate} is blocked by: ${unsatisfied.join(", ")}`);
+    if (task.state !== "open" && task.state !== "in_progress") {
+        throw new FlowError("INVALID_TARGET", `task ${task.coordinate} is ${task.state}, not open or in_progress for bind`);
     }
     if (task.contractId !== undefined) {
         throw new FlowError("INVALID_TARGET", `task ${task.coordinate} is already bound to contract ${task.contractId}`);
     }
 }
+/** Read the sole live task prerequisite gate for a task-selected contract. */
+export async function readRemainingTaskNeedsForSettlement(cwd, evidence) {
+    const needIds = [...new Set(evidence?.selected.flatMap((task) => task.needs
+            .filter((need) => need.contractId === undefined)
+            .map((need) => need.taskId)) ?? [])].sort();
+    if (needIds.length === 0)
+        return [];
+    const board = requireHealthySettlementBoard(await readTaskBoard(taskRepositoryFromStore(await openTaskStore(cwd))));
+    return needIds.map((id) => {
+        const task = board.byId.get(id);
+        if (!task)
+            throw new FlowError("INTERNAL_STATE", `task prerequisite ${id} disappeared from the authoritative board`);
+        return { id, satisfied: task.state === "done" || task.state === "drop", state: task.state };
+    });
+}
 export function selectReadyTasksForBind(board, taskIds) {
     requireHealthySettlementBoard(board);
     const rootIds = taskIds.map((taskId) => resolveTaskReadId(board, taskId));

package/build/core/task/source-board.js

@@ -24,6 +24,7 @@ function taskDocument(parsed) {
         from: [...parsed.from],
         supersedes: [...parsed.supersedes],
         relatesTo: [...parsed.relatesTo],
+        notes: parsed.notes.map((note) => ({ ...note })),
         createdAt: parsed.createdAt,
         ...(parsed.updatedAt === undefined ? {} : { updatedAt: parsed.updatedAt }),
         creator: parsed.creator,

package/build/core/task/task-bind-preparation.js

@@ -1,4 +1,5 @@
 import { FlowError } from "../../flow-error.js";
+import { readCommitCoordinate } from "../../git/commits.js";
 import { runGitProcess } from "../../git/core.js";
 import { assertGitObservation, requireGitRepository } from "../../git/branches.js";
 import { inspectCurrentBranch, createTaskBoardCommit, publishForwardTaskBoardCommit, reconcileTaskPathsetIndex, refHead, taskSourcesAtCommit, taskWritesFromSources, } from "./settlement-git.js";
@@ -21,6 +22,7 @@ function linkedTaskDocument(task, contractId, at) {
         from: [...task.from],
         supersedes: [...task.supersedes],
         relatesTo: [...task.relatesTo],
+        notes: task.notes.map((note) => ({ ...note })),
         createdAt: task.createdAt,
         updatedAt: advancedTaskUpdatedAt(task, at),
         creator: task.creator,
@@ -32,11 +34,10 @@ function selectedEvidence(board, selected) {
     return selected.map((task) => ({
         taskId: task.coordinate,
         needs: task.needs.map((taskId) => {
-            const state = board.byId.get(taskId)?.state;
-            if (state !== "done" && state !== "drop") {
-                throw new FlowError("INTERNAL_STATE", `ready task ${task.coordinate} has unsatisfied need ${taskId}`);
-            }
-            return { taskId, state };
+            const need = board.byId.get(taskId);
+            if (!need)
+                throw new FlowError("INTERNAL_STATE", `selected task ${task.coordinate} has missing need ${taskId}`);
+            return { taskId, state: need.state, ...(need.contractId === undefined ? {} : { contractId: need.contractId }) };
         }),
     }));
 }
@@ -100,6 +101,52 @@ export async function withPreparedTaskBind(input, deps = {}) {
         return { preparation, result };
     }, { signal: input.signal });
 }
+/** Task-lock admission from bind's already-observed repository and board coordinates. */
+export async function withPreparedTaskBindSnapshot(input, deps = {}) {
+    return await withLockHeldTaskBoard(input.location.root, async (transaction) => {
+        const prepared = await prepareLockedTaskBindFromSnapshot(transaction, input, deps);
+        return { preparation: prepared, result: await input.transact(prepared, transaction) };
+    }, { signal: input.signal }, input.location);
+}
+async function prepareLockedTaskBindFromSnapshot(transaction, input, deps) {
+    if (transaction.location.mode !== "git")
+        throw new FlowError("NOT_GIT_REPO", "task bind requires Git task storage");
+    const observedBoard = await input.observeBoard();
+    const board = requireHealthySettlementBoard(taskBoardFromSourceBoard(buildTaskSourceBoard(transaction.sources)));
+    const selected = selectReadyTasksForBind(board, input.taskIds);
+    if (selected.length === 0)
+        throw new FlowError("INVALID_TARGET", "task bind requires at least one selected task");
+    const attempt = await input.prepare(selected);
+    const evidence = selectedEvidence(board, selected);
+    const linked = prepareTaskDocumentReplacements(transaction.sources, selected.map((task) => linkedTaskDocument(task, attempt.contractId, attempt.at)));
+    const linkedIds = new Set(selected.map((task) => task.coordinate));
+    const linkedSources = linked.sources.filter((source) => linkedIds.has(taskCoordinateFromSourcePath(source.path).coordinate));
+    const originalSources = transaction.sources.filter((source) => linkedIds.has(taskCoordinateFromSourcePath(source.path).coordinate));
+    const newHead = await (deps.createTaskBoardCommit ?? createTaskBoardCommit)({
+        cwd: transaction.location.root,
+        gitDir: transaction.location.gitDir,
+        root: transaction.location.root,
+        parent: observedBoard.head,
+        sources: linkedSources,
+        subject: selected.length === 1
+            ? `Bind task ${selected[0].coordinate} to contract ${attempt.contractId}`
+            : `Bind ${selected.length} tasks to contract ${attempt.contractId}`,
+    });
+    return {
+        boardRef: observedBoard.ref,
+        expectedHead: observedBoard.head,
+        newHead,
+        entryBase: newHead,
+        taskIds: selected.map((task) => task.coordinate),
+        selected: evidence,
+        taskBoard: { ref: observedBoard.ref, expectedHead: observedBoard.head, head: newHead },
+        replay: {
+            paths: selected.map((task) => `.keiyaku/tasks/${task.coordinate}.md`).sort(),
+            linkedSources,
+            originalSources,
+        },
+    };
+}
 /** Complete the prepared task projection while its authority transaction still owns the task lock. */
 export async function replayPreparedTaskBindLocked(transaction, prepared) {
     if (transaction.location.mode !== "git")
@@ -149,11 +196,14 @@ export async function replayCommittedTaskBindForfeit(cwd, commit, boardRef, task
     return await withLockHeldTaskBoard(cwd, async (transaction) => {
         if (transaction.location.mode !== "git")
             throw new FlowError("NOT_GIT_REPO", "task forfeit replay requires Git task storage");
-        const parentResult = await runGitProcess(transaction.location.root, ["rev-parse", "--verify", `${commit}^`]);
-        if (parentResult.status !== 0 || parentResult.error) {
-            throw new FlowError("INTERNAL_STATE", `committed task bind base ${commit} has no readable parent`, { cause: parentResult.error });
+        const coordinate = await readCommitCoordinate(transaction.location.root, commit);
+        if (coordinate.status !== "ok") {
+            throw new FlowError("INTERNAL_STATE", `committed task bind base ${commit} has no readable parent`, { cause: coordinate.status === "failed" ? coordinate.error : undefined });
+        }
+        const parent = coordinate.coordinate.parents[0];
+        if (!parent) {
+            throw new FlowError("INTERNAL_STATE", `committed task bind base ${commit} has no readable parent`);
         }
-        const parent = parentResult.stdout.trim();
         const paths = taskIds.map((taskId) => `.keiyaku/tasks/${taskId}.md`).sort();
         const originalSources = await taskSourcesAtCommit(transaction.location.root, transaction.location.root, parent, paths);
         if (!originalSources)

package/build/core/task/task-contract.js

@@ -5,7 +5,7 @@ import { prepareTaskDocumentReplacements, taskBoardFromSourceBoard, taskReposito
 import { buildTaskSourceBoard } from "./source-board.js";
 import { formatTaskCoordinate } from "./coordinate.js";
 import { createTaskBoardCommit, publishTaskMutationCommit, inspectCurrentBranch, publishForwardTaskBoardCommit, reconcileTaskPathsetIndex, refHead, taskContractAtCommit, taskSourcesAtCommit, taskWritesFromSources, trackedTaskPaths, updateBranch, } from "./settlement-git.js";
-import { contractPointerDocument, doneTaskReplacements, reopenedTaskDocument, requireHealthySettlementBoard, requireSettledTask, selectReadyTasksForBind, tasksForContract, } from "./settlement-policy.js";
+import { boundTaskDocument, contractPointerDocument, doneTaskReplacements, reopenedTaskDocument, requireHealthySettlementBoard, requireSettledTask, selectReadyTasksForBind, tasksForContract, } from "./settlement-policy.js";
 import { stableRepoRoot } from "../worktree-path.js";
 /**
  * Read the same healthy task board and run the same ready-task selector as bind
@@ -147,7 +147,7 @@ export async function settleTaskBoardForBind(input, deps = {}) {
         const prepared = taskBound ? await input.prepare(selectedTasks) : input;
         const contractId = prepared.contractId;
         if (taskBound && selectedTasks.length > 0) {
-            await replaceTaskDocuments(repository, selectedTasks.map((task) => contractPointerDocument(task, contractId, updatedAt)));
+            await replaceTaskDocuments(repository, selectedTasks.map((task) => boundTaskDocument(task, contractId, updatedAt)));
         }
         const taskIds = taskBound ? selectedTasks.map((t) => t.coordinate) : undefined;
         const selectedPaths = ownedTaskPaths(await repository.read(), taskIds);

package/build/core/task/task-git-store.js

@@ -337,6 +337,7 @@ export function openTaskStoreAt(board, deps = {}) {
                             gitDir: transaction.location.gitDir,
                             writes: plan.writes,
                             subject: subject,
+                            requireCommit: plan.requireCommit,
                             signal: deps.signal,
                         });
                     }

package/build/core/task/task-store-repository.js

@@ -15,6 +15,7 @@ export function taskBoardFromSourceBoard(sourceBoard) {
         from: [...task.from],
         supersedes: [...task.supersedes],
         relatesTo: [...task.relatesTo],
+        notes: task.notes.map((note) => ({ ...note })),
         createdAt: task.createdAt,
         ...(task.updatedAt === undefined ? {} : { updatedAt: task.updatedAt }),
         creator: task.creator,
@@ -75,6 +76,7 @@ function mutationPlan(sources, mutation) {
         writes: prepared.writes,
         value: mutation.select(prepared.board),
         ...(mutation.subject === undefined ? {} : { subject: mutation.subject }),
+        requireCommit: mutation.requireCommit ?? true,
     };
 }
 export function taskRepositoryFromStore(store) {

package/build/core/task/task.js

@@ -1,7 +1,7 @@
 export { deriveTaskDisplay, parseTaskFilter, parseTaskSort, selectTaskList } from "./query.js";
 export { advancedTaskUpdatedAt, taskUpdatedAt } from "./model.js";
-export { parseTaskDocument, serializeTaskDocument, } from "./document.js";
+export { parseTaskCreationDocument, parseTaskDocument, serializeTaskDocument, } from "./document.js";
 export { resolveTaskReadId, } from "./board.js";
 export { buildTaskBoard } from "./source-board.js";
 export { buildTaskTree } from "./tree.js";
-export { readTaskBoard, createTask, updateTask, updateTaskWithReceipt, startTask, stopTask, holdTask, resumeTask, doneTask, dropTask, selectSoleInProgress, rollbackOrphanTaskPointers, } from "./commands.js";
+export { readTaskBoard, createTask, updateTask, updateTaskWithReceipt, startTask, stopTask, holdTask, resumeTask, doneTask, dropTask, dropTaskWithNote, appendTaskNote, selectSoleInProgress, rollbackOrphanTaskPointers, } from "./commands.js";

package/build/core/transcripts.js

@@ -410,7 +410,7 @@ export async function locateResponseArtifact(input) {
         return carry(error);
     }
     if (!isResponseArtifactId(identity)) {
-        return carry(new FlowError("INVALID_RESPONSE_PATH", `${identity} is not a response artifact handle; revive expects an artifact id`));
+        return carry(new FlowError("INVALID_RESPONSE_PATH", `${identity} is not a response artifact handle; fork expects an artifact id`));
     }
     let physicalLocalRoot;
     try {
@@ -463,11 +463,11 @@ export async function locateResponseArtifact(input) {
 }
 export function requireResumableArtifact(artifact) {
     if (!artifact.session)
-        throw artifactError(artifact.artifactId, RESPONSE_HISTORY_SESSION_KEY, "is missing; this conversation cannot be revived");
+        throw artifactError(artifact.artifactId, RESPONSE_HISTORY_SESSION_KEY, "is missing; this conversation cannot be forked");
     if (!artifact.subagentName)
-        throw artifactError(artifact.artifactId, "subagent_name", "is missing; this conversation cannot be revived");
+        throw artifactError(artifact.artifactId, "subagent_name", "is missing; this conversation cannot be forked");
     if (!artifact.launchSnapshot)
-        throw artifactError(artifact.artifactId, RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY, "is missing; this conversation cannot be revived");
+        throw artifactError(artifact.artifactId, RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY, "is missing; this conversation cannot be forked");
     return artifact;
 }
 export async function nextReviewResponseNumber(cwd) {

package/build/core/verification-declaration.js

@@ -0,0 +1,95 @@
+import { FlowError } from "../flow-error.js";
+import { z } from "zod";
+export const VERIFICATION_EXECUTORS = ["bash", "zsh", "pwsh"];
+export const verificationDeclarationSchema = z.object({
+    executor: z.enum(VERIFICATION_EXECUTORS),
+    script: z.string().refine((value) => value.trim().length > 0, "expected a nonblank script"),
+}).strict();
+function example(heading) {
+    return `${heading}\n\`\`\`bash\n<verification script>\n\`\`\``;
+}
+function invalid(options, detail) {
+    throw new FlowError("INVALID_KEIYAKU_DRAFT", `${options.heading} ${detail}. Use a fenced executor script block:\n${example(options.heading)}`);
+}
+function isExecutor(value) {
+    return VERIFICATION_EXECUTORS.includes(value);
+}
+/**
+ * Parse the sole persisted contract Verification declaration grammar. Bodies
+ * are deliberately source-level so shell backticks and blank lines stay exact.
+ */
+export function parseVerificationDeclarations(source, options) {
+    const lines = source.split(/\r?\n/);
+    const declarations = [];
+    let sawNone = false;
+    for (let index = 0; index < lines.length;) {
+        const line = lines[index];
+        if (line.trim().length === 0) {
+            index += 1;
+            continue;
+        }
+        if (options.allowNone && line.trim() === "- (none)") {
+            if (declarations.length > 0 || sawNone) {
+                invalid(options, "the explicit '- (none)' replacement cannot be combined with Verification declarations");
+            }
+            sawNone = true;
+            index += 1;
+            continue;
+        }
+        const opening = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+        if (!opening)
+            invalid(options, "must contain only direct fenced script blocks");
+        const fence = opening[1];
+        const delimiter = fence[0];
+        const executor = opening[2].trim();
+        if (!executor)
+            invalid(options, "fenced script blocks require an executor header (bash, zsh, or pwsh)");
+        if (!isExecutor(executor))
+            invalid(options, `does not support the '${executor}' executor`);
+        const body = [];
+        index += 1;
+        let closed = false;
+        while (index < lines.length) {
+            const candidate = lines[index];
+            const close = candidate.match(/^ {0,3}(`+|~+)[ \t]*$/);
+            if (close && close[1][0] === delimiter && close[1].length >= fence.length) {
+                closed = true;
+                index += 1;
+                break;
+            }
+            body.push(candidate);
+            index += 1;
+        }
+        if (!closed)
+            invalid(options, "contains an unclosed fenced script block");
+        const script = body.join("\n");
+        if (script.trim().length === 0)
+            invalid(options, "contains an empty fenced script block");
+        if (sawNone) {
+            invalid(options, "the explicit '- (none)' replacement cannot be combined with Verification declarations");
+        }
+        declarations.push({ executor, script });
+    }
+    if (sawNone)
+        return [];
+    if (declarations.length === 0)
+        invalid(options, "must contain at least one fenced script block");
+    return declarations;
+}
+function fenceFor(executor, script) {
+    const candidateLengths = ["`", "~"].map((delimiter) => {
+        const largestRun = script.split("\n").reduce((largest, line) => {
+            const match = line.match(new RegExp(`^ {0,3}\\${delimiter}+`));
+            return Math.max(largest, match?.[0].trim().length ?? 0);
+        }, 0);
+        return { delimiter, length: Math.max(3, largestRun + 1) };
+    });
+    const selected = candidateLengths.sort((left, right) => left.length - right.length)[0];
+    return selected.delimiter.repeat(selected.length);
+}
+export function renderVerificationDeclarations(declarations) {
+    return declarations.map((declaration) => {
+        const fence = fenceFor(declaration.executor, declaration.script);
+        return `${fence}${declaration.executor}\n${declaration.script}\n${fence}`;
+    }).join("\n\n");
+}

package/build/core/worktree-bootstrap.js

@@ -1,5 +1,5 @@
 import { spawn as nodeSpawn } from "node:child_process";
-import { terminateProcessGroup } from "./process-group.js";
+import { terminateProcessGroup } from "./run-control/process-tree.js";
 export const WORKTREE_BOOTSTRAP_OUTPUT_TAIL_BYTES = 2048;
 export const WORKTREE_BOOTSTRAP_KILL_GRACE_MS = 10_000;
 function defaultWait(ms) {

package/build/core/worktree-path.js

@@ -101,23 +101,19 @@ export function worktreeContainsCoordinate(root, candidate) {
 }
 export async function stableRepoRoot(cwd) {
     const git = createGit(cwd);
-    let bare;
+    let facts;
     try {
-        bare = (await git.raw(["rev-parse", "--is-bare-repository"])).trim();
+        facts = (await git.raw(["rev-parse", "--is-bare-repository", "--path-format=absolute", "--git-common-dir"])).trim().split("\n");
     }
     catch (error) {
-        throw wrapGitError("rev-parse --is-bare-repository", error, cwd);
+        throw wrapGitError("rev-parse repository coordinate", error, cwd);
     }
+    const [bare, commonDir] = facts;
     if (bare === "true") {
         throw new FlowError("INTERNAL_STATE", "Keiyaku worktree operations require a non-bare repository");
     }
-    let commonDir;
-    try {
-        commonDir = (await git.raw(["rev-parse", "--path-format=absolute", "--git-common-dir"])).trim();
-    }
-    catch (error) {
-        throw wrapGitError("rev-parse --path-format=absolute --git-common-dir", error, cwd);
-    }
+    if (!commonDir)
+        throw new FlowError("INTERNAL_STATE", "Git did not report its common directory");
     const stableRoot = gitCommonRootPath(commonDir);
     if (!path.isAbsolute(stableRoot)) {
         throw new FlowError("INTERNAL_STATE", `git common directory is not absolute: ${commonDir}`);
@@ -132,7 +128,7 @@ export async function stableRepoRoot(cwd) {
 export async function contractWorktreePathFromBind(cwd, contractId, bind) {
     return contractWorktreePathFromStableRoot(await stableRepoRoot(cwd), contractId, bind);
 }
-function contractWorktreePathFromStableRoot(stableRoot, contractId, bind) {
+export function contractWorktreePathFromStableRoot(stableRoot, contractId, bind) {
     return path.join(stableRoot, ".keiyaku", "wt", bind?.data.place ?? contractId);
 }
 export async function contractWorktreePath(cwd, contractId) {

package/build/flow-error.js

@@ -55,6 +55,12 @@ export function resolveFlowErrorHints(code, context, facts) {
     if (facts?.kind === "projection_wake_failure") {
         return [];
     }
+    if (facts?.kind === "task_contract_workspace") {
+        return ["Select an active contract with a materialized workspace, or retry from the desired checkout with -C."];
+    }
+    if (facts?.kind === "carrier_dispatch_refusal") {
+        return [facts.recoveryCommand];
+    }
     switch (code) {
         case "NOT_GIT_REPO":
             return ["The provided `cwd` is not a git repository."];
@@ -64,10 +70,17 @@ export function resolveFlowErrorHints(code, context, facts) {
             return [`Next: open an arc with \`${context.arcToolName}\`, then use \`${context.renewToolName}\` when delivery must follow the current base, or \`${context.closeToolName}\` to settle it.`];
         case "CONTRACT_AMBIGUOUS":
             return ["Address a specific contract workspace, or use `call --bare` to run without contract attachment."];
+        case "CONTRACT_WORKSPACE_UNAVAILABLE":
+            return [];
         case "TASK_AMBIGUOUS":
             return ["Pass one complete task coordinate from the listed candidates."];
         case "UNKNOWN_COMMAND":
             return ["Run `keiyaku --help` to inspect available commands."];
+        case "UNKNOWN_OPTION":
+        case "UNKNOWN_ADDRESS":
+        case "INVALID_USAGE":
+        case "STDIN_EMPTY":
+            return [];
         case "EMPTY_PARAM":
             return ["One or more required parameters are empty."];
         case "DIRTY_WORKTREE":
@@ -95,7 +108,7 @@ export function resolveFlowErrorHints(code, context, facts) {
         case "FROM_DRAFT_NOT_FOUND":
             return ["The path in `from_draft` does not exist. `from_draft` must reference an existing file path (absolute or relative to `cwd`)."];
         case "INVALID_KEIYAKU_DRAFT":
-            return ["Invalid draft/input. Use a `# <title>` heading with non-empty `## Context`, `## Objective`, `## Design`, `## Scope`, `## Criteria`, and `## Verification` sections (or the equivalent shape in `from_draft`)."];
+            return ["Invalid draft/input. Use a `# <title>` heading with non-empty `## Context`, `## Objective`, `## Design & Approach`, `## Scope`, `## Criteria`, and `## Verification` sections (or the equivalent shape in `from_draft`)."];
         case "BIND_TASK_INCOMPLETE":
             return ["Task supplies title/objective defaults; pipe only the missing sections as partial contract Markdown on stdin."];
         case "KEIYAKU_FILE_EXISTS":
@@ -103,7 +116,7 @@ export function resolveFlowErrorHints(code, context, facts) {
         case "DETACHED_HEAD":
             return ["Repository is in detached HEAD state. Address an active contract workspace before retrying."];
         case "INVALID_RESPONSE_PATH":
-            return ["`keiyaku revive ARTIFACT_ID` needs a valid previous Keiyaku response artifact that includes complete provenance plus `session` and `subagent_name`."];
+            return ["`keiyaku fork ARTIFACT_ID` needs a valid previous Keiyaku response artifact that includes complete provenance plus `session` and `subagent_name`."];
         case "INVALID_CLOSE_INTENT":
             return ["Invalid close intent. Valid values are `CLAIM` and `FORFEIT`."];
         case "INVALID_SETTINGS":

package/build/generated/version.js

@@ -1,3 +1,3 @@
 // Generated into build output by scripts/build.mjs
-export const VERSION = "2.9.11";
-export const GIT_HASH = "4384d75";
+export const VERSION = "2.9.13";
+export const GIT_HASH = "0971934";