cairn-ai 0.5.0 → 0.6.0

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({
@@ -137,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
@@ -154,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;
@@ -163,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) {
@@ -232,7 +274,7 @@ function allowedOptions(command) {
     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: [],
@@ -257,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);

package/scripts/cairn-goal-history.mjs

@@ -0,0 +1,316 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+import { lstat, readFile, readdir, rename, rm } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { cairnHome, goalStateDirectory, repositoryId } from "./cairn-paths.mjs";
+import { assertNoSymlinkComponents, safeWriteFile } from "./cairn-safe-fs.mjs";
+
+export const GOAL_HISTORY_SCHEMA_VERSION = 1;
+export const GOAL_HISTORY_MAX_RECORDS = 200;
+export const GOAL_HISTORY_LIMIT_MAX = 200;
+const TITLE_MAX_LENGTH = 120;
+const PLAN_FILE_MAX_BYTES = 512 * 1024;
+const RECENT_MAX = 5;
+const TREND_MIN_COMPLETED = 4;
+const historyStatuses = new Set(["completed", "cancelled"]);
+const memoryPromotionValues = ["note", "none", "missing", "unknown"];
+const memoryPromotionLine = /^\s*(?:[-*]\s*)?Memory promotion\s*:\s*(.*)$/gim;
+
+export function goalHistoryPath(root = process.cwd()) {
+  return join(goalStateDirectory(root), "history.jsonl");
+}
+
+export function memoryPromotionReminder(planId) {
+  return `Cairn memory: plan ${planId} has no "Memory promotion:" line. If this goal produced reusable repository knowledge, write it to docs/memory/<domain>.md and run cairn memory index; otherwise record "Memory promotion: none: <reason>" in the plan.`;
+}
+
+// Classifies the plan's memory promotion decision. Anything that is not a regular repository file of at most
+// 512 KiB (an id such as plan-status, a symlink, a directory, a path outside root) is "unknown"; never throws.
+export function memoryPromotionStatus(root, planId) {
+  try {
+    const workspaceRoot = resolve(root);
+    const target = resolve(workspaceRoot, String(planId));
+    const relation = relative(workspaceRoot, target);
+    if (relation === "" || relation === ".." || relation.startsWith(`..${sep}`) || isAbsolute(relation)) return "unknown";
+    let current = workspaceRoot;
+    for (const component of relation.split(sep)) {
+      current = join(current, component);
+      if (lstatSync(current).isSymbolicLink()) return "unknown";
+    }
+    const stat = lstatSync(target);
+    if (!stat.isFile() || stat.size > PLAN_FILE_MAX_BYTES) return "unknown";
+    const text = readFileSync(target, "utf8");
+    for (const match of text.matchAll(memoryPromotionLine)) {
+      const value = match[1].trim();
+      if (value.length === 0 || /^<.*>$/.test(value)) continue;
+      return /^(?:none|없음)/i.test(value) ? "none" : "note";
+    }
+    return "missing";
+  } catch {
+    return "unknown";
+  }
+}
+
+// Builds the schemaVersion 1 summary of a terminal goal. It carries ids and counts only, never absolute paths.
+export function buildGoalHistoryRecord(state, { root = process.cwd(), recordedBy, endedAt = state.goal.updatedAt } = {}) {
+  const { goal, tasks, receipts } = state;
+  const createdMs = Date.parse(goal.createdAt);
+  const endedMs = Date.parse(endedAt);
+  const durationMs = Number.isFinite(createdMs) && Number.isFinite(endedMs) ? Math.max(0, endedMs - createdMs) : 0;
+  const byKind = {};
+  const latest = new Set();
+  let reruns = 0;
+  // Same rerun definition as goalStats: a later receipt for an already-seen scope, task, and kind.
+  for (const receipt of receipts) {
+    byKind[receipt.kind] = (byKind[receipt.kind] ?? 0) + 1;
+    const key = `${receipt.scope}\0${receipt.taskId ?? ""}\0${receipt.kind}`;
+    if (latest.has(key)) reruns += 1;
+    latest.add(key);
+  }
+  const models = {};
+  const efforts = {};
+  for (const task of tasks) {
+    if (task.model) models[task.model] = (models[task.model] ?? 0) + 1;
+    if (task.effort) efforts[task.effort] = (efforts[task.effort] ?? 0) + 1;
+  }
+  return {
+    schemaVersion: GOAL_HISTORY_SCHEMA_VERSION,
+    goalId: goal.id,
+    planId: goal.planId,
+    title: Array.from(goal.title).slice(0, TITLE_MAX_LENGTH).join(""),
+    status: goal.status,
+    worktreeId: goal.worktreeId ?? null,
+    createdAt: goal.createdAt,
+    endedAt,
+    durationMs,
+    revision: state.revision,
+    evidencePolicy: goal.evidencePolicy,
+    tasks: {
+      total: tasks.length,
+      completed: tasks.filter((task) => task.status === "completed").length,
+      heavy: tasks.filter((task) => task.route === "heavy").length,
+      light: tasks.filter((task) => task.route === "light").length,
+      delegated: tasks.filter((task) => task.assignedAgentId).length,
+      design: tasks.filter((task) => task.kind === "design").length,
+    },
+    receipts: {
+      total: receipts.length,
+      tool: receipts.filter((receipt) => receipt.source === "tool").length,
+      reruns,
+      byKind,
+    },
+    waivers: {
+      effort: tasks.filter((task) => task.effortWaiver).length,
+      design: tasks.filter((task) => task.designWaiver).length,
+    },
+    models,
+    efforts,
+    memoryPromotion: memoryPromotionStatus(root, goal.planId),
+    recordedBy,
+  };
+}
+
+// Records a terminal goal while the caller holds the goal state lock. History is best effort: it never throws, and
+// the caller reports a returned error instead of blocking the transition.
+export async function recordGoalHistoryUnlocked(root, state, options) {
+  let record = null;
+  try {
+    record = buildGoalHistoryRecord(state, { ...options, root });
+    await writeGoalHistoryRecordUnlocked(root, record);
+    return { record, error: null };
+  } catch (error) {
+    return { record, error };
+  }
+}
+
+// Keeps valid lines only, replaces a record with the same goalId, appends, and keeps the newest 200 records.
+// The state lock serializes writers per worktree; temporary file + rename keeps readers on a whole file.
+export async function writeGoalHistoryRecordUnlocked(root, record) {
+  const path = goalHistoryPath(root);
+  await assertNoSymlinkComponents(cairnHome(), path);
+  const { records } = await readHistoryFile(path);
+  const kept = records.filter((item) => item.goalId !== record.goalId);
+  kept.push(record);
+  const text = kept.slice(-GOAL_HISTORY_MAX_RECORDS).map((item) => JSON.stringify(item)).join("\n");
+  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await safeWriteFile(cairnHome(), temporaryPath, `${text}\n`, "utf8");
+    await rename(temporaryPath, path);
+  } catch (error) {
+    await rm(temporaryPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function readHistoryFile(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return { records: [], skippedLines: 0 };
+    throw error;
+  }
+  const records = [];
+  let skippedLines = 0;
+  for (const line of text.split("\n")) {
+    if (line.trim().length === 0) continue;
+    let value;
+    try {
+      value = JSON.parse(line);
+    } catch {
+      value = null;
+    }
+    if (isHistoryRecord(value)) records.push(value);
+    else skippedLines += 1;
+  }
+  return { records, skippedLines };
+}
+
+function isHistoryRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+    && value.schemaVersion === GOAL_HISTORY_SCHEMA_VERSION
+    && typeof value.goalId === "string" && value.goalId.length > 0
+    && historyStatuses.has(value.status)
+    && typeof value.endedAt === "string" && Number.isFinite(Date.parse(value.endedAt));
+}
+
+// Reads every worktree history of this repository without taking locks or creating directories.
+async function readRepositoryHistory(root) {
+  const worktreesDirectory = join(cairnHome(), "projects", repositoryId(root), "worktrees");
+  let entries;
+  try {
+    await assertNoSymlinkComponents(cairnHome(), worktreesDirectory);
+    entries = await readdir(worktreesDirectory, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return { records: [], skippedLines: 0 };
+    throw error;
+  }
+  const byGoal = new Map();
+  let skippedLines = 0;
+  for (const entry of entries.filter((item) => item.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+    const path = join(worktreesDirectory, entry.name, "history.jsonl");
+    try {
+      if (!(await lstat(path)).isFile()) continue;
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      throw error;
+    }
+    const file = await readHistoryFile(path);
+    skippedLines += file.skippedLines;
+    for (const record of file.records) {
+      const existing = byGoal.get(record.goalId);
+      if (!existing || Date.parse(record.endedAt) > Date.parse(existing.endedAt)) byGoal.set(record.goalId, record);
+    }
+  }
+  return { records: [...byGoal.values()], skippedLines };
+}
+
+export function validHistoryLimit(value) {
+  if (value === undefined || value === null) return null;
+  const text = String(value);
+  const result = Number(text);
+  if (!/^\d+$/.test(text) || !Number.isSafeInteger(result) || result < 1 || result > GOAL_HISTORY_LIMIT_MAX) {
+    throw new Error(`--limit must be an integer between 1 and ${GOAL_HISTORY_LIMIT_MAX}`);
+  }
+  return result;
+}
+
+// Repository-wide summary across goals. Medians, p90, rates, and trend use completed goals only; limit keeps the
+// newest N records by endedAt.
+export async function goalHistoryStats({ root = process.cwd(), limit } = {}) {
+  const normalizedLimit = validHistoryLimit(limit);
+  const history = await readRepositoryHistory(root);
+  const ordered = history.records.sort((a, b) => Date.parse(a.endedAt) - Date.parse(b.endedAt) || a.goalId.localeCompare(b.goalId));
+  const records = normalizedLimit === null ? ordered : ordered.slice(-normalizedLimit);
+  if (records.length === 0) {
+    return {
+      schemaVersion: GOAL_HISTORY_SCHEMA_VERSION,
+      scope: "repository",
+      goals: 0,
+      ...(history.skippedLines > 0 ? { skippedLines: history.skippedLines } : {}),
+    };
+  }
+  const completed = records.filter((record) => record.status === "completed");
+  const memoryPromotion = Object.fromEntries(memoryPromotionValues.map((value) => [value, 0]));
+  for (const record of records) {
+    const value = memoryPromotionValues.includes(record.memoryPromotion) ? record.memoryPromotion : "unknown";
+    memoryPromotion[value] += 1;
+  }
+  const durations = completed.map((record) => count(record.durationMs)).sort((a, b) => a - b);
+  const receiptTotals = completed.map((record) => count(record.receipts?.total));
+  return {
+    schemaVersion: GOAL_HISTORY_SCHEMA_VERSION,
+    scope: "repository",
+    goals: records.length,
+    completed: completed.length,
+    cancelled: records.length - completed.length,
+    skippedLines: history.skippedLines,
+    window: { from: records[0].endedAt, to: records.at(-1).endedAt },
+    durationMs: { median: median(durations), p90: durations.length === 0 ? 0 : durations[Math.ceil(0.9 * durations.length) - 1] },
+    tasks: {
+      total: sum(completed, (record) => record.tasks?.total),
+      median: median(completed.map((record) => count(record.tasks?.total))),
+      heavy: sum(completed, (record) => record.tasks?.heavy),
+      light: sum(completed, (record) => record.tasks?.light),
+      delegated: sum(completed, (record) => record.tasks?.delegated),
+    },
+    receipts: {
+      total: sum(completed, (record) => record.receipts?.total),
+      tool: sum(completed, (record) => record.receipts?.tool),
+      reruns: sum(completed, (record) => record.receipts?.reruns),
+      rerunRate: rerunRate(completed),
+      median: median(receiptTotals),
+    },
+    waivers: {
+      effort: sum(records, (record) => record.waivers?.effort),
+      design: sum(records, (record) => record.waivers?.design),
+    },
+    memoryPromotion,
+    trend: trend(completed),
+    recent: records.slice(-RECENT_MAX).reverse().map((record) => ({
+      goalId: record.goalId,
+      planId: record.planId,
+      status: record.status,
+      endedAt: record.endedAt,
+      durationMs: count(record.durationMs),
+      tasks: count(record.tasks?.total),
+      receipts: count(record.receipts?.total),
+      reruns: count(record.receipts?.reruns),
+      memoryPromotion: record.memoryPromotion,
+    })),
+  };
+}
+
+// Completed goals in endedAt order split in half; an odd count gives newer the extra goal.
+function trend(completed) {
+  if (completed.length < TREND_MIN_COMPLETED) return null;
+  const middle = Math.floor(completed.length / 2);
+  const summarize = (records) => ({
+    goals: records.length,
+    durationMsMedian: median(records.map((record) => count(record.durationMs))),
+    receiptsMedian: median(records.map((record) => count(record.receipts?.total))),
+    rerunRate: rerunRate(records),
+  });
+  return { older: summarize(completed.slice(0, middle)), newer: summarize(completed.slice(middle)) };
+}
+
+function rerunRate(records) {
+  const total = sum(records, (record) => record.receipts?.total);
+  const reruns = sum(records, (record) => record.receipts?.reruns);
+  return Number((reruns / Math.max(1, total)).toFixed(3));
+}
+
+function median(values) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 1 ? sorted[middle] : Math.round((sorted[middle - 1] + sorted[middle]) / 2);
+}
+
+function sum(records, pick) {
+  return records.reduce((total, record) => total + count(pick(record)), 0);
+}
+
+function count(value) {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}

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

@@ -133,7 +133,7 @@ export async function verifyAndRecord({
 
 // Completes the active task, proves every goal-level evidence kind with one run, and completes the goal.
 export async function finishGoal({
-  root = process.cwd(), argv = [], watchPaths = [], runner, timeoutMs = 600_000,
+  root = process.cwd(), argv = [], watchPaths = [], runner, timeoutMs = 600_000, onTerminal,
 } = {}) {
   const initialState = await readGoalState({ root });
   if (!initialState) throw new Error("No Cairn goal state exists; start a goal first");
@@ -149,7 +149,7 @@ export async function finishGoal({
   if (goalKinds.length > 0) {
     await verifyAndRecord({ root, scope: "goal", kind: goalKinds, argv, watchPaths, runner, timeoutMs });
   }
-  return transitionGoal({ root, status: "completed" });
+  return transitionGoal({ root, status: "completed", onTerminal });
 }
 
 // Overhead measurement: how many verifications ran, how many were reruns, and which latest receipts are stale.