cairn-ai 0.2.6 → 0.2.7

package/docs/model-guidance/codex.md

@@ -19,7 +19,7 @@ Codex-family models are strong at small implementation tasks, explicit tool use,
 
 - On every fresh entry, compaction recovery, restart, delegation, or handoff, restore optional root `MEMORY.md` → current phase skill → active plan → current-task references → recorded model guidance. Missing `MEMORY.md` never blocks and must not trigger another memory service. If persisted state or the assignment requires another missing, unreadable, or inconsistent reference, fail closed and report a blocker before editing, delegating, approving, or completing.
 - Do not start implementation without a plan.
-- Keep the model inherited. Read each plan task's `Requested reasoning effort` and `Effective reasoning effort`; only a newly dispatched task or worker may receive the requested effort through the host's task/subagent option, with no model override. For an unsupported host or value, record the effective reasoning effort as `inherited` and leave model/global configuration unchanged.
+- Keep the model inherited. `Requested reasoning effort` is Cairn's desired profile; `Effective reasoning effort` is what the dispatch response confirms. Only a newly dispatched task or worker may receive the requested effort through the host's task/subagent option, with no model override. For an unsupported host or value, record Effective `inherited`; this means no task override was confirmed, not proof of missing host capability. Infer capability only from the exposed interface or dispatch response, distinguish Cairn non-integration from host non-support, and leave model/global configuration unchanged.
 - Do not treat complexity as a one-time choice. Require the provisional request checkpoint, post-exploration planning checkpoint, and code checkpoint after exact file/caller/test inspection immediately before the first edit. Before editing, evidence may change either route. Every change must synchronize the plan artifact, repository goal task roadmap through `goal replan`, and native UI plan, including reviews and required evidence. After editing begins, a new Heavy signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.
 - Do not stop before local implementation solely because subagent tools are unavailable; the main agent takes over implementation directly and records that takeover in evidence.
 - Keep work units small. Split large changes into smaller plan tasks.
@@ -46,7 +46,7 @@ Codex-family models are strong at small implementation tasks, explicit tool use,
 ### Implementation
 
 - Invest Codex reasoning in executable test design first, then hand the bounded failing contract to implementation and require the minimum passing patch.
-- Run verification through `goal verify -- ...`. Its default timeout is 600,000 ms (10 minutes), capped at 3,600,000 ms (1 hour). On success, retain exact argv, tool exit code, pass count, output digest, and watched-workspace fingerprint; commit evidence only when the starting goal/task identity and pre/post watched fingerprint match. Choose the watch set and command at the semantic boundary that proves the claim. Expand diagnostics only for the failing test and its related file/symbol scope; reject stale evidence after related changes.
+- Run verification through `goal verify -- ...`. Its default timeout is 600,000 ms (10 minutes), capped at 3,600,000 ms (1 hour). On success, retain exact argv, tool exit code, pass count, output digest, and watched-workspace fingerprint; commit evidence only when the starting goal/task identity and pre/post watched fingerprint match. Choose the watch set and command at the semantic boundary that proves the claim. The default Git fingerprint excludes ignored files; explicitly `--watch` every ignored artifact needed by the claim. Expand diagnostics only for the failing test and its related file/symbol scope; reject stale evidence after related changes.
 - If acting as the user-called/main agent, orchestrate the work and delegate actual implementation edits to `worker` whenever subagent tools are available, regardless of Light Path or Heavy Path.
 - If acting as the user-called/main agent, immediately relay received subagent status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion.
 - If acting as the user-called/main agent, close or release completed subagents after capturing their final report and evidence, then review the final report and evidence before marking the work complete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-ai",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity",
   "license": "MIT",
   "author": {
@@ -32,7 +32,9 @@
     "commands/",
     "docs/model-guidance/",
     "hooks/",
-    "scripts/",
+    "scripts/cairn",
+    "scripts/*.mjs",
+    "scripts/release-integrity-*.json",
     "skills/",
     "templates/",
     "README.md",

package/scripts/cairn-cleanup.mjs

@@ -5,24 +5,28 @@ import { pathToFileURL } from "node:url";
 import { reconcileWorktreeState } from "./cairn-goal.mjs";
 import { parseRootArgs } from "./cairn-paths.mjs";
 
-const knownNames = new Set(["state.json", "state.lock", "tools"]);
+const staleLockName = /^state\.lock\.stale\..+\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 
 export async function cleanupProjectCairn({ root = process.cwd(), apply = false } = {}) {
   const repoRoot = resolve(root);
   const legacyRoot = join(repoRoot, ".cairn");
-  let entries;
+  let rootStat;
   try {
-    entries = await readdir(legacyRoot, { withFileTypes: true });
+    rootStat = await lstat(legacyRoot);
   } catch (error) {
     if (error?.code === "ENOENT") return { root: repoRoot, apply, known: [], unknown: [], removed: [], projectDirectoryRemoved: false };
     throw error;
   }
+  if (rootStat.isSymbolicLink()) throw new Error(`Legacy Cairn root must not be a symbolic link: ${legacyRoot}`);
+  if (!rootStat.isDirectory()) throw new Error(`Legacy Cairn root is not a directory: ${legacyRoot}`);
 
+  const entries = await readdir(legacyRoot, { withFileTypes: true });
   const known = [];
   const unknown = [];
   for (const entry of entries) {
-    const isKnownStaleLock = entry.name.startsWith("state.lock.stale.");
-    (knownNames.has(entry.name) || isKnownStaleLock ? known : unknown).push(entry.name);
+    const isKnownFile = entry.isFile() && (entry.name === "state.json" || entry.name === "state.lock" || staleLockName.test(entry.name));
+    const isKnownDirectory = entry.isDirectory() && entry.name === "tools";
+    (isKnownFile || isKnownDirectory ? known : unknown).push(entry.name);
   }
   if (!apply) return { root: repoRoot, apply, known: known.sort(), unknown: unknown.sort(), removed: [], projectDirectoryRemoved: false };
 
@@ -32,7 +36,9 @@ export async function cleanupProjectCairn({ root = process.cwd(), apply = false
     const path = join(legacyRoot, name);
     try {
       const stat = await lstat(path);
-      await rm(path, { recursive: stat.isDirectory(), force: true });
+      const expectedType = name === "tools" ? stat.isDirectory() : stat.isFile();
+      if (!expectedType) continue;
+      await rm(path, { recursive: name === "tools", force: true });
       removed.push(name);
     } catch (error) {
       if (error?.code !== "ENOENT") throw error;

package/scripts/cairn-goal-cli.mjs

@@ -0,0 +1,233 @@
+export async function runGoalCli(args, {
+  stdout = console.log,
+  defaultGoalEvidence,
+  operations,
+}) {
+  const [firstCommand = "help", ...remaining] = args;
+  const [command = "help", ...rest] = firstCommand === "goal" ? remaining : [firstCommand, ...remaining];
+  const { options, positional, passthrough } = parseArgs(rest, command);
+  const root = options.root ?? process.cwd();
+  const emit = options.quiet ? () => {} : stdout;
+  if (command === "start") {
+    const tasks = parseTasks(options.tasks ?? positional.slice(0));
+    const state = await operations.startGoal({
+      root,
+      goal: options.goal,
+      planId: options.plan,
+      tasks,
+      completionCriteria: splitValues(options.criteria),
+      requiredEvidence: options.requiredEvidence ? splitValues(options.requiredEvidence) : defaultGoalEvidence,
+      ownerSessionId: options.session,
+      evidencePolicy: options.evidencePolicy ?? options["evidence-policy"] ?? "tool-bound",
+    });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  if (command === "status") {
+    const state = await operations.readGoalState({ root });
+    stdout(JSON.stringify(state));
+    return state;
+  }
+  if (command === "task") {
+    if (positional[0] === "status" && options.status === undefined) {
+      const state = await operations.readGoalState({ root });
+      if (!state) {
+        stdout(JSON.stringify(null));
+        return null;
+      }
+      const requestedTaskId = options.task ?? positional[1];
+      const task = requestedTaskId === undefined
+        ? state.tasks.find((candidate) => candidate.status === "active") ?? null
+        : state.tasks.find((candidate) => candidate.id === requestedTaskId);
+      if (requestedTaskId !== undefined && task === undefined) throw new Error(`Unknown task: ${requestedTaskId}`);
+      stdout(JSON.stringify(task));
+      return task;
+    }
+    const taskAction = taskStatusFromAction(positional[0]);
+    const state = await operations.setTaskStatus({
+      root,
+      taskId: options.task ?? (taskAction ? positional[1] : positional[0]),
+      status: options.status ?? taskAction ?? positional[1],
+      blocker: options.reason,
+    });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  if (command === "replan") {
+    const state = await operations.replanGoal({ root, tasks: parseTasks(options.tasks ?? positional.slice(0)) });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  if (command === "assign") {
+    const state = await operations.assignTask({
+      root,
+      taskId: options.task ?? positional[0],
+      agentId: options.agent ?? positional[1] ?? null,
+    });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  if (command === "receipt") {
+    const state = await operations.recordReceipt({
+      root,
+      taskId: options.task ?? positional[0],
+      kind: options.kind,
+      scope: options.scope,
+      command: options.command,
+      exitCode: numberOption(options.exitCode ?? options["exit-code"] ?? options.exit),
+      timestamp: options.timestamp,
+      goalId: options.goalId ?? options["goal-id"],
+      planId: options.plan,
+    });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  if (command === "verify") {
+    const result = await operations.verifyAndRecord({
+      root,
+      taskId: options.task ?? positional[0],
+      kind: options.kind,
+      scope: options.scope,
+      watchPaths: splitValues(options.watch),
+      argv: passthrough,
+      timeoutMs: options["timeout-ms"] === undefined
+        ? 600_000
+        : positiveIntegerOption(options["timeout-ms"], "timeout-ms"),
+    });
+    emit(JSON.stringify({
+      id: result.evidence.id,
+      scope: result.evidence.scope,
+      kind: result.evidence.kind,
+      exitCode: result.evidence.exitCode,
+      outputDigest: result.evidence.outputDigest,
+      workspaceFingerprint: result.evidence.workspaceFingerprint,
+    }));
+    return result.state;
+  }
+  if (["pause", "resume", "block", "cancel", "complete"].includes(command)) {
+    const state = await operations.transitionGoal({
+      root,
+      status: { pause: "paused", resume: "active", block: "blocked", cancel: "cancelled", complete: "completed" }[command],
+      blocker: options.reason,
+    });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  throw new Error("Usage: cairn-goal start|status|task|replan|assign|receipt|verify|pause|resume|block|cancel|complete [--root PATH]");
+}
+
+function parseArgs(args, command) {
+  const options = {};
+  const positional = [];
+  const passthrough = [];
+  const booleanOptions = new Set(["quiet"]);
+  const allowed = allowedOptions(command);
+  const seenCanonicalOptions = new Set();
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === "--") {
+      passthrough.push(...args.slice(index + 1));
+      break;
+    }
+    if (!value.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+    const option = value.slice(2);
+    const equalsIndex = option.indexOf("=");
+    const key = equalsIndex === -1 ? option : option.slice(0, equalsIndex);
+    const inline = equalsIndex === -1 ? undefined : option.slice(equalsIndex + 1);
+    if (!allowed.has(key)) throw new Error(`Unknown option for ${command}: --${key}`);
+    const canonicalKey = canonicalOptionKey(key);
+    if (seenCanonicalOptions.has(canonicalKey)) throw new Error(`--${canonicalKey} may only be provided once`);
+    seenCanonicalOptions.add(canonicalKey);
+    if (inline !== undefined) {
+      if (!booleanOptions.has(key) && inline.length === 0) throw new Error(`--${key} requires a value`);
+      if (booleanOptions.has(key) && !["true", "false"].includes(inline)) throw new Error(`--${key} must be true or false`);
+      options[key] = booleanOptions.has(key) ? inline !== "false" : inline;
+    } else if (booleanOptions.has(key)) {
+      options[key] = true;
+    } else {
+      const next = args[index + 1];
+      if (next === undefined || next === "--" || next.startsWith("--")) throw new Error(`--${key} requires a value`);
+      options[key] = next;
+      index += 1;
+    }
+  }
+  return { options, positional, passthrough };
+}
+
+function canonicalOptionKey(key) {
+  return {
+    exitCode: "exit-code",
+    exit: "exit-code",
+    goalId: "goal-id",
+    evidencePolicy: "evidence-policy",
+  }[key] ?? key;
+}
+
+function allowedOptions(command) {
+  const common = ["root", "quiet"];
+  const byCommand = {
+    start: ["goal", "plan", "tasks", "criteria", "requiredEvidence", "session", "evidencePolicy", "evidence-policy"],
+    status: [],
+    task: ["task", "status", "reason"],
+    replan: ["tasks"],
+    assign: ["task", "agent"],
+    receipt: ["task", "kind", "scope", "command", "exitCode", "exit-code", "exit", "timestamp", "goalId", "goal-id", "plan"],
+    verify: ["task", "kind", "scope", "watch", "timeout-ms"],
+    pause: [],
+    resume: [],
+    block: ["reason"],
+    cancel: [],
+    complete: [],
+    help: [],
+  };
+  return new Set([...common, ...(byCommand[command] ?? [])]);
+}
+
+function parseTasks(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error("Provide tasks with --tasks JSON or positional task titles");
+  try {
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed)) throw new Error("--tasks JSON must be an array");
+    return parsed;
+  } catch (error) {
+    if (error instanceof SyntaxError) return value.split("|").map((item) => item.trim()).filter(Boolean);
+    throw error;
+  }
+}
+
+function splitValues(value) {
+  if (!value) return [];
+  return String(value).split("|").map((item) => item.trim()).filter(Boolean);
+}
+
+function numberOption(value) {
+  if (value === undefined) return undefined;
+  const result = Number(value);
+  if (!Number.isInteger(result)) throw new Error("exitCode must be an integer");
+  return result;
+}
+
+function positiveIntegerOption(value, label) {
+  const result = Number(value);
+  if (!Number.isSafeInteger(result) || result <= 0 || result > 3_600_000) {
+    throw new Error(`${label} must be an integer between 1 and 3600000`);
+  }
+  return result;
+}
+
+function taskStatusFromAction(value) {
+  return {
+    start: "active",
+    activate: "active",
+    active: "active",
+    complete: "completed",
+    completed: "completed",
+    block: "blocked",
+    blocked: "blocked",
+    pending: "pending",
+  }[value] ?? null;
+}

package/scripts/cairn-goal-evidence.mjs

@@ -0,0 +1,179 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readlinkSync, readdirSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+
+export function normalizeVerificationArgv(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) throw new Error("verification command must follow -- as argv");
+  return argv.map((item, index) => {
+    if (typeof item !== "string") throw new Error(`verification argv[${index}] must be a string`);
+    if (index === 0 && item.trim().length === 0) throw new Error("verification executable must be a non-empty string");
+    return item;
+  });
+}
+
+export function normalizeWatchPaths(root, watchPaths) {
+  if (!Array.isArray(watchPaths)) throw new Error("watchPaths must be an array");
+  const workspaceRoot = resolve(root);
+  return [...new Set(watchPaths.map((item, index) => {
+    const source = requiredText(item, `watchPaths[${index}]`);
+    const absolutePath = resolve(workspaceRoot, source);
+    const relativePath = relative(workspaceRoot, absolutePath);
+    if (relativePath === ".." || relativePath.startsWith(`..${sep}`)) {
+      throw new Error(`watch path must remain inside the workspace: ${source}`);
+    }
+    const normalizedPath = relativePath === "" ? "." : relativePath.split(sep).join("/");
+    if (isInternalStatePath(normalizedPath)) throw new Error(`watch path cannot target internal Cairn or Git state: ${source}`);
+    return normalizedPath;
+  }))];
+}
+
+export function workspaceFingerprint(root = process.cwd(), watchPaths = []) {
+  const workspaceRoot = resolve(root);
+  const normalizedWatchPaths = normalizeWatchPaths(workspaceRoot, watchPaths);
+  const gitPaths = normalizedWatchPaths.length === 0 ? listGitWorkspacePaths(workspaceRoot) : null;
+  const paths = normalizedWatchPaths.length > 0
+    ? listFilesystemPaths(workspaceRoot, normalizedWatchPaths)
+    : (gitPaths ?? listFilesystemPaths(workspaceRoot, normalizedWatchPaths));
+  const hash = createHash("sha256");
+  for (const path of [...new Set(paths)].sort()) hashWorkspacePath(hash, workspaceRoot, path);
+  return `sha256:${hash.digest("hex")}`;
+}
+
+export function runVerificationEvidence({
+  root,
+  argv,
+  watchPaths,
+  runner = spawnSync,
+  timeoutMs,
+}) {
+  const initialFingerprint = workspaceFingerprint(root, watchPaths);
+  const result = runner(argv[0], argv.slice(1), {
+    cwd: resolve(root),
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    shell: false,
+    timeout: validTimeout(timeoutMs),
+  });
+  if (result.error?.code === "ETIMEDOUT") throw new Error(`Verification timed out after ${timeoutMs}ms`);
+  if (result.error) throw new Error(`Verification could not start: ${result.error.message}`);
+  const exitCode = Number.isInteger(result.status) ? result.status : 1;
+  const output = combinedOutput(result.stdout, result.stderr);
+  if (exitCode !== 0) {
+    const detail = boundedText(output, 2000);
+    throw new Error(`Verification failed with exit ${exitCode}${detail ? `:\n${detail}` : ""}`);
+  }
+
+  const fingerprint = workspaceFingerprint(root, watchPaths);
+  if (fingerprint !== initialFingerprint) throw new Error("Watched workspace changed during verification; evidence was not recorded");
+  return {
+    argv,
+    command: argv.map((value) => JSON.stringify(value)).join(" "),
+    outputDigest: sha256(output),
+    summary: successSummary(output),
+    workspaceFingerprint: fingerprint,
+    watchPaths,
+  };
+}
+
+function listGitWorkspacePaths(root) {
+  const result = spawnSync("git", ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.status !== 0 || result.error) return null;
+  return result.stdout.split("\0").filter(Boolean).filter((path) => !isInternalStatePath(path));
+}
+
+function listFilesystemPaths(root, watchPaths) {
+  const paths = [];
+  const visit = (relativePath) => {
+    if (isInternalStatePath(relativePath)) return;
+    const absolutePath = relativePath === "." ? root : join(root, ...relativePath.split("/"));
+    let stat;
+    try {
+      stat = lstatSync(absolutePath);
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        paths.push(relativePath);
+        return;
+      }
+      throw error;
+    }
+    if (!stat.isDirectory()) {
+      paths.push(relativePath);
+      return;
+    }
+    const entries = readdirSync(absolutePath).sort();
+    if (entries.length === 0) paths.push(relativePath);
+    for (const entry of entries) {
+      const child = relativePath === "." ? entry : `${relativePath}/${entry}`;
+      visit(child);
+    }
+  };
+  for (const path of watchPaths.length > 0 ? watchPaths : ["."]) visit(path);
+  return paths;
+}
+
+function hashWorkspacePath(hash, root, relativePath) {
+  const absolutePath = relativePath === "." ? root : join(root, ...relativePath.split("/"));
+  hash.update(`${relativePath}\0`);
+  let stat;
+  try {
+    stat = lstatSync(absolutePath);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      hash.update("missing\0");
+      return;
+    }
+    throw error;
+  }
+  hash.update(`${stat.mode}\0`);
+  if (stat.isSymbolicLink()) {
+    hash.update(`symlink\0${readlinkSync(absolutePath)}\0`);
+  } else if (stat.isFile()) {
+    hash.update("file\0");
+    hash.update(readFileSync(absolutePath));
+    hash.update("\0");
+  } else if (stat.isDirectory()) {
+    hash.update("directory\0");
+  } else {
+    hash.update("other\0");
+  }
+}
+
+function isInternalStatePath(path) {
+  const firstSegment = path.split("/")[0];
+  return firstSegment === ".git" || firstSegment === ".cairn";
+}
+
+function requiredText(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${label} must be a non-empty string`);
+  return value.trim();
+}
+
+function combinedOutput(stdout, stderr) {
+  return [stdout, stderr].filter((value) => typeof value === "string" && value.length > 0).join("\n").trim();
+}
+
+function boundedText(value, maxLength) {
+  const text = String(value ?? "").trim();
+  if (text.length <= maxLength) return text;
+  return `…${text.slice(-(maxLength - 1))}`;
+}
+
+function successSummary(output) {
+  const text = String(output ?? "");
+  const outputBytes = Buffer.byteLength(text);
+  const outputLines = text.length === 0 ? 0 : text.split(/\r?\n/).length;
+  return `verification passed; outputBytes=${outputBytes}; outputLines=${outputLines}`;
+}
+
+function sha256(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function validTimeout(value) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new Error("timeoutMs must be a positive integer");
+  return value;
+}

package/scripts/cairn-goal-operations-evidence.mjs

@@ -0,0 +1,124 @@
+import { randomUUID } from "node:crypto";
+import { normalizeVerificationArgv, normalizeWatchPaths, runVerificationEvidence, workspaceFingerprint } from "./cairn-goal-evidence.mjs";
+import { readGoalState } from "./cairn-goal-state.mjs";
+import {
+  normalizeToolEvidence, requiredText, timestamp, validReceiptCommand, validReceiptScope,
+  validReceiptSource, validTimestamp,
+} from "./cairn-goal-state-validation.mjs";
+import { assertGoalMutable, mutateGoal, taskById } from "./cairn-goal-operations-mutations.mjs";
+
+export async function recordReceipt(options = {}) {
+  if (options.source !== undefined && options.source !== "declared") throw new Error("Only goal verify can create tool evidence");
+  return recordEvidence({ ...options, source: "declared" });
+}
+
+async function recordEvidence({
+  root = process.cwd(), taskId, kind, scope = "task", command, exitCode,
+  timestamp: receiptTimestamp, goalId, planId, source, argv, outputDigest,
+  summary, workspaceFingerprint: fingerprint, watchPaths = [], expectedIdentity,
+  expectedFingerprint,
+} = {}) {
+  const normalizedScope = validReceiptScope(scope);
+  const normalizedTaskId = normalizedScope === "task" ? requiredText(taskId, "taskId") : undefined;
+  const normalizedKind = requiredText(kind, "evidence kind");
+  const normalizedCommand = validReceiptCommand(command);
+  const normalizedSource = validReceiptSource(source);
+  if (exitCode !== 0) throw new Error("evidence exitCode must be 0");
+  const normalizedTimestamp = validTimestamp(receiptTimestamp ?? timestamp());
+  const toolFields = normalizedSource === "tool" ? normalizeToolEvidence({ argv, outputDigest, summary, fingerprint, watchPaths }) : {};
+  return mutateGoal(root, (state) => {
+    assertGoalMutable(state);
+    const task = normalizedScope === "task" ? taskById(state, normalizedTaskId) : null;
+    if (expectedIdentity && (state.goal.id !== expectedIdentity.goalId || state.goal.planId !== expectedIdentity.planId)) {
+      throw new Error("Goal identity changed during verification; evidence was not recorded");
+    }
+    if (expectedIdentity && normalizedScope === "task" && (
+      task?.id !== expectedIdentity.taskId
+      || task?.status !== expectedIdentity.taskStatus
+      || task?.assignedAgentId !== expectedIdentity.taskAgentId
+    )) throw new Error("Verification task changed during verification; evidence was not recorded");
+    if (expectedFingerprint && workspaceFingerprint(root, watchPaths) !== expectedFingerprint) {
+      throw new Error("Watched workspace changed during verification; evidence was not recorded");
+    }
+    if (goalId !== undefined && goalId !== state.goal.id) throw new Error("evidence goalId does not match the active goal");
+    if (planId !== undefined && planId !== state.goal.planId) throw new Error("evidence planId does not match the active goal");
+    const receipt = {
+      id: `receipt-${randomUUID()}`,
+      scope: normalizedScope,
+      kind: normalizedKind,
+      ...(task ? { taskId: task.id } : {}),
+      goalId: state.goal.id,
+      planId: state.goal.planId,
+      command: normalizedCommand,
+      exitCode: 0,
+      timestamp: normalizedTimestamp,
+      source: normalizedSource,
+      ...toolFields,
+    };
+    state.receipts.push(receipt);
+    if (task) task.updatedAt = timestamp();
+    state.goal.updatedAt = timestamp();
+    return state;
+  });
+}
+
+export async function verifyAndRecord({
+  root = process.cwd(), taskId, kind, scope = "task", argv, watchPaths = [],
+  runner, timeoutMs = 600_000,
+} = {}) {
+  const normalizedArgv = normalizeVerificationArgv(argv);
+  const normalizedWatchPaths = normalizeWatchPaths(root, watchPaths);
+  const normalizedScope = validReceiptScope(scope);
+  const normalizedKind = requiredText(kind, "evidence kind");
+  const initialState = await readGoalState({ root });
+  if (!initialState) throw new Error("No Cairn goal state exists; start a goal first");
+  assertGoalMutable(initialState);
+  const normalizedTaskId = normalizedScope === "task" ? requiredText(taskId, "taskId") : undefined;
+  const initialTask = normalizedScope === "task" ? taskById(initialState, normalizedTaskId) : null;
+  if (initialTask && !["active", "completed"].includes(initialTask.status)) {
+    throw new Error(`Verification task must be active or completed: ${initialTask.id}`);
+  }
+  const identity = {
+    goalId: initialState.goal.id,
+    planId: initialState.goal.planId,
+    taskId: normalizedTaskId,
+    taskStatus: initialTask?.status,
+    taskAgentId: initialTask?.assignedAgentId,
+  };
+  const evidence = runVerificationEvidence({
+    root,
+    argv: normalizedArgv,
+    watchPaths: normalizedWatchPaths,
+    runner,
+    timeoutMs,
+  });
+  const postState = await readGoalState({ root });
+  if (!postState || postState.goal.id !== identity.goalId || postState.goal.planId !== identity.planId) {
+    throw new Error("Goal identity changed during verification; evidence was not recorded");
+  }
+  if (normalizedScope === "task") {
+    const postTask = taskById(postState, normalizedTaskId);
+    if (postTask.status !== identity.taskStatus || postTask.assignedAgentId !== identity.taskAgentId) {
+      throw new Error("Verification task changed during verification; evidence was not recorded");
+    }
+  }
+  const state = await recordEvidence({
+    root,
+    taskId: normalizedTaskId,
+    kind: normalizedKind,
+    scope: normalizedScope,
+    command: evidence.command,
+    exitCode: 0,
+    source: "tool",
+    argv: evidence.argv,
+    outputDigest: evidence.outputDigest,
+    summary: evidence.summary,
+    workspaceFingerprint: evidence.workspaceFingerprint,
+    watchPaths: evidence.watchPaths,
+    goalId: identity.goalId,
+    planId: identity.planId,
+    expectedIdentity: identity,
+    expectedFingerprint: evidence.workspaceFingerprint,
+  });
+  return { state, evidence: state.receipts.at(-1) };
+}