cairn-ai 0.2.9 → 0.3.0

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, assertTaskGraph,
   defaultGoalEvidence, normalizeCriteria, normalizeTask, optionalText, requiredText,
   terminalGoalStatuses, timestamp, validEvidencePolicy, validGoalStatus, 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,6 +115,7 @@ 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;
 }
 
@@ -124,19 +128,14 @@ export async function setTaskStatus({ root = process.cwd(), taskId, status, bloc
     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") 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 +148,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) => {

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,10 +26,22 @@ 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 ${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 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.`,
+    };
+  }
+  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 goal "${state.goal.title}" is active with parallel tasks ${list}. Collect or continue each one; record successful evidence before marking a task complete.`,
     };
   }
   return {
@@ -34,3 +49,8 @@ export function evaluateStop(state, { subagent = false, agentId } = {}) {
     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.`,
   };
 }
+
+function clip(value, maxLength) {
+  const text = String(value ?? "");
+  return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
+}

package/scripts/cairn-goal-state-validation.mjs

@@ -1,6 +1,7 @@
 import { normalizeVerificationArgv } from "./cairn-goal-evidence.mjs";
 
-export const GOAL_STATE_VERSION = 2;
+export const GOAL_STATE_VERSION = 3;
+export const MAX_ACTIVE_TASKS = 4;
 export const GOAL_STATUSES = new Set(["active", "paused", "blocked", "cancelled", "completed"]);
 export const TASK_STATUSES = new Set(["pending", "active", "blocked", "completed"]);
 export const PLAN_ID_MAX_LENGTH = 128;
@@ -43,7 +44,6 @@ export function validateState(value) {
   if (!Array.isArray(value.tasks) || value.tasks.length === 0) throw new Error("Cairn goal state must contain tasks");
   if (!Array.isArray(value.receipts)) throw new Error("Cairn goal state evidence records (receipts) must be an array");
   const ids = new Set();
-  let activeTasks = 0;
   for (const task of value.tasks) {
     if (!task || typeof task !== "object") throw new Error("Each task must be an object");
     const taskId = boundedRequiredText(task.id, "task.id", TASK_ID_MAX_LENGTH);
@@ -52,7 +52,8 @@ export function validateState(value) {
     ids.add(task.id);
     requiredText(task.title, "task.title");
     validTaskStatus(task.status);
-    if (task.status === "active") activeTasks += 1;
+    if (!Array.isArray(task.dependsOn)) throw new Error(`task ${task.id} dependsOn must be an array`);
+    if (task.writeScope !== null && !Array.isArray(task.writeScope)) throw new Error(`task ${task.id} writeScope must be an array or null`);
     if (task.assignedAgentId !== null && task.assignedAgentId !== undefined) requiredText(task.assignedAgentId, "task.assignedAgentId");
     if (!Array.isArray(task.requiredEvidence) || task.requiredEvidence.length === 0) throw new Error(`task ${task.id} requiredEvidence must be a non-empty array`);
     task.requiredEvidence.forEach((kind, index) => requiredText(kind, `task ${task.id} requiredEvidence[${index}]`));
@@ -60,7 +61,9 @@ export function validateState(value) {
     validTimestamp(task.createdAt);
     validTimestamp(task.updatedAt);
   }
-  if (activeTasks > 1) throw new Error("Only one task may be active");
+  assertTaskGraph(value.tasks);
+  const active = value.tasks.filter((task) => task.status === "active");
+  for (const task of active) assertCanRunAlongside(task, active.filter((other) => other !== task));
   for (const receipt of value.receipts) validateReceipt(receipt, value);
   return value;
 }
@@ -86,7 +89,9 @@ function validateReceipt(receipt, state) {
   }
 }
 
-export function normalizeTask(task, index, defaultStatus) {
+// dependsOn omitted means "after the previous task in list order" so existing sequential plans keep their order;
+// an explicit [] means no dependency.
+export function normalizeTask(task, index, defaultStatus, previousTaskId = null) {
   const source = typeof task === "string" ? { title: task } : task;
   if (!source || typeof source !== "object") throw new Error(`tasks[${index}] must be a string or object`);
   const id = source.id === undefined ? `task-${index + 1}` : boundedRequiredText(source.id, `tasks[${index}].id`, TASK_ID_MAX_LENGTH);
@@ -97,6 +102,12 @@ export function normalizeTask(task, index, defaultStatus) {
     status: source.status === undefined ? defaultStatus : validTaskStatus(source.status),
     assignedAgentId: source.assignedAgentId === undefined || source.assignedAgentId === null ? null : requiredText(source.assignedAgentId, `tasks[${index}].assignedAgentId`),
     requiredEvidence: normalizeCriteria(source.requiredEvidence ?? defaultTaskEvidence),
+    dependsOn: source.dependsOn === undefined
+      ? (previousTaskId === null ? [] : [previousTaskId])
+      : normalizeDependsOn(source.dependsOn, `tasks[${index}].dependsOn`),
+    writeScope: source.writeScope === undefined || source.writeScope === null
+      ? null
+      : normalizeWriteScope(source.writeScope, `tasks[${index}].writeScope`),
     blocker: null,
     createdAt: timestamp(),
     updatedAt: timestamp(),
@@ -104,13 +115,103 @@ export function normalizeTask(task, index, defaultStatus) {
 }
 
 export function migrateState(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value) || value.schemaVersion !== 1) return value;
-  return {
-    ...value,
-    schemaVersion: GOAL_STATE_VERSION,
-    goal: { ...value.goal, evidencePolicy: value.goal?.evidencePolicy ?? "tool-bound" },
-    receipts: Array.isArray(value.receipts) ? value.receipts.map((receipt) => ({ ...receipt, source: "declared" })) : value.receipts,
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  let state = value;
+  if (state.schemaVersion === 1) {
+    state = {
+      ...state,
+      schemaVersion: 2,
+      goal: { ...state.goal, evidencePolicy: state.goal?.evidencePolicy ?? "tool-bound" },
+      receipts: Array.isArray(state.receipts) ? state.receipts.map((receipt) => ({ ...receipt, source: "declared" })) : state.receipts,
+    };
+  }
+  if (state.schemaVersion === 2) {
+    // v2 tasks ran strictly in list order; make that order explicit as previous-task dependencies.
+    state = {
+      ...state,
+      schemaVersion: 3,
+      tasks: Array.isArray(state.tasks)
+        ? state.tasks.map((task, index) => ({
+          ...task,
+          dependsOn: index === 0 ? [] : [state.tasks[index - 1]?.id],
+          writeScope: null,
+        }))
+        : state.tasks,
+    };
+  }
+  return state;
+}
+
+export function normalizeDependsOn(value, label) {
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array of task ids`);
+  return [...new Set(value.map((item, index) => boundedRequiredText(item, `${label}[${index}]`, TASK_ID_MAX_LENGTH)))];
+}
+
+export function normalizeWriteScope(value, label) {
+  if (!Array.isArray(value) || value.length === 0) throw new Error(`${label} writeScope must be a non-empty array of repository paths`);
+  return [...new Set(value.map((item, index) => {
+    const path = requiredText(item, `${label}[${index}]`).replace(/\\/g, "/").replace(/\/{2,}/g, "/")
+      .replace(/^(\.\/)+/, "").replace(/\/+$/, "");
+    if (/[*?[\]{}]/.test(path)) throw new Error(`${label} writeScope must list literal paths, not globs: ${item}`);
+    if (path === "" || path === "." || path.startsWith("/") || /^[a-zA-Z]:/.test(path) || path.split("/").includes("..")) {
+      throw new Error(`${label} writeScope must stay inside the repository: ${item}`);
+    }
+    return path;
+  }))];
+}
+
+// Segment-wise prefix match, case-insensitive so case-insensitive filesystems cannot hide an overlap.
+export function writeScopesOverlap(left, right) {
+  return left.some((a) => right.some((b) => pathContains(a, b) || pathContains(b, a)));
+}
+
+export function pathContains(scope, path) {
+  const outer = scope.toLowerCase();
+  const inner = path.toLowerCase();
+  return inner === outer || inner.startsWith(`${outer}/`);
+}
+
+export function assertTaskGraph(tasks) {
+  const byId = new Map();
+  for (const task of tasks) {
+    if (byId.has(task.id)) throw new Error(`Duplicate task id: ${task.id}`);
+    byId.set(task.id, task);
+  }
+  for (const task of tasks) {
+    for (const dependency of task.dependsOn) {
+      if (dependency === task.id) throw new Error(`Task ${task.id} cannot depend on itself`);
+      if (!byId.has(dependency)) throw new Error(`Task ${task.id} depends on unknown task: ${dependency}`);
+    }
+  }
+  const visiting = new Set();
+  const done = new Set();
+  const visit = (task, path) => {
+    if (done.has(task.id)) return;
+    if (visiting.has(task.id)) throw new Error(`Task dependency cycle: ${[...path, task.id].join(" -> ")}`);
+    visiting.add(task.id);
+    for (const dependency of task.dependsOn) visit(byId.get(dependency), [...path, task.id]);
+    visiting.delete(task.id);
+    done.add(task.id);
   };
+  for (const task of tasks) visit(task, []);
+}
+
+// Throws unless task may be active next to otherActive: dependencies completed, under the cap, and disjoint
+// writeScopes. A task without writeScope may only run alone.
+export function assertCanBeActive(tasks, task, otherActive) {
+  const waiting = task.dependsOn.filter((id) => tasks.find((item) => item.id === id)?.status !== "completed");
+  if (waiting.length > 0) throw new Error(`Task ${task.id} is waiting for: ${waiting.join(", ")}`);
+  assertCanRunAlongside(task, otherActive);
+}
+
+function assertCanRunAlongside(task, otherActive) {
+  if (otherActive.length === 0) return;
+  if (otherActive.length + 1 > MAX_ACTIVE_TASKS) throw new Error(`Only at most ${MAX_ACTIVE_TASKS} active tasks are allowed`);
+  if (task.writeScope === null) throw new Error(`Task ${task.id} without writeScope cannot run alongside active task ${otherActive[0].id}`);
+  for (const other of otherActive) {
+    if (other.writeScope === null) throw new Error(`Task ${task.id} cannot run alongside active task ${other.id} without writeScope`);
+    if (writeScopesOverlap(task.writeScope, other.writeScope)) throw new Error(`Task ${task.id} writeScope overlaps active task ${other.id}`);
+  }
 }
 
 export function requiredText(value, label) {
@@ -145,7 +246,7 @@ export function validTaskStatus(value) {
 }
 
 export function validReceiptScope(value) {
-  if (value !== "task" && value !== "goal") throw new Error(`Invalid evidence scope: ${value}`);
+  if (value !== "task" && value !== "goal") throw new Error(`Invalid evidence scope: ${value} (allowed: task, goal)`);
   return value;
 }
 

package/scripts/cairn-goal-state.mjs

@@ -18,12 +18,24 @@ export async function readGoalState({ root = process.cwd() } = {}) {
 }
 
 export function stopGuardPath(root = process.cwd()) {
-  return join(goalStateDirectory(root), "stop-guard.json");
+  return hookGuardPath(root, "stop");
+}
+
+export function hookGuardPath(root = process.cwd(), name) {
+  return join(goalStateDirectory(root), `${name}-guard.json`);
 }
 
 export async function readStopGuard(root = process.cwd()) {
+  return readHookGuard(root, "stop");
+}
+
+export async function writeStopGuard(root = process.cwd(), value) {
+  return writeHookGuard(root, "stop", value);
+}
+
+export async function readHookGuard(root = process.cwd(), name) {
   try {
-    const path = stopGuardPath(root);
+    const path = hookGuardPath(root, name);
     await assertNoSymlinkComponents(cairnHome(), path);
     const value = JSON.parse(await readFile(path, "utf8"));
     return value && typeof value === "object" ? value : null;
@@ -32,11 +44,11 @@ export async function readStopGuard(root = process.cwd()) {
   }
 }
 
-export async function writeStopGuard(root = process.cwd(), value) {
+export async function writeHookGuard(root = process.cwd(), name, value) {
   try {
-    await safeWriteFile(cairnHome(), stopGuardPath(root), `${JSON.stringify(value)}\n`, "utf8");
+    await safeWriteFile(cairnHome(), hookGuardPath(root, name), `${JSON.stringify(value)}\n`, "utf8");
   } catch {
-    // The guard only prevents no-progress continuation loops; failing to persist it must not break the stop hook.
+    // Guards only deduplicate hook output; failing to persist one must not break the hook.
   }
 }
 

package/scripts/cairn-goal.mjs

@@ -3,8 +3,9 @@ import { realpathSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { runGoalCli } from "./cairn-goal-cli.mjs";
 import { assignTask, claimGoal, replanGoal, setTaskStatus, startGoal, transitionGoal } from "./cairn-goal-operations.mjs";
-import { recordReceipt, verifyAndRecord } from "./cairn-goal-operations-evidence.mjs";
+import { finishGoal, goalStats, recordReceipt, verifyAndRecord } from "./cairn-goal-operations-evidence.mjs";
 import { readGoalState } from "./cairn-goal-state.mjs";
+import { readyTasks } from "./cairn-goal-operations-mutations.mjs";
 import { defaultGoalEvidence } from "./cairn-goal-state-validation.mjs";
 
 export { workspaceFingerprint } from "./cairn-goal-evidence.mjs";
@@ -20,8 +21,9 @@ export {
 } from "./cairn-goal-state-validation.mjs";
 export { goalStatePath, readGoalState, writeGoalState } from "./cairn-goal-state.mjs";
 export { assignTask, claimGoal, reconcileWorktreeState, replanGoal, setTaskStatus, startGoal, transitionGoal } from "./cairn-goal-operations.mjs";
-export { recordReceipt, verifyAndRecord } from "./cairn-goal-operations-evidence.mjs";
+export { finishGoal, goalStats, recordReceipt, verifyAndRecord } from "./cairn-goal-operations-evidence.mjs";
 export { currentTask, evaluateStop, isGoalOwnedBySession } from "./cairn-goal-policy.mjs";
+export { readyTasks } from "./cairn-goal-operations-mutations.mjs";
 
 export async function handleGoalCli(args = process.argv.slice(2), { stdout = console.log } = {}) {
   return runGoalCli(args, {
@@ -30,7 +32,10 @@ export async function handleGoalCli(args = process.argv.slice(2), { stdout = con
     operations: {
       assignTask,
       claimGoal,
+      finishGoal,
+      goalStats,
       readGoalState,
+      readyTasks,
       recordReceipt,
       replanGoal,
       setTaskStatus,

package/scripts/cairn-state-context.mjs

@@ -3,6 +3,7 @@ const contextLimits = {
   roadmapTaskId: 24,
   taskTitle: 40,
   roadmapWindow: 3,
+  parallelTitle: 16,
 };
 
 export function prependContext(result, notice) {
@@ -21,6 +22,8 @@ export function prependContext(result, notice) {
   };
 }
 
+import { currentTask } from "./cairn-goal-policy.mjs";
+
 export function contextResult({ ko, state, event }) {
   const base = kernelBase(ko);
   const idlePolicy = event === "user-prompt-submit"
@@ -37,9 +40,7 @@ export function contextResult({ ko, state, event }) {
     return interruptedContextResult(event, ko, state);
   }
   if (!state || state.goal.status !== "active") return contextHookResult({ event, message: `${base}${idlePolicy}${failClosed}` });
-  const task = state.tasks.find((item) => item.status === "active")
-    ?? state.tasks.find((item) => item.status === "pending")
-    ?? state.tasks.find((item) => item.status === "blocked");
+  const task = currentTask(state);
   const planId = state.goal.planId;
   const phase = task ? "cairn-work" : "cairn-review";
   const activeHeader = ko
@@ -69,7 +70,15 @@ export function contextResult({ ko, state, event }) {
         ? `곁가지 질문·조향 뒤 ${taskId}를 재개하고 남은 task를 최종 검토까지 진행하세요(일시정지·중단·전환 요청 제외).`
         : `After a side question or steer, resume ${taskId}, then advance remaining tasks to final review unless asked to pause, stop, or switch.`))
     : "";
-  return contextHookResult({ event, message: [activeHeader, taskRoadmap(ko, state), continuation, resume].filter(Boolean).join("\n") });
+  return contextHookResult({ event, message: [activeHeader, taskRoadmap(ko, state), continuation, parallelLine(ko, state), resume].filter(Boolean).join("\n") });
+}
+
+// Only when several tasks run at once: their ids and clipped titles, never the dependency graph.
+function parallelLine(ko, state) {
+  const active = state.tasks.filter((task) => task.status === "active");
+  if (active.length < 2) return "";
+  const list = active.map((task) => `${clipText(task.id, contextLimits.roadmapTaskId)} (${clipText(task.title, contextLimits.parallelTitle)})`).join(", ");
+  return `${ko ? "병렬 active" : "Parallel active"}: ${list}`;
 }
 
 function kernelBase(ko) {

package/scripts/cairn-state.mjs

@@ -5,7 +5,7 @@ import { contextResult, foreignSessionContextResult, prependContext } from "./ca
 import { continuationReason, stopAllowedMessage, stopHookOutput } from "./cairn-state-hook.mjs";
 import { initializeProject } from "./cairn-state-init.mjs";
 import { evaluateStop, isGoalOwnedBySession, reconcileWorktreeState } from "./cairn-goal.mjs";
-import { readStopGuard, writeStopGuard } from "./cairn-goal-state.mjs";
+import { readHookGuard, readStopGuard, writeHookGuard, writeStopGuard } from "./cairn-goal-state.mjs";
 import { resolveRepoRoot } from "./cairn-paths.mjs";
 
 const recoverableGoalStatuses = new Set(["active", "paused", "blocked"]);
@@ -52,7 +52,10 @@ export async function runStateResult(event = "manual", {
     if (recoverableGoalStatuses.has(state?.goal?.status) && !isGoalOwnedBySession(state, payload?.session_id)) {
       return foreignSessionContextResult({ ko, event, sessionId: payload?.session_id, root: resolvedRoot });
     }
-    const result = contextResult({ ko, state, event });
+    const context = contextResult({ ko, state, event });
+    // SessionStart (also after compaction) carries a literal CLI prefix so agents do not rebuild or store it in a
+    // shell variable, which does not survive between tool calls.
+    const result = event === "session-start" ? appendContext(context, cliPrefixLine()) : context;
     if (!reconciled.removed) return result;
     const notice = ko
       ? "Cairn worktree 점검: 현재 worktree에 속하지 않는 stale Cairn 상태를 제거했습니다."
@@ -67,6 +70,19 @@ export async function runStateResult(event = "manual", {
     if (state?.goal?.status !== "active" || !isGoalOwnedBySession(state, payload?.session_id)) {
       return { status: 0, message: "", hookOutput: {} };
     }
+    // Remind once per goal, task, and session; repeating it after every edit only grows the cached prefix.
+    const reminderKey = {
+      goalId: state.goal.id,
+      taskId: state.tasks.find((task) => task.status === "active")?.id ?? null,
+      sessionId: payload?.session_id ?? null,
+    };
+    const previousReminder = await readHookGuard(resolvedRoot, "reminder");
+    if (previousReminder?.goalId === reminderKey.goalId
+      && previousReminder?.taskId === reminderKey.taskId
+      && previousReminder?.sessionId === reminderKey.sessionId) {
+      return { status: 0, message: "", hookOutput: {} };
+    }
+    await writeHookGuard(resolvedRoot, "reminder", reminderKey);
     const message = ko
       ? "Cairn 점검: 외부 상태 변경에는 dry-run/check 증거 기록이 필요합니다. 활성 목표가 있다면 현재 task에 성공 증거를 기록하세요."
       : "Cairn check: external-state changes need dry-run/check evidence. When a goal is active, record successful evidence for its current task.";
@@ -106,14 +122,40 @@ export async function runStateResult(event = "manual", {
 
 async function recordStopProgress(root, state, event, payload) {
   const scope = event === "subagent-stop" ? `subagent:${payload?.agent_id ?? ""}` : "turn";
+  // Parallel workers share this guard: keep one entry per scope, and measure a worker's progress by its own task
+  // so sibling writes (which bump the goal revision) do not look like progress.
+  const assigned = event === "subagent-stop"
+    ? state.tasks.find((task) => task.status === "active" && task.assignedAgentId === payload?.agent_id)
+    : null;
+  const marker = assigned ? `${assigned.id}:${assigned.status}:${assigned.updatedAt}` : state.revision;
   const previous = await readStopGuard(root);
-  const progressed = previous?.goalId !== state.goal.id
-    || previous?.scope !== scope
-    || previous?.revision !== state.revision;
-  if (progressed) await writeStopGuard(root, { goalId: state.goal.id, scope, revision: state.revision });
+  const scopes = previous?.goalId === state.goal.id && previous?.scopes && typeof previous.scopes === "object" ? previous.scopes : {};
+  const progressed = scopes[scope] !== marker;
+  if (progressed) {
+    const entries = Object.entries({ ...scopes, [scope]: marker }).slice(-16);
+    await writeStopGuard(root, { goalId: state.goal.id, scopes: Object.fromEntries(entries) });
+  }
   return progressed;
 }
 
+// Only the CLI path: goal commands resolve the repository root themselves, and a second absolute path would let
+// long install or checkout paths push the SessionStart capsule past its budget.
+function cliPrefixLine() {
+  const cli = fileURLToPath(new URL("./cairn.mjs", import.meta.url));
+  return `Cairn CLI: node ${JSON.stringify(cli)} goal <command>`;
+}
+
+function appendContext(result, line) {
+  const specific = result.hookOutput?.hookSpecificOutput;
+  return {
+    ...result,
+    message: `${result.message}\n${line}`,
+    hookOutput: specific
+      ? { ...result.hookOutput, hookSpecificOutput: { ...specific, additionalContext: `${specific.additionalContext}\n${line}` } }
+      : result.hookOutput,
+  };
+}
+
 function hookFailureResult(event, error) {
   const detail = String(error?.message ?? error).split("\n")[0].slice(0, 300);
   const message = `Cairn ${event} hook could not read goal state: ${detail}. Run cairn goal status to inspect it; do not treat an active goal as finished.`;