@astrosheep/keiyaku 2.9.3 → 2.9.5

package/build/core/{task-git-store.js → task/task-git-store.js}

@@ -1,16 +1,21 @@
 import { randomBytes } from "node:crypto";
-import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DatabaseSync } from "node:sqlite";
-import { FlowError } from "../flow-error.js";
-import { syncDirectorySync } from "../fs/durability.js";
-import { isGitExecutableUnavailable, NOT_GIT_REPOSITORY_PATTERNS } from "../git/core.js";
-import { gitCommonRootPath, normalizeGitPath } from "./path-coordinate.js";
-const TASK_ID = /^k-[0-9a-f]{12}$/;
+import { setTimeout as delay } from "node:timers/promises";
+import { FlowError } from "../../flow-error.js";
+import { syncDirectorySync } from "../../fs/durability.js";
+import { normalizeFilesystemCoordinate } from "../../fs/path-coordinate.js";
+import { isGitExecutableUnavailable, NOT_GIT_REPOSITORY_PATTERNS, runGitProcess } from "../../git/core.js";
+import { gitCommonRootPath, normalizeGitPath } from "../../git/path-coordinate.js";
+import { inspectCurrentBranch, publishTaskMutationCommit } from "./settlement-git.js";
+import { isTaskId } from "./validation.js";
 const SQLITE_BUSY = 5;
 const LOCK_FILE = "task-lock.sqlite";
 const GIT_LOCK_FILE = "keiyaku-task-lock.sqlite";
+export const TASK_LOCK_ADMISSION_TIMEOUT_MS = 4_000;
+export const TASK_LOCK_ADMISSION_INITIAL_DELAY_MS = 10;
+export const TASK_LOCK_ADMISSION_MAX_DELAY_MS = 100;
 export class TaskLockHeldError extends Error {
     path;
     code = "TASK_LOCK_HELD";
@@ -20,6 +25,16 @@ export class TaskLockHeldError extends Error {
         this.name = "TaskLockHeldError";
     }
 }
+export class TaskLockAdmissionTimeoutError extends FlowError {
+    path;
+    timeoutMs;
+    constructor(path, timeoutMs, options) {
+        super("TASK_LOCK_ADMISSION_TIMEOUT", `task lock admission timed out after ${timeoutMs}ms: ${path}`, { cause: options?.cause });
+        this.path = path;
+        this.timeoutMs = timeoutMs;
+        this.name = "TaskLockAdmissionTimeoutError";
+    }
+}
 function errorText(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -29,17 +44,11 @@ function isSqliteBusy(error) {
         && "errcode" in error
         && error.errcode === SQLITE_BUSY;
 }
-function defaultRunGit(cwd, args, input) {
-    return spawnSync("git", [...args], {
-        cwd,
-        input,
-        encoding: "utf8",
-        env: { ...process.env, GIT_TERMINAL_PROMPT: "0", LC_ALL: "C" },
-        stdio: ["pipe", "pipe", "pipe"],
-    });
+async function defaultRunGit(cwd, args, input) {
+    return await runGitProcess(cwd, args, { input });
 }
 function nearestDirectoryBoard(cwd) {
-    const original = path.resolve(cwd);
+    const original = path.resolve(normalizeFilesystemCoordinate(cwd));
     let candidate = original;
     while (true) {
         if (lstatIfPresent(path.join(candidate, ".keiyaku")))
@@ -54,7 +63,8 @@ export function taskBoardRootFromGitDir(rawGitDir, platform = process.platform)
     return gitCommonRootPath(rawGitDir, platform);
 }
 export async function locateTaskBoard(cwd, runGitProbe = defaultRunGit) {
-    const probe = runGitProbe(cwd, ["rev-parse", "--is-inside-work-tree", "--is-bare-repository"]);
+    cwd = normalizeFilesystemCoordinate(cwd);
+    const probe = await runGitProbe(cwd, ["rev-parse", "--is-inside-work-tree", "--is-bare-repository"]);
     if (probe.error && !isGitExecutableUnavailable(probe.error)) {
         throw new FlowError("INTERNAL_STATE", `cannot inspect task repository: ${probe.error.message}`, { cause: probe.error });
     }
@@ -72,7 +82,7 @@ export async function locateTaskBoard(cwd, runGitProbe = defaultRunGit) {
     if (bare === "true" || insideWorktree !== "true") {
         throw new FlowError("NOT_GIT_REPO", "bare repositories are not supported for task storage");
     }
-    const facts = runGitProbe(cwd, ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"]);
+    const facts = await runGitProbe(cwd, ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"]);
     if (facts.error) {
         throw new FlowError("INTERNAL_STATE", `git rev-parse failed: ${facts.error.message}`, { cause: facts.error });
     }
@@ -139,6 +149,31 @@ function acquireTaskLock(lockPath) {
         throw new FlowError("INTERNAL_STATE", `cannot acquire task lock: ${errorText(error)}`, { cause: error });
     }
 }
+async function acquireTaskLockWithAdmission(lockPath, deps) {
+    const now = deps.now ?? Date.now;
+    const random = deps.random ?? Math.random;
+    const sleep = deps.sleep ?? ((milliseconds, signal) => (delay(milliseconds, undefined, signal ? { signal } : undefined)));
+    const deadline = now() + TASK_LOCK_ADMISSION_TIMEOUT_MS;
+    let delayCapMs = TASK_LOCK_ADMISSION_INITIAL_DELAY_MS;
+    for (;;) {
+        deps.signal?.throwIfAborted();
+        try {
+            return acquireTaskLock(lockPath);
+        }
+        catch (error) {
+            if (!(error instanceof TaskLockHeldError))
+                throw error;
+            const observedAt = now();
+            if (observedAt >= deadline) {
+                throw new TaskLockAdmissionTimeoutError(lockPath, TASK_LOCK_ADMISSION_TIMEOUT_MS, { cause: error });
+            }
+            const unit = Math.max(0, Math.min(1, random()));
+            const jitteredDelayMs = Math.ceil((delayCapMs / 2) + ((delayCapMs / 2) * unit));
+            await sleep(Math.min(jitteredDelayMs, deadline - observedAt), deps.signal);
+            delayCapMs = Math.min(TASK_LOCK_ADMISSION_MAX_DELAY_MS, delayCapMs * 2);
+        }
+    }
+}
 export async function inspectTaskLock(cwd) {
     const lockPath = taskLockPath(await locateTaskBoard(cwd));
     if (!fs.existsSync(lockPath))
@@ -236,7 +271,7 @@ function validateWrites(writes) {
     const targets = new Set();
     for (const write of writes) {
         const target = `${write.id}.md`;
-        if (!TASK_ID.test(write.id)) {
+        if (!isTaskId(write.id)) {
             throw new FlowError("INTERNAL_STATE", `invalid task mutation id: ${write.id}`);
         }
         if (targets.has(target))
@@ -321,9 +356,32 @@ export async function openTaskStore(cwd, deps = {}) {
         },
         async mutate(apply) {
             return withLockHeldTaskBoard(cwd, async (transaction) => {
+                const previousSources = transaction.sources;
                 const plan = await apply(transaction.sources);
                 validatePlan(plan);
+                let subject;
+                if (transaction.location.mode === "git") {
+                    subject = plan.subject?.trim();
+                    if (!subject) {
+                        throw new FlowError("INTERNAL_STATE", "git task mutation requires a micro-commit subject");
+                    }
+                    await inspectCurrentBranch(transaction.location.root);
+                }
                 await transaction.replace(plan.writes);
+                if (transaction.location.mode === "git") {
+                    try {
+                        await (deps.publishMutation ?? publishTaskMutationCommit)({
+                            cwd: transaction.location.root,
+                            gitDir: transaction.location.gitDir,
+                            writes: plan.writes,
+                            subject: subject,
+                        });
+                    }
+                    catch (error) {
+                        await transaction.restore(plan.writes, previousSources);
+                        throw error;
+                    }
+                }
                 return plan.value;
             }, deps, board);
         },
@@ -333,7 +391,7 @@ export async function withLockHeldTaskBoard(cwd, apply, deps = {}, locatedBoard)
     const board = locatedBoard ?? await locateTaskBoard(cwd, deps.runGit);
     const directory = taskDirectory(board);
     assertKeiyakuDirectory(board);
-    const database = acquireTaskLock(taskLockPath(board));
+    const database = await acquireTaskLockWithAdmission(taskLockPath(board), deps);
     try {
         let sources = await readTaskSources(directory);
         const transaction = {
@@ -368,6 +426,19 @@ export async function withLockHeldTaskBoard(cwd, apply, deps = {}, locatedBoard)
                 }
                 sources = await readTaskSources(directory);
             },
+            async restore(writes, previousSources) {
+                validateWrites(writes);
+                const currentSources = await readTaskSources(directory);
+                if (!sameSources(sources, currentSources)) {
+                    throw new FlowError("CONCURRENT_MODIFICATION", "task sources changed while rolling back a failed publication");
+                }
+                const previousById = new Map(previousSources.map((source) => [path.basename(source.path, ".md"), source.text]));
+                restoreFiles(writes.map((write) => ({
+                    path: path.join(directory, mutationTarget(write)),
+                    text: previousById.get(write.id),
+                })), deps);
+                sources = await readTaskSources(directory);
+            },
         };
         return await apply(transaction);
     }

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

@@ -0,0 +1 @@
+export {};

package/build/core/{task-store-repository.js → task/task-store-repository.js}

@@ -1,7 +1,7 @@
-import { requireHealthy } from "./task/board.js";
-import { parseTaskDocument, serializeTaskDocument } from "./task/document.js";
-import { buildTaskSourceBoard } from "./task/source-board.js";
-function taskBoardFromSourceBoard(sourceBoard) {
+import { requireHealthy } from "./board.js";
+import { parseTaskDocument, serializeTaskDocument } from "./document.js";
+import { buildTaskSourceBoard } from "./source-board.js";
+export function taskBoardFromSourceBoard(sourceBoard) {
     const tasks = sourceBoard.tasks.map((task) => ({
         id: task.id,
         title: task.title,
@@ -11,6 +11,7 @@ function taskBoardFromSourceBoard(sourceBoard) {
         parent: task.parent,
         from: [...task.from],
         createdAt: task.createdAt,
+        ...(task.updatedAt === undefined ? {} : { updatedAt: task.updatedAt }),
         creator: task.creator,
         ...(task.startedAt === undefined ? {} : { startedAt: task.startedAt }),
         ...(task.contractId === undefined ? {} : { contractId: task.contractId }),
@@ -66,6 +67,7 @@ function mutationPlan(sources, mutation) {
     return {
         writes: prepared.writes,
         value: mutation.select(prepared.board),
+        ...(mutation.subject === undefined ? {} : { subject: mutation.subject }),
     };
 }
 export function taskRepositoryFromStore(store) {

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

@@ -0,0 +1 @@
+export {};

package/build/core/{task-worktree.js → task/task-worktree.js}

@@ -1,4 +1,4 @@
-import { FlowError } from "../flow-error.js";
+import { FlowError } from "../../flow-error.js";
 function documentFacts(task) {
     return JSON.stringify({
         id: task.id,
@@ -41,6 +41,7 @@ export function withTaskWorktreePolicy(repository, contractId) {
             const mutation = await apply(before);
             return {
                 replacements: mutation.replacements,
+                ...(mutation.subject === undefined ? {} : { subject: mutation.subject }),
                 select(after) {
                     validateTaskWorktreeMutation(before, mutation.replacements, after, contractId);
                     return mutation.select(after);

package/build/core/task/task.js

@@ -0,0 +1,7 @@
+export { deriveTaskDisplay, parseTaskFilter, parseTaskSort, selectTaskList } from "./query.js";
+export { advancedTaskUpdatedAt, taskUpdatedAt } from "./model.js";
+export { 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, startTask, stopTask, doneTask, dropTask, selectSoleInProgress, rollbackOrphanTaskPointers, } from "./commands.js";

package/build/core/task/tree.js

@@ -0,0 +1,37 @@
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** Board task order is the deterministic order for every parent child list. */
+function compareBoardOrder(left, right) {
+    const leftTerminal = left.state === "done" || left.state === "drop" ? 1 : 0;
+    const rightTerminal = right.state === "done" || right.state === "drop" ? 1 : 0;
+    return leftTerminal - rightTerminal
+        || left.pri - right.pri
+        || compareText(left.createdAt, right.createdAt)
+        || compareText(left.id, right.id);
+}
+function diagnosticOrder(left, right) {
+    return compareText(left.code, right.code)
+        || compareText(left.id ?? "", right.id ?? "")
+        || compareText(left.message, right.message);
+}
+export function buildTaskTree(board, rootId) {
+    const childrenByParent = new Map();
+    for (const task of board.tasks) {
+        if (task.parent === null)
+            continue;
+        childrenByParent.set(task.parent, [...(childrenByParent.get(task.parent) ?? []), task]);
+    }
+    for (const children of childrenByParent.values())
+        children.sort(compareBoardOrder);
+    const visit = (parentId, ancestors) => (childrenByParent.get(parentId) ?? [])
+        .filter((child) => !ancestors.has(child.id))
+        .map((child) => ({
+        task: child,
+        children: visit(child.id, new Set([...ancestors, child.id])),
+    }));
+    return {
+        descendants: visit(rootId, new Set([rootId])),
+        diagnostics: [...board.diseases].sort(diagnosticOrder),
+    };
+}

package/build/core/task/validation.js

@@ -1,5 +1,5 @@
 import { FlowError } from "../../flow-error.js";
-export const TASK_ID = /^k-[0-9a-f]{12}$/;
+import { isNormalizedIdentifierSlug } from "../identifier-slug.js";
 export const TASK_STATES = new Set(["open", "in_progress", "done", "drop"]);
 const CANONICAL_ISO_UTC_MS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
 export function invalid(message) {
@@ -13,10 +13,13 @@ export function nonblank(field, value) {
 }
 export function fullId(field, value) {
     const id = nonblank(field, value);
-    if (!TASK_ID.test(id))
+    if (!isTaskId(id))
         invalid(`task field '${field}' must be a canonical full task id`);
     return id;
 }
+export function isTaskId(value) {
+    return isNormalizedIdentifierSlug(value);
+}
 export function canonicalTimestamp(field, value) {
     const timestamp = nonblank(field, value);
     if (!CANONICAL_ISO_UTC_MS.test(timestamp)) {

package/build/core/transcripts.js

@@ -21,6 +21,15 @@ const RESPONSE_HISTORY_SESSION_KEY = "session";
 const RESPONSE_HISTORY_LAUNCH_SNAPSHOT_KEY = "launch_snapshot";
 const RESPONSE_HISTORY_PROVENANCE_KEY = "provenance";
 const REVIEW_HISTORY_FILE_RE = /^\d{8}-\d{9}_REVIEW_(\d+)\.md$/;
+/** Artifact-owner rendering of seal receipt/diffstat facts into the durable Diff section. */
+export function renderSealDiffSection(sealed, emptyLabel) {
+    if (!sealed)
+        return emptyLabel;
+    if (sealed.receipts.length === 0)
+        return "nothing sealed";
+    const count = sealed.receipts.length;
+    return `${count} receipt${count === 1 ? "" : "s"} · +${sealed.diffstat.insertions} −${sealed.diffstat.deletions}`;
+}
 export const RESPONSE_ARTIFACT_HEADINGS = {
     call: "# Call",
     bind: "# Bind",
@@ -100,9 +109,12 @@ function buildMarkdown(input, iso, provenance) {
         return [...frontmatter, "# Call", "", "## Task", section(input.task), "", "## Context", section(input.context), "", "## Response", section(input.response), ""].join("\n");
     if (input.tool === "review")
         return [...frontmatter, "# Review", "", "## Prompt", section(input.prompt), "", "## Response", section(input.response), ""].join("\n");
-    if (input.tool === "arc")
-        return [...frontmatter, "# Arc", "", "## Objective", section(input.objective), "", "## Brief", section(input.brief), "", "## Ledger Commit", section(input.ledgerCommit), "", "## Summary", section(input.summary), "", "## Diff", section(input.diff), ""].join("\n");
-    return [...frontmatter, "# Renew", "", "## Base", `${input.oldBase} -> ${input.newBase}`, "", "## Head", `${input.oldHead} -> ${input.newHead}`, "", "## Ledger Commit", section(input.ledgerCommit), "", "## Summary", section(input.summary), "", "## Diff", section(input.diff), ""].join("\n");
+    if (input.tool === "arc") {
+        const diff = renderSealDiffSection(input.sealed, input.emptyDiffLabel);
+        return [...frontmatter, "# Arc", "", "## Objective", section(input.objective), "", "## Brief", section(input.brief), "", "## Ledger Commit", section(input.ledgerCommit), "", "## Summary", section(input.summary), "", "## Diff", section(diff), ""].join("\n");
+    }
+    const diff = renderSealDiffSection(input.sealed, input.emptyDiffLabel);
+    return [...frontmatter, "# Renew", "", "## Base", `${input.oldBase} -> ${input.newBase}`, "", "## Head", `${input.oldHead} -> ${input.newHead}`, "", "## Ledger Commit", section(input.ledgerCommit), "", "## Summary", section(input.summary), "", "## Diff", section(diff), ""].join("\n");
 }
 /** The sole response artifact writer. */
 export async function persistResponseHistory(input) {

package/build/core/worktree-path.js

@@ -3,9 +3,9 @@ import * as fs from "node:fs/promises";
 import { FlowError } from "../flow-error.js";
 import { createGit, wrapGitError } from "../git/core.js";
 import { readLedger } from "./ledger.js";
-import { listContractIds } from "./ledger.js";
 import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
-import { gitCommonRootPath, resolveGitCommonRoot } from "./path-coordinate.js";
+import { normalizeFilesystemCoordinate } from "../fs/path-coordinate.js";
+import { gitCommonRootPath, resolveGitCommonRoot } from "../git/path-coordinate.js";
 export function findBindEntry(entries) {
     return entries.find((entry) => entry.kind === "bind");
 }
@@ -36,8 +36,10 @@ async function listWorktrees(cwd) {
         throw wrapGitError("worktree list --porcelain -z", error, cwd);
     }
 }
-function pathContains(root, candidate) {
-    const relative = path.relative(root, candidate);
+export function worktreeContainsCoordinate(root, candidate) {
+    const normalizedRoot = normalizeFilesystemCoordinate(root);
+    const normalizedCandidate = normalizeFilesystemCoordinate(candidate);
+    const relative = path.relative(normalizedRoot, normalizedCandidate);
     return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
 }
 export async function stableRepoRoot(cwd) {
@@ -100,6 +102,37 @@ async function findContractWorktree(cwd, contractId) {
 export async function findContractWorktreePath(cwd, contractId) {
     return (await findContractWorktree(cwd, contractId)).path;
 }
+export async function findRegisteredContractWorktreePath(cwd, contractId) {
+    const stableRoot = await stableRepoRoot(cwd);
+    const ledger = await readLedger(stableRoot, contractId);
+    const bind = ledger ? findBindEntry(ledger.entries) : undefined;
+    if (!bind || bind.data.workspace !== "worktree")
+        return undefined;
+    let expected;
+    try {
+        expected = await fs.realpath(await contractWorktreePathFromBind(stableRoot, contractId, bind));
+    }
+    catch {
+        return undefined;
+    }
+    for (const worktree of await listWorktrees(stableRoot)) {
+        try {
+            if (await fs.realpath(worktree.path) === expected)
+                return worktree.path;
+        }
+        catch {
+            // A stale Git registration is not an engine-owned worktree fact.
+        }
+    }
+    return undefined;
+}
+/**
+ * Delivery coordinate for dirty admission and KEIYAKU.md render: the linked
+ * contract worktree when Git registers one, otherwise cwd (workspace here).
+ */
+export async function resolveContractDeliveryCwd(cwd, contractId) {
+    return (await findContractWorktreePath(cwd, contractId)) ?? cwd;
+}
 /**
  * Resolve the contract id for an engine-owned bound worktree containing cwd.
  * Matches the canonical bind place path and worktree workspace only; ledger
@@ -132,27 +165,23 @@ async function contractIdForEngineOwnedWorktree(cwd, options) {
         }
         if (canonicalWorktree !== expectedWorktree)
             continue;
-        if (pathContains(canonicalWorktree, canonicalCwd))
+        if (worktreeContainsCoordinate(canonicalWorktree, canonicalCwd))
             return contractId;
     }
     return undefined;
 }
-/**
- * Resolve the active commission presented by an engine-owned contract
- * worktree containing cwd. Ordinary repository directories and arbitrary
- * worktrees never present a commission address.
- */
-export async function contractPresentedByWorktree(cwd) {
-    return contractIdForEngineOwnedWorktree(cwd, { requireActive: true });
-}
 /**
  * Resolve the contract bound by an engine-owned worktree containing cwd,
  * including when the ledger is already terminal. Task CLI contract context
- * uses this residual binding; call/addressing keep active-only presentation.
+ * uses this residual binding; call attachment never infers from cwd.
  */
 export async function contractBoundByEngineWorktree(cwd) {
     return contractIdForEngineOwnedWorktree(cwd, { requireActive: false });
 }
+/** Existing-contract verbs may infer only a verified, active engine binding. */
+export async function activeContractBoundByEngineWorktree(cwd) {
+    return contractIdForEngineOwnedWorktree(cwd, { requireActive: true });
+}
 export async function cleanupContractWorkspace(cwd, contractId) {
     const stableRoot = await stableRepoRoot(cwd);
     const git = createGit(stableRoot);
@@ -197,17 +226,3 @@ export async function cleanupContractWorkspace(cwd, contractId) {
     }
     return facts;
 }
-export async function activeContractIdForWorktreeDir(cwd, dirname) {
-    const ids = await listContractIds(cwd);
-    for (const id of ids) {
-        const ledger = await readLedger(cwd, id);
-        if (!ledger || isTerminalState(deriveContractState(ledger.entries)))
-            continue;
-        if (id === dirname)
-            return id;
-        const place = ledger ? findBindEntry(ledger.entries)?.data.place : undefined;
-        if (place === dirname)
-            return id;
-    }
-    return undefined;
-}

package/build/flow-error.js

@@ -1,4 +1,5 @@
 import { ACTOR_IDENTITY, SETTINGS_PATH_SEGMENTS } from "./keiyaku-constants.js";
+import { formatArtifactDirectories, KEIYAKU_ARTIFACT_DIRS } from "./artifact-directories.js";
 const SETTINGS_DISPLAY_PATH = SETTINGS_PATH_SEGMENTS.join("/");
 const DEFAULT_HINT_CONTEXT = {
     bindToolName: "bind",
@@ -17,69 +18,115 @@ export function renderTemplate(template, values) {
         return Object.prototype.hasOwnProperty.call(values, key) ? values[key] : match;
     });
 }
-function resolveFlowErrorHint(code, context) {
+function formatInvalidSettingsDiseaseHints(diseases) {
+    return diseases.map((disease) => {
+        const where = disease.knob ? `${disease.source}:${disease.knob}` : `${disease.source}:(root)`;
+        return `${where}: ${disease.reason}`;
+    });
+}
+/** CLI-owned typed hint table. Domain code supplies code + facts only. */
+export function resolveFlowErrorHints(code, context, facts) {
+    if (facts?.kind === "invalid_settings") {
+        return formatInvalidSettingsDiseaseHints(facts.diseases);
+    }
+    if (facts?.kind === "verification_failure") {
+        return [
+            `Fix failures from '${facts.label}', then retry CLAIM.`,
+            `stdout:\n${facts.stdout}`,
+            `stderr:\n${facts.stderr}`,
+        ];
+    }
+    if (facts?.kind === "dirty_worktree") {
+        return [
+            `Files under \`.keiyaku/\` are blocking the operation. Add ${formatArtifactDirectories(KEIYAKU_ARTIFACT_DIRS)} to \`.gitignore\` if you do not want those artifacts tracked.`,
+        ];
+    }
+    if (facts?.kind === "loose_commits") {
+        return [
+            `keiyaku @${facts.contractId} arc — opens a new arc to receipt them, then ${facts.nextVerb}`,
+        ];
+    }
+    if (facts?.kind === "needs_renew") {
+        return [`keiyaku @${facts.contractId} renew — renews delivery before petition`];
+    }
+    if (facts?.kind === "projection_in_flight") {
+        return ["keiyaku status — watch for the akuma to land, then renew"];
+    }
+    if (facts?.kind === "projection_wake_failure") {
+        return [];
+    }
     switch (code) {
         case "NOT_GIT_REPO":
-            return "The provided `cwd` is not a git repository.";
+            return ["The provided `cwd` is not a git repository."];
         case "GIT_UNAVAILABLE":
-            return "Install Git, or use an explicitly bare command that does not require repository authority.";
+            return ["Install Git, or use an explicitly bare command that does not require repository authority."];
         case "ACTIVE_KEIYAKU_EXISTS":
-            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.`;
+            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.";
+            return ["Address a specific contract workspace, or use `call --bare` to run without contract attachment."];
         case "UNKNOWN_COMMAND":
-            return "Run `keiyaku --help` to inspect available commands.";
+            return ["Run `keiyaku --help` to inspect available commands."];
         case "EMPTY_PARAM":
-            return "One or more required parameters are empty.";
+            return ["One or more required parameters are empty."];
         case "DIRTY_WORKTREE":
-            return "The working tree has uncommitted changes.";
+            return ["The working tree has uncommitted changes."];
         case "NOT_ACTIVE_KEIYAKU_BRANCH":
-            return "Checkout an active Keiyaku branch to continue.";
+            return ["keiyaku bind — opens a new contract"];
         case "MISSING_KEIYAKU_BASE":
-            return "Current branch is not associated with an active contract ledger.";
+            return ["Current branch is not associated with an active contract ledger."];
         case "MISSING_PROTOCOL_FILES":
-            return "Required protocol file is missing (`KEIYAKU.md`).";
+            return ["Required protocol file is missing (`KEIYAKU.md`)."];
         case "CLOSE_MERGE_CONFLICT":
-            return [
-                "Renew conflict detected; the workspace was restored without ledger writes.",
-                `Address the conflicting delivery and retry \`${context.renewToolName}\`.`,
-                `For CLAIM conflicts: resolve and commit before \`${context.closeToolName}\` can be attempted again.`,
-            ].join(" ");
+            return [`Open a Keiyaku recovery session with \`keiyaku ${context.renewToolName} --resolve\`.`];
+        case "RENEW_COORDINATE_DRIFT":
+            return [`Restore the delivery to its ledger-recorded history with Git reflog, then retry \`keiyaku ${context.renewToolName}\`.`];
+        case "RENEW_SESSION_OPEN":
+            return [`Continue the owned rewrite with \`keiyaku ${context.renewToolName} --continue\`, or restore it with \`keiyaku ${context.renewToolName} --abort\`.`];
+        case "RENEW_SESSION_NOT_FOUND":
+            return [`No recovery session is open; run \`keiyaku ${context.renewToolName}\` normally.`];
         case "CLOSE_QUALITY_GATE_FAILED":
-            return `CLAIM denied: a configured verification command failed. Use \`${context.arcToolName}\` after addressing the failure before petitioning again.`;
+            return [`CLAIM denied: a configured verification command failed. Use \`${context.arcToolName}\` after addressing the failure before petitioning again.`];
         case "INVALID_BRANCH_TITLE":
-            return "Title cannot be converted to a valid branch token for `keiyaku/<title>`.";
+            return ["Title cannot be converted to a valid branch token for `keiyaku/<title>`."];
         case "UNKNOWN_SUBAGENT": {
             const names = context.availableActorNames.join(", ");
-            return `Unknown ${context.actorIdentity.toLowerCase()} name. Valid options: ${names}.`;
+            return [`Unknown ${context.actorIdentity.toLowerCase()} name. Valid options: ${names}.`];
         }
         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`).";
+            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 `## Objective` and `## Scope` sections (or the equivalent shape in `from_draft`).";
+            return ["Invalid draft/input. Use a `# <title>` heading with non-empty `## Objective` and `## Scope` sections (or the equivalent shape in `from_draft`)."];
+        case "BIND_TASK_INCOMPLETE":
+            return ["Task supplies name/objective defaults; pipe only the missing sections as partial contract Markdown on stdin."];
         case "KEIYAKU_FILE_EXISTS":
-            return `\`${context.bindToolName}\` requires a clean slate. \`KEIYAKU.md\` must be removed before starting.`;
+            return [`\`${context.bindToolName}\` requires a clean slate. \`KEIYAKU.md\` must be removed before starting.`];
         case "DETACHED_HEAD":
-            return "Repository is in detached HEAD state. Address an active contract workspace before retrying.";
+            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 revive 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`.";
+            return ["Invalid close intent. Valid values are `CLAIM` and `FORFEIT`."];
         case "INVALID_SETTINGS":
-            return `Fix invalid configuration in \`${SETTINGS_DISPLAY_PATH}\` and retry.`;
+            return [`Fix invalid configuration in \`${SETTINGS_DISPLAY_PATH}\` and retry.`];
         case "INVALID_EFFORT_OVERRIDE":
-            return "Choose an effort value declared by the selected Akuma's effortOptions.";
+            return ["Choose an effort value declared by the selected Akuma's effortOptions."];
         case "CONCURRENT_MODIFICATION":
-            return `Concurrent repository changes were detected during \`${context.arcToolName}\` or \`${context.renewToolName}\`. Retry on the latest branch state.`;
+            return [`Concurrent repository changes were detected during \`${context.arcToolName}\` or \`${context.renewToolName}\`. Retry on the latest branch state.`];
+        case "TASK_LOCK_ADMISSION_TIMEOUT":
+            return ["Task coordination did not become available before the bounded deadline. Retry the command; repeated timeouts indicate a stuck or damaged repository lock."];
         case "INTERNAL_STATE":
-            return "An internal state error occurred. Please verify your repository status.";
+            return ["An internal state error occurred. Please verify your repository status."];
+        case "SCOPE_VIOLATION":
+            return ["Files outside the contract's declared scope were modified. Append ordered scope terms with `--append-scope`, amend the contract, or move the changes back."];
+        case "NO_OPEN_ARC":
+            return ["Open an arc to receipt delivery commits after the fence, then retry."];
         case "REVIEW_REJECTED":
-            return `CLAIM denied by the reviewer. Address the findings and retry \`${context.arcToolName}\` before petitioning again.`;
+            return [`CLAIM denied by the reviewer. Address the findings and retry \`${context.arcToolName}\` before petitioning again.`];
         case "VERDICT_DENIED":
         case "OATH_MISSING":
-            return DEFAULT_ERROR_HINT;
+            return [DEFAULT_ERROR_HINT];
         default:
-            return DEFAULT_ERROR_HINT;
+            return [DEFAULT_ERROR_HINT];
     }
 }
 function getDefaultErrorHint() {
@@ -87,14 +134,14 @@ function getDefaultErrorHint() {
 }
 export class FlowError extends Error {
     code;
-    hints;
     review;
+    facts;
     constructor(code, message, options) {
         super(message, options?.cause === undefined ? undefined : { cause: options.cause });
         this.name = "FlowError";
         this.code = code;
-        this.hints = options?.hints;
         this.review = options?.review;
+        this.facts = options?.facts;
     }
 }
 export function isFlowError(err) {
@@ -117,18 +164,15 @@ export function wrapFlowError(action, err) {
     if (isFlowError(err)) {
         return new FlowError(err.code, `${action} failed: ${err.message}`, {
             cause: err,
-            hints: err.hints,
             review: err.review,
+            facts: err.facts,
         });
     }
     return new Error(`${action} failed: ${asMessage(err)}`);
 }
 export function pickHintsFromError(err, hintContext = DEFAULT_HINT_CONTEXT) {
     if (isFlowError(err)) {
-        if (err.hints && err.hints.length > 0) {
-            return err.hints;
-        }
-        return [resolveFlowErrorHint(err.code, hintContext)];
+        return resolveFlowErrorHints(err.code, hintContext, err.facts);
     }
     return [getDefaultErrorHint()];
 }