cairn-ai 0.2.1 → 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
 
@@ -65,6 +66,7 @@ This file is a short index of active and completed work plans.
 ## Planning Rules
 
 - Every agent must start assigned work by reading the project-root \`MEMORY.md\` for domain knowledge and repository policy.
+- For implementation or continued execution, first write an initial plan with \`triage-plan\` active, synchronize it to native UI plan/goal tools and the repository goal before exploration, then update it after triage.
 - Plans must be decision-complete before implementation.
 - Run complexity triage before applying agent, plugin, or delegated workflow guidance.
 - Record the selected Light Path or Heavy Path and the checked Heavy Path signals in \`docs/plan/<topic>.md\`.
@@ -96,6 +98,7 @@ const planTemplateKo = `# PLAN
 ## Planning Rules
 
 - 모든 에이전트는 배정된 작업을 시작할 때 도메인 지식과 저장소 정책을 위해 프로젝트 루트 \`MEMORY.md\`를 먼저 읽어야 합니다.
+- 구현 또는 계속 실행 요청은 먼저 \`triage-plan\`이 active인 초기 계획을 쓰고, 탐색 전에 UI plan/goal과 저장소 goal을 동기화한 뒤 트리아지 결과로 계획을 갱신합니다.
 - 계획은 구현 전에 의사결정이 완료된 상태여야 합니다.
 - 에이전트, 플러그인, 위임 워크플로 지침을 적용하기 전에 복잡도 트리아지를 실행합니다.
 - 선택한 Light Path 또는 Heavy Path와 확인한 Heavy Path 신호를 \`docs/plan/<topic>.md\`에 기록합니다.
@@ -112,6 +115,13 @@ const planTemplateKo = `# PLAN
 - 두 번 실패한 뒤에는 blocker를 \`docs/plan/<topic>.md\`에 기록합니다.
 `;
 
+const contextLimits = {
+  goalTitle: 64,
+  taskId: 32,
+  taskTitle: 40,
+  roadmapWindow: 3,
+};
+
 if (isCliEntry()) {
   const event = process.argv[2] ?? "manual";
   const payload = await readHookInput();
@@ -153,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 receipt가 필요합니다. 활성 목표가 있다면 현재 task에 성공 receipt를 기록하세요."
-        : "Cairn check: external-state changes need a dry-run/check receipt. When a goal is active, record a successful receipt for its current task.",
-      hookOutput: {},
+      message,
+      hookOutput: {
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: message,
+        },
+      },
     };
   }
 
@@ -184,53 +200,79 @@ 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 });
+    }
   }
 }
 
 function contextResult({ ko, state, event }) {
-  const base = ko
-    ? "Cairn 컨텍스트: 작업 전 프로젝트 루트 MEMORY.md를 읽으세요."
-    : "Cairn context: read the project-root MEMORY.md before working.";
-  const goalPolicy = event === "user-prompt-submit"
+  const base = ko ? "Cairn: 루트 MEMORY.md를 읽으세요." : "Cairn: read root MEMORY.md.";
+  const idlePolicy = event === "user-prompt-submit"
     ? (ko
-      ? "현재 사용자 prompt가 구현 또는 계속 실행을 요청한다면, 사용자가 goal을 언급하지 않아도 이 요청 자체를 권한으로 간주하세요. decision-complete plan에 순서가 있는 stable task 단계를 정의한 뒤 구현 전에 활성 Cairn goal을 생성하거나 연결하고, 완료·일시정지·차단·취소 상태가 될 때까지 계속 진행하세요. 상담·설명·계획 전용 요청에는 goal을 만들지 마세요."
-      : "If the current user prompt requests implementation or continued execution, treat the request itself as authorization even when the user does not mention a goal. Define stable, ordered task steps in a decision-complete plan, then create or attach an active Cairn goal before implementation and continue until it is completed, paused, blocked, or cancelled. Do not create a goal for consultation, explanation, or plan-only requests.")
+      ? " 구현/계속 실행: 초기 트리아지 계획 작성 → update_plan → create_goal → 탐색 전 저장소 goal 시작 → 트리아지 후 계획 확정 → 구현. 상담·설명·계획 전용은 goal 없이 처리하세요."
+      : " Implementation/continue: write an initial triage plan; call update_plan, then create_goal; start the repository goal before exploration; finalize the plan after triage, then implement. Skip goals for consultation, explanation, or plan-only requests.")
     : "";
-  const initialContext = [base, goalPolicy].filter(Boolean).join(" ");
-  if (!state || state.goal.status !== "active") return contextHookResult({ event, message: initialContext });
-  const task = state.tasks.find((item) => item.status === "active") ?? state.tasks.find((item) => item.status === "pending");
+  if (!state || state.goal.status !== "active") return contextHookResult({ event, message: `${base}${idlePolicy}` });
+  const task = state.tasks.find((item) => item.status === "active")
+    ?? state.tasks.find((item) => item.status === "pending")
+    ?? state.tasks.find((item) => item.status === "blocked");
+  const goalTitle = clipText(state.goal.title, contextLimits.goalTitle);
+  const activeHeader = ko
+    ? `Cairn active: "${goalTitle}". ${base}`
+    : `Cairn active: "${goalTitle}". ${base}`;
   if (!task) {
     return contextHookResult({
       event,
-      message: [initialContext, taskRoadmap(ko, state), activeGoalCompletionMessage(ko, state)].join("\n"),
+      message: [activeHeader, taskRoadmap(ko, state), activeGoalCompletionMessage(ko, state)].join("\n"),
     });
   }
+  const taskId = clipText(task.id, contextLimits.taskId);
+  const taskTitle = clipText(task.title, contextLimits.taskTitle);
   const continuation = ko
-    ? `활성 목표 "${state.goal.title}"의 현재 task는 ${task.id} (${task.title})입니다. 완료 전 성공 receipt를 기록하세요.`
-    : `Active goal "${state.goal.title}" current task: ${task.id} (${task.title}). Record a successful receipt before completing it.`;
+    ? `현재: ${taskId} (${taskTitle}). 바인딩된 증거 뒤에만 완료하세요.`
+    : `Current: ${taskId} (${taskTitle}). Complete only after bound evidence.`;
   const resume = event === "user-prompt-submit"
     ? (ko
-      ? `곁가지 질문에 답한 뒤 사용자가 명시적으로 일시정지·중단·전환을 요청하지 않았다면 현재 task ${task.id}로 돌아와 계속 진행하세요.`
-      : `After answering a side question, return to current task ${task.id} and continue unless the user explicitly asks to pause, stop, or switch tasks.`)
+      ? `곁가지 질문 뒤 일시정지·중단·전환 요청이 없으면 ${taskId}를 재개하세요.`
+      : `After a side question, resume ${taskId} unless asked to pause, stop, or switch.`)
     : "";
-  return contextHookResult({ event, message: [initialContext, taskRoadmap(ko, state), continuation, resume].filter(Boolean).join("\n") });
+  return contextHookResult({ event, message: [activeHeader, taskRoadmap(ko, state), continuation, resume].filter(Boolean).join("\n") });
 }
 
 function taskRoadmap(ko, state) {
-  const steps = state.tasks.map((task, index) => `${index + 1}. ${task.id} [${task.status}] ${task.title}`);
-  return `${ko ? "작업 단계" : "Work steps"}:\n${steps.join("\n")}`;
+  const formatTask = (task, index) => `${index + 1}. ${clipText(task.id, contextLimits.taskId)} [${task.status}] ${clipText(task.title, contextLimits.taskTitle)}`;
+  if (state.tasks.length <= contextLimits.roadmapWindow) {
+    return `${ko ? "작업 단계" : "Work steps"}:\n${state.tasks.map(formatTask).join("\n")}`;
+  }
+
+  const currentIndex = Math.max(0, state.tasks.findIndex((task) => task.status === "active" || task.status === "pending"));
+  const maxStart = state.tasks.length - contextLimits.roadmapWindow;
+  const start = Math.min(Math.max(0, currentIndex - 1), maxStart);
+  const visible = state.tasks.slice(start, start + contextLimits.roadmapWindow);
+  const counts = Object.fromEntries([...TASK_STATUS_NAMES].map((status) => [status, state.tasks.filter((task) => task.status === status).length]));
+  const countSummary = Object.entries(counts).filter(([, count]) => count > 0).map(([status, count]) => `${status} ${count}`).join(", ");
+  const omitted = state.tasks.length - visible.length;
+  const header = ko
+    ? `작업 단계 (${state.tasks.length}개; ${countSummary})`
+    : `Work steps (${state.tasks.length}; ${countSummary})`;
+  const omission = ko ? `… ${omitted}개 단계 생략` : `… ${omitted} steps omitted`;
+  return `${header}:\n${visible.map((task, index) => formatTask(task, start + index)).join("\n")}\n${omission}`;
 }
 
 function contextHookResult({ event, message }) {
@@ -272,9 +314,17 @@ function stopAllowedMessage({ ko, state, event }) {
 }
 
 function activeGoalCompletionMessage(ko, state) {
+  const goalTitle = clipText(state.goal.title, contextLimits.goalTitle);
   return ko
-    ? `활성 목표 "${state.goal.title}"의 모든 task가 완료되었습니다. 완료 기준을 확인하고 명시적으로 complete 상태로 전이하세요.`
-    : `All tasks for active goal "${state.goal.title}" are complete. Verify criteria and explicitly transition the goal to completed.`;
+    ? `활성 목표 "${goalTitle}"의 모든 task가 완료되었습니다. 완료 기준을 확인하고 명시적으로 complete 상태로 전이하세요.`
+    : `All tasks for active goal "${goalTitle}" are complete. Verify criteria and explicitly transition the goal to completed.`;
+}
+
+const TASK_STATUS_NAMES = ["active", "pending", "blocked", "completed"];
+
+function clipText(value, maxLength) {
+  const text = String(value ?? "");
+  return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
 }
 
 function resolveRoot(root, payload) {

package/scripts/cairn-state.sh

@@ -85,6 +85,7 @@ if [ ! -f "$plan" ]; then
 ## Planning Rules
 
 - 모든 에이전트는 배정된 작업을 시작할 때 도메인 지식과 저장소 정책을 위해 프로젝트 루트 `MEMORY.md`를 먼저 읽어야 합니다.
+- 구현 또는 계속 실행 요청은 먼저 `triage-plan`이 active인 초기 계획을 쓰고, 탐색 전에 UI plan/goal과 저장소 goal을 동기화한 뒤 트리아지 결과로 계획을 갱신합니다.
 - 계획은 구현 전에 의사결정이 완료된 상태여야 합니다.
 - 에이전트, 플러그인, 위임 워크플로 지침을 적용하기 전에 복잡도 트리아지를 실행합니다.
 - 선택한 Light Path 또는 Heavy Path와 확인한 Heavy Path 신호를 `docs/plan/<topic>.md`에 기록합니다.
@@ -117,6 +118,7 @@ This file is a short index of active and completed work plans.
 ## Planning Rules
 
 - Every agent must start assigned work by reading the project-root `MEMORY.md` for domain knowledge and repository policy.
+- For implementation or continued execution, first write an initial plan with `triage-plan` active, synchronize it to native UI plan/goal tools and the repository goal before exploration, then update it after triage.
 - Plans must be decision-complete before implementation.
 - Split implementation into small module tasks.
 - Detect repository stack and required LSP/check tools before implementation.