cairn-ai 0.2.9 → 0.4.0

package/scripts/cairn-goal-cli.mjs

@@ -1,12 +1,16 @@
+import { resolveRepoRoot } from "./cairn-paths.mjs";
+
 export async function runGoalCli(args, {
   stdout = console.log,
+  stderr = console.error,
   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();
+  // Without --root, resolve the repository (HARNESS_REPO_ROOT or the nearest .git ancestor), not a subdirectory cwd.
+  const root = resolveRepoRoot({ explicitRoot: options.root ?? null });
   const emit = options.quiet ? () => {} : stdout;
   if (command === "start") {
     const tasks = parseTasks(options.tasks ?? positional.slice(0));
@@ -49,6 +53,7 @@ export async function runGoalCli(args, {
       taskId: options.task ?? (taskAction ? positional[1] : positional[0]),
       status: options.status ?? taskAction ?? positional[1],
       blocker: options.reason,
+      effortWaiver: options["allow-inherited-effort"],
     });
     emit(JSON.stringify(state));
     return state;
@@ -68,7 +73,15 @@ export async function runGoalCli(args, {
       root,
       taskId: options.task ?? positional[0],
       agentId: options.agent ?? positional[1] ?? null,
+      effort: options.effort,
+      effortSource: options["effort-source"],
+      route: options.route,
+      effortWaiver: options["allow-inherited-effort"],
     });
+    const task = state.tasks.find((item) => item.id === String(options.task ?? positional[0]).trim());
+    if (task?.route === "heavy" && task.assignedAgentId && (!task.effort || task.effortSource === "not-applied")) {
+      stderr(`Cairn warning: Heavy task ${task.id} is assigned without an applied effort (effort ${task.effort ?? "none"}, source ${task.effortSource ?? "none"}); dispatch with the plan's effort and record --effort <level> --effort-source host-option.`);
+    }
     emit(JSON.stringify(state));
     return state;
   }
@@ -91,7 +104,7 @@ export async function runGoalCli(args, {
     const result = await operations.verifyAndRecord({
       root,
       taskId: options.task ?? positional[0],
-      kind: options.kind,
+      kind: splitValues(options.kind),
       scope: options.scope,
       watchPaths: splitValues(options.watch),
       argv: passthrough,
@@ -99,16 +112,41 @@ export async function runGoalCli(args, {
         ? 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,
+    const summaries = result.receipts.map((receipt) => ({
+      id: receipt.id,
+      scope: receipt.scope,
+      kind: receipt.kind,
+      exitCode: receipt.exitCode,
+      outputDigest: receipt.outputDigest,
+      workspaceFingerprint: receipt.workspaceFingerprint,
     }));
+    emit(JSON.stringify(summaries.length === 1 ? summaries[0] : summaries));
     return result.state;
   }
+  if (command === "finish") {
+    const state = await operations.finishGoal({
+      root,
+      watchPaths: splitValues(options.watch),
+      argv: passthrough,
+      timeoutMs: options["timeout-ms"] === undefined
+        ? 600_000
+        : positiveIntegerOption(options["timeout-ms"], "timeout-ms"),
+    });
+    emit(JSON.stringify({ id: state.goal.id, status: state.goal.status }));
+    return state;
+  }
+  if (command === "ready") {
+    const state = await operations.readGoalState({ root });
+    const ids = (status) => (state ? state.tasks.filter((task) => task.status === status).map((task) => task.id) : []);
+    const summary = { active: ids("active"), ready: operations.readyTasks(state).map((task) => task.id), blocked: ids("blocked") };
+    stdout(JSON.stringify(summary));
+    return summary;
+  }
+  if (command === "stats") {
+    const stats = operations.goalStats(await operations.readGoalState({ root }), root);
+    stdout(JSON.stringify(stats));
+    return stats;
+  }
   if (["pause", "resume", "block", "cancel", "complete"].includes(command)) {
     const state = await operations.transitionGoal({
       root,
@@ -118,7 +156,7 @@ export async function runGoalCli(args, {
     emit(JSON.stringify(state));
     return state;
   }
-  throw new Error("Usage: cairn-goal start|status|task|replan|claim|assign|receipt|verify|pause|resume|block|cancel|complete [--root PATH]");
+  throw new Error("Usage: cairn-goal start|status|ready|stats|task|replan|claim|assign|receipt|verify|finish|pause|resume|block|cancel|complete [--root PATH]");
 }
 
 function parseArgs(args, command) {
@@ -176,12 +214,15 @@ function allowedOptions(command) {
   const byCommand = {
     start: ["goal", "plan", "tasks", "criteria", "requiredEvidence", "session", "evidencePolicy", "evidence-policy"],
     status: [],
-    task: ["task", "status", "reason"],
+    task: ["task", "status", "reason", "allow-inherited-effort"],
     replan: ["tasks"],
     claim: ["session"],
-    assign: ["task", "agent"],
+    assign: ["task", "agent", "effort", "effort-source", "route", "allow-inherited-effort"],
     receipt: ["task", "kind", "scope", "command", "exitCode", "exit-code", "exit", "timestamp", "goalId", "goal-id", "plan"],
     verify: ["task", "kind", "scope", "watch", "timeout-ms"],
+    finish: ["watch", "timeout-ms"],
+    stats: [],
+    ready: [],
     pause: [],
     resume: [],
     block: ["reason"],

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

@@ -2,10 +2,11 @@ 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,
+  normalizeToolEvidence, pathContains, requiredText, timestamp, validReceiptCommand, validReceiptScope,
   validReceiptSource, validTimestamp,
 } from "./cairn-goal-state-validation.mjs";
-import { assertGoalMutable, mutateGoal, taskById } from "./cairn-goal-operations-mutations.mjs";
+import { assertGoalMutable, isReceiptFresh, mutateGoal, taskById } from "./cairn-goal-operations-mutations.mjs";
+import { setTaskStatus, transitionGoal } from "./cairn-goal-operations.mjs";
 
 export async function recordReceipt(options = {}) {
   if (options.source !== undefined && options.source !== "declared") throw new Error("Only goal verify can create tool evidence");
@@ -69,7 +70,7 @@ export async function verifyAndRecord({
   const normalizedArgv = normalizeVerificationArgv(argv);
   const normalizedWatchPaths = normalizeWatchPaths(root, watchPaths);
   const normalizedScope = validReceiptScope(scope);
-  const normalizedKind = requiredText(kind, "evidence kind");
+  const normalizedKinds = normalizeKinds(kind);
   const initialState = await readGoalState({ root });
   if (!initialState) throw new Error("No Cairn goal state exists; start a goal first");
   assertGoalMutable(initialState);
@@ -78,6 +79,7 @@ export async function verifyAndRecord({
   if (initialTask && !["active", "completed"].includes(initialTask.status)) {
     throw new Error(`Verification task must be active or completed: ${initialTask.id}`);
   }
+  assertParallelWatch(initialState, initialTask, normalizedWatchPaths);
   const identity = {
     goalId: initialState.goal.id,
     planId: initialState.goal.planId,
@@ -102,23 +104,104 @@ export async function verifyAndRecord({
       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) };
+  // One verification run may prove several evidence kinds; record one receipt per kind without rerunning it.
+  const receipts = [];
+  let state;
+  for (const normalizedKind of normalizedKinds) {
+    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,
+    });
+    receipts.push(state.receipts.at(-1));
+  }
+  return { state, evidence: receipts.at(-1), receipts };
+}
+
+// Completes the active task, proves every goal-level evidence kind with one run, and completes the goal.
+export async function finishGoal({
+  root = process.cwd(), argv = [], watchPaths = [], runner, timeoutMs = 600_000,
+} = {}) {
+  const initialState = await readGoalState({ root });
+  if (!initialState) throw new Error("No Cairn goal state exists; start a goal first");
+  assertGoalMutable(initialState);
+  const active = initialState.tasks.find((task) => task.status === "active");
+  const unfinished = initialState.tasks.filter((task) => task.status !== "completed" && task !== active);
+  if (unfinished.length > 0) {
+    throw new Error(`Goal cannot be finished while other tasks remain: ${unfinished.map((task) => task.id).join(", ")}`);
+  }
+  const goalKinds = initialState.goal.requiredEvidence;
+  if (goalKinds.length > 0) normalizeVerificationArgv(argv);
+  if (active) await setTaskStatus({ root, taskId: active.id, status: "completed" });
+  if (goalKinds.length > 0) {
+    await verifyAndRecord({ root, scope: "goal", kind: goalKinds, argv, watchPaths, runner, timeoutMs });
+  }
+  return transitionGoal({ root, status: "completed" });
+}
+
+// Overhead measurement: how many verifications ran, how many were reruns, and which latest receipts are stale.
+export function goalStats(state, root = process.cwd()) {
+  if (!state) return null;
+  const byKind = {};
+  const latest = new Map();
+  let reruns = 0;
+  for (const receipt of state.receipts) {
+    byKind[receipt.kind] = (byKind[receipt.kind] ?? 0) + 1;
+    const key = `${receipt.scope}\0${receipt.taskId ?? ""}\0${receipt.kind}`;
+    if (latest.has(key)) reruns += 1;
+    latest.set(key, receipt);
+  }
+  const stale = [...latest.values()]
+    .filter((receipt) => receipt.source === "tool" && !isReceiptFresh(root, receipt))
+    .map((receipt) => ({ scope: receipt.scope, ...(receipt.taskId ? { taskId: receipt.taskId } : {}), kind: receipt.kind }));
+  return {
+    goalId: state.goal.id,
+    status: state.goal.status,
+    receipts: state.receipts.length,
+    toolReceipts: state.receipts.filter((receipt) => receipt.source === "tool").length,
+    byKind,
+    reruns,
+    stale,
+    tasks: state.tasks.map((task) => ({
+      id: task.id,
+      status: task.status,
+      route: task.route ?? null,
+      effort: task.effort ?? null,
+      effortSource: task.effortSource ?? null,
+      ...(task.effortWaiver ? { effortWaiver: task.effortWaiver } : {}),
+    })),
+  };
+}
+
+// While other tasks run in parallel, an unscoped fingerprint would include their edits. Require a watch set,
+// and keep it inside the task's declared writeScope so sibling edits cannot stale or fail this evidence.
+function assertParallelWatch(state, task, watchPaths) {
+  const othersActive = state.tasks.filter((item) => item.status === "active" && item.id !== task?.id);
+  if (task ? othersActive.length === 0 : othersActive.length < 2) return;
+  if (watchPaths.length === 0) {
+    throw new Error(`Other tasks are active (${othersActive.map((item) => item.id).join(", ")}); pass --watch with this task's write scope`);
+  }
+  if (task?.writeScope) {
+    const outside = watchPaths.filter((path) => !task.writeScope.some((scope) => pathContains(scope, path)));
+    if (outside.length > 0) throw new Error(`--watch must stay inside task ${task.id} writeScope while other tasks are active: ${outside.join(", ")}`);
+  }
+}
+
+function normalizeKinds(kind) {
+  const kinds = (Array.isArray(kind) ? kind : [kind]).map((item) => requiredText(item, "evidence kind"));
+  if (kinds.length === 0) throw new Error("evidence kind is required");
+  return [...new Set(kinds)];
 }

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

@@ -20,8 +20,27 @@ export function ensureTaskCanComplete(state, task, root) {
 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(", ")}`);
+  const goalReceipts = state.goal.requiredEvidence.map((kind) => ensureCurrentEvidence({ state, root, scope: "goal", kind }));
+  // Task freshness was enforced when each task completed. Fresh goal-level evidence recorded after every task
+  // receipt supersedes it, so later edits do not force reruns of every earlier task's checks.
+  const lastTaskReceipt = state.receipts.findLastIndex((receipt) => receipt.scope === "task");
+  const superseded = goalReceipts.length > 0
+    && goalReceipts.every((receipt) => state.receipts.indexOf(receipt) > lastTaskReceipt);
+  if (superseded) {
+    for (const task of state.tasks) ensureTaskEvidenceExists(state, task);
+    return;
+  }
   for (const task of state.tasks) ensureTaskCanComplete(state, task, root);
-  for (const kind of state.goal.requiredEvidence) ensureCurrentEvidence({ state, root, scope: "goal", kind });
+}
+
+function ensureTaskEvidenceExists(state, task) {
+  for (const kind of task.requiredEvidence) {
+    const recorded = state.receipts.some((receipt) => (
+      receipt.scope === "task" && receipt.taskId === task.id && receipt.kind === kind
+      && (state.goal.evidencePolicy === "declared" || receipt.source === "tool")
+    ));
+    if (!recorded) throw new Error(`Task ${task.id} cannot be completed without tool-bound evidence record: ${kind}`);
+  }
 }
 
 function ensureCurrentEvidence({ state, root, scope, task, kind }) {
@@ -31,25 +50,40 @@ function ensureCurrentEvidence({ state, root, scope, task, kind }) {
   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;
+    return candidates.at(-1);
   }
   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;
+    if (isReceiptFresh(root, receipt)) return receipt;
   }
   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");
+export function isReceiptFresh(root, receipt) {
+  return receipt.source === "tool" && workspaceFingerprint(root, receipt.watchPaths) === receipt.workspaceFingerprint;
+}
+
+export function readyTasks(state) {
+  if (!state) return [];
+  const completed = new Set(state.tasks.filter((task) => task.status === "completed").map((task) => task.id));
+  return state.tasks.filter((task) => task.status === "pending" && task.dependsOn.every((id) => completed.has(id)));
+}
+
+// Keeps the goal moving after a task leaves "active": when nothing is active, activate the first ready task in
+// list order (the sequential behavior); when nothing is active or ready while work remains, block the goal.
+export function advanceGoal(state, preferredBlocker = null, { block = true } = {}) {
+  if (state.tasks.some((task) => task.status === "active")) return;
+  const next = readyTasks(state)[0];
   if (next) {
     next.status = "active";
     next.updatedAt = new Date().toISOString();
-    return true;
+    return;
   }
-  return false;
+  if (!block || state.tasks.every((task) => task.status === "completed")) return;
+  state.goal.status = "blocked";
+  state.goal.blocker = preferredBlocker ?? state.tasks.find((task) => task.status === "blocked")?.blocker
+    ?? "No task is ready: remaining tasks wait on unfinished dependencies";
 }
 
 export function assertGoalMutable(state) {

package/scripts/cairn-goal-operations.mjs

@@ -5,11 +5,12 @@ 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,
+  assertCanBeActive, assertEffortRecord, assertTaskGraph,
   defaultGoalEvidence, normalizeCriteria, normalizeTask, optionalText, requiredText,
-  terminalGoalStatuses, timestamp, validEvidencePolicy, validGoalStatus, validTaskStatus, validateState,
+  terminalGoalStatuses, timestamp, validEvidencePolicy, validGoalStatus, validTaskRoute, validTaskStatus, validateState,
 } from "./cairn-goal-state-validation.mjs";
 import {
-  activateNextPendingTask, assertGoalMutable, ensureGoalCanComplete, ensureTaskCanComplete,
+  advanceGoal, assertGoalMutable, ensureGoalCanComplete, ensureTaskCanComplete,
   mutateGoal, taskById,
 } from "./cairn-goal-operations-mutations.mjs";
 
@@ -44,7 +45,8 @@ export async function startGoal({ root = process.cwd(), goal, planId, tasks, com
       throw new Error(`An unfinished Cairn goal already exists (${existing.goal.id}, ${existing.goal.status}); add the new work to it with goal replan (resume it first if paused or blocked), or cancel or complete it before starting another goal`);
     }
     const now = timestamp();
-    const normalizedTasks = tasks.map((task, index) => normalizeTask(task, index, index === 0 ? "active" : "pending"));
+    const normalizedTasks = normalizeTaskList(tasks, []);
+    assertTaskGraph(normalizedTasks);
     for (const task of normalizedTasks) assertRecoveryReferenceBudget(normalizedPlanId, task.id);
     const state = {
       schemaVersion: GOAL_STATE_VERSION,
@@ -66,6 +68,7 @@ export async function startGoal({ root = process.cwd(), goal, planId, tasks, com
       tasks: normalizedTasks,
       receipts: [],
     };
+    advanceGoal(state);
     await writeGoalStateUnlocked({ root, state });
     return state;
   });
@@ -112,31 +115,33 @@ function applyGoalTransition(state, nextStatus, blocker, root) {
   if (nextStatus === "active") state.goal.blocker = null;
   state.goal.status = nextStatus;
   state.goal.updatedAt = timestamp();
+  if (nextStatus === "active" && currentStatus === "blocked") advanceGoal(state, null, { block: false });
   return state;
 }
 
-export async function setTaskStatus({ root = process.cwd(), taskId, status, blocker } = {}) {
+export async function setTaskStatus({ root = process.cwd(), taskId, status, blocker, effortWaiver } = {}) {
   const nextStatus = validTaskStatus(status);
   const normalizedTaskId = requiredText(taskId, "taskId");
+  const normalizedWaiver = optionalText(effortWaiver, "effortWaiver");
+  if (normalizedWaiver !== null && nextStatus !== "completed") throw new Error("--allow-inherited-effort applies only when completing a task");
   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`);
+      assertCanBeActive(state.tasks, task, state.tasks.filter((item) => item.id !== task.id && item.status === "active"));
+    }
+    if (nextStatus === "completed") {
+      if (normalizedWaiver !== null) task.effortWaiver = normalizedWaiver;
+      ensureHeavyEffortApplied(task);
+      ensureTaskCanComplete(state, task, root);
     }
-    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;
-    }
+    if (nextStatus === "completed" || nextStatus === "blocked") advanceGoal(state, nextStatus === "blocked" ? task.blocker : null);
     state.goal.updatedAt = timestamp();
     return state;
   });
@@ -149,20 +154,34 @@ export async function replanGoal({ root = process.cwd(), tasks } = {}) {
     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;
-    });
+    const replacementTasks = normalizeTaskList(
+      tasks.map((task) => (typeof task === "string" ? task : { ...task, status: undefined, blocker: undefined })),
+      completedTasks,
+    );
+    for (const task of replacementTasks) {
+      if (completedIds.has(task.id)) throw new Error(`Replanned task conflicts with completed task id: ${task.id}`);
+    }
     state.tasks = [...completedTasks, ...replacementTasks];
+    assertTaskGraph(state.tasks);
     state.receipts = state.receipts.filter((receipt) => receipt.scope === "task" && completedIds.has(receipt.taskId));
     state.goal.blocker = null;
     state.goal.updatedAt = timestamp();
+    advanceGoal(state);
     return state;
   });
 }
 
+// Normalizes tasks as pending; an omitted dependsOn follows the previous task across completed + new tasks.
+function normalizeTaskList(tasks, precedingTasks) {
+  let previousId = precedingTasks.at(-1)?.id ?? null;
+  const normalized = tasks.map((task, index) => {
+    const result = normalizeTask(task, index, "pending", previousId);
+    previousId = result.id;
+    return result;
+  });
+  return normalized;
+}
+
 export async function claimGoal({ root = process.cwd(), sessionId } = {}) {
   const normalizedSessionId = requiredText(sessionId, "sessionId");
   return mutateGoal(root, (state) => {
@@ -173,13 +192,41 @@ export async function claimGoal({ root = process.cwd(), sessionId } = {}) {
   });
 }
 
-export async function assignTask({ root = process.cwd(), taskId, agentId = null } = {}) {
+// A Heavy task delegated to a worker must record the effort the host actually applied; a missing, not-applied, or
+// inherited effort needs an explicit waiver reason. Unassigned (main-agent) and Light tasks are not checked.
+function ensureHeavyEffortApplied(task) {
+  if (task.route !== "heavy" || !task.assignedAgentId || task.effortWaiver) return;
+  const source = task.effortSource ?? null;
+  if (task.effort && source !== "not-applied" && source !== "inherited") return;
+  throw new Error(`Heavy task ${task.id} assigned to ${task.assignedAgentId} has no applied effort (effort ${task.effort ?? "none"}, source ${source ?? "none"}); record goal assign ${task.id} --effort <low|medium|high|xhigh|max> --effort-source host-option, or complete with --allow-inherited-effort <reason>`);
+}
+
+// Omitted effort/route/waiver options keep stored values, so a reassignment can change only the agent. When effort
+// or effortSource is given, both are replaced together; an omitted source is inferred from the effort.
+export async function assignTask({
+  root = process.cwd(), taskId, agentId = null, effort, effortSource, route, effortWaiver,
+} = {}) {
   const normalizedTaskId = requiredText(taskId, "taskId");
   const normalizedAgentId = agentId === null ? null : requiredText(agentId, "agentId");
+  const effortGiven = effort !== undefined || effortSource !== undefined;
+  const normalizedEffort = effort ?? null;
+  const normalizedSource = effortSource ?? (normalizedEffort === null ? null : normalizedEffort === "inherited" ? "inherited" : "host-option");
+  if (effortGiven) {
+    if (normalizedEffort === null && normalizedSource !== "not-applied") throw new Error("--effort-source requires --effort unless it is not-applied");
+    assertEffortRecord(normalizedEffort, normalizedSource, "assign");
+  }
+  const normalizedRoute = route === undefined ? undefined : validTaskRoute(route);
+  const normalizedWaiver = effortWaiver === undefined ? undefined : requiredText(effortWaiver, "effortWaiver");
   return mutateGoal(root, (state) => {
     assertGoalMutable(state);
     const task = taskById(state, normalizedTaskId);
     task.assignedAgentId = normalizedAgentId;
+    if (effortGiven) {
+      task.effort = normalizedEffort;
+      task.effortSource = normalizedSource;
+    }
+    if (normalizedRoute !== undefined) task.route = normalizedRoute;
+    if (normalizedWaiver !== undefined) task.effortWaiver = normalizedWaiver;
     task.updatedAt = timestamp();
     state.goal.updatedAt = timestamp();
     return state;

package/scripts/cairn-goal-policy.mjs

@@ -1,6 +1,9 @@
+import { readyTasks } from "./cairn-goal-operations-mutations.mjs";
+
 export function currentTask(state) {
   if (!state) return null;
   return state.tasks.find((task) => task.status === "active")
+    ?? readyTasks(state)[0]
     ?? state.tasks.find((task) => task.status === "pending")
     ?? state.tasks.find((task) => task.status === "blocked")
     ?? null;
@@ -23,14 +26,37 @@ export function evaluateStop(state, { subagent = false, agentId } = {}) {
     };
   }
   if (subagent) {
-    if (!agentId || task.assignedAgentId !== agentId) return { block: false };
+    // Parallel workers each own a task; gate on the stopping agent's own unfinished task, not the first active one.
+    const assigned = !agentId ? null
+      : state.tasks.find((item) => item.status === "active" && item.assignedAgentId === agentId)
+        ?? (task.assignedAgentId === agentId ? task : null);
+    if (!assigned) return { block: false };
+    return {
+      block: true,
+      reason: `Cairn task ${assigned.id} (${assigned.title}) is assigned to this subagent and is ${assigned.status}. Continue only this assigned task, record a successful evidence record, then hand off.${effortWarning([assigned])}`,
+    };
+  }
+  const active = state.tasks.filter((item) => item.status === "active");
+  if (active.length > 1) {
+    const list = active.map((item) => `${item.id} (${clip(item.title, 40)})`).join(", ");
     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.`,
+      reason: `Cairn goal "${state.goal.title}" is active with parallel tasks ${list}. Collect or continue each one; record successful evidence before marking a task complete.${effortWarning(active)}`,
     };
   }
   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.`,
+    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.${effortWarning(active)}`,
   };
 }
+
+// Delegated work must record the effort the host applied; flag assigned tasks whose effort source is still empty.
+function effortWarning(tasks) {
+  const ids = tasks.filter((item) => item.assignedAgentId && !item.effortSource).map((item) => item.id);
+  return ids.length === 0 ? "" : ` Effort unrecorded for assigned task ${ids.join(", ")}: record goal assign --effort/--effort-source.`;
+}
+
+function clip(value, maxLength) {
+  const text = String(value ?? "");
+  return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
+}