@astrosheep/keiyaku 2.9.12 → 2.9.13

package/build/core/task/document.js

@@ -10,6 +10,7 @@ const FIELD_ORDER = [
     "from",
     "supersedes",
     "relatesTo",
+    "notes",
     "createdAt",
     "updatedAt",
     "creator",
@@ -17,6 +18,9 @@ const FIELD_ORDER = [
     "contractId",
 ];
 const FIELD_SET = new Set(FIELD_ORDER);
+const CREATION_INPUT_FIELDS = new Set([
+    "title", "pri", "needs", "parent", "from", "supersedes", "relatesTo",
+]);
 function validateNode(node) {
     if (node == null)
         return;
@@ -60,7 +64,7 @@ function frontMatter(source) {
         body: lines.slice(closing + 1).join("\n"),
     };
 }
-export function parseTaskDocument(source) {
+function parseTaskSource(source) {
     const split = frontMatter(source);
     const parsed = parseDocument(split.yaml, {
         merge: false,
@@ -83,6 +87,10 @@ export function parseTaskDocument(source) {
         if (!FIELD_SET.has(key))
             invalid(`unknown task front matter key '${key}'`);
         const value = item.value;
+        if (key === "notes") {
+            values.set(key, noteArray(value));
+            continue;
+        }
         if (isSeq(value)) {
             const items = value.items.map((entry) => {
                 if (!isScalar(entry) || typeof entry.value !== "string") {
@@ -102,6 +110,68 @@ export function parseTaskDocument(source) {
             invalid(`task field '${key}' must be a scalar or string array`);
         }
     }
+    return { values, body: split.body };
+}
+function noteArray(value) {
+    if (!isSeq(value))
+        invalid("task field 'notes' must be an array of note objects");
+    return value.items.map((item) => {
+        if (!isMap(item))
+            invalid("task field 'notes' must contain only note objects");
+        const values = new Map();
+        for (const pair of item.items) {
+            if (!isScalar(pair.key) || typeof pair.key.value !== "string") {
+                invalid("task note fields must be strings");
+            }
+            const key = pair.key.value;
+            if (key !== "actor" && key !== "timestamp" && key !== "text") {
+                invalid(`unknown task note field '${key}'`);
+            }
+            if (!isScalar(pair.value))
+                invalid(`task note field '${key}' must be a string`);
+            values.set(key, pair.value.value);
+        }
+        return {
+            actor: nonblank("task note actor", values.get("actor")),
+            timestamp: canonicalTimestamp("task note timestamp", values.get("timestamp")),
+            text: nonblank("task note text", values.get("text")),
+        };
+    });
+}
+function taskNotes(values) {
+    const value = values.get("notes");
+    return value === undefined ? [] : value;
+}
+function stringArray(values, field, required) {
+    const value = values.get(field);
+    if (value === undefined && !required)
+        return [];
+    if (!Array.isArray(value))
+        invalid(`task field '${field}' must be a string array`);
+    const related = value.map((item) => fullId(field, item));
+    if (new Set(related).size !== related.length)
+        invalid(`task field '${field}' must be unique`);
+    return related;
+}
+function priority(values, required) {
+    const value = values.get("pri");
+    if (value === undefined && !required)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 3) {
+        invalid("task field 'pri' must be an integer from 0 through 3");
+    }
+    return value;
+}
+function parent(values, required) {
+    const value = values.get("parent");
+    if (value === undefined && !required)
+        return null;
+    if (value === null)
+        return null;
+    return fullId("parent", value);
+}
+export function parseTaskDocument(source) {
+    const { values, body } = parseTaskSource(source);
     const id = nonblank("id", values.get("id"));
     if (!isTaskId(id))
         invalid("task field 'id' must be a canonical local task id");
@@ -110,42 +180,13 @@ export function parseTaskDocument(source) {
     if (typeof state !== "string" || !TASK_STATES.has(state)) {
         invalid("task field 'state' must be open, in_progress, on_hold, done, or drop");
     }
-    const pri = values.get("pri");
-    if (typeof pri !== "number" || !Number.isInteger(pri) || pri < 0 || pri > 3) {
-        invalid("task field 'pri' must be an integer from 0 through 3");
-    }
-    const needsValue = values.get("needs");
-    if (!Array.isArray(needsValue))
-        invalid("task field 'needs' must be a string array");
-    const needs = needsValue.map((need) => fullId("needs", need));
-    if (new Set(needs).size !== needs.length)
-        invalid("task field 'needs' must be unique");
-    const relationship = (field) => {
-        const value = values.get(field);
-        if (value === null)
-            return null;
-        return fullId(field, value);
-    };
-    const parent = relationship("parent");
-    const fromValue = values.get("from");
-    if (!Array.isArray(fromValue))
-        invalid("task field 'from' must be a string array");
-    const from = fromValue.map((related) => fullId("from", related));
-    if (new Set(from).size !== from.length)
-        invalid("task field 'from' must be unique");
-    const relationships = (field) => {
-        const value = values.get(field);
-        if (value === undefined)
-            return [];
-        if (!Array.isArray(value))
-            invalid(`task field '${field}' must be a string array`);
-        const related = value.map((item) => fullId(field, item));
-        if (new Set(related).size !== related.length)
-            invalid(`task field '${field}' must be unique`);
-        return related;
-    };
-    const supersedes = relationships("supersedes");
-    const relatesTo = relationships("relatesTo");
+    const pri = priority(values, true);
+    const needs = stringArray(values, "needs", true);
+    const taskParent = parent(values, true);
+    const from = stringArray(values, "from", true);
+    const supersedes = stringArray(values, "supersedes", false);
+    const relatesTo = stringArray(values, "relatesTo", false);
+    const notes = taskNotes(values);
     const createdAt = canonicalTimestamp("createdAt", values.get("createdAt"));
     const updatedValue = values.get("updatedAt");
     const updatedAt = updatedValue === undefined ? undefined : canonicalTimestamp("updatedAt", updatedValue);
@@ -166,19 +207,40 @@ export function parseTaskDocument(source) {
         state: state,
         pri,
         needs,
-        parent,
+        parent: taskParent,
         from,
         supersedes,
         relatesTo,
+        notes,
         createdAt,
         ...(updatedAt === undefined ? {} : { updatedAt }),
         creator,
         ...(startedAt === undefined ? {} : { startedAt }),
         ...(contractId === undefined ? {} : { contractId }),
-        body: split.body,
+        body,
         source,
     };
 }
+/** Parse the caller-owned subset of the canonical task document grammar. */
+export function parseTaskCreationDocument(source) {
+    const { values, body } = parseTaskSource(source);
+    for (const field of values.keys()) {
+        if (!CREATION_INPUT_FIELDS.has(field)) {
+            invalid(`task creation document field '${field}' is creation-owned and cannot be supplied`);
+        }
+    }
+    const pri = priority(values, false);
+    return {
+        title: nonblank("title", values.get("title")),
+        body,
+        ...(pri === undefined ? {} : { pri }),
+        needs: stringArray(values, "needs", false),
+        parent: parent(values, false),
+        from: stringArray(values, "from", false),
+        supersedes: stringArray(values, "supersedes", false),
+        relatesTo: stringArray(values, "relatesTo", false),
+    };
+}
 function validateDocument(document) {
     return parseTaskDocument({ path: `${document.id}.md`, text: serializeUnchecked(document) });
 }
@@ -193,6 +255,7 @@ function serializeUnchecked(document) {
         from: document.from,
         ...(document.supersedes.length === 0 ? {} : { supersedes: document.supersedes }),
         ...(document.relatesTo.length === 0 ? {} : { relatesTo: document.relatesTo }),
+        ...(document.notes.length === 0 ? {} : { notes: document.notes.map((note) => ({ ...note })) }),
         createdAt: document.createdAt,
         ...(document.updatedAt === undefined ? {} : { updatedAt: document.updatedAt }),
         creator: document.creator,

package/build/core/task/index.js

@@ -4,7 +4,7 @@
  * Package-internal modules must import each other directly, not through this file.
  */
 export { previewTaskBoardForBind, reconcileTaskForfeit, replayClaimTasks, } from "./task-contract.js";
-export { replayPreparedTaskBind, replayPreparedTaskBindLocked, replayCommittedTaskBind, replayCommittedTaskBindForfeit, replayPreparedTaskBindForfeit, withPreparedTaskBind, } from "./task-bind-preparation.js";
+export { replayPreparedTaskBind, replayPreparedTaskBindLocked, replayCommittedTaskBind, replayCommittedTaskBindForfeit, replayPreparedTaskBindForfeit, withPreparedTaskBind, withPreparedTaskBindSnapshot, } from "./task-bind-preparation.js";
 export { readTaskBoardGeneration } from "./task-git-store.js";
 export { resolveTaskCreator } from "./task-git-actor.js";
 export { openTaskCommandRepository, openTaskMutationContext, readTaskDoctor, taskCommandContractId, taskCommandNamespace, } from "./task-git-runtime.js";
@@ -12,5 +12,5 @@ export { openTaskStore, readTaskHistory, readTaskNamespaces } from "./task-git-s
 export { taskRepositoryFromStore } from "./task-store-repository.js";
 export { composeTasks, planTaskComposition, parseTaskCompositionSketch, } from "./compose.js";
 export { isTaskId } from "./validation.js";
-export { isTaskCoordinate, parseTaskCoordinate, taskCoordinateFromSourcePath } from "./coordinate.js";
-export { buildTaskTree, createTask, doneTask, dropTask, parseTaskDocument, readTaskBoard, resolveTaskReadId, serializeTaskDocument, startTask, stopTask, holdTask, resumeTask, updateTask, updateTaskWithReceipt, deriveTaskDisplay, selectTaskList, taskUpdatedAt, advancedTaskUpdatedAt, } from "./task.js";
+export { isTaskCoordinate, parseTaskCoordinate, taskCoordinateFromSourcePath, taskNamespaceFromScope } from "./coordinate.js";
+export { buildTaskTree, createTask, doneTask, dropTask, dropTaskWithNote, appendTaskNote, parseTaskCreationDocument, parseTaskDocument, readTaskBoard, resolveTaskReadId, serializeTaskDocument, startTask, stopTask, holdTask, resumeTask, updateTask, updateTaskWithReceipt, deriveTaskDisplay, selectTaskList, taskUpdatedAt, advancedTaskUpdatedAt, } from "./task.js";

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

@@ -278,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-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,

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) {