cairn-ai 0.2.4 → 0.2.6

package/scripts/cairn-goal.mjs

@@ -2,10 +2,13 @@
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { lstatSync, readFileSync, readlinkSync, realpathSync, readdirSync } from "node:fs";
-import { readFile, rename, rm } from "node:fs/promises";
-import { join, relative, resolve, sep } from "node:path";
+import { lstat, readFile, rename, rm } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertNoSymlinkComponents, safeMkdir, safeWriteFile, withStateLock } from "./cairn-safe-fs.mjs";
+import { cairnHome, goalStateDirectory, worktreeId } from "./cairn-paths.mjs";
+
+export { worktreeId } from "./cairn-paths.mjs";
 
 export const GOAL_STATE_VERSION = 2;
 export const GOAL_STATUSES = new Set(["active", "paused", "blocked", "cancelled", "completed"]);
@@ -33,17 +36,17 @@ const taskTransitions = {
 };
 
 export function goalStatePath(root = process.cwd()) {
-  return join(resolve(root), ".cairn", "state.json");
+  return join(goalStateDirectory(root), "state.json");
 }
 
 export async function readGoalState({ root = process.cwd() } = {}) {
   try {
     const path = goalStatePath(root);
-    await assertNoSymlinkComponents(root, path);
+    await assertNoSymlinkComponents(cairnHome(), path);
     const text = await readFile(path, "utf8");
     return validateState(migrateState(JSON.parse(text)));
   } catch (error) {
-    if (error?.code === "ENOENT") return null;
+    if (error?.code === "ENOENT") return migrateLegacyGoalState(root);
     if (error instanceof SyntaxError) throw new Error(`Cairn goal state is invalid JSON: ${error.message}`);
     throw error;
   }
@@ -54,8 +57,15 @@ export async function startGoal({ root = process.cwd(), goal, planId, tasks, com
   const normalizedPlanId = boundedRequiredText(planId, "planId", PLAN_ID_MAX_LENGTH);
   if (!Array.isArray(tasks) || tasks.length === 0) throw new Error("tasks must contain at least one task");
 
-  return withStateLock(root, async () => {
-    const existing = await readGoalState({ root });
+  return withGoalStateLock(root, async () => {
+    let existing = await readGoalState({ root });
+    const currentWorktreeId = worktreeId(root);
+    if (existing && existing.goal.worktreeId !== currentWorktreeId) {
+      const path = goalStatePath(root);
+      await assertNoSymlinkComponents(cairnHome(), path, { allowMissing: false });
+      await rm(path);
+      existing = null;
+    }
     if (existing && !terminalGoalStatuses.has(existing.goal.status)) {
       throw new Error(`An active Cairn goal already exists (${existing.goal.id}); pause, block, cancel, or complete it first`);
     }
@@ -75,6 +85,7 @@ export async function startGoal({ root = process.cwd(), goal, planId, tasks, com
         completionCriteria: normalizeCriteria(completionCriteria),
         requiredEvidence: normalizeCriteria(requiredEvidence),
         evidencePolicy: validEvidencePolicy(evidencePolicy),
+        worktreeId: currentWorktreeId,
         ownerSessionId: optionalText(ownerSessionId, "ownerSessionId"),
         blocker: null,
         createdAt: now,
@@ -88,18 +99,36 @@ export async function startGoal({ root = process.cwd(), goal, planId, tasks, com
   });
 }
 
+export async function reconcileWorktreeState({ root = process.cwd() } = {}) {
+  const initial = await readGoalState({ root });
+  if (!initial || initial.goal.worktreeId === worktreeId(root)) {
+    return { state: initial, removed: false };
+  }
+  return withGoalStateLock(root, async () => {
+    const state = await readGoalState({ root });
+    if (!state || state.goal.worktreeId === worktreeId(root)) {
+      return { state, removed: false };
+    }
+    const staleWorktreeId = state.goal.worktreeId;
+    const path = goalStatePath(root);
+    await assertNoSymlinkComponents(cairnHome(), path, { allowMissing: false });
+    await rm(path);
+    return { state: null, removed: true, staleWorktreeId };
+  });
+}
+
 export async function writeGoalState({ root = process.cwd(), state } = {}) {
-  return withStateLock(root, () => writeGoalStateUnlocked({ root, state }));
+  return withGoalStateLock(root, () => writeGoalStateUnlocked({ root, state }));
 }
 
 async function writeGoalStateUnlocked({ root = process.cwd(), state } = {}) {
   const validated = validateState(state);
   const path = goalStatePath(root);
-  await safeMkdir(root, ".cairn");
-  await assertNoSymlinkComponents(root, path);
+  await ensureGoalStateDirectory(root);
+  await assertNoSymlinkComponents(cairnHome(), path);
   const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
   try {
-    await safeWriteFile(root, temporaryPath, `${JSON.stringify(validated, null, 2)}\n`, "utf8");
+    await safeWriteFile(cairnHome(), temporaryPath, `${JSON.stringify(validated, null, 2)}\n`, "utf8");
     await rename(temporaryPath, path);
   } catch (error) {
     await rm(temporaryPath, { force: true }).catch(() => {});
@@ -109,21 +138,38 @@ async function writeGoalStateUnlocked({ root = process.cwd(), state } = {}) {
 
 export async function transitionGoal({ root = process.cwd(), status, blocker } = {}) {
   const nextStatus = validGoalStatus(status);
+  if (terminalGoalStatuses.has(nextStatus)) {
+    return withGoalStateLock(root, async () => {
+      const state = await readGoalState({ root });
+      if (!state) throw new Error("No Cairn goal state exists; start a goal first");
+      const next = applyGoalTransition(structuredClone(state), nextStatus, blocker, root);
+      next.revision += 1;
+      validateState(next);
+      const path = goalStatePath(root);
+      await assertNoSymlinkComponents(cairnHome(), path, { allowMissing: false });
+      await rm(path);
+      return next;
+    });
+  }
   return mutateGoal(root, (state) => {
-    const currentStatus = state.goal.status;
-    if (currentStatus === nextStatus) return state;
-    if (!goalTransitions[currentStatus].has(nextStatus)) {
-      throw new Error(`Cannot transition goal from ${currentStatus} to ${nextStatus}`);
-    }
-    if (nextStatus === "completed") ensureGoalCanComplete(state, root);
-    if (nextStatus === "blocked") state.goal.blocker = requiredText(blocker, "blocker");
-    if (nextStatus === "active") state.goal.blocker = null;
-    state.goal.status = nextStatus;
-    state.goal.updatedAt = timestamp();
-    return state;
+    return applyGoalTransition(state, nextStatus, blocker, root);
   });
 }
 
+function applyGoalTransition(state, nextStatus, blocker, root) {
+  const currentStatus = state.goal.status;
+  if (currentStatus === nextStatus) return state;
+  if (!goalTransitions[currentStatus].has(nextStatus)) {
+    throw new Error(`Cannot transition goal from ${currentStatus} to ${nextStatus}`);
+  }
+  if (nextStatus === "completed") ensureGoalCanComplete(state, root);
+  if (nextStatus === "blocked") state.goal.blocker = requiredText(blocker, "blocker");
+  if (nextStatus === "active") state.goal.blocker = null;
+  state.goal.status = nextStatus;
+  state.goal.updatedAt = timestamp();
+  return state;
+}
+
 export async function setTaskStatus({ root = process.cwd(), taskId, status, blocker } = {}) {
   const nextStatus = validTaskStatus(status);
   const normalizedTaskId = requiredText(taskId, "taskId");
@@ -153,6 +199,34 @@ export async function setTaskStatus({ root = process.cwd(), taskId, status, bloc
   });
 }
 
+export async function replanGoal({ root = process.cwd(), tasks } = {}) {
+  if (!Array.isArray(tasks) || tasks.length === 0) {
+    throw new Error("replan tasks must contain at least one incomplete task");
+  }
+
+  return mutateGoal(root, (state) => {
+    assertGoalMutable(state);
+    if (state.goal.status !== "active") throw new Error("Only an active goal can be replanned");
+
+    const completedTasks = state.tasks.filter((task) => task.status === "completed");
+    const completedIds = new Set(completedTasks.map((task) => task.id));
+    const replacementTasks = tasks.map((task, index) => {
+      const source = typeof task === "string" ? task : { ...task, status: undefined, blocker: undefined };
+      const normalized = normalizeTask(source, index, index === 0 ? "active" : "pending");
+      if (completedIds.has(normalized.id)) {
+        throw new Error(`Replanned task conflicts with completed task id: ${normalized.id}`);
+      }
+      return normalized;
+    });
+
+    state.tasks = [...completedTasks, ...replacementTasks];
+    state.receipts = state.receipts.filter((receipt) => receipt.scope === "task" && completedIds.has(receipt.taskId));
+    state.goal.blocker = null;
+    state.goal.updatedAt = timestamp();
+    return state;
+  });
+}
+
 export async function assignTask({ root = process.cwd(), taskId, agentId = null } = {}) {
   const normalizedTaskId = requiredText(taskId, "taskId");
   const normalizedAgentId = agentId === null ? null : requiredText(agentId, "agentId");
@@ -403,6 +477,11 @@ export async function handleGoalCli(args = process.argv.slice(2), { stdout = con
     emit(JSON.stringify(state));
     return state;
   }
+  if (command === "replan") {
+    const state = await replanGoal({ root, tasks: parseTasks(options.tasks ?? positional.slice(0)) });
+    emit(JSON.stringify(state));
+    return state;
+  }
   if (command === "assign") {
     const state = await assignTask({ root, taskId: options.task ?? positional[0], agentId: options.agent ?? positional[1] ?? null });
     emit(JSON.stringify(state));
@@ -452,11 +531,11 @@ export async function handleGoalCli(args = process.argv.slice(2), { stdout = con
     emit(JSON.stringify(state));
     return state;
   }
-  throw new Error("Usage: cairn-goal start|status|task|assign|receipt|verify|pause|resume|block|cancel|complete [--root PATH]");
+  throw new Error("Usage: cairn-goal start|status|task|replan|assign|receipt|verify|pause|resume|block|cancel|complete [--root PATH]");
 }
 
 async function mutateGoal(root, mutate) {
-  return withStateLock(root, async () => {
+  return withGoalStateLock(root, async () => {
     const state = await readGoalState({ root });
     if (!state) throw new Error("No Cairn goal state exists; start a goal first");
     const next = await mutate(structuredClone(state));
@@ -466,6 +545,44 @@ async function mutateGoal(root, mutate) {
   });
 }
 
+async function withGoalStateLock(root, operation) {
+  await ensureGoalStateDirectory(root);
+  return withStateLock(goalStateDirectory(root), operation);
+}
+
+async function ensureGoalStateDirectory(root) {
+  const home = cairnHome();
+  let existingAncestor = home;
+  while (true) {
+    try {
+      const stat = await lstat(existingAncestor);
+      if (!stat.isDirectory()) throw new Error(`Cairn home ancestor is not a directory: ${existingAncestor}`);
+      break;
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      const parent = dirname(existingAncestor);
+      if (parent === existingAncestor) throw error;
+      existingAncestor = parent;
+    }
+  }
+  await safeMkdir(existingAncestor, relative(existingAncestor, goalStateDirectory(root)));
+}
+
+async function migrateLegacyGoalState(root) {
+  const legacyPath = join(resolve(root), ".cairn", "state.json");
+  try {
+    await assertNoSymlinkComponents(root, legacyPath, { allowMissing: false });
+    const state = validateState(migrateState(JSON.parse(await readFile(legacyPath, "utf8"))));
+    await writeGoalStateUnlocked({ root, state });
+    await rm(legacyPath);
+    return state;
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    if (error instanceof SyntaxError) throw new Error(`Cairn goal state is invalid JSON: ${error.message}`);
+    throw error;
+  }
+}
+
 function normalizeTask(task, index, defaultStatus) {
   const source = typeof task === "string" ? { title: task } : task;
   if (!source || typeof source !== "object") throw new Error(`tasks[${index}] must be a string or object`);
@@ -516,6 +633,7 @@ function validateState(value) {
   if (!Array.isArray(goal.requiredEvidence) || goal.requiredEvidence.length === 0) throw new Error("goal.requiredEvidence must be a non-empty array");
   goal.requiredEvidence.forEach((kind, index) => requiredText(kind, `goal.requiredEvidence[${index}]`));
   if (goal.ownerSessionId !== null && goal.ownerSessionId !== undefined) requiredText(goal.ownerSessionId, "goal.ownerSessionId");
+  if (goal.worktreeId !== null && goal.worktreeId !== undefined) requiredText(goal.worktreeId, "goal.worktreeId");
   if (goal.blocker !== null && goal.blocker !== undefined) requiredText(goal.blocker, "goal.blocker");
   if (!Array.isArray(value.tasks) || value.tasks.length === 0) throw new Error("Cairn goal state must contain tasks");
   if (!Array.isArray(value.receipts)) throw new Error("Cairn goal state evidence records (receipts) must be an array");
@@ -916,6 +1034,7 @@ function allowedOptions(command) {
     start: ["goal", "plan", "tasks", "criteria", "requiredEvidence", "session", "evidencePolicy", "evidence-policy"],
     status: [],
     task: ["task", "status", "reason"],
+    replan: ["tasks"],
     assign: ["task", "agent"],
     receipt: ["task", "kind", "scope", "command", "exitCode", "exit-code", "exit", "timestamp", "goalId", "goal-id", "plan"],
     verify: ["task", "kind", "scope", "watch", "timeout-ms"],

package/scripts/cairn-lifecycle.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createHash, randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { constants as fsConstants, realpathSync } from "node:fs";
 import {
   copyFile, cp, lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, rmdir, writeFile,
 } from "node:fs/promises";
@@ -119,17 +119,18 @@ async function uninstall() {
   const conflicts = [];
   for (const record of ownership.targets) {
     const current = await targetDigest(record.path, record.type);
-    if (current !== record.installedDigest) conflicts.push(record.path);
+    if (record.type !== "config" && current !== record.installedDigest) conflicts.push(record.path);
   }
   if (conflicts.length > 0) throw new Error(`Refusing to uninstall modified managed artifacts: ${conflicts.join(", ")}`);
   const transaction = await createTransaction();
   try {
     const configRecord = ownership.targets.find((record) => record.type === "config");
-    if (configRecord) {
+    if (configRecord && await exists(configRecord.path)) {
+      const snapshot = await readSharedConfigSnapshot(configRecord.path);
       const staged = join(transaction.stageRoot, "uninstall-config.toml");
       await mkdir(dirname(staged), { recursive: true });
-      await writeFile(staged, removeCairnConfig(await readText(configRecord.path)));
-      await replaceTarget({ ...configRecord, staged }, transaction);
+      await writeFile(staged, removeCairnConfig(snapshot.text));
+      await replaceTarget({ ...configRecord, staged, configSourceDigest: snapshot.digest }, transaction);
     }
     injectFailure("uninstall-after-config");
     for (const phase of ["antigravity", "claude"]) {
@@ -166,7 +167,7 @@ async function doctor() {
   checks.push(["installed CLI script", await exists(join(versionedPluginRoot, "scripts", "cairn.mjs"))]);
   checks.push(["installed plan template", await exists(join(versionedPluginRoot, "templates", "work-plan.md"))]);
   checks.push(["installed model guidance", await exists(join(versionedPluginRoot, "docs", "model-guidance", "codex.md"))]);
-  const config = await readText(configPath);
+  const config = (await readSharedConfigSnapshot(configPath)).text;
   checks.push(["config marketplace", splitSections(config).some((section) => section.header === "marketplaces.cairn")]);
   checks.push(["config plugin enabled", hasSetting(config, 'plugins."cairn@cairn"', "enabled", "true")]);
   checks.push(["Claude runtime locator", await validRuntimeLocator(claudeRuntimeLocatorPath)]);
@@ -204,7 +205,7 @@ async function ownershipDigestsValid(ownership) {
 
 async function stageInstall(stageRoot) {
   const targets = [];
-  const add = (id, phase, destination, staged, type = "tree") => targets.push({ id, phase, path: destination, staged, type });
+  const add = (id, phase, destination, staged, type = "tree", details = {}) => targets.push({ id, phase, path: destination, staged, type, ...details });
   const sourceStage = join(stageRoot, "codex-source");
   const runtimeStage = join(stageRoot, "codex-runtime");
   await copyPluginCandidate(sourceStage, versionedPluginRoot);
@@ -239,8 +240,9 @@ async function stageInstall(stageRoot) {
 
   const configStage = join(stageRoot, "config.toml");
   const hookStates = await trustedHookStates(runtimeStage);
-  await writeFile(configStage, updateConfig(await readText(configPath), hookStates));
-  add("codex-config", "config", configPath, configStage, "config");
+  const configSnapshot = await readSharedConfigSnapshot(configPath);
+  await writeFile(configStage, updateConfig(configSnapshot.text, hookStates));
+  add("codex-config", "config", configPath, configStage, "config", { configSourceDigest: configSnapshot.digest });
   for (const target of targets) await assertRegularTree(target.staged);
   return targets;
 }
@@ -465,6 +467,15 @@ function pidIsAlive(pid) {
 function delay(ms) { return new Promise((resolvePromise) => setTimeout(resolvePromise, ms)); }
 
 async function replaceTarget(target, transaction) {
+  let configProjection = null;
+  if (target.type === "config") {
+    const snapshot = await readSharedConfigSnapshot(target.path);
+    configProjection = cairnConfigProjection((await readSharedConfigSnapshot(target.staged)).text);
+    if (snapshot.digest !== target.configSourceDigest) {
+      await writeFile(target.staged, `${removeCairnConfig(snapshot.text)}${configProjection}`);
+      target.configSourceDigest = snapshot.digest;
+    }
+  }
   const existed = await exists(target.path);
   const backup = join(transaction.backupRoot, String(transaction.entries.length));
   await mkdir(dirname(backup), { recursive: true });
@@ -482,7 +493,30 @@ async function replaceTarget(target, transaction) {
   };
   transaction.entries.push(entry);
   await writeTransactionJournal(transaction);
-  if (existed) await rename(target.path, backup);
+  if (target.type === "config" && process.env.CAIRN_TEST_APPEND_CONFIG_BEFORE_REPLACE) {
+    const snapshot = await readSharedConfigSnapshot(target.path);
+    await writeFile(target.path, `${snapshot.text}${process.env.CAIRN_TEST_APPEND_CONFIG_BEFORE_REPLACE}`);
+  }
+  if (target.type === "config" && process.env.CAIRN_TEST_REMOVE_CONFIG_BEFORE_REPLACE === "1") {
+    await rm(target.path, { force: true });
+  }
+  if (target.type === "config") {
+    let capturedExists = true;
+    try {
+      await rename(target.path, backup);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      capturedExists = false;
+    }
+    if (process.env.CAIRN_TEST_CRASH_AFTER_CONFIG_CAPTURE === "1") process.exit(86);
+    const captured = await readSharedConfigSnapshot(backup);
+    if (capturedExists) await writeFile(target.staged, `${removeCairnConfig(captured.text)}${configProjection}`);
+    else await writeFile(target.staged, configProjection);
+    entry.existed = capturedExists;
+    entry.previousDigest = capturedExists ? await targetDigest(backup, target.type) : "missing";
+    entry.expectedNewDigest = await targetDigest(target.staged, target.type);
+    await writeTransactionJournal(transaction);
+  } else if (existed) await rename(target.path, backup);
   await mkdir(dirname(target.path), { recursive: true });
   await rename(target.staged, target.path);
   entry.status = "applied";
@@ -632,6 +666,18 @@ async function rollbackEntries(transaction) {
     const destinationExists = await exists(entry.path);
     const backupExists = await exists(entry.backup);
     if (backupExists) {
+      if (entry.type === "config" && entry.status === "prepared") {
+        const previousConfig = (await readSharedConfigSnapshot(entry.backup)).text;
+        if (destinationExists) {
+          const currentConfig = (await readSharedConfigSnapshot(entry.path)).text;
+          await writeFile(entry.path, `${removeCairnConfig(currentConfig)}${cairnConfigProjection(previousConfig)}`);
+          await rm(entry.backup, { force: true });
+        } else {
+          await mkdir(dirname(entry.path), { recursive: true });
+          await rename(entry.backup, entry.path);
+        }
+        continue;
+      }
       if (!entry.existed) throw new Error(`Cannot recover transaction because an unexpected backup exists: ${entry.path}`);
       if (await targetDigest(entry.backup, entry.type) !== entry.previousDigest) {
         throw new Error(`Cannot recover transaction because its durable backup changed: ${entry.path}`);
@@ -640,8 +686,8 @@ async function rollbackEntries(transaction) {
         const current = await targetDigest(entry.path, entry.type);
         if (current !== entry.expectedNewDigest) throw new Error(`Cannot recover transaction because destination changed: ${entry.path}`);
         if (entry.type === "config") {
-          const currentConfig = await readText(entry.path);
-          const previousConfig = await readText(entry.backup);
+          const currentConfig = (await readSharedConfigSnapshot(entry.path)).text;
+          const previousConfig = (await readSharedConfigSnapshot(entry.backup)).text;
           await writeFile(entry.path, `${removeCairnConfig(currentConfig)}${cairnConfigProjection(previousConfig)}`);
           await rm(entry.backup, { force: true });
           continue;
@@ -650,12 +696,14 @@ async function rollbackEntries(transaction) {
       }
       await mkdir(dirname(entry.path), { recursive: true });
       await rename(entry.backup, entry.path);
+    } else if (entry.type === "config" && entry.status === "prepared" && !destinationExists) {
+      continue;
     } else if (!entry.existed) {
       if (destinationExists) {
         const current = await targetDigest(entry.path, entry.type);
         if (current !== entry.expectedNewDigest) throw new Error(`Cannot recover new transaction target because it changed: ${entry.path}`);
         if (entry.type === "config") {
-          const preserved = removeCairnConfig(await readText(entry.path));
+          const preserved = removeCairnConfig((await readSharedConfigSnapshot(entry.path)).text);
           if (preserved.length > 0) await writeFile(entry.path, preserved);
           else await rm(entry.path, { force: true });
         } else await rm(entry.path, { recursive: true, force: true });
@@ -688,7 +736,7 @@ async function assertTargetsReplaceable(targets, ownership) {
     }
     const record = records.get(target.id);
     if (!record) {
-      if (target.type === "config" && cairnConfigProjection(await readText(target.path)).length === 0) continue;
+      if (target.type === "config" && cairnConfigProjection((await readSharedConfigSnapshot(target.path)).text).length === 0) continue;
       throw new Error(`Refusing to overwrite unmanaged artifact: ${target.path}`);
     }
     if (target.id === "codex-runtime" && ownership?.version !== releaseVersion) {
@@ -696,13 +744,14 @@ async function assertTargetsReplaceable(targets, ownership) {
     }
     if (record.path !== target.path || record.type !== target.type) throw new Error(`Ownership manifest target mismatch: ${target.id}`);
     const current = await targetDigest(target.path, target.type);
-    if (current !== record.installedDigest) throw new Error(`Managed artifact was modified: ${target.path}`);
+    if (target.type !== "config" && current !== record.installedDigest) throw new Error(`Managed artifact was modified: ${target.path}`);
   }
 }
 
 async function assertOwnershipDigests(ownership) {
   for (const record of ownership.targets) {
-    if (await targetDigest(record.path, record.type) !== record.installedDigest) {
+    const current = await targetDigest(record.path, record.type);
+    if (record.type !== "config" && current !== record.installedDigest) {
       throw new Error(`Managed artifact was modified: ${record.path}`);
     }
   }
@@ -806,7 +855,7 @@ function versionedRuntimeRoot(version) {
 async function anyManagedArtifactExists(targets) {
   for (const target of targets) {
     if (!(await exists(target.path))) continue;
-    if (target.type !== "config" || cairnConfigProjection(await readText(target.path)).length > 0) return true;
+    if (target.type !== "config" || cairnConfigProjection((await readSharedConfigSnapshot(target.path)).text).length > 0) return true;
   }
   return false;
 }
@@ -826,7 +875,7 @@ async function adoptLegacy(targets, transaction) {
       }
     }
     if (target.type === "config") {
-      const projection = cairnConfigProjection(await readText(target.path));
+      const projection = cairnConfigProjection((await readSharedConfigSnapshot(target.path)).text);
       if (!projection.includes("[marketplaces.cairn]") || !projection.includes('[plugins."cairn@cairn"]')) {
         throw new Error(`Legacy Cairn config cannot be identified: ${target.path}`);
       }
@@ -923,7 +972,7 @@ async function verifyLegacyMirror(target) {
 
 export async function targetDigest(path, type) {
   if (!(await exists(path))) return "missing";
-  if (type === "config") return sha(cairnConfigProjection(await readText(path)));
+  if (type === "config") return sha(cairnConfigProjection((await readSharedConfigSnapshot(path)).text));
   const info = await lstat(path);
   if (info.isSymbolicLink() || (!info.isFile() && !info.isDirectory())) throw new Error(`Managed artifact is not a regular file/tree: ${path}`);
   if (info.isFile()) return sha(await readFile(path));
@@ -969,19 +1018,60 @@ export function updateConfig(config, hookStates, { marketplacePath = marketplace
 }
 
 export function removeCairnConfig(config) {
-  return splitSections(config).filter((section) => {
-    if (section.header === null) return true;
-    if (section.header === "marketplaces.cairn") return false;
-    if (section.header === 'plugins."cairn@cairn"') return false;
-    return !(section.header.startsWith("hooks.state.") && section.header.includes("cairn@cairn:"));
-  }).map((section) => section.text).join("");
+  return splitSections(config).map((section) => isCairnConfigSection(section)
+    ? splitTrailingTomlTrivia(section.text).trivia
+    : section.text).join("");
 }
 
 function cairnConfigProjection(config) {
-  return splitSections(config).filter((section) => section.header === "marketplaces.cairn"
+  return splitSections(config).filter(isCairnConfigSection)
+    .map((section) => splitTrailingTomlTrivia(section.text).body).join("");
+}
+
+function isCairnConfigSection(section) {
+  return section.header === "marketplaces.cairn"
     || section.header === 'plugins."cairn@cairn"'
-    || (section.header?.startsWith("hooks.state.") && section.header.includes("cairn@cairn:")))
-    .map((section) => section.text).join("");
+    || (section.header?.startsWith("hooks.state.") && section.header.includes("cairn@cairn:"));
+}
+
+function splitTrailingTomlTrivia(text) {
+  const lines = text.split(/(?<=\n)/);
+  let boundary = lines.length;
+  while (boundary > 0) {
+    const line = lines[boundary - 1];
+    if (line.length === 0 || line.trim().length === 0 || line.trimStart().startsWith("#")) boundary -= 1;
+    else break;
+  }
+  return { body: lines.slice(0, boundary).join(""), trivia: lines.slice(boundary).join("") };
+}
+
+async function readSharedConfigSnapshot(path) {
+  let pathInfo;
+  try {
+    pathInfo = await lstat(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") return { exists: false, text: "", digest: "missing" };
+    throw error;
+  }
+  if (pathInfo.isSymbolicLink() || !pathInfo.isFile()) throw new Error(`Managed config is not a regular file: ${path}`);
+  let handle;
+  try {
+    const flags = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0);
+    handle = await open(path, flags);
+  } catch (error) {
+    if (["ELOOP", "EFTYPE", "ENXIO"].includes(error?.code)) throw new Error(`Managed config is not a regular file: ${path}`);
+    throw error;
+  }
+  try {
+    const openedInfo = await handle.stat();
+    if (!openedInfo.isFile() || openedInfo.dev !== pathInfo.dev || openedInfo.ino !== pathInfo.ino) {
+      throw new Error(`Managed config changed identity while opening: ${path}`);
+    }
+    const text = await handle.readFile("utf8");
+    return { exists: true, text, digest: sha(text) };
+  } finally {
+    await handle.close();
+  }
 }
 
 export function ensureSetting(config, sectionName, key, value) {

package/scripts/cairn-paths.mjs

@@ -1,9 +1,55 @@
-import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const RUNTIME_LOCATOR_SCHEMA_VERSION = 1;
 
+export function cairnHome(env = process.env) {
+  const userHome = env.HOME ?? env.USERPROFILE ?? homedir();
+  return resolve(env.CAIRN_HOME ?? join(userHome, ".cairn"));
+}
+
+export function repositoryId(root = process.cwd()) {
+  return `project-${hashPath(gitLayout(root).commonDir)}`;
+}
+
+export function worktreeId(root = process.cwd()) {
+  return `worktree-${hashPath(gitLayout(root).gitDir)}`;
+}
+
+export function goalStateDirectory(root = process.cwd(), env = process.env) {
+  return join(cairnHome(env), "projects", repositoryId(root), "worktrees", worktreeId(root));
+}
+
+function gitLayout(root) {
+  const workspaceRoot = realpathSync(resolve(root));
+  const gitEntry = join(workspaceRoot, ".git");
+  try {
+    const stat = lstatSync(gitEntry);
+    const gitDir = stat.isDirectory() ? realpathSync(gitEntry) : resolveGitFile(workspaceRoot, gitEntry);
+    const commonFile = join(gitDir, "commondir");
+    const commonDir = existsSync(commonFile)
+      ? realpathSync(resolve(gitDir, readFileSync(commonFile, "utf8").trim()))
+      : gitDir;
+    return { gitDir, commonDir };
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    return { gitDir: workspaceRoot, commonDir: workspaceRoot };
+  }
+}
+
+function resolveGitFile(workspaceRoot, gitEntry) {
+  const match = readFileSync(gitEntry, "utf8").match(/^gitdir:\s*(.+)\s*$/m);
+  if (!match) throw new Error(`Invalid Git worktree file: ${gitEntry}`);
+  return realpathSync(resolve(workspaceRoot, match[1]));
+}
+
+function hashPath(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
 export function resolvePluginRoot(moduleUrl = import.meta.url) {
   return resolve(dirname(fileURLToPath(moduleUrl)), "..");
 }