cairn-ai 0.2.2 → 0.2.3

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

@@ -29,7 +29,7 @@ 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.

package/docs/model-guidance/codex.md

@@ -42,7 +42,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.3",
   "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,9 +2,10 @@
 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"]);
@@ -34,7 +35,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;
@@ -48,44 +51,51 @@ export async function startGoal({ root = process.cwd(), goal, planId, tasks, com
   const normalizedPlanId = requiredText(planId, "planId");
   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"));
+    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 +185,8 @@ async function recordEvidence({
   summary,
   workspaceFingerprint: fingerprint,
   watchPaths = [],
+  expectedIdentity,
+  expectedFingerprint,
 } = {}) {
   const normalizedScope = validReceiptScope(scope);
   const normalizedTaskId = normalizedScope === "task" ? requiredText(taskId, "taskId") : undefined;
@@ -189,6 +201,16 @@ 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
+    )) 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 +241,7 @@ export async function verifyAndRecord({
   argv,
   watchPaths = [],
   runner = spawnSync,
+  timeoutMs = 600_000,
 } = {}) {
   const normalizedArgv = validArgv(argv);
   const normalizedWatchPaths = normalizeWatchPaths(root, watchPaths);
@@ -228,13 +251,23 @@ 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 && initialTask.status !== "active") throw new Error(`Verification task must be active: ${initialTask.id}`);
+  const identity = {
+    goalId: initialState.goal.id,
+    planId: initialState.goal.planId,
+    taskId: normalizedTaskId,
+    taskStatus: initialTask?.status,
+  };
+  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 +278,14 @@ 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" && taskById(postState, normalizedTaskId).status !== identity.taskStatus) {
+    throw new Error("Verification task is no longer active; evidence was not recorded");
+  }
   const command = normalizedArgv.map((value) => JSON.stringify(value)).join(" ");
   const state = await recordEvidence({
     root,
@@ -259,6 +300,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 +357,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 +405,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 +419,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,12 +444,14 @@ 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) {
@@ -786,11 +834,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 +855,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 +928,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 {