cairn-ai 0.2.5 → 0.2.7

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) };
+}

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

@@ -0,0 +1,63 @@
+import { workspaceFingerprint } from "./cairn-goal-evidence.mjs";
+import { readGoalStateUnlocked, withGoalStateLock, writeGoalStateUnlocked } from "./cairn-goal-state.mjs";
+import { terminalGoalStatuses } from "./cairn-goal-state-validation.mjs";
+
+export async function mutateGoal(root, mutate) {
+  return withGoalStateLock(root, async () => {
+    const state = await readGoalStateUnlocked(root);
+    if (!state) throw new Error("No Cairn goal state exists; start a goal first");
+    const next = await mutate(structuredClone(state));
+    next.revision += 1;
+    await writeGoalStateUnlocked({ root, state: next });
+    return next;
+  });
+}
+
+export function ensureTaskCanComplete(state, task, root) {
+  for (const kind of task.requiredEvidence) ensureCurrentEvidence({ state, root, scope: "task", task, kind });
+}
+
+export function ensureGoalCanComplete(state, root) {
+  const incomplete = state.tasks.filter((task) => task.status !== "completed");
+  if (incomplete.length > 0) throw new Error(`Goal cannot be completed while tasks remain: ${incomplete.map((task) => task.id).join(", ")}`);
+  for (const task of state.tasks) ensureTaskCanComplete(state, task, root);
+  for (const kind of state.goal.requiredEvidence) ensureCurrentEvidence({ state, root, scope: "goal", kind });
+}
+
+function ensureCurrentEvidence({ state, root, scope, task, kind }) {
+  const candidates = state.receipts.filter((receipt) => (
+    receipt.scope === scope && receipt.kind === kind && (scope === "goal" || receipt.taskId === task.id)
+  ));
+  const subject = scope === "goal" ? "Goal" : `Task ${task.id}`;
+  if (state.goal.evidencePolicy === "declared") {
+    if (candidates.length === 0) throw new Error(`${subject} cannot be completed without successful, bound evidence record: ${kind}`);
+    return;
+  }
+  const toolEvidence = candidates.filter((receipt) => receipt.source === "tool");
+  if (toolEvidence.length === 0) throw new Error(`${subject} cannot be completed without tool-bound evidence record: ${kind}`);
+  for (const receipt of [...toolEvidence].reverse()) {
+    if (workspaceFingerprint(root, receipt.watchPaths) === receipt.workspaceFingerprint) return;
+  }
+  throw new Error(`${subject} has stale evidence record: ${kind}`);
+}
+
+export function activateNextPendingTask(state) {
+  if (state.tasks.some((task) => task.status === "active")) return true;
+  const next = state.tasks.find((task) => task.status === "pending");
+  if (next) {
+    next.status = "active";
+    next.updatedAt = new Date().toISOString();
+    return true;
+  }
+  return false;
+}
+
+export function assertGoalMutable(state) {
+  if (terminalGoalStatuses.has(state.goal.status)) throw new Error(`Cannot change a ${state.goal.status} goal`);
+}
+
+export function taskById(state, taskId) {
+  const task = state.tasks.find((item) => item.id === taskId);
+  if (!task) throw new Error(`Unknown task: ${taskId}`);
+  return task;
+}

package/scripts/cairn-goal-operations.mjs

@@ -0,0 +1,177 @@
+import { randomUUID } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { cairnHome, worktreeId } from "./cairn-paths.mjs";
+import { assertNoSymlinkComponents } from "./cairn-safe-fs.mjs";
+import { goalStatePath, readGoalState, readGoalStateUnlocked, withGoalStateLock, writeGoalStateUnlocked } from "./cairn-goal-state.mjs";
+import {
+  GOAL_STATE_VERSION, PLAN_ID_MAX_LENGTH, assertRecoveryReferenceBudget, boundedRequiredText,
+  defaultGoalEvidence, normalizeCriteria, normalizeTask, optionalText, requiredText,
+  terminalGoalStatuses, timestamp, validEvidencePolicy, validGoalStatus, validTaskStatus, validateState,
+} from "./cairn-goal-state-validation.mjs";
+import {
+  activateNextPendingTask, assertGoalMutable, ensureGoalCanComplete, ensureTaskCanComplete,
+  mutateGoal, taskById,
+} from "./cairn-goal-operations-mutations.mjs";
+
+const goalTransitions = {
+  active: new Set(["paused", "blocked", "cancelled", "completed"]),
+  paused: new Set(["active", "blocked", "cancelled"]),
+  blocked: new Set(["active", "paused", "cancelled"]),
+  cancelled: new Set(),
+  completed: new Set(),
+};
+const taskTransitions = {
+  pending: new Set(["active", "blocked"]),
+  active: new Set(["pending", "blocked", "completed"]),
+  blocked: new Set(["pending", "active"]),
+  completed: new Set(),
+};
+
+export async function startGoal({ root = process.cwd(), goal, planId, tasks, completionCriteria = [], requiredEvidence = defaultGoalEvidence, ownerSessionId = null, evidencePolicy = "tool-bound" } = {}) {
+  const normalizedGoal = requiredText(goal, "goal");
+  const normalizedPlanId = boundedRequiredText(planId, "planId", PLAN_ID_MAX_LENGTH);
+  if (!Array.isArray(tasks) || tasks.length === 0) throw new Error("tasks must contain at least one task");
+  return withGoalStateLock(root, async () => {
+    let existing = await readGoalStateUnlocked(root);
+    const currentWorktreeId = worktreeId(root);
+    if (existing && existing.goal.worktreeId !== currentWorktreeId) {
+      const path = goalStatePath(root);
+      await assertNoSymlinkComponents(cairnHome(), path, { allowMissing: false });
+      await rm(path);
+      existing = null;
+    }
+    if (existing && !terminalGoalStatuses.has(existing.goal.status)) {
+      throw new Error(`An active Cairn goal already exists (${existing.goal.id}); pause, block, cancel, or complete it first`);
+    }
+    const now = timestamp();
+    const normalizedTasks = tasks.map((task, index) => normalizeTask(task, index, index === 0 ? "active" : "pending"));
+    for (const task of normalizedTasks) assertRecoveryReferenceBudget(normalizedPlanId, task.id);
+    const state = {
+      schemaVersion: GOAL_STATE_VERSION,
+      revision: 1,
+      goal: {
+        id: `goal-${randomUUID()}`,
+        title: normalizedGoal,
+        planId: normalizedPlanId,
+        status: "active",
+        completionCriteria: normalizeCriteria(completionCriteria),
+        requiredEvidence: normalizeCriteria(requiredEvidence),
+        evidencePolicy: validEvidencePolicy(evidencePolicy),
+        worktreeId: currentWorktreeId,
+        ownerSessionId: optionalText(ownerSessionId, "ownerSessionId"),
+        blocker: null,
+        createdAt: now,
+        updatedAt: now,
+      },
+      tasks: normalizedTasks,
+      receipts: [],
+    };
+    await writeGoalStateUnlocked({ root, state });
+    return state;
+  });
+}
+
+export async function reconcileWorktreeState({ root = process.cwd() } = {}) {
+  const initial = await readGoalState({ root });
+  if (!initial || initial.goal.worktreeId === worktreeId(root)) return { state: initial, removed: false };
+  return withGoalStateLock(root, async () => {
+    const state = await readGoalStateUnlocked(root);
+    if (!state || state.goal.worktreeId === worktreeId(root)) return { state, removed: false };
+    const staleWorktreeId = state.goal.worktreeId;
+    const path = goalStatePath(root);
+    await assertNoSymlinkComponents(cairnHome(), path, { allowMissing: false });
+    await rm(path);
+    return { state: null, removed: true, staleWorktreeId };
+  });
+}
+
+export async function transitionGoal({ root = process.cwd(), status, blocker } = {}) {
+  const nextStatus = validGoalStatus(status);
+  if (terminalGoalStatuses.has(nextStatus)) {
+    return withGoalStateLock(root, async () => {
+      const state = await readGoalStateUnlocked(root);
+      if (!state) throw new Error("No Cairn goal state exists; start a goal first");
+      const next = applyGoalTransition(structuredClone(state), nextStatus, blocker, root);
+      next.revision += 1;
+      validateState(next);
+      const path = goalStatePath(root);
+      await assertNoSymlinkComponents(cairnHome(), path, { allowMissing: false });
+      await rm(path);
+      return next;
+    });
+  }
+  return mutateGoal(root, (state) => applyGoalTransition(state, nextStatus, blocker, root));
+}
+
+function applyGoalTransition(state, nextStatus, blocker, root) {
+  const currentStatus = state.goal.status;
+  if (currentStatus === nextStatus) return state;
+  if (!goalTransitions[currentStatus].has(nextStatus)) throw new Error(`Cannot transition goal from ${currentStatus} to ${nextStatus}`);
+  if (nextStatus === "completed") ensureGoalCanComplete(state, root);
+  if (nextStatus === "blocked") state.goal.blocker = requiredText(blocker, "blocker");
+  if (nextStatus === "active") state.goal.blocker = null;
+  state.goal.status = nextStatus;
+  state.goal.updatedAt = timestamp();
+  return state;
+}
+
+export async function setTaskStatus({ root = process.cwd(), taskId, status, blocker } = {}) {
+  const nextStatus = validTaskStatus(status);
+  const normalizedTaskId = requiredText(taskId, "taskId");
+  return mutateGoal(root, (state) => {
+    assertGoalMutable(state);
+    const task = taskById(state, normalizedTaskId);
+    if (task.status === nextStatus) return state;
+    if (!taskTransitions[task.status].has(nextStatus)) throw new Error(`Cannot transition task ${task.id} from ${task.status} to ${nextStatus}`);
+    if (nextStatus === "active") {
+      const anotherActive = state.tasks.find((item) => item.id !== task.id && item.status === "active");
+      if (anotherActive) throw new Error(`Task ${anotherActive.id} is already active`);
+    }
+    if (nextStatus === "completed") ensureTaskCanComplete(state, task, root);
+    if (nextStatus === "blocked") task.blocker = requiredText(blocker, "blocker");
+    if (nextStatus === "active" || nextStatus === "pending") task.blocker = null;
+    task.status = nextStatus;
+    task.updatedAt = timestamp();
+    if (nextStatus === "completed") activateNextPendingTask(state);
+    if (nextStatus === "blocked" && !activateNextPendingTask(state)) {
+      state.goal.status = "blocked";
+      state.goal.blocker = task.blocker;
+    }
+    state.goal.updatedAt = timestamp();
+    return state;
+  });
+}
+
+export async function replanGoal({ root = process.cwd(), tasks } = {}) {
+  if (!Array.isArray(tasks) || tasks.length === 0) throw new Error("replan tasks must contain at least one incomplete task");
+  return mutateGoal(root, (state) => {
+    assertGoalMutable(state);
+    if (state.goal.status !== "active") throw new Error("Only an active goal can be replanned");
+    const completedTasks = state.tasks.filter((task) => task.status === "completed");
+    const completedIds = new Set(completedTasks.map((task) => task.id));
+    const replacementTasks = tasks.map((task, index) => {
+      const source = typeof task === "string" ? task : { ...task, status: undefined, blocker: undefined };
+      const normalized = normalizeTask(source, index, index === 0 ? "active" : "pending");
+      if (completedIds.has(normalized.id)) throw new Error(`Replanned task conflicts with completed task id: ${normalized.id}`);
+      return normalized;
+    });
+    state.tasks = [...completedTasks, ...replacementTasks];
+    state.receipts = state.receipts.filter((receipt) => receipt.scope === "task" && completedIds.has(receipt.taskId));
+    state.goal.blocker = null;
+    state.goal.updatedAt = timestamp();
+    return state;
+  });
+}
+
+export async function assignTask({ root = process.cwd(), taskId, agentId = null } = {}) {
+  const normalizedTaskId = requiredText(taskId, "taskId");
+  const normalizedAgentId = agentId === null ? null : requiredText(agentId, "agentId");
+  return mutateGoal(root, (state) => {
+    assertGoalMutable(state);
+    const task = taskById(state, normalizedTaskId);
+    task.assignedAgentId = normalizedAgentId;
+    task.updatedAt = timestamp();
+    state.goal.updatedAt = timestamp();
+    return state;
+  });
+}

package/scripts/cairn-goal-policy.mjs

@@ -0,0 +1,33 @@
+export function currentTask(state) {
+  if (!state) return null;
+  return state.tasks.find((task) => task.status === "active")
+    ?? state.tasks.find((task) => task.status === "pending")
+    ?? state.tasks.find((task) => task.status === "blocked")
+    ?? null;
+}
+
+export function isGoalOwnedBySession(state, sessionId) {
+  return !state?.goal?.ownerSessionId || state.goal.ownerSessionId === sessionId;
+}
+
+export function evaluateStop(state, { subagent = false, agentId } = {}) {
+  if (!state || state.goal.status !== "active") return { block: false };
+  const task = currentTask(state);
+  if (!task) {
+    return {
+      block: true,
+      reason: `Cairn goal "${state.goal.title}" has no incomplete task, but is still active. Verify completion criteria and explicitly mark the goal complete.`,
+    };
+  }
+  if (subagent) {
+    if (!agentId || task.assignedAgentId !== agentId) return { block: false };
+    return {
+      block: true,
+      reason: `Cairn task ${task.id} (${task.title}) is assigned to this subagent and is ${task.status}. Continue only this assigned task, record a successful evidence record, then hand off.`,
+    };
+  }
+  return {
+    block: true,
+    reason: `Cairn goal "${state.goal.title}" is active. Continue current task ${task.id} (${task.title}); its status is ${task.status}. Record a successful evidence record before marking it complete.`,
+  };
+}