cairn-ai 0.4.1 → 0.6.0

package/docs/model-guidance/README.md

@@ -51,7 +51,7 @@ The goal is not to make prompts long by model. The goal is to stabilize the same
 ## Model and Reasoning Effort Routing
 
 - The plan decides each task's model from its nature and records `Requested model` and `Effective model`; models are not always inherited. Tiers: fast = read-only exploration, search, inventory, summarization (Claude Code `haiku`); balanced = Light Path implementation and routine verification (`sonnet`); stronger = planning, complexity triage, Heavy Path implementation, review, and final verification/review (`opus`); strongest = Heavy Path design only (`fable`), run as a separate `kind: "design"` task dispatched to that tier rather than part of planning. Antigravity `invoke_subagent` `Model` accepts only a tier enum (fast `flash_lite`, balanced `flash`, stronger `pro`, strongest `pro`; no tier above `pro`) and has no effort option, so Effective reasoning effort is `inherited`. Codex slugs: fast `gpt-6-luna`, balanced `gpt-6.1-terra`, stronger `gpt-6-sol`, strongest `gpt-6-astra`.
-- Model Effective: passed and not rejected is that value; not passed is `not-applied: <reason>`; `inherited` only when the host has no model option. If a lower-tier worker fails a gate, re-dispatch that task one tier up (fast, balanced, stronger, strongest) before recording a blocker.
+- Model Effective: the passed value plus the exact model ID the worker reports from its own system prompt (e.g. `fable (claude-fable-5-1)`; `<value> (unreported)` when absent, never guess; `goal assign --effective-model <id|unreported>`); not passed is `not-applied: <reason>`; `inherited` only when the host has no model option. If a lower-tier worker fails a gate, re-dispatch that task one tier up (fast, balanced, stronger, strongest) before recording a blocker. A subagent's model and effort are fixed at dispatch; any re-dispatch that changes either (one tier up, Light → Heavy promotion, route-change recalculation) MUST be a new dispatch (Claude Code: a new Agent call), never `SendMessage` to the existing subagent. A design model that is not the host's strongest tier (`--host claude-code` `fable`, `codex` `gpt-6-astra`, `antigravity` `pro`; any of the three when `--host` is omitted) fails completion unless `--allow-no-design-model <reason>`.
 - Routing is per dispatch only; never change model or global/user config files. `Model routing: inherited` in `MEMORY.md` or the plan disables per-task selection.
 - Light Path planning, implementation, and verification request `medium`.
 - Heavy Path planning, review, and implementation request `high`; final verification and review request `xhigh`.

package/docs/model-guidance/claude.md

@@ -18,7 +18,7 @@ Claude-family models are strong at long-context retention, policy interpretation
 - Do not skip the two verification gates even on Light Path.
 - Do not approve a plan that lacks dry-run or check evidence for external-state-changing work.
 - Do not allow open-ended verification loops. Require a blocker or sub-task split after two failed passes.
-- Choose the model per task (fast `haiku`, balanced `sonnet`, stronger `opus`: planning, triage, Heavy implementation, review, final verification/review; strongest `fable`: Heavy design only, as a separate `kind: "design"` task dispatched to that tier rather than part of planning) and record `Requested model`/`Effective model`; Effective is the passed value, `not-applied: <reason>`, or `inherited` when the host has no model option. Re-dispatch one tier up (fast, balanced, stronger, strongest) if a lower-tier worker fails a gate. `Model routing: inherited` disables this. `Requested reasoning effort` is Cairn's desired profile; `Effective reasoning effort` is what the dispatch response confirms. Every new task/worker dispatch MUST pass the task's requested effort through the host option together with the chosen model; recording without passing is a defect. Effective is the requested value when the dispatch passed it and the host did not reject it, `not-applied: <reason>` when it was not passed, and `inherited` only when the host exposes no effort option. Infer capability only from the exposed interface or dispatch response, distinguish Cairn non-integration from host non-support, and change no global/user configuration.
+- Choose the model per task (fast `haiku`, balanced `sonnet`, stronger `opus`: planning, triage, Heavy implementation, review, final verification/review; strongest `fable`: Heavy design only, as a separate `kind: "design"` task dispatched to that tier rather than part of planning) and record `Requested model`/`Effective model`; Effective is the passed value plus the exact model ID the worker reports from its own system prompt (`<value> (unreported)` when absent, never guess), `not-applied: <reason>`, or `inherited` when the host has no model option. Re-dispatch one tier up (fast, balanced, stronger, strongest) if a lower-tier worker fails a gate. A subagent's model and effort are fixed at dispatch; any re-dispatch that changes either (one tier up, Light → Heavy promotion, route-change recalculation) MUST be a new dispatch (Claude Code: a new Agent call), never `SendMessage` to the existing subagent. A design model that is not the host's strongest tier (`--host claude-code` `fable`, `codex` `gpt-6-astra`, `antigravity` `pro`; any of the three when `--host` is omitted) fails completion unless `--allow-no-design-model <reason>`. `Model routing: inherited` disables this. `Requested reasoning effort` is Cairn's desired profile; `Effective reasoning effort` is what the dispatch response confirms. Every new task/worker dispatch MUST pass the task's requested effort through the host option together with the chosen model; recording without passing is a defect. Effective is the requested value when the dispatch passed it and the host did not reject it, `not-applied: <reason>` when it was not passed, and `inherited` only when the host exposes no effort option. Infer capability only from the exposed interface or dispatch response, distinguish Cairn non-integration from host non-support, and change no global/user configuration.
 - In Claude Code, pass model with the Agent tool `model` parameter (`haiku|sonnet|opus|fable`) and effort with `effort` (`low|medium|high|xhigh|max`, same as Cairn values), for example `{"description": "Implement task-1", "subagent_type": "general-purpose", "model": "sonnet", "effort": "medium", "prompt": "..."}`. `subagent_type: "fork"` ignores `model` and `effort`; never dispatch routed work as a fork.
 - On Heavy Path, check plan gaps before implementation.
 - Review all three complexity records: the provisional request checkpoint, post-exploration planning checkpoint, and code checkpoint after exact file/caller/test inspection immediately before the first edit. Before editing, evidence may change either route. Every change must synchronize the plan artifact, repository goal task roadmap through `goal replan`, and native UI plan, including reviews and required evidence. After editing begins, a new Heavy signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-ai",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity",
   "license": "MIT",
   "author": {

package/scripts/cairn-cleanup.mjs

@@ -1,11 +1,17 @@
 #!/usr/bin/env node
-import { lstat, readdir, rm, rmdir } from "node:fs/promises";
+import { constants, readFileSync } from "node:fs";
+import { lstat, open, readdir, rm, rmdir } from "node:fs/promises";
+import { hostname } from "node:os";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { reconcileWorktreeState } from "./cairn-goal.mjs";
-import { parseRootArgs } from "./cairn-paths.mjs";
+import { resolvePluginRoot, resolveRepoRoot } from "./cairn-paths.mjs";
+import { lockOwnerIsDead, parseLockRecord } from "./cairn-safe-fs.mjs";
 
-const staleLockName = /^state\.lock\.stale\..+\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const staleLockPrefix = "state.lock.stale.";
+const staleLockName = /^state\.lock\.stale\.(.+)\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const MAX_LOCK_RECORD_BYTES = 4096;
+const usage = "Usage: cairn cleanup [--root PATH] [--check | --yes]";
 
 export async function cleanupProjectCairn({ root = process.cwd(), apply = false } = {}) {
   const repoRoot = resolve(root);
@@ -14,7 +20,9 @@ export async function cleanupProjectCairn({ root = process.cwd(), apply = false
   try {
     rootStat = await lstat(legacyRoot);
   } catch (error) {
-    if (error?.code === "ENOENT") return { root: repoRoot, apply, known: [], unknown: [], removed: [], projectDirectoryRemoved: false };
+    if (error?.code === "ENOENT") {
+      return { root: repoRoot, apply, known: [], unknown: [], removed: [], projectDirectoryRemoved: false, preservedReasons: {} };
+    }
     throw error;
   }
   if (rootStat.isSymbolicLink()) throw new Error(`Legacy Cairn root must not be a symbolic link: ${legacyRoot}`);
@@ -23,21 +31,42 @@ export async function cleanupProjectCairn({ root = process.cwd(), apply = false
   const entries = await readdir(legacyRoot, { withFileTypes: true });
   const known = [];
   const unknown = [];
+  const preservedReasons = {};
   for (const entry of entries) {
-    const isKnownFile = entry.isFile() && (entry.name === "state.json" || entry.name === "state.lock" || staleLockName.test(entry.name));
+    if (entry.isFile() && isLockFileName(entry.name)) {
+      // Lock files are Cairn-owned only when their content is a lock record that may be removed.
+      const reason = await lockFileReason(join(legacyRoot, entry.name), entry.name);
+      if (reason === null) known.push(entry.name);
+      else {
+        unknown.push(entry.name);
+        preservedReasons[entry.name] = reason;
+      }
+      continue;
+    }
+    const isKnownFile = entry.isFile() && entry.name === "state.json";
     const isKnownDirectory = entry.isDirectory() && entry.name === "tools";
     (isKnownFile || isKnownDirectory ? known : unknown).push(entry.name);
   }
-  if (!apply) return { root: repoRoot, apply, known: known.sort(), unknown: unknown.sort(), removed: [], projectDirectoryRemoved: false };
+  if (!apply) return cleanupResult({ repoRoot, apply, known, unknown, removed: [], projectDirectoryRemoved: false, preservedReasons });
 
   if (known.includes("state.json")) await reconcileWorktreeState({ root: repoRoot });
   const removed = [];
-  for (const name of known) {
+  for (const name of [...known]) {
     const path = join(legacyRoot, name);
     try {
       const stat = await lstat(path);
       const expectedType = name === "tools" ? stat.isDirectory() : stat.isFile();
       if (!expectedType) continue;
+      if (isLockFileName(name)) {
+        // Judge the lock again right before removal; a lock that changed owner is preserved.
+        const reason = await lockFileReason(path, name);
+        if (reason !== null) {
+          known.splice(known.indexOf(name), 1);
+          unknown.push(name);
+          preservedReasons[name] = reason;
+          continue;
+        }
+      }
       await rm(path, { recursive: name === "tools", force: true });
       removed.push(name);
     } catch (error) {
@@ -51,17 +80,115 @@ export async function cleanupProjectCairn({ root = process.cwd(), apply = false
   } catch (error) {
     if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error?.code)) throw error;
   }
-  return { root: repoRoot, apply, known: known.sort(), unknown: unknown.sort(), removed: removed.sort(), projectDirectoryRemoved };
+  return cleanupResult({ repoRoot, apply, known, unknown, removed, projectDirectoryRemoved, preservedReasons });
+}
+
+function cleanupResult({ repoRoot, apply, known, unknown, removed, projectDirectoryRemoved, preservedReasons }) {
+  return {
+    root: repoRoot,
+    apply,
+    known: known.sort(),
+    unknown: unknown.sort(),
+    removed: removed.sort(),
+    projectDirectoryRemoved,
+    preservedReasons: Object.fromEntries(Object.keys(preservedReasons).sort().map((name) => [name, preservedReasons[name]])),
+  };
+}
+
+function isLockFileName(name) {
+  return name === "state.lock" || name.startsWith(staleLockPrefix);
+}
+
+// Returns null when the lock file may be removed, otherwise the reason it is preserved.
+async function lockFileReason(path, name) {
+  let nonce = null;
+  if (name !== "state.lock") {
+    const match = staleLockName.exec(name);
+    if (!match) return "invalid-lock-record";
+    nonce = match[1];
+  }
+  const record = await readLockRecord(path);
+  if (!record) return "invalid-lock-record";
+  if (nonce !== null) return record.nonce === nonce ? null : "invalid-lock-record";
+  if (lockOwnerIsDead(record)) return null;
+  return record.hostname === hostname() ? "live-lock-owner" : "foreign-host-lock";
+}
+
+async function readLockRecord(path) {
+  let handle;
+  try {
+    // Never follow a link or block on a special file that replaced the inspected entry.
+    handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > MAX_LOCK_RECORD_BYTES) return null;
+    const buffer = Buffer.alloc(MAX_LOCK_RECORD_BYTES + 1);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    if (bytesRead > MAX_LOCK_RECORD_BYTES) return null;
+    return parseLockRecord(buffer.subarray(0, bytesRead).toString("utf8"));
+  } catch {
+    return null;
+  } finally {
+    await handle?.close();
+  }
+}
+
+class CleanupUsageError extends Error {}
+
+function parseCleanupArgs(args) {
+  const provided = new Set();
+  let explicitRoot = null;
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (["--help", "--version", "--check", "--yes"].includes(argument)) {
+      if (provided.has(argument)) throw new CleanupUsageError(`${argument} may only be provided once`);
+      provided.add(argument);
+    } else if (argument === "--root" || argument.startsWith("--root=")) {
+      if (explicitRoot !== null) throw new CleanupUsageError("--root may only be provided once");
+      const value = argument === "--root" ? args[index + 1] : argument.slice("--root=".length);
+      if (!value || value.startsWith("--")) throw new CleanupUsageError("--root requires a path");
+      explicitRoot = value;
+      if (argument === "--root") index += 1;
+    } else {
+      throw new CleanupUsageError(`unknown option: ${argument}`);
+    }
+  }
+  if (provided.has("--help") && provided.has("--version")) throw new CleanupUsageError("--help and --version cannot be used together");
+  if (provided.has("--check") && provided.has("--yes")) throw new CleanupUsageError("--check and --yes cannot be used together");
+  const action = provided.has("--help") ? "help" : provided.has("--version") ? "version" : "cleanup";
+  return { action, explicitRoot, apply: provided.has("--yes") };
+}
+
+async function main(args) {
+  let options;
+  try {
+    options = parseCleanupArgs(args);
+  } catch (error) {
+    console.error(`Cairn cleanup error: ${firstLine(error)}`);
+    process.exitCode = 2;
+    return;
+  }
+  if (options.action === "help") {
+    console.log(usage);
+    return;
+  }
+  if (options.action === "version") {
+    const { version } = JSON.parse(readFileSync(join(resolvePluginRoot(import.meta.url), "package.json"), "utf8"));
+    console.log(`cairn ${version}`);
+    return;
+  }
+  try {
+    const repoRoot = resolveRepoRoot({ explicitRoot: options.explicitRoot });
+    console.log(JSON.stringify(await cleanupProjectCairn({ root: repoRoot, apply: options.apply }), null, 2));
+  } catch (error) {
+    console.error(`Cairn cleanup error: ${firstLine(error)}`);
+    process.exitCode = 1;
+  }
 }
 
-async function main() {
-  const { args, repoRoot } = parseRootArgs(process.argv.slice(2));
-  const apply = args.includes("--yes");
-  const unsupported = args.filter((value) => value !== "--yes" && value !== "--check");
-  if (unsupported.length > 0) throw new Error(`Unknown cleanup option: ${unsupported[0]}`);
-  console.log(JSON.stringify(await cleanupProjectCairn({ root: repoRoot, apply }), null, 2));
+function firstLine(error) {
+  return String(error instanceof Error ? error.message : error).split(/\r?\n/)[0];
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  await main();
+  await main(process.argv.slice(2));
 }

package/scripts/cairn-goal-cli.mjs

@@ -1,4 +1,13 @@
-import { resolveRepoRoot } from "./cairn-paths.mjs";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { memoryPromotionReminder } from "./cairn-goal-history.mjs";
+import { resolvePluginRoot, resolveRepoRoot } from "./cairn-paths.mjs";
+
+const GOAL_COMMANDS = ["start", "status", "ready", "stats", "task", "replan", "claim", "assign", "receipt", "verify", "finish", "pause", "resume", "block", "cancel", "complete"];
+const GOAL_USAGE = [
+  `Usage: cairn goal <${GOAL_COMMANDS.join("|")}> [options] [--root PATH]`,
+  "Note: --criteria (completionCriteria) is advisory and is not enforced; completion is gated only by required evidence.",
+].join("\n");
 
 export async function runGoalCli(args, {
   stdout = console.log,
@@ -8,10 +17,31 @@ export async function runGoalCli(args, {
 }) {
   const [firstCommand = "help", ...remaining] = args;
   const [command = "help", ...rest] = firstCommand === "goal" ? remaining : [firstCommand, ...remaining];
+  // Help and version are answered before parsing options or touching state; arguments after -- are passed through.
+  const leading = [command, ...rest];
+  const separator = leading.indexOf("--");
+  const beforeSeparator = separator === -1 ? leading : leading.slice(0, separator);
+  const help = command === "help" || beforeSeparator.includes("--help");
+  const version = beforeSeparator.includes("--version");
+  if (help && version) throw new Error("--help and --version cannot be used together");
+  if (help) {
+    stdout(GOAL_USAGE);
+    return null;
+  }
+  if (version) {
+    stdout(`cairn ${JSON.parse(readFileSync(join(resolvePluginRoot(import.meta.url), "package.json"), "utf8")).version}`);
+    return null;
+  }
+  if (!GOAL_COMMANDS.includes(command)) throw new Error(unknownCommandMessage(command));
   const { options, positional, passthrough } = parseArgs(rest, command);
   // Without --root, resolve the repository (HARNESS_REPO_ROOT or the nearest .git ancestor), not a subdirectory cwd.
   const root = resolveRepoRoot({ explicitRoot: options.root ?? null });
   const emit = options.quiet ? () => {} : stdout;
+  // Terminal notices go to stderr only; stdout and the exit code stay those of the transition.
+  const onTerminal = (record, { historyError } = {}) => {
+    if (historyError) stderr(`Cairn warning: goal history was not recorded: ${firstLine(historyError)}`);
+    if (record?.status === "completed" && record.memoryPromotion === "missing") stderr(memoryPromotionReminder(record.planId));
+  };
   if (command === "start") {
     const tasks = parseTasks(options.tasks ?? positional.slice(0));
     const state = await operations.startGoal({
@@ -82,11 +112,17 @@ export async function runGoalCli(args, {
       model: options.model,
       modelSource: options["model-source"],
       designWaiver: options["allow-no-design-model"],
+      effectiveModel: options["effective-model"],
+      modelHost: options.host,
     });
     const task = state.tasks.find((item) => item.id === String(options.task ?? positional[0]).trim());
     if (task?.route === "heavy" && task.assignedAgentId && (!task.effort || task.effortSource === "not-applied")) {
       stderr(`Cairn warning: Heavy task ${task.id} is assigned without an applied effort (effort ${task.effort ?? "none"}, source ${task.effortSource ?? "none"}); dispatch with the plan's effort and record --effort <level> --effort-source host-option.`);
     }
+    // A worker-reported ID that does not contain the passed alias hints at a silent fallback; warn, never block.
+    if (task?.model && task.effectiveModel && task.effectiveModel !== "unreported" && !task.effectiveModel.toLowerCase().includes(task.model.toLowerCase())) {
+      stderr(`Cairn warning: Task ${task.id} effective model ${task.effectiveModel} does not match the passed model ${task.model}; check the dispatch result.`);
+    }
     emit(JSON.stringify(state));
     return state;
   }
@@ -131,6 +167,7 @@ export async function runGoalCli(args, {
   if (command === "finish") {
     const state = await operations.finishGoal({
       root,
+      onTerminal,
       watchPaths: splitValues(options.watch),
       argv: passthrough,
       timeoutMs: options["timeout-ms"] === undefined
@@ -148,6 +185,12 @@ export async function runGoalCli(args, {
     return summary;
   }
   if (command === "stats") {
+    if (options.limit !== undefined && !options.history) throw new Error("--limit requires --history");
+    if (options.history) {
+      const history = await operations.goalHistoryStats({ root, limit: options.limit });
+      stdout(JSON.stringify(history));
+      return history;
+    }
     const stats = operations.goalStats(await operations.readGoalState({ root }), root);
     stdout(JSON.stringify(stats));
     return stats;
@@ -157,18 +200,23 @@ export async function runGoalCli(args, {
       root,
       status: { pause: "paused", resume: "active", block: "blocked", cancel: "cancelled", complete: "completed" }[command],
       blocker: options.reason,
+      onTerminal,
     });
     emit(JSON.stringify(state));
     return state;
   }
-  throw new Error("Usage: cairn-goal start|status|ready|stats|task|replan|claim|assign|receipt|verify|finish|pause|resume|block|cancel|complete [--root PATH]");
+  throw new Error(unknownCommandMessage(command));
+}
+
+function unknownCommandMessage(command) {
+  return `unknown goal command: ${command} (run cairn goal --help)`;
 }
 
 function parseArgs(args, command) {
   const options = {};
   const positional = [];
   const passthrough = [];
-  const booleanOptions = new Set(["quiet"]);
+  const booleanOptions = new Set(["quiet", "history"]);
   const allowed = allowedOptions(command);
   const seenCanonicalOptions = new Set();
   for (let index = 0; index < args.length; index += 1) {
@@ -222,11 +270,11 @@ function allowedOptions(command) {
     task: ["task", "status", "reason", "allow-inherited-effort", "allow-no-design-model"],
     replan: ["tasks"],
     claim: ["session"],
-    assign: ["task", "agent", "effort", "effort-source", "route", "allow-inherited-effort", "kind", "model", "model-source", "allow-no-design-model"],
+    assign: ["task", "agent", "effort", "effort-source", "route", "allow-inherited-effort", "kind", "model", "model-source", "allow-no-design-model", "effective-model", "host"],
     receipt: ["task", "kind", "scope", "command", "exitCode", "exit-code", "exit", "timestamp", "goalId", "goal-id", "plan"],
     verify: ["task", "kind", "scope", "watch", "timeout-ms"],
     finish: ["watch", "timeout-ms"],
-    stats: [],
+    stats: ["history", "limit"],
     ready: [],
     pause: [],
     resume: [],
@@ -251,6 +299,10 @@ function parseTasks(value) {
   }
 }
 
+function firstLine(error) {
+  return String(error?.message ?? error).split(/\r?\n/)[0];
+}
+
 function splitValues(value) {
   if (!value) return [];
   return String(value).split("|").map((item) => item.trim()).filter(Boolean);