cairn-ai 0.2.2 → 0.2.4

package/agents/worker.md

@@ -10,6 +10,8 @@ Handle narrow, focused tasks.
 
 Before doing any assigned task, read the project-root `MEMORY.md`. Treat it as the domain knowledge and repository policy index, then read only the relevant `docs/memory/*.md` notes needed for the task.
 
+At the start and after compaction, restart, or handoff, restore context in this order: root `MEMORY.md` → the phase skill named by the assignment → the active plan → current-task references → model guidance recorded by that plan. The assignment must identify the plan and current task whenever persisted work is active. If a required reference is missing, unreadable, or inconsistent with the assignment or goal state, report a blocker and do not edit, delegate, or claim completion.
+
 When subagent tools are available, you may recursively delegate bounded sub-tasks to subagents. Every child subagent must read the project-root `MEMORY.md`, keep the assigned scope, and preserve others' edits.
 
 Use for:

package/commands/cairn-doctor.md

@@ -8,15 +8,17 @@ Run from the published or global package:
 bunx cairn-ai@latest doctor
 ```
 
+The doctor validates the custom marketplace installation and ownership manifest without repairing it. Diagnostics are read-only; rollback is performed only by lifecycle transaction recovery.
+
 Checks:
 
 - Source plugin manifest.
 - Codex cached installation.
 - Marketplace file.
 - Hook manifest link in the installed copy.
-- `features.plugins`, `features.plugin_hooks`, `features.multi_agent`.
-- `agents.max_depth`.
-- `cairn@cairn` plugin enabled.
+- ownership manifest presence and managed destination digests.
+- `cairn@cairn` installed/enabled/version from the actual Codex CLI.
+- effective Codex plugin/hook/multi-agent feature state (reported, never forced).
 - hook trust state.
 - Claude Code commands and agents mirror files.
 - Antigravity IDE/CLI skills and workflows mirror files.

package/commands/cairn-install.md

@@ -8,14 +8,15 @@ Run from the published or global package, not from the installed cache copy:
 bunx cairn-ai@latest install
 ```
 
-The current custom lifecycle remains in use. Do not invoke lifecycle install/upgrade from the cached plugin root because that copy is the replacement target.
+The current custom marketplace lifecycle remains in use; this is not a migration to `codex plugin add`. Do not invoke lifecycle install/upgrade from the cached plugin root because that copy is the replacement target.
 
 Actions:
 
-- Copy the Cairn installation into the Codex marketplace cache.
+- Stage and validate the Cairn installation, then transactionally commit the custom marketplace source and versioned runtime cache.
 - Add the `hooks/hooks.json` link to the installed manifest.
-- Register marketplace, plugin, and hook trust state in `~/.codex/config.toml`.
+- Register only Cairn-owned marketplace, plugin, and hook trust sections in `~/.codex/config.toml`; do not rewrite public feature or agent settings.
 - Install `cairn-*` commands and agents mirror files for Claude Code.
 - Install `cairn-*` skills and workflows mirror files for Antigravity IDE/CLI.
 - Write runtime locators so all mirrors resolve scripts, templates, and model guidance from the installed plugin root.
-- Create `*.cairn-backup-*` backups before changing settings.
+- Record every managed destination and digest in the ownership manifest under the custom marketplace, and rollback committed phases in reverse order on failure.
+- Adopt an exact, unmodified supported legacy install only after release-integrity validation; preserve and reject modified or unknown artifacts.

package/commands/cairn-uninstall.md

@@ -8,11 +8,15 @@ Run from the published or global package:
 bunx cairn-ai@latest uninstall
 ```
 
-Removed items:
+The custom marketplace ownership manifest is authoritative. Uninstall removes or restores only destinations whose current digest still matches the recorded installed digest; modified or unmanaged targets are preserved as conflicts. A failure rolls back the transaction.
+
+Managed items:
 
 - Cairn marketplace, plugin, and hook trust state blocks in `~/.codex/config.toml`.
 - `~/.codex/plugins/cache/cairn`.
 - Claude Code `cairn-*` commands and agents mirror files.
 - Antigravity IDE/CLI `cairn-*` skills and workflows mirror files.
 
-The source work folder is not deleted.
+After the transaction commits, Cairn removes empty managed scaffold directories bottom-up and removes the custom marketplace root only after releasing its own lifecycle lock. A directory containing any unmanaged child is preserved; pruning never uses recursive deletion.
+
+The source work folder and repository `MEMORY.md`, `PLAN.md`, `docs/`, and `.cairn/state.json` are not deleted. The globally installed `cairn-ai` package, package-manager download caches, legacy backup files, and legacy shared settings not recorded by the current ownership manifest are also outside this command's scope and require a separate, explicit cleanup decision.

package/commands/cairn-upgrade.md

@@ -8,13 +8,13 @@ Run from the published or global package, not from the installed cache copy:
 bunx cairn-ai@latest upgrade
 ```
 
-The current custom lifecycle remains in use. The cached plugin root is a replacement target and must not upgrade itself.
+The current custom marketplace lifecycle remains in use. The cached plugin root is a replacement target and must not upgrade itself.
 
 Actions:
 
-- Replace the Cairn installation in the Codex cache.
-- Recompute hook trust state and update settings.
-- Overwrite Claude Code mirror files with the latest content.
-- Overwrite Antigravity IDE/CLI skills and workflows mirror files with the latest content.
+- Replace only files tracked by the ownership manifest whose current digest still matches the installed digest.
+- Recompute Cairn-owned hook trust state without rewriting public feature or agent settings.
+- Replace owned Claude Code and Antigravity mirror files with the latest content.
 - Refresh runtime locators for every installed surface.
-- Create `*.cairn-backup-*` backups before changing settings.
+- Stage and validate all candidates before commit; rollback committed phases in reverse order on failure.
+- Preserve and report a conflict for modified, unmanaged, or invalid legacy artifacts.

package/commands/cairn-work.md

@@ -19,9 +19,9 @@ Procedure:
 9. Give implementation the test contract, failing evidence, exact file ownership, and constraints. Require minimal implementation and no repeated broad discovery. Preserve status, final-report, close-and-review, recursive bounded delegation, and main-agent fallback rules.
 10. Treat tool exit codes and bounded summaries as authoritative. Keep success output concise; expand only the failing test and related code context.
 11. For Heavy Path, run the recorded automated test command and record explicit `Tests:` evidence.
-12. Run focused module acceptance, then one final surface integration check through `goal verify -- ...` so the tool exit code, bounded output, and watched-workspace fingerprint are recorded together.
+12. Run focused module acceptance, then one final surface integration check through `goal verify -- ...`. Verification defaults to 600,000 ms (10 minutes), may be shortened with `--timeout-ms`, and is capped at 3,600,000 ms (1 hour). The command runs without holding the state lock; evidence is recorded only if the starting goal/task identity and the pre/post watched fingerprint still match.
 13. Before package verification, inspect package lifecycle scripts. Run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it when the prior full check remains fresh.
-14. Record evidence bound to goal/task/plan. Missing, failed, skipped, stale, or placeholder evidence never completes work; relevant mutation invalidates affected evidence.
+14. Record evidence at the semantic boundary that proves the claimed behavior, bound to goal/task/plan. Missing, failed, skipped, stale, or placeholder evidence never completes work; relevant mutation invalidates affected evidence.
 15. Complete the task and continue the goal. Use `--quiet` on successful state mutations; workers report only their assigned task and never select the next one.
 16. Update the plan, goal state, and `PLAN.md` only after evidence exists.
 17. Answer side questions briefly and resume unless explicitly asked to pause, stop, or switch.

package/docs/model-guidance/README.md

@@ -14,6 +14,7 @@ The goal is not to make prompts long by model. The goal is to stabilize the same
 
 ## Common Rules
 
+- On every fresh entry, compaction recovery, restart, delegation, or handoff, restore context in this order: root `MEMORY.md` → current phase skill → active plan → current-task references → model guidance recorded by the plan. If persisted state or an assignment requires a reference that is missing, unreadable, or inconsistent, fail closed: do not edit, delegate, approve, or complete; report or record a blocker.
 - Keep root `MEMORY.md` and `PLAN.md` as indexes only.
 - Keep repository-specific judgment in `docs/memory/` and `docs/plan/`. Keep Cairn's model guidance in the installed plugin and reference it with `cairn://docs/model-guidance/...`.
 - Preserve proper nouns, file names, variable names, service names, alert names, MCP tool names, and agent names exactly as written.
@@ -29,13 +30,22 @@ The goal is not to make prompts long by model. The goal is to stabilize the same
 - Treat missing, failed, skipped, stale, or placeholder evidence as failure. Task evidence records must be bound to the current goal, task, and plan.
 - Treat the repository Cairn state as the fail-closed transition authority. Advance the matching Codex UI plan step only after the evidence-gated repository task transition succeeds.
 - Spend reasoning on a focused executable test contract before implementation: requirements, invariants, boundaries, and failure modes. Give implementation only that contract, failing evidence, file scope, and constraints; require the minimum passing change.
-- Run verification through `goal verify -- ...`; treat tool exit codes and bounded machine summaries as authoritative. Compress success output and expand context only for failing tests and related code. The exact argv, output digest, and watched-workspace fingerprint make stale evidence fail closed.
+- Run verification through `goal verify -- ...`; its default timeout is 600,000 ms and its maximum is 3,600,000 ms. Treat tool exit codes and bounded machine summaries as authoritative. Record evidence only when the starting goal/task identity and pre/post watched fingerprint still match, and choose the watch set and command at the semantic boundary that proves the claim. Compress success output and expand context only for failing tests and related code.
 - Use a verification ladder: focused contract tests, one full check after the final change, then package dry-run while the full check remains fresh. Inspect package lifecycle scripts first and run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it.
 - Every implementation task must pass module acceptance verification and surface integration verification.
 - Before mutating external state, run the closest available dry-run, check, plan, diff, validate, or equivalent command.
 - Limit each task to two verification passes by default. After two failed passes, record the blocker or split it into sub-tasks instead of continuing a repeated loop.
 - User-visible responses and generated or updated documentation, plans, and memory artifacts must follow the OS locale unless the user asks for another language.
 
+## Prompt Cache Shape
+
+- Keep `.codex-plugin/plugin.json` `defaultPrompt` as a small, stable policy and recovery kernel. Put detailed bootstrap, delegation, test, package, and verification procedures in the phase skills and this installed guidance.
+- Put static instructions before dynamic goal data. Hook capsules must be deterministic for the same locale, event, and persisted state; prompt text and turn IDs must not change their content.
+- Idle capsules reference root `MEMORY.md` and `cairn-plan`; active-work capsules reference the active plan, current task, and `cairn-work`; all-tasks-complete capsules reference `cairn-review`.
+- A foreign session receives only a generic ownership-conflict capsule on session/prompt events. It must not expose goal, plan, or task details, and it must not make stop hooks block work owned by another session.
+- Character budgets are regression proxies for cache-friendly prompt shape, not measurements of provider cache hits or cost. Cairn does not require provider cache keys, breakpoints, or live API telemetry.
+- Do not add read receipts that claim model attention. Restore references on every re-entry and use readable state plus fresh bound evidence as the enforceable contract.
+
 ## Delegation Defaults
 
 - `explorer`: use for read-only codebase discovery, impact analysis, pattern searches, and read-only verification when available.

package/docs/model-guidance/codex.md

@@ -17,6 +17,7 @@ Codex-family models are strong at small implementation tasks, explicit tool use,
 
 ## Adjustment Rules
 
+- On every fresh entry, compaction recovery, restart, delegation, or handoff, restore root `MEMORY.md` → current phase skill → active plan → current-task references → recorded model guidance. If persisted state or the assignment requires a missing, unreadable, or inconsistent reference, fail closed and report a blocker before editing, delegating, approving, or completing.
 - Do not start implementation without a plan.
 - 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.
@@ -26,6 +27,7 @@ Codex-family models are strong at small implementation tasks, explicit tool use,
 - Do not skip LSP, typecheck, lint, dry-run, or verification because a tool is missing. Try repository-local installation or record the failed install attempt as a blocker.
 - Do not continue an open-ended verification loop. Use at most two verification passes per task unless the plan records a risk-based exception.
 - Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
+- Preserve the stable prompt prefix: keep detailed workflow in phase skills/model guidance, and do not vary a hook capsule with prompt text or turn ID when persisted state is unchanged.
 
 ## Path Guidance
 
@@ -42,7 +44,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 -- ...`. On success, retain exact argv, tool exit code, pass count, output digest, and watched-workspace fingerprint. 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. 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.2",
+  "version": "0.2.4",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity",
   "license": "MIT",
   "author": {
@@ -39,7 +39,7 @@
     "README.*.md"
   ],
   "scripts": {
-    "check": "node --check scripts/cairn.mjs && node --check scripts/cairn-paths.mjs && node --check scripts/cairn-goal.mjs && node --check scripts/cairn-state.mjs && node --check scripts/cairn-lifecycle.mjs && node --check scripts/cairn-toolcheck.mjs && node -e \"JSON.parse(require('node:fs').readFileSync('package.json','utf8')); JSON.parse(require('node:fs').readFileSync('.codex-plugin/plugin.json','utf8')); JSON.parse(require('node:fs').readFileSync('hooks/hooks.json','utf8'))\" && npm test",
+    "check": "node --check scripts/cairn.mjs && node --check scripts/cairn-paths.mjs && node --check scripts/cairn-safe-fs.mjs && node --check scripts/cairn-goal.mjs && node --check scripts/cairn-state.mjs && node --check scripts/cairn-lifecycle.mjs && node --check scripts/cairn-toolcheck.mjs && node -e \"JSON.parse(require('node:fs').readFileSync('package.json','utf8')); JSON.parse(require('node:fs').readFileSync('.codex-plugin/plugin.json','utf8')); JSON.parse(require('node:fs').readFileSync('hooks/hooks.json','utf8')); JSON.parse(require('node:fs').readFileSync('scripts/release-integrity-0.2.2.json','utf8'))\" && npm test",
     "test": "node --test",
     "prepack": "npm run check"
   },

package/scripts/cairn-goal.mjs

@@ -2,13 +2,17 @@
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { lstatSync, readFileSync, readlinkSync, realpathSync, readdirSync } from "node:fs";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { readFile, rename, rm } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { assertNoSymlinkComponents, safeMkdir, safeWriteFile, withStateLock } from "./cairn-safe-fs.mjs";
 
 export const GOAL_STATE_VERSION = 2;
 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;
+export const TASK_ID_MAX_LENGTH = 64;
+export const RECOVERY_REFERENCE_MAX_LENGTH = 160;
 
 const terminalGoalStatuses = new Set(["cancelled", "completed"]);
 const evidencePolicies = new Set(["declared", "tool-bound"]);
@@ -34,7 +38,9 @@ export function goalStatePath(root = process.cwd()) {
 
 export async function readGoalState({ root = process.cwd() } = {}) {
   try {
-    const text = await readFile(goalStatePath(root), "utf8");
+    const path = goalStatePath(root);
+    await assertNoSymlinkComponents(root, path);
+    const text = await readFile(path, "utf8");
     return validateState(migrateState(JSON.parse(text)));
   } catch (error) {
     if (error?.code === "ENOENT") return null;
@@ -45,47 +51,55 @@ export async function readGoalState({ root = process.cwd() } = {}) {
 
 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 = requiredText(planId, "planId");
+  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");
 
-  const existing = await readGoalState({ root });
-  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`);
-  }
+  return withStateLock(root, async () => {
+    const existing = await readGoalState({ root });
+    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 goalId = `goal-${randomUUID()}`;
-  const normalizedTasks = tasks.map((task, index) => normalizeTask(task, index, index === 0 ? "active" : "pending"));
-  const state = {
-    schemaVersion: GOAL_STATE_VERSION,
-    revision: 1,
-    goal: {
-      id: goalId,
-      title: normalizedGoal,
-      planId: normalizedPlanId,
-      status: "active",
-      completionCriteria: normalizeCriteria(completionCriteria),
-      requiredEvidence: normalizeCriteria(requiredEvidence),
-      evidencePolicy: validEvidencePolicy(evidencePolicy),
-      ownerSessionId: optionalText(ownerSessionId, "ownerSessionId"),
-      blocker: null,
-      createdAt: now,
-      updatedAt: now,
-    },
-    tasks: normalizedTasks,
-    receipts: [],
-  };
-  await writeGoalState({ root, state });
-  return state;
+    const now = timestamp();
+    const goalId = `goal-${randomUUID()}`;
+    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: goalId,
+        title: normalizedGoal,
+        planId: normalizedPlanId,
+        status: "active",
+        completionCriteria: normalizeCriteria(completionCriteria),
+        requiredEvidence: normalizeCriteria(requiredEvidence),
+        evidencePolicy: validEvidencePolicy(evidencePolicy),
+        ownerSessionId: optionalText(ownerSessionId, "ownerSessionId"),
+        blocker: null,
+        createdAt: now,
+        updatedAt: now,
+      },
+      tasks: normalizedTasks,
+      receipts: [],
+    };
+    await writeGoalStateUnlocked({ root, state });
+    return state;
+  });
 }
 
 export async function writeGoalState({ root = process.cwd(), state } = {}) {
+  return withStateLock(root, () => writeGoalStateUnlocked({ root, state }));
+}
+
+async function writeGoalStateUnlocked({ root = process.cwd(), state } = {}) {
   const validated = validateState(state);
   const path = goalStatePath(root);
-  await mkdir(dirname(path), { recursive: true });
+  await safeMkdir(root, ".cairn");
+  await assertNoSymlinkComponents(root, path);
   const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
   try {
-    await writeFile(temporaryPath, `${JSON.stringify(validated, null, 2)}\n`, "utf8");
+    await safeWriteFile(root, temporaryPath, `${JSON.stringify(validated, null, 2)}\n`, "utf8");
     await rename(temporaryPath, path);
   } catch (error) {
     await rm(temporaryPath, { force: true }).catch(() => {});
@@ -175,6 +189,8 @@ async function recordEvidence({
   summary,
   workspaceFingerprint: fingerprint,
   watchPaths = [],
+  expectedIdentity,
+  expectedFingerprint,
 } = {}) {
   const normalizedScope = validReceiptScope(scope);
   const normalizedTaskId = normalizedScope === "task" ? requiredText(taskId, "taskId") : undefined;
@@ -189,6 +205,18 @@ async function recordEvidence({
   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 = {
@@ -219,6 +247,7 @@ export async function verifyAndRecord({
   argv,
   watchPaths = [],
   runner = spawnSync,
+  timeoutMs = 600_000,
 } = {}) {
   const normalizedArgv = validArgv(argv);
   const normalizedWatchPaths = normalizeWatchPaths(root, watchPaths);
@@ -228,13 +257,26 @@ export async function verifyAndRecord({
   if (!initialState) throw new Error("No Cairn goal state exists; start a goal first");
   assertGoalMutable(initialState);
   const normalizedTaskId = normalizedScope === "task" ? requiredText(taskId, "taskId") : undefined;
-  if (normalizedScope === "task") taskById(initialState, normalizedTaskId);
+  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 initialFingerprint = workspaceFingerprint(root, normalizedWatchPaths);
   const result = runner(normalizedArgv[0], normalizedArgv.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);
@@ -245,6 +287,17 @@ export async function verifyAndRecord({
 
   const outputDigest = sha256(output);
   const fingerprint = workspaceFingerprint(root, normalizedWatchPaths);
+  if (fingerprint !== initialFingerprint) throw new Error("Watched workspace changed during verification; evidence was not recorded");
+  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 command = normalizedArgv.map((value) => JSON.stringify(value)).join(" ");
   const state = await recordEvidence({
     root,
@@ -259,6 +312,10 @@ export async function verifyAndRecord({
     summary: successSummary(output),
     workspaceFingerprint: fingerprint,
     watchPaths: normalizedWatchPaths,
+    goalId: identity.goalId,
+    planId: identity.planId,
+    expectedIdentity: identity,
+    expectedFingerprint: fingerprint,
   });
   return { state, evidence: state.receipts.at(-1) };
 }
@@ -312,7 +369,7 @@ export function evaluateStop(state, { subagent = false, agentId } = {}) {
 export async function handleGoalCli(args = process.argv.slice(2), { stdout = console.log } = {}) {
   const [firstCommand = "help", ...remaining] = args;
   const [command = "help", ...rest] = firstCommand === "goal" ? remaining : [firstCommand, ...remaining];
-  const { options, positional, passthrough } = parseArgs(rest);
+  const { options, positional, passthrough } = parseArgs(rest, command);
   const root = options.root ?? process.cwd();
   const emit = options.quiet ? () => {} : stdout;
   if (command === "start") {
@@ -360,7 +417,7 @@ export async function handleGoalCli(args = process.argv.slice(2), { stdout = con
       command: options.command,
       exitCode: numberOption(options.exitCode ?? options["exit-code"] ?? options.exit),
       timestamp: options.timestamp,
-      goalId: options.goalId,
+      goalId: options.goalId ?? options["goal-id"],
       planId: options.plan,
     });
     emit(JSON.stringify(state));
@@ -374,6 +431,7 @@ export async function handleGoalCli(args = process.argv.slice(2), { stdout = con
       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,
@@ -398,18 +456,20 @@ export async function handleGoalCli(args = process.argv.slice(2), { stdout = con
 }
 
 async function mutateGoal(root, mutate) {
-  const state = await readGoalState({ 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 writeGoalState({ root, state: next });
-  return next;
+  return withStateLock(root, async () => {
+    const state = await readGoalState({ 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;
+  });
 }
 
 function normalizeTask(task, index, defaultStatus) {
   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}` : requiredText(source.id, `tasks[${index}].id`);
+  const id = source.id === undefined ? `task-${index + 1}` : boundedRequiredText(source.id, `tasks[${index}].id`, TASK_ID_MAX_LENGTH);
   const title = requiredText(source.title, `tasks[${index}].title`);
   return {
     id,
@@ -447,7 +507,7 @@ function validateState(value) {
   const goal = value.goal;
   requiredText(goal.id, "goal.id");
   requiredText(goal.title, "goal.title");
-  requiredText(goal.planId, "goal.planId");
+  const planId = boundedRequiredText(goal.planId, "goal.planId", PLAN_ID_MAX_LENGTH);
   validGoalStatus(goal.status);
   validEvidencePolicy(goal.evidencePolicy);
   validTimestamp(goal.createdAt);
@@ -463,7 +523,8 @@ function validateState(value) {
   let activeTasks = 0;
   for (const task of value.tasks) {
     if (!task || typeof task !== "object") throw new Error("Each task must be an object");
-    requiredText(task.id, "task.id");
+    const taskId = boundedRequiredText(task.id, "task.id", TASK_ID_MAX_LENGTH);
+    assertRecoveryReferenceBudget(planId, taskId);
     if (ids.has(task.id)) throw new Error(`Duplicate task id: ${task.id}`);
     ids.add(task.id);
     requiredText(task.title, "task.title");
@@ -574,6 +635,19 @@ function requiredText(value, label) {
   return value.trim();
 }
 
+function boundedRequiredText(value, label, maxLength) {
+  const text = requiredText(value, label);
+  if (value !== text) throw new Error(`${label} must not have leading or trailing whitespace`);
+  if (text.length > maxLength) throw new Error(`${label} must be at most ${maxLength} characters`);
+  return text;
+}
+
+function assertRecoveryReferenceBudget(planId, taskId) {
+  if (planId.length + taskId.length > RECOVERY_REFERENCE_MAX_LENGTH) {
+    throw new Error(`planId and taskId must total at most ${RECOVERY_REFERENCE_MAX_LENGTH} characters for exact recovery context`);
+  }
+}
+
 function validGoalStatus(value) {
   if (!GOAL_STATUSES.has(value)) throw new Error(`Invalid goal status: ${value}`);
   return value;
@@ -786,11 +860,13 @@ function timestamp() {
   return new Date().toISOString();
 }
 
-function parseArgs(args) {
+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 === "--") {
@@ -805,13 +881,54 @@ function parseArgs(args) {
     const equalsIndex = option.indexOf("=");
     const key = equalsIndex === -1 ? option : option.slice(0, equalsIndex);
     const inline = equalsIndex === -1 ? undefined : option.slice(equalsIndex + 1);
-    if (inline !== undefined) options[key] = booleanOptions.has(key) ? inline !== "false" : inline;
+    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 options[key] = args[++index];
+    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"],
+    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");
@@ -837,6 +954,19 @@ function numberOption(value) {
   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 validTimeout(value) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new Error("timeoutMs must be a positive integer");
+  return value;
+}
+
 function isCliEntry() {
   if (!process.argv[1]) return false;
   try {