cairn-ai 0.2.2 → 0.2.3

package/scripts/cairn-safe-fs.mjs

@@ -0,0 +1,246 @@
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { link, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+const LOCK_SCHEMA_VERSION = 1;
+const DEFAULT_LOCK_TIMEOUT_MS = 5_000;
+const DEFAULT_RETRY_MS = 25;
+const DEFAULT_MALFORMED_STALE_MS = 30_000;
+const TRANSIENT_LOCK_ERROR_CODES = new Set(["EACCES", "EBUSY", "EPERM"]);
+
+export function stateLockPath(root = process.cwd()) {
+  return safePath(root, ".cairn/state.lock");
+}
+
+export function safePath(root, relativePath) {
+  const workspaceRoot = resolve(root);
+  const target = resolve(workspaceRoot, relativePath);
+  const relation = relative(workspaceRoot, target);
+  if (relation === ".." || relation.startsWith(`..${sep}`)) {
+    throw new Error(`Managed path must remain inside the workspace: ${relativePath}`);
+  }
+  return target;
+}
+
+export async function assertNoSymlinkComponents(root, target, { allowMissing = true } = {}) {
+  const workspaceRoot = resolve(root);
+  const absoluteTarget = resolve(target);
+  const relation = relative(workspaceRoot, absoluteTarget);
+  if (relation === ".." || relation.startsWith(`..${sep}`)) {
+    throw new Error(`Managed path must remain inside the workspace: ${target}`);
+  }
+  const components = relation === "" ? [] : relation.split(sep);
+  let current = workspaceRoot;
+  await rejectSymlink(current);
+  for (const component of components) {
+    current = join(current, component);
+    try {
+      await rejectSymlink(current);
+    } catch (error) {
+      if (allowMissing && error?.code === "ENOENT") return;
+      throw error;
+    }
+  }
+}
+
+export async function safeMkdir(root, relativePath) {
+  const workspaceRoot = resolve(root);
+  const target = safePath(workspaceRoot, relativePath);
+  await assertNoSymlinkComponents(workspaceRoot, workspaceRoot, { allowMissing: false });
+  const relation = relative(workspaceRoot, target);
+  let current = workspaceRoot;
+  for (const component of relation.split(sep).filter(Boolean)) {
+    current = join(current, component);
+    try {
+      const stat = await lstat(current);
+      if (stat.isSymbolicLink()) throw symlinkError(current);
+      if (!stat.isDirectory()) throw new Error(`Managed directory component is not a directory: ${current}`);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      try {
+        await mkdir(current);
+      } catch (mkdirError) {
+        if (mkdirError?.code !== "EEXIST") throw mkdirError;
+        const stat = await lstat(current);
+        if (stat.isSymbolicLink()) throw symlinkError(current);
+        if (!stat.isDirectory()) throw new Error(`Managed directory component is not a directory: ${current}`);
+      }
+    }
+  }
+  return target;
+}
+
+export async function safeWriteFile(root, target, data, options) {
+  const absoluteTarget = safePath(root, relative(resolve(root), resolve(target)));
+  await assertNoSymlinkComponents(root, dirname(absoluteTarget), { allowMissing: false });
+  await assertNoSymlinkComponents(root, absoluteTarget);
+  return writeFile(absoluteTarget, data, options);
+}
+
+export async function withStateLock(root, operation, {
+  timeoutMs = DEFAULT_LOCK_TIMEOUT_MS,
+  retryMs = DEFAULT_RETRY_MS,
+  malformedStaleMs = DEFAULT_MALFORMED_STALE_MS,
+  testHooks = {},
+} = {}) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new Error("lock timeoutMs must be a non-negative number");
+  const workspaceRoot = resolve(root);
+  await safeMkdir(workspaceRoot, ".cairn");
+  const lockPath = stateLockPath(workspaceRoot);
+  const owner = {
+    schemaVersion: LOCK_SCHEMA_VERSION,
+    pid: process.pid,
+    hostname: hostname(),
+    nonce: randomUUID(),
+    acquiredAt: new Date().toISOString(),
+  };
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    try {
+      await safeWriteFile(workspaceRoot, lockPath, `${JSON.stringify(owner)}\n`, { encoding: "utf8", flag: "wx" });
+      await testHooks.afterLockWritten?.({ lockPath, owner: structuredClone(owner) });
+      if (await confirmsLockOwnership(lockPath, owner.nonce)) break;
+    } catch (error) {
+      if (isTransientLockError(error)) {
+        // Windows can briefly deny a lock file that another process is closing.
+        // Retry within the deadline; permission errors are not evidence of staleness.
+      } else if (error?.code === "EEXIST") {
+        try {
+          await testHooks.beforeContendedLockConfirmation?.({ lockPath });
+          if (await confirmsLockOwnership(lockPath, owner.nonce)) break;
+          const reclaimed = await reclaimStaleLock(workspaceRoot, lockPath, malformedStaleMs, testHooks);
+          if (reclaimed) continue;
+        } catch (inspectionError) {
+          if (!isTransientLockError(inspectionError)) throw inspectionError;
+        }
+      } else {
+        throw error;
+      }
+    }
+    if (Date.now() >= deadline) throw new Error(`Timed out waiting for Cairn state lock after ${timeoutMs}ms`);
+    await delay(Math.min(retryMs, Math.max(1, deadline - Date.now())));
+  }
+
+  try {
+    return await operation();
+  } finally {
+    await releaseOwnedLock(lockPath, owner.nonce);
+  }
+}
+
+async function reclaimStaleLock(root, lockPath, malformedStaleMs, testHooks) {
+  let observed;
+  let stat;
+  try {
+    [observed, stat] = await Promise.all([readFile(lockPath, "utf8"), lstat(lockPath)]);
+  } catch (error) {
+    if (error?.code === "ENOENT") return true;
+    throw error;
+  }
+  if (stat.isSymbolicLink()) throw symlinkError(lockPath);
+  const record = parseLockRecord(observed);
+  if (record) {
+    if (record.hostname !== hostname()) return false;
+    if (pidIsAlive(record.pid)) return false;
+  } else if (Date.now() - stat.mtimeMs <= malformedStaleMs) {
+    return false;
+  }
+
+  await testHooks.afterStaleObserved?.({ lockPath, observed, record: record ? structuredClone(record) : null });
+  const quarantine = safePath(root, `.cairn/state.lock.stale.${record?.nonce ?? "malformed"}.${randomUUID()}`);
+  try {
+    await rename(lockPath, quarantine);
+  } catch (error) {
+    if (error?.code === "ENOENT") return true;
+    throw error;
+  }
+  const moved = await readFile(quarantine, "utf8");
+  if (moved !== observed) {
+    const restored = await restoreMovedCandidate(lockPath, quarantine);
+    await testHooks.afterReclaimMismatch?.({ lockPath, restored });
+    return false;
+  }
+  await rm(quarantine, { force: true });
+  return true;
+}
+
+async function restoreMovedCandidate(lockPath, quarantine) {
+  try {
+    await link(quarantine, lockPath);
+    await rm(quarantine);
+    return true;
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    await rm(quarantine, { force: true });
+    return false;
+  }
+}
+
+async function confirmsLockOwnership(lockPath, nonce) {
+  try {
+    return parseLockRecord(await readFile(lockPath, "utf8"))?.nonce === nonce;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function releaseOwnedLock(lockPath, nonce) {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    try {
+      const record = parseLockRecord(await readFile(lockPath, "utf8"));
+      if (record?.nonce !== nonce) return;
+      await rm(lockPath);
+      return;
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      if (!isTransientLockError(error) || attempt === 7) throw error;
+      await delay(10 * (attempt + 1));
+    }
+  }
+}
+
+function isTransientLockError(error) {
+  return TRANSIENT_LOCK_ERROR_CODES.has(error?.code);
+}
+
+function parseLockRecord(text) {
+  try {
+    const value = JSON.parse(text);
+    if (value?.schemaVersion !== LOCK_SCHEMA_VERSION) return null;
+    if (!Number.isSafeInteger(value.pid) || value.pid <= 0) return null;
+    if (typeof value.hostname !== "string" || value.hostname.length === 0) return null;
+    if (typeof value.nonce !== "string" || value.nonce.length === 0) return null;
+    if (typeof value.acquiredAt !== "string" || Number.isNaN(Date.parse(value.acquiredAt))) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+function pidIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error?.code === "EPERM") return true;
+    if (error?.code === "ESRCH") return false;
+    return true;
+  }
+}
+
+async function rejectSymlink(path) {
+  const stat = await lstat(path);
+  if (stat.isSymbolicLink()) throw symlinkError(path);
+}
+
+function symlinkError(path) {
+  const error = new Error(`Managed path must not contain a symbolic link: ${path}`);
+  error.code = "CAIRN_SYMLINK";
+  return error;
+}
+
+function delay(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}

package/scripts/cairn-state.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { evaluateStop, isGoalOwnedBySession, readGoalState } from "./cairn-goal.mjs";
 import { resolveRepoRoot } from "./cairn-paths.mjs";
+import { assertNoSymlinkComponents, safeMkdir, safeWriteFile } from "./cairn-safe-fs.mjs";
 
 const memoryTemplate = `# MEMORY
 
@@ -162,12 +163,18 @@ export async function runStateResult(event = "manual", {
   }
 
   if (event === "post-tool-use") {
+    const message = ko
+      ? "Cairn 점검: 외부 상태 변경에는 dry-run/check 증거 기록이 필요합니다. 활성 목표가 있다면 현재 task에 성공 증거를 기록하세요."
+      : "Cairn check: external-state changes need dry-run/check evidence. When a goal is active, record successful evidence for its current task.";
     return {
       status: 0,
-      message: ko
-        ? "Cairn 점검: 외부 상태 변경에는 dry-run/check 증거 기록이 필요합니다. 활성 목표가 있다면 현재 task에 성공 증거를 기록하세요."
-        : "Cairn check: external-state changes need dry-run/check evidence. When a goal is active, record successful evidence for its current task.",
-      hookOutput: {},
+      message,
+      hookOutput: {
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: message,
+        },
+      },
     };
   }
 
@@ -193,18 +200,24 @@ export async function runStateResult(event = "manual", {
 }
 
 async function initializeProject(root, ko) {
-  await mkdir(join(root, "docs", "memory"), { recursive: true });
-  await mkdir(join(root, "docs", "plan"), { recursive: true });
-  await writeIfMissing(join(root, "MEMORY.md"), ko ? memoryTemplateKo : memoryTemplate);
-  await writeIfMissing(join(root, "PLAN.md"), ko ? planTemplateKo : planTemplate);
+  await safeMkdir(root, "docs/memory");
+  await safeMkdir(root, "docs/plan");
+  await writeIfMissing(root, join(root, "MEMORY.md"), ko ? memoryTemplateKo : memoryTemplate);
+  await writeIfMissing(root, join(root, "PLAN.md"), ko ? planTemplateKo : planTemplate);
 }
 
-async function writeIfMissing(path, content) {
+async function writeIfMissing(root, path, content) {
+  await assertNoSymlinkComponents(root, path);
   try {
     await readFile(path, "utf8");
   } catch (error) {
     if (error?.code !== "ENOENT") throw error;
-    await writeFile(path, content);
+    try {
+      await safeWriteFile(root, path, content, { encoding: "utf8", flag: "wx" });
+    } catch (writeError) {
+      if (writeError?.code !== "EEXIST") throw writeError;
+      await assertNoSymlinkComponents(root, path, { allowMissing: false });
+    }
   }
 }
 

package/scripts/cairn-toolcheck.mjs

@@ -58,11 +58,12 @@ export async function createReport({
   runner = run,
   timeoutMs = DEFAULT_TIMEOUT_MS,
   localChecker = localExecutableAvailable,
+  platform = process.platform,
 } = {}) {
   const resolvedRoot = resolve(root);
   const entries = await collectEntries(resolvedRoot);
   const detected = detectStacks(entries);
-  const requirements = buildRequirements(detected, entries);
+  const requirements = buildRequirements(detected, entries, commandOk, platform);
   const results = [];
   const installRefused = install && !yes;
 
@@ -72,6 +73,7 @@ export async function createReport({
       runner,
       timeoutMs,
       localChecker,
+      platform,
     });
     let installed = false;
     let installDiagnostic = null;
@@ -95,6 +97,7 @@ export async function createReport({
             runner,
             timeoutMs,
             localChecker,
+            platform,
           });
         }
       }
@@ -157,22 +160,24 @@ export async function collectEntries(base) {
 
 export function detectStacks(paths) {
   const stacks = new Set();
-  if (paths.some((path) => path === "package.json")) stacks.add("javascript");
-  if (paths.some((path) => path === "tsconfig.json" || path.endsWith(".ts") || path.endsWith(".tsx"))) stacks.add("typescript");
-  if (paths.some((path) => path === "pyproject.toml" || path.endsWith(".py"))) stacks.add("python");
-  if (paths.some((path) => path === "composer.json" || path.endsWith(".php"))) stacks.add("php");
-  if (paths.some((path) => path === "pom.xml" || path === "build.gradle" || path.endsWith(".java"))) stacks.add("java");
+  if (hasBasename(paths, "package.json")) stacks.add("javascript");
+  if (hasBasename(paths, "tsconfig.json") || paths.some((path) => path.endsWith(".ts") || path.endsWith(".tsx"))) stacks.add("typescript");
+  if (hasBasename(paths, "pyproject.toml") || paths.some((path) => path.endsWith(".py"))) stacks.add("python");
+  if (hasBasename(paths, "composer.json") || paths.some((path) => path.endsWith(".php"))) stacks.add("php");
+  if (hasBasename(paths, "pom.xml", "build.gradle", "build.gradle.kts") || paths.some((path) => path.endsWith(".java"))) stacks.add("java");
   if (paths.some((path) => path.endsWith(".kt") || path.endsWith(".kts"))) stacks.add("kotlin");
-  if (paths.some((path) => path === "Package.swift" || path.endsWith(".xcodeproj") || path.endsWith(".xcworkspace") || path.endsWith(".swift"))) stacks.add("swift");
-  if (paths.some((path) => path === "go.mod" || path.endsWith(".go"))) stacks.add("go");
-  if (paths.some((path) => path === "Cargo.toml" || path.endsWith(".rs"))) stacks.add("rust");
+  if (hasBasename(paths, "Package.swift") || paths.some((path) => hasPathSegmentWithSuffix(path, ".xcodeproj", ".xcworkspace") || path.endsWith(".swift"))) stacks.add("swift");
+  if (hasBasename(paths, "go.mod") || paths.some((path) => path.endsWith(".go"))) stacks.add("go");
+  if (hasBasename(paths, "Cargo.toml") || paths.some((path) => path.endsWith(".rs"))) stacks.add("rust");
   return [...stacks];
 }
 
 export function buildRequirements(stacks, entries = [], _commandAvailable = commandOk, platform = process.platform) {
   const requirements = [];
   if (stacks.includes("javascript")) {
-    requirements.push(req("node", ["--version"], "JavaScript runtime for package scripts and CLI checks"));
+    requirements.push(unsafeReq("node", ["--version"], "JavaScript runtime for package scripts and CLI checks", "automatic runtime installation is unavailable"));
+    const manager = packageManager(entries);
+    requirements.push(unsafeReq(manager, ["--version"], `JavaScript package manager selected from ${packageManagerSource(entries)}`, "automatic package-manager installation is unavailable"));
   }
   if (stacks.includes("typescript")) {
     requirements.push(unsafeReq("typescript-language-server", ["--version"], "TypeScript LSP server", "automatic package installation is disabled without pinned package versions"));
@@ -183,7 +188,7 @@ export function buildRequirements(stacks, entries = [], _commandAvailable = comm
     requirements.push(unsafeReq("ruff", ["--version"], "Python lint and format checker", "automatic Python package installation is disabled without pinned package versions"));
   }
   if (stacks.includes("php")) {
-    const composerProject = entries.includes("composer.json");
+    const composerProject = hasBasename(entries, "composer.json");
     requirements.push(req("php", ["--version"], "PHP runtime for Composer scripts and CLI checks"));
     if (composerProject) requirements.push(req("composer", ["--version"], "PHP package manager for project-local tool installation"));
     requirements.push(unsafeReq("phpactor", ["--version"], "PHP LSP server", "automatic Composer package installation is disabled without pinned package versions"));
@@ -204,7 +209,7 @@ export function buildRequirements(stacks, entries = [], _commandAvailable = comm
   if (stacks.includes("swift")) {
     requirements.push(req("swift", ["--version"], "Swift toolchain for build and test commands"));
     requirements.push(req("sourcekit-lsp", ["--version"], "Swift LSP server"));
-    if (entries.some((path) => path.endsWith(".xcodeproj") || path.endsWith(".xcworkspace"))) {
+    if (entries.some((path) => hasPathSegmentWithSuffix(path, ".xcodeproj", ".xcworkspace"))) {
       requirements.push(req("xcodebuild", ["-version"], "Xcode build verification"));
     }
   }
@@ -229,13 +234,16 @@ export function addJvmRequirements(requirements) {
 }
 
 export function addJvmBuildToolRequirements(requirements, entries = []) {
-  if (entries.includes("gradlew.bat")) pushUnique(requirements, req("gradlew.bat", ["--version"], "Gradle wrapper availability", null, { localOnly: true }));
-  else if (entries.includes("gradlew")) pushUnique(requirements, req("./gradlew", ["--version"], "Gradle wrapper availability", null, { localOnly: true }));
-  else if (entries.includes("build.gradle") || entries.includes("build.gradle.kts")) pushUnique(requirements, req("gradle", ["--version"], "Gradle availability"));
-  if (entries.includes("mvnw.cmd")) pushUnique(requirements, req("mvnw.cmd", ["--version"], "Maven wrapper availability", null, { localOnly: true }));
-  else if (entries.includes("mvnw.bat")) pushUnique(requirements, req("mvnw.bat", ["--version"], "Maven wrapper availability", null, { localOnly: true }));
-  else if (entries.includes("mvnw")) pushUnique(requirements, req("./mvnw", ["--version"], "Maven wrapper availability", null, { localOnly: true }));
-  else if (entries.includes("pom.xml")) pushUnique(requirements, req("mvn", ["--version"], "Maven availability"));
+  const gradleWindows = findBasename(entries, "gradlew.bat");
+  const gradleUnix = findBasename(entries, "gradlew");
+  if (gradleWindows) pushUnique(requirements, req(repositoryCommand(gradleWindows), ["--version"], "Gradle wrapper availability", null, { localOnly: true }));
+  else if (gradleUnix) pushUnique(requirements, req(repositoryCommand(gradleUnix), ["--version"], "Gradle wrapper availability", null, { localOnly: true }));
+  else if (hasBasename(entries, "build.gradle", "build.gradle.kts")) pushUnique(requirements, req("gradle", ["--version"], "Gradle availability"));
+  const mavenWindows = findBasename(entries, "mvnw.cmd", "mvnw.bat");
+  const mavenUnix = findBasename(entries, "mvnw");
+  if (mavenWindows) pushUnique(requirements, req(repositoryCommand(mavenWindows), ["--version"], "Maven wrapper availability", null, { localOnly: true }));
+  else if (mavenUnix) pushUnique(requirements, req(repositoryCommand(mavenUnix), ["--version"], "Maven wrapper availability", null, { localOnly: true }));
+  else if (hasBasename(entries, "pom.xml")) pushUnique(requirements, req("mvn", ["--version"], "Maven availability"));
 }
 
 export function pushUnique(requirements, requirement) {
@@ -276,10 +284,12 @@ export function unsafeReq(command, args, reason, installUnavailableReason) {
 }
 
 export function packageManager(entries = []) {
-  if (entries.includes("bun.lockb") || entries.includes("bun.lock")) return "bun";
-  if (entries.includes("pnpm-lock.yaml")) return "pnpm";
-  if (entries.includes("yarn.lock")) return "yarn";
-  return "npm";
+  return selectPackageManager(entries).manager;
+}
+
+export function packageManagerSource(entries = []) {
+  const selected = selectPackageManager(entries);
+  return selected.path ?? "the npm default (no lockfile found)";
 }
 
 export function installDev(pm, packages) {
@@ -294,20 +304,24 @@ export function inspectCommand(requirement, {
   runner = run,
   timeoutMs = DEFAULT_TIMEOUT_MS,
   localChecker = localExecutableAvailable,
+  platform = process.platform,
 } = {}) {
-  const candidates = commandCandidates(requirement.command, root);
+  const candidates = commandCandidates(requirement.command, root, platform);
   const localOnly = requirement.localOnly || isRepositoryCommand(requirement.command, root);
 
   if (!localOnly) {
-    const diagnostic = execute(requirement.command, requirement.args, { root, runner, timeoutMs });
-    if (diagnostic.status === 0) {
-      return {
-        ok: true,
-        availability: "verified",
-        source: "system",
-        candidate: requirement.command,
-        diagnostic,
-      };
+    let diagnostic = null;
+    for (const candidate of systemCommandCandidates(requirement.command, platform)) {
+      diagnostic = execute(candidate, requirement.args, { root, runner, timeoutMs });
+      if (diagnostic.status === 0) {
+        return {
+          ok: true,
+          availability: "verified",
+          source: "system",
+          candidate,
+          diagnostic,
+        };
+      }
     }
 
     for (const candidate of candidates.slice(1)) {
@@ -324,7 +338,7 @@ export function inspectCommand(requirement, {
 
     return {
       ok: false,
-      availability: diagnostic.timedOut ? "timeout" : "missing",
+      availability: diagnostic?.timedOut ? "timeout" : "missing",
       source: null,
       candidate: null,
       diagnostic,
@@ -370,6 +384,11 @@ export function commandCandidates(command, root = process.cwd(), platform = proc
   return [...new Set(candidates.flatMap((candidate) => hasWindowsExecutableExtension(candidate) ? [candidate] : [candidate, ...extensions.map((extension) => `${candidate}${extension}`)]))];
 }
 
+export function systemCommandCandidates(command, platform = process.platform) {
+  if (platform !== "win32" || hasWindowsExecutableExtension(command) || isAbsolute(command)) return [command];
+  return [command, `${command}.cmd`, `${command}.bat`, `${command}.exe`];
+}
+
 export function localExecutableAvailable(command, platform = process.platform) {
   try {
     const info = statSync(command);
@@ -479,6 +498,69 @@ function normalizePath(path) {
   return path.split(sep).join("/");
 }
 
+function pathBasename(path) {
+  const normalized = normalizePath(path);
+  return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+
+function hasBasename(paths, ...names) {
+  const expected = new Set(names);
+  return paths.some((path) => expected.has(pathBasename(path)));
+}
+
+function findBasename(paths, ...names) {
+  const expected = new Set(names);
+  return [...paths]
+    .filter((path) => expected.has(pathBasename(path)))
+    .sort(compareRepositoryPaths)[0] ?? null;
+}
+
+function hasPathSegmentWithSuffix(path, ...suffixes) {
+  return normalizePath(path)
+    .split("/")
+    .some((segment) => suffixes.some((suffix) => segment.endsWith(suffix)));
+}
+
+function repositoryCommand(path) {
+  const normalized = normalizePath(path);
+  return normalized.startsWith("./") ? normalized : `./${normalized}`;
+}
+
+function selectPackageManager(entries) {
+  const lockfiles = [
+    { manager: "bun", names: new Set(["bun.lock", "bun.lockb"]), priority: 0 },
+    { manager: "pnpm", names: new Set(["pnpm-lock.yaml"]), priority: 1 },
+    { manager: "yarn", names: new Set(["yarn.lock"]), priority: 2 },
+    { manager: "npm", names: new Set(["package-lock.json", "npm-shrinkwrap.json"]), priority: 3 },
+  ];
+  const candidates = [];
+
+  for (const path of entries) {
+    const normalized = normalizePath(path);
+    const name = pathBasename(normalized);
+    const match = lockfiles.find(({ names }) => names.has(name));
+    if (!match) continue;
+    candidates.push({
+      manager: match.manager,
+      path: normalized,
+      depth: normalized.split("/").length - 1,
+      priority: match.priority,
+    });
+  }
+
+  candidates.sort((left, right) => left.depth - right.depth
+    || left.priority - right.priority
+    || left.path.localeCompare(right.path));
+  return candidates[0] ?? { manager: "npm", path: null };
+}
+
+function compareRepositoryPaths(left, right) {
+  const leftPath = normalizePath(left);
+  const rightPath = normalizePath(right);
+  const depth = leftPath.split("/").length - rightPath.split("/").length;
+  return depth || leftPath.localeCompare(rightPath);
+}
+
 function hasWindowsExecutableExtension(command) {
   return /\.(cmd|bat|exe)$/i.test(command);
 }

package/scripts/release-integrity-0.2.2.json

@@ -0,0 +1,68 @@
+{
+  "schemaVersion": 1,
+  "release": "0.2.2",
+  "files": {
+    ".agents/workflows/cairn-doctor.md": "cb5525f795ec1b1b3155396b6e175362af0f88ef376f9b92271ef5f7924f9da8",
+    ".agents/workflows/cairn-install.md": "036a74fae6df7c7b7b4dc567a3fdb4986fae4ef41c273ad2950a54e57a5e3cfd",
+    ".agents/workflows/cairn-memory.md": "af7c94799d0d0878d5386610ba95be9c22a673f75d81e5449053ef4af6bb8c2c",
+    ".agents/workflows/cairn-plan.md": "ad6791e3c34cefff161bf9d0d985dd3fe277808c6d3d3e43ffedd132fda756bd",
+    ".agents/workflows/cairn-review.md": "4a8698b2680cab3220a2b318eb053ae9b69378f745c0d9084eabd912a65832f5",
+    ".agents/workflows/cairn-toolcheck.md": "530051de82b89ba97a5f8bc8951e0c80482849551cb81c6c5dc5dd975c2f0845",
+    ".agents/workflows/cairn-uninstall.md": "81f2e1551eff44b97128da0d715fe1b43f14305eb0dc1b06aad4743fae8d2d67",
+    ".agents/workflows/cairn-upgrade.md": "0a646846edb989aef7cbce3963721906860f0edc1af55811cc3b4b3ad3ff9f15",
+    ".agents/workflows/cairn-work.md": "c508db4dd2f8c00c4439c10153cce5a63a0fcb60f9e3ffa94412f3e64ab1e84b",
+    ".claude/agents/explorer.md": "bb7807ebc8a39d1e63b342e0d4e44d24b93ee110d15e322ec60d43c49b9a9d45",
+    ".claude/agents/worker.md": "2619eb04fce8dd637cf506ac604f7d41cb8fb13934a2cd4e9ed2df05b95ab30e",
+    ".claude/commands/cairn-doctor.md": "1c6b39fe9f7fdbd285018d39677b0e35b9cd5ddb99eb343f85bb5f735efbb733",
+    ".claude/commands/cairn-install.md": "52b2b09c0a756112b13da9dd6653fbc84a86b026b24c123b248c80c797dbd77e",
+    ".claude/commands/cairn-memory.md": "3da4f95c24b2b12eddf09ef365023a2d1fd79467f8c50dee86e5a860c62bd9fd",
+    ".claude/commands/cairn-plan.md": "dfb9d5fb4643158323f3b4e116dfda518384a74ca300b6571929e806a5cdae1f",
+    ".claude/commands/cairn-review.md": "c5a8aa682e871c824f07830ef2cc8d6644df12e256393ed1a54739cbc3b0f817",
+    ".claude/commands/cairn-toolcheck.md": "169e52144875b79b230fbe9f20343c820b81c4f6a87a5328d9db7155253d819d",
+    ".claude/commands/cairn-uninstall.md": "86c46dc88f1f7d236046d996768b91145deacdbc8b5a456044d9696ee1769038",
+    ".claude/commands/cairn-upgrade.md": "8b7b82a3d235e0f6a0dbedc393a3ebe5773e88d593bcaa8468ac7bbc653b038d",
+    ".claude/commands/cairn-work.md": "6b434795411ffeac53625f3daceefee2edb47030dd9b93d764a539de5c79562b",
+    ".codex-plugin/plugin.json": "5d75b04c4240da2235c5489a328ac94450f7d9c49078fba33273d1ca0eb96a30",
+    "LICENSE": "1284a0177aecbc8ed521c2c99480f0f6767ab1ca4b832f30d513ae1aa1368f92",
+    "README.de.md": "3d73f892136bd1beb15f1e95071b85b74b9e18ef38d8cebde02a09266beadb28",
+    "README.es.md": "7bc44d65b47b1c8ee9a7a6a65360bef89a0ed611c1e808d0ed1a4a95108c9271",
+    "README.fr.md": "65eb784d27249c50e317708adf75aafb2495e4f552cb0ec3b123999a920abef0",
+    "README.ja.md": "241fd360d6ea430494b099872fbe9f64480e22ef26409e7fc43a4eee1fe183ee",
+    "README.ko.md": "f39289045e26834ce518ffded3af3f6ac45ca09ec72c86eef6aa1c265c5d7aad",
+    "README.md": "2ccb2cab43bad082ccc566cf9330d577e66df283746e37c4d8ab25a935e57473",
+    "README.pt.md": "306ccf468c59d2cea50e385c99308aa4d7a952dbfd65c5586cf06faab13e7b5b",
+    "README.zh.md": "d788cdccb4fc327b8242085eed45a3e8ac59a0f3c4bf53f51dcae49e0996f578",
+    "agents/explorer.md": "21e0306e1184bd0adc9d5339f86f8e8e0125892054142047446c705581cf50d1",
+    "agents/worker.md": "6564dc9676687bc8f5a2b62691f4f3a776c0f5580bfa9f9bf3fe1c4831acd377",
+    "commands/cairn-doctor.md": "96af34769f64796d1b75837f4124b75f04da4363d80b521d387489d79a0a5ae3",
+    "commands/cairn-install.md": "0a6208ad7a3057bf7ee3af49654e009ae96154d25335f78706c9cca5d9482be9",
+    "commands/cairn-memory.md": "396e3d3d0863267aef2e9d450f6c664268aa53f3e61cfd759fd9a6d568b98aa5",
+    "commands/cairn-plan.md": "278da82240c8d19f11cf83d8da084f8b309443a8736f7e75503250a0a9b16e1e",
+    "commands/cairn-review.md": "1ce071e653ed06cfc915cae134aed8bc3391b3563af5bff5531289e292d90596",
+    "commands/cairn-toolcheck.md": "b0ce6737f69bb8e138b49b9b412c0cf0e9dc50534c31657eb0936f1513d5572c",
+    "commands/cairn-uninstall.md": "bf7005ef29817c19b39a21c4ffc440da0f0e694a0a09355c6e23777a8a291ab5",
+    "commands/cairn-upgrade.md": "593d1ceb3af93c94242ccb8de0a2601519072303f463be4961fd803e71e5d880",
+    "commands/cairn-work.md": "475de81bbf54c4deccccd7a63969efb20db6654ff34734f93daf95d4a8799e40",
+    "docs/model-guidance/README.md": "9291a6ca8a7717aefb39facf0dd085672e30fed2ba02461bd1e27efb0c6d1826",
+    "docs/model-guidance/claude.md": "7c8a3ff0e9d639735088d765794d168c43b87a6611dc89a6776a5e840ea2df19",
+    "docs/model-guidance/codex.md": "45eb20fcf35b9ecfc0ea7159235081c5afdce983d73174505079d3db8198ab5c",
+    "hooks/hooks.json": "5603c6533a461b53b332273ba2172a625fd6ae21d24e1ceb3a1c16862737b098",
+    "package.json": "d8e558f53ad4cd7d24a19d119aed27811a9ce88bde70d6423a7b6bd55e4e8802",
+    "scripts/cairn": "0df05a9c2480617eebd11d4e6299c3ff56fe3e243801c1fb55ab6a80a9006fe6",
+    "scripts/cairn-goal.mjs": "05f7277ba0ffa26ce5674259a6a4d40de01ffdb746645e7e32ff7c680ca214cd",
+    "scripts/cairn-lifecycle.mjs": "74b543bbb201514f4120f6de35b5d27643644b6a01f2ebf347c1f767c57f4109",
+    "scripts/cairn-paths.mjs": "815a33bc2ad6b29a3cd1c1db867f7c3e36e2913772e64dc53e563a2f9c30d674",
+    "scripts/cairn-state.mjs": "199b28e5ba3e9a296279866ba73f9769150537ceb90722b2958a1a0303511379",
+    "scripts/cairn-state.sh": "26f817a50a70b79aade3212ba89dbe0ac507998a4ce1565510624623b3899186",
+    "scripts/cairn-toolcheck.mjs": "141ec6572f81f9bf82b3e69b4b074e877ffa6166722faf3dd5b0a003a44e431d",
+    "scripts/cairn.mjs": "935048771c7393a0f5900ebc1a0501b0cfe2b63703febe9135c1fba541ca5169",
+    "skills/cairn-memory/SKILL.md": "0dcf32ceee7133df2889ea33e1b0856a0d5eedfd6d66ec43835c6b68846b66d1",
+    "skills/cairn-plan/SKILL.md": "a6997738a0311d0b9f40cf150e768f879af2577cbc4194595ed267fd42a91ac4",
+    "skills/cairn-review/SKILL.md": "52d2d2c3b96d6341f15350255acffa83e54ca3669a88f1c927811accb06f6a6a",
+    "skills/cairn-work/SKILL.md": "a20e47bb7cee345c526d619787e6ce054ea96806a51e8815a4329440237592be",
+    "templates/MEMORY.md": "a7791c4d400d3acec0dd813709c1dd8362ffc2ed2f9c407730b807b9370bdd75",
+    "templates/PLAN.md": "66a53a8f347949761cadfb95677f2e2ffca4e9dcc7b7129cdd70693cc558e00b",
+    "templates/domain-memory.md": "4a22556739a6068694c23eef723a6c40e41855884d420ed92623c3a5af42de49",
+    "templates/work-plan.md": "40458e17fbd1f8c307ba07638612131f996f711fd100d31e3fca06eeb8a8edb9"
+  }
+}

package/skills/cairn-work/SKILL.md

@@ -41,6 +41,8 @@ node "<pluginRoot>/scripts/cairn.mjs" goal complete --quiet --root "<repoRoot>"
 
 `goal verify` executes the argv after `--` without a shell and records its exit code, bounded tool output, output digest, and watched-workspace fingerprint. The legacy `goal receipt` command imports declared evidence for compatibility; declared evidence does not satisfy a default tool-bound goal.
 
+Verification defaults to 600,000 ms (10 minutes), accepts a shorter `--timeout-ms`, and is capped at 3,600,000 ms (1 hour). The external command never holds the state lock. A receipt is committed only when the starting goal/task identity and the pre/post watched fingerprint still match. Choose the watch set and verification command at the semantic boundary that proves the claimed behavior.
+
 Use `goal pause`, `goal block --reason "<concrete blocker>"`, or `goal cancel` when that is the truthful state. A task can be blocked with `goal task --task "<task-id>" --status blocked --reason "<concrete blocker>"`.
 
 ## Token-Efficient Test Contract

package/templates/work-plan.md

@@ -84,6 +84,8 @@ Describe the observable result.
 - Token budget: high reasoning for plan/triage/test design; bounded minimum implementation; concise tool-derived verification summaries.
 - Verification ladder: focused tests, one final full check, then package dry-run if no files changed. Inspect lifecycle scripts first; run normal `npm pack --dry-run` by default. Content-producing or unknown scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it while evidence remains fresh.
 - Evidence freshness: relevant changes after verification make affected evidence stale.
+- Verification execution: `goal verify` defaults to 600,000 ms (10 minutes), is capped at 3,600,000 ms (1 hour), and records only when the starting goal/task identity and pre/post watched fingerprint match.
+- Evidence boundary: choose the semantic boundary whose watch set and command prove the claimed behavior.
 - Dry-run or check mode before external-state mutation:
 - No dry-run available, if applicable:
 - Verification loop budget: two passes per task by default.