cairn-ai 0.2.5 → 0.2.7

package/scripts/cairn-lifecycle-legacy.mjs

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { cp, lstat, mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { cairnConfigProjection, readSharedConfigSnapshot } from "./cairn-lifecycle-config.mjs";
+import {
+  antigravityRuntimeLocatorPath, antigravitySkillLocatorPath, renderMirrorFile,
+  validLegacyLocator, writeLocator,
+} from "./cairn-lifecycle-mirror.mjs";
+
+export function createLegacyIntegrity(context) {
+  const {
+    antigravityCliHome, antigravityHome, claudeRuntimeLocatorPath,
+    installedPluginRoot, legacyAntigravityHome, marketplaceName, pluginName,
+    pluginRoot, regularFiles, skillNames, targetDigest,
+  } = context;
+async function adoptLegacy(targets, transaction) {
+  if (!(await exists(installedPluginRoot))) throw new Error("Existing lifecycle artifacts are unmanaged; legacy Cairn root is missing.");
+  await verifyLegacy022Root(installedPluginRoot);
+  const records = [];
+  for (const target of targets) {
+    if (!(await exists(target.path))) continue;
+    if (target.id === "codex-runtime") continue;
+    if (target.id === "marketplace") {
+      const marketplace = await readJson(target.path);
+      const entry = marketplace?.plugins?.find((plugin) => plugin.name === pluginName);
+      if (marketplace?.name !== marketplaceName || entry?.source?.source !== "local" || entry?.source?.path !== "./plugins/cairn") {
+        throw new Error(`Legacy Cairn marketplace cannot be identified: ${target.path}`);
+      }
+    }
+    if (target.type === "config") {
+      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}`);
+      }
+    } else if (target.id.endsWith("-runtime")) {
+      const locator = await readJson(target.path);
+      if (!validLegacyLocator(locator, installedPluginRoot)) throw new Error(`Legacy runtime mirror is invalid: ${target.path}`);
+    } else if (target.id !== "codex-source" && target.id !== "marketplace") {
+      await verifyLegacyMirror(target);
+    }
+    const backup = join(transaction.backupRoot, `legacy-${records.length}`);
+    await mkdir(dirname(backup), { recursive: true });
+    await cp(target.path, backup, { recursive: true });
+    records.push({ id: target.id, phase: target.phase, path: target.path, type: target.type, installedDigest: await targetDigest(target.path, target.type), previous: null });
+  }
+  return { schemaVersion: 1, plugin: pluginName, version: "0.2.2", transactionId: `legacy-${transaction.id}`, targets: records };
+}
+
+async function verifyLegacy022Root(root) {
+  const integrity = JSON.parse(await readFile(join(pluginRoot, "scripts", "release-integrity-0.2.2.json"), "utf8"));
+  const allowedGenerated = new Set([".cairn-runtime.json", ...skillNames().map((name) => `skills/${name}/references/cairn-runtime.json`)]);
+  const actual = await regularFiles(root);
+  const expected = new Set([...Object.keys(integrity.files), ...allowedGenerated]);
+  if (actual.length !== expected.size || actual.some((file) => !expected.has(file))) throw new Error("Legacy Cairn 0.2.2 root file set does not match the pinned SHA-256 file-hash allowlist.");
+  for (const [path, expectedHash] of Object.entries(integrity.files)) {
+    const content = await readFile(join(root, path));
+    if (path === ".codex-plugin/plugin.json") {
+      const manifest = JSON.parse(content);
+      if (manifest.name !== "cairn" || manifest.version !== "0.2.2" || manifest.hooks !== "./hooks/hooks.json") throw new Error("Legacy Cairn manifest identity is invalid.");
+      delete manifest.hooks;
+      if (sha(`${JSON.stringify(manifest, null, 2)}\n`) !== `sha256:${expectedHash}`) throw new Error("Legacy Cairn manifest differs from release 0.2.2.");
+    } else if (sha(content) !== `sha256:${expectedHash}`) throw new Error(`Legacy Cairn release file was modified: ${path}`);
+  }
+  for (const path of allowedGenerated) {
+    const locator = JSON.parse(await readFile(join(root, path), "utf8"));
+    if (!validLegacyLocator(locator, root)) throw new Error(`Legacy runtime locator is invalid: ${path}`);
+  }
+}
+
+async function verifyLegacyMirror(target) {
+  // Legacy mirrors are accepted only when byte-identical to a deterministic render
+  // from the verified release tree. Unknown or user-modified mirrors are preserved.
+  const temp = await mkdtemp(join(tmpdir(), "cairn-legacy-mirror-"));
+  try {
+    const expected = join(temp, "expected");
+    if (target.id.startsWith("claude-command-")) {
+      const name = target.id.slice("claude-command-".length);
+      await renderMirrorFile(join(installedPluginRoot, ".claude", "commands", `cairn-${name}.md`), expected, { locatorPath: claudeRuntimeLocatorPath, runtimeRoot: installedPluginRoot });
+    } else if (target.id.startsWith("claude-agent-")) {
+      const name = target.id.slice("claude-agent-".length);
+      await renderMirrorFile(join(installedPluginRoot, ".claude", "agents", `${name}.md`), expected, { locatorPath: claudeRuntimeLocatorPath, runtimeRoot: installedPluginRoot });
+    } else if (target.id.startsWith("ide-skill-")) {
+      const name = target.id.slice("ide-skill-".length);
+      await cp(join(installedPluginRoot, "skills", name), expected, { recursive: true });
+      const locator = antigravitySkillLocatorPath(antigravityHome, name);
+      await renderMirrorFile(join(installedPluginRoot, "skills", name, "SKILL.md"), join(expected, "SKILL.md"), { locatorPath: locator, runtimeRoot: installedPluginRoot, includeLocatorNotice: true });
+      await writeLocator(join(expected, "references", "cairn-runtime.json"), installedPluginRoot);
+    } else if (target.id.startsWith("cli-skill-")) {
+      const name = target.id.slice("cli-skill-".length);
+      await renderMirrorFile(join(installedPluginRoot, "skills", name, "SKILL.md"), expected, {
+        locatorPath: antigravityRuntimeLocatorPath(antigravityCliHome),
+        runtimeRoot: installedPluginRoot,
+        includeLocatorNotice: true,
+      });
+    } else if (target.id.startsWith("legacy-ide-skill-") || target.id.startsWith("legacy-cli-skill-")) {
+      const isIde = target.id.startsWith("legacy-ide-skill-");
+      const prefix = isIde ? "legacy-ide-skill-" : "legacy-cli-skill-";
+      const name = target.id.slice(prefix.length);
+      const root = isIde ? legacyAntigravityHome : antigravityCliHome;
+      const locator = antigravitySkillLocatorPath(root, name);
+      await cp(join(installedPluginRoot, "skills", name), expected, { recursive: true });
+      await renderMirrorFile(join(installedPluginRoot, "skills", name, "SKILL.md"), join(expected, "SKILL.md"), { locatorPath: locator, runtimeRoot: installedPluginRoot, includeLocatorNotice: true });
+      await writeLocator(join(expected, "references", "cairn-runtime.json"), installedPluginRoot);
+    } else if (target.id.startsWith("legacy-ide-workflow-")) {
+      const name = target.id.slice("legacy-ide-workflow-".length);
+      await renderMirrorFile(join(installedPluginRoot, ".agents", "workflows", `cairn-${name}.md`), expected, {
+        locatorPath: antigravityRuntimeLocatorPath(legacyAntigravityHome),
+        runtimeRoot: installedPluginRoot,
+      });
+    } else if (target.id.startsWith("ide-workflow-") || target.id.startsWith("cli-workflow-")) {
+      const isIde = target.id.startsWith("ide-workflow-");
+      const prefix = isIde ? "ide-workflow-" : "cli-workflow-";
+      const name = target.id.slice(prefix.length);
+      const root = isIde ? antigravityHome : antigravityCliHome;
+      await renderMirrorFile(join(installedPluginRoot, ".agents", "workflows", `cairn-${name}.md`), expected, { locatorPath: antigravityRuntimeLocatorPath(root), runtimeRoot: installedPluginRoot });
+    } else {
+      throw new Error(`Legacy mirror target is not recognized: ${target.id}`);
+    }
+    if (await targetDigest(expected, "file") !== await targetDigest(target.path, target.type)) throw new Error(`Legacy mirror was modified: ${target.path}`);
+  } finally {
+    await rm(temp, { recursive: true, force: true });
+  }
+}
+
+
+  return { adoptLegacy, verifyLegacy022Root };
+
+  function sha(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+  }
+
+  async function readJson(path) {
+    if (!(await exists(path))) return null;
+    return JSON.parse(await readFile(path, "utf8"));
+  }
+
+  async function exists(path) {
+    try { await lstat(path); return true; }
+    catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  }
+}

package/scripts/cairn-lifecycle-lock.mjs

@@ -0,0 +1,205 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, rename, rm, rmdir, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+export const DEFAULT_LIFECYCLE_LOCK_TIMEOUT_MS = 60_000;
+
+export function createLifecycleLock({ lifecycleLockPath }) {
+async function withLifecycleLock(operation, {
+  timeoutMs = DEFAULT_LIFECYCLE_LOCK_TIMEOUT_MS,
+  retryMs = 25,
+  malformedStaleMs = 30_000,
+  afterRelease,
+  testHooks = {},
+} = {}) {
+  await mkdir(dirname(lifecycleLockPath), { recursive: true });
+  if (process.env.CAIRN_TEST_PRUNE_LOCK_PARENT_BEFORE_ACQUIRE === "1") await rmdir(dirname(lifecycleLockPath));
+  const owner = { schemaVersion: 1, pid: process.pid, hostname: hostname(), nonce: randomUUID(), acquiredAt: new Date().toISOString() };
+  const deadline = Date.now() + timeoutMs;
+  let waitReported = false;
+  while (true) {
+    let acquired = false;
+    try {
+      await writeFile(lifecycleLockPath, `${JSON.stringify(owner)}\n`, { flag: "wx" });
+      await testHooks.afterLockWritten?.({ owner: structuredClone(owner) });
+      if (process.env.CAIRN_TEST_REPLACE_LOCK_AFTER_ACQUIRE === "1") {
+        await writeFile(lifecycleLockPath, `${JSON.stringify({ ...owner, nonce: randomUUID() })}\n`);
+      }
+      const written = parseLifecycleLock(await readFile(lifecycleLockPath, "utf8"));
+      if (written?.nonce !== owner.nonce) throw new Error("Cairn lifecycle lock ownership changed after acquisition");
+      acquired = !(await activeReclaimClaimExists());
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        if (Date.now() >= deadline) throw new Error(`Timed out waiting for Cairn lifecycle lock after ${timeoutMs}ms`);
+        await mkdir(dirname(lifecycleLockPath), { recursive: true });
+        continue;
+      }
+      if (error?.code !== "EEXIST") throw error;
+      if (!waitReported && process.env.CAIRN_TEST_REPORT_LOCK_WAIT === "1") {
+        console.log("CAIRN_TEST_LOCK_WAIT");
+        waitReported = true;
+      }
+      await testHooks.beforeContendedLockConfirmation?.();
+      acquired = await confirmsUnclaimedLifecycleLockOwnership(owner.nonce);
+      if (!acquired && await reclaimLifecycleLock(owner, malformedStaleMs, testHooks)) continue;
+    }
+    if (acquired) {
+      if (process.env.CAIRN_TEST_HOLD_LOCK_STDIN === "1") {
+        console.log("CAIRN_TEST_LOCK_ACQUIRED");
+        await new Promise((resolvePromise) => process.stdin.once("data", resolvePromise));
+      }
+      break;
+    }
+    if (Date.now() >= deadline) throw new Error(`Timed out waiting for Cairn lifecycle lock after ${timeoutMs}ms`);
+    await delay(Math.min(retryMs, Math.max(1, deadline - Date.now())));
+  }
+  let operationSucceeded = false;
+  try {
+    const result = await operation();
+    operationSucceeded = true;
+    return result;
+  } finally {
+    if (process.env.CAIRN_TEST_REPLACE_LOCK_BEFORE_RELEASE === "1") {
+      await writeFile(lifecycleLockPath, `${JSON.stringify({ ...owner, nonce: randomUUID() })}\n`);
+    }
+    const released = await releaseOwnedLock(lifecycleLockPath, owner);
+    if (operationSucceeded && released && afterRelease) await afterRelease();
+  }
+}
+
+async function releaseOwnedLock(path, owner) {
+  let current;
+  try {
+    current = parseLifecycleLock(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+  if (current?.nonce !== owner.nonce) return false;
+  const releasedPath = `${path}.released.${owner.nonce}`;
+  try {
+    await rename(path, releasedPath);
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+  const released = parseLifecycleLock(await readFile(releasedPath, "utf8"));
+  if (released?.nonce !== owner.nonce) {
+    if (!(await exists(path))) await rename(releasedPath, path);
+    return false;
+  }
+  await rm(releasedPath, { force: true });
+  return true;
+}
+
+async function reclaimLifecycleLock(owner, malformedStaleMs, testHooks) {
+  let observed;
+  let info;
+  try {
+    [observed, info] = await Promise.all([readFile(lifecycleLockPath, "utf8"), lstat(lifecycleLockPath)]);
+  } catch (error) {
+    if (error?.code === "ENOENT") return true;
+    throw error;
+  }
+  if (info.isSymbolicLink()) throw new Error(`Lifecycle lock must not be a symlink: ${lifecycleLockPath}`);
+  const record = parseLifecycleLock(observed);
+  if (!isReclaimableLifecycleLock(record, info, malformedStaleMs)) return false;
+  await testHooks.afterStaleObserved?.();
+
+  const claimPath = `${lifecycleLockPath}.reclaim.${owner.nonce}`;
+  await writeFile(claimPath, `${JSON.stringify(owner)}\n`, { flag: "wx" });
+  try {
+    await testHooks.afterReclaimInterlock?.();
+    let claimed;
+    let claimedInfo;
+    try {
+      [claimed, claimedInfo] = await Promise.all([readFile(lifecycleLockPath, "utf8"), lstat(lifecycleLockPath)]);
+    } catch (error) {
+      if (error?.code === "ENOENT") return true;
+      throw error;
+    }
+    if (claimedInfo.isSymbolicLink()) throw new Error(`Lifecycle lock must not be a symlink: ${lifecycleLockPath}`);
+    const claimedRecord = parseLifecycleLock(claimed);
+    if (!isReclaimableLifecycleLock(claimedRecord, claimedInfo, malformedStaleMs)) return false;
+
+    const quarantine = `${lifecycleLockPath}.stale.${claimedRecord?.nonce ?? "malformed"}.${randomUUID()}`;
+    try {
+      await rename(lifecycleLockPath, quarantine);
+    } catch (error) {
+      if (error?.code === "ENOENT") return true;
+      throw error;
+    }
+    if (await readFile(quarantine, "utf8") !== claimed) {
+      if (!(await exists(lifecycleLockPath))) await rename(quarantine, lifecycleLockPath);
+      throw new Error("Cairn lifecycle lock ownership changed during stale recovery");
+    }
+    await rm(quarantine, { force: true });
+    return true;
+  } finally {
+    await releaseOwnedLock(claimPath, owner);
+  }
+}
+
+function isReclaimableLifecycleLock(record, info, malformedStaleMs) {
+  if (record) return record.hostname === hostname() && !pidIsAlive(record.pid);
+  return Date.now() - info.mtimeMs > malformedStaleMs;
+}
+
+async function confirmsUnclaimedLifecycleLockOwnership(nonce) {
+  if (await activeReclaimClaimExists()) return false;
+  try {
+    return parseLifecycleLock(await readFile(lifecycleLockPath, "utf8"))?.nonce === nonce;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function activeReclaimClaimExists() {
+  const claimNames = (await readdir(dirname(lifecycleLockPath)))
+    .filter((name) => name.startsWith(`${basename(lifecycleLockPath)}.reclaim.`));
+  for (const name of claimNames) {
+    const claimPath = join(dirname(lifecycleLockPath), name);
+    let info;
+    let record;
+    try {
+      [info, record] = await Promise.all([lstat(claimPath), readFile(claimPath, "utf8").then(parseLifecycleLock)]);
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      throw error;
+    }
+    if (info.isSymbolicLink()) throw new Error(`Lifecycle reclaim claim must not be a symlink: ${claimPath}`);
+    if (record?.hostname === hostname() && !pidIsAlive(record.pid)) {
+      await releaseOwnedLock(claimPath, record);
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+
+function parseLifecycleLock(text) {
+  try {
+    const value = JSON.parse(text);
+    if (value?.schemaVersion !== 1 || !Number.isSafeInteger(value.pid) || value.pid <= 0
+        || typeof value.hostname !== "string" || value.hostname.length === 0 || typeof value.nonce !== "string" || value.nonce.length === 0
+        || 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) { return error?.code !== "ESRCH"; }
+}
+
+function delay(ms) { return new Promise((resolvePromise) => setTimeout(resolvePromise, ms)); }
+
+
+  return { withLifecycleLock };
+
+  async function exists(path) {
+    try { await lstat(path); return true; }
+    catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  }
+}

package/scripts/cairn-lifecycle-mirror.mjs

@@ -0,0 +1,91 @@
+import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, posix, resolve, win32 } from "node:path";
+import {
+  RUNTIME_LOCATOR_SCHEMA_VERSION,
+  createRuntimeLocator,
+  runtimeRequiredPaths,
+} from "./cairn-paths.mjs";
+
+export function antigravityRuntimeLocatorPath(root) {
+  return join(root, "cairn", "runtime.json");
+}
+
+export function installedSkillLocatorPath(runtimeRoot, name) {
+  return join(runtimeRoot, "skills", name, "references", "cairn-runtime.json");
+}
+
+export function antigravitySkillLocatorPath(root, name) {
+  return join(root, "skills", name, "references", "cairn-runtime.json");
+}
+
+export async function writeLocator(path, root) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(createRuntimeLocator(root), null, 2)}\n`);
+}
+
+export function validLegacyLocator(locator, root) {
+  const expected = createRuntimeLocator(root);
+  return locator?.schemaVersion === RUNTIME_LOCATOR_SCHEMA_VERSION
+    && locator.pluginRoot === expected.pluginRoot
+    && JSON.stringify(locator.entrypoints) === JSON.stringify(expected.entrypoints)
+    && JSON.stringify(locator.resources) === JSON.stringify(expected.resources);
+}
+
+export async function validRuntimeLocator(path, runtimeRoot) {
+  try {
+    const locator = JSON.parse(await readFile(path, "utf8"));
+    const expected = createRuntimeLocator(runtimeRoot);
+    if (locator?.schemaVersion !== RUNTIME_LOCATOR_SCHEMA_VERSION || resolve(locator.pluginRoot ?? ".") !== resolve(runtimeRoot)) return false;
+    for (const [name, value] of Object.entries(expected.entrypoints)) if (locator.entrypoints?.[name] !== value) return false;
+    for (const [name, value] of Object.entries(expected.resources)) if (locator.resources?.[name] !== value) return false;
+    return (await Promise.all(runtimeRequiredPaths(locator).map(exists))).every(Boolean);
+  } catch {
+    return false;
+  }
+}
+
+export async function renderMirrorFile(source, destination, { locatorPath, runtimeRoot, includeLocatorNotice = false }) {
+  const content = await readFile(source, "utf8");
+  const notice = includeLocatorNotice ? `\n\n## Installed Cairn runtime\n\nRead the structured runtime locator at \`${JSON.stringify(locatorPath)}\`. Resolve Cairn scripts and static resources from its absolute paths, never from the target project.\n` : "";
+  await mkdir(dirname(destination), { recursive: true });
+  await writeFile(destination, `${renderInstalledMirror(content, { runtimeRoot, locatorPath }).trimEnd()}${notice}`);
+}
+
+export function renderInstalledMirror(content, { runtimeRoot, locatorPath, platform = process.platform }) {
+  const platformJoin = platform === "win32" ? win32.join : posix.join;
+  const quotedCli = quoteShellArg(platformJoin(runtimeRoot, "scripts", "cairn.mjs"), platform);
+  let rendered = content.replaceAll("{{CAIRN_RUNTIME_LOCATOR_JSON}}", JSON.stringify(locatorPath))
+    .replace(/\bnode\s+scripts\/cairn\.mjs\b/g, `node ${quotedCli}`)
+    .replace(/\bnode\s+scripts\/([A-Za-z0-9._/-]+)/g, (_, path) => `node ${quoteShellArg(platformJoin(runtimeRoot, "scripts", path), platform)}`);
+  rendered = rendered.replace(/(^|[\s`("'=])(commands|agents|templates|docs\/model-guidance)\/([A-Za-z0-9._<>/-]+)/gm,
+    (_, prefix, directory, suffix) => `${prefix}${platformJoin(runtimeRoot, directory, suffix)}`);
+  return rendered;
+}
+
+export function quoteShellArg(value, platform = process.platform) {
+  return platform === "win32" ? `"${value.replaceAll('"', '""')}"` : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+export async function validateAntigravitySkills(root, skillNames, runtimeRoot) {
+  try {
+    if (!(await validRuntimeLocator(antigravityRuntimeLocatorPath(root), runtimeRoot))) return false;
+    for (const name of skillNames) {
+      const content = await readFile(join(root, "skills", `${name}.md`), "utf8");
+      if (!/^---\r?\n[\s\S]*?\r?\n---\r?\n/.test(content) || !/^name:\s*\S+/m.test(content) || !/^description:\s*\S+/m.test(content)) return false;
+      if (!content.includes(JSON.stringify(antigravityRuntimeLocatorPath(root)))) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function exists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}

package/scripts/cairn-lifecycle-staging.mjs

@@ -0,0 +1,152 @@
+import { copyFile, cp, lstat, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { readSharedConfigSnapshot, trustedHookStates } from "./cairn-lifecycle-config.mjs";
+import {
+  antigravityRuntimeLocatorPath, antigravitySkillLocatorPath, renderMirrorFile, writeLocator,
+} from "./cairn-lifecycle-mirror.mjs";
+
+export function createStaging(context) {
+  const {
+    agentNames, antigravityCliHome, antigravityHome, claudeHome,
+    claudeRuntimeLocatorPath, commandNames, configPath, installedPluginRoot,
+    legacyAntigravityHome, marketplaceJsonPath, marketplaceName, pluginName,
+    pluginRoot, skillNames, updateConfig, versionedPluginRoot, assertRegularTree,
+  } = context;
+async function stageInstall(stageRoot) {
+  const targets = [];
+  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);
+  await copyPluginCandidate(runtimeStage, versionedPluginRoot);
+  add("codex-source", "codex", installedPluginRoot, sourceStage);
+  add("codex-runtime", "codex", versionedPluginRoot, runtimeStage);
+
+  const marketplaceStage = join(stageRoot, "marketplace.json");
+  await writeFile(marketplaceStage, `${JSON.stringify({
+    name: marketplaceName,
+    interface: { displayName: "Cairn" },
+    plugins: [{ name: pluginName, source: { source: "local", path: "./plugins/cairn" }, policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" }, category: "Productivity" }],
+  }, null, 2)}\n`);
+  add("marketplace", "codex", marketplaceJsonPath, marketplaceStage, "file");
+
+  const claudeLocator = join(stageRoot, "claude-runtime.json");
+  await writeLocator(claudeLocator, versionedPluginRoot);
+  add("claude-runtime", "claude", claudeRuntimeLocatorPath, claudeLocator, "file");
+  for (const name of commandNames()) {
+    const staged = join(stageRoot, "claude-commands", `cairn-${name}.md`);
+    await renderMirrorFile(join(runtimeStage, ".claude", "commands", `cairn-${name}.md`), staged, { locatorPath: claudeRuntimeLocatorPath, runtimeRoot: versionedPluginRoot });
+    add(`claude-command-${name}`, "claude", join(claudeHome, "commands", `cairn-${name}.md`), staged, "file");
+  }
+  for (const name of agentNames()) {
+    const staged = join(stageRoot, "claude-agents", `cairn-${name}.md`);
+    await renderMirrorFile(join(runtimeStage, ".claude", "agents", `${name}.md`), staged, { locatorPath: claudeRuntimeLocatorPath, runtimeRoot: versionedPluginRoot });
+    add(`claude-agent-${name}`, "claude", join(claudeHome, "agents", `cairn-${name}.md`), staged, "file");
+  }
+
+  await stageAntigravity(targets, stageRoot, runtimeStage, antigravityHome, "ide", false);
+  await stageAntigravity(targets, stageRoot, runtimeStage, antigravityCliHome, "cli", true);
+
+  const configStage = join(stageRoot, "config.toml");
+  const hookStates = await trustedHookStates(runtimeStage);
+  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;
+}
+
+async function stageAntigravity(targets, stageRoot, runtimeStage, destinationRoot, label, flatSkills) {
+  const locatorPath = antigravityRuntimeLocatorPath(destinationRoot);
+  const locatorStage = join(stageRoot, `${label}-runtime.json`);
+  await writeLocator(locatorStage, versionedPluginRoot);
+  targets.push({ id: `${label}-runtime`, phase: "antigravity", path: locatorPath, staged: locatorStage, type: "file" });
+  for (const name of skillNames()) {
+    if (flatSkills) {
+      const staged = join(stageRoot, `${label}-skills`, `${name}.md`);
+      await renderMirrorFile(join(runtimeStage, "skills", name, "SKILL.md"), staged, { locatorPath, runtimeRoot: versionedPluginRoot, includeLocatorNotice: true });
+      targets.push({ id: `${label}-skill-${name}`, phase: "antigravity", path: join(destinationRoot, "skills", `${name}.md`), staged, type: "file" });
+    } else {
+      const staged = join(stageRoot, `${label}-skills`, name);
+      await cp(join(runtimeStage, "skills", name), staged, { recursive: true });
+      await renderMirrorFile(join(runtimeStage, "skills", name, "SKILL.md"), join(staged, "SKILL.md"), {
+        locatorPath: antigravitySkillLocatorPath(destinationRoot, name),
+        runtimeRoot: versionedPluginRoot,
+        includeLocatorNotice: true,
+      });
+      await writeLocator(join(staged, "references", "cairn-runtime.json"), versionedPluginRoot);
+      targets.push({ id: `${label}-skill-${name}`, phase: "antigravity", path: join(destinationRoot, "skills", name), staged, type: "tree" });
+    }
+  }
+  for (const name of commandNames()) {
+    const staged = join(stageRoot, `${label}-workflows`, `cairn-${name}.md`);
+    await renderMirrorFile(join(runtimeStage, ".agents", "workflows", `cairn-${name}.md`), staged, { locatorPath, runtimeRoot: versionedPluginRoot });
+    targets.push({ id: `${label}-workflow-${name}`, phase: "antigravity", path: join(destinationRoot, "workflows", `cairn-${name}.md`), staged, type: "file" });
+  }
+}
+
+async function legacyMigrationTargets() {
+  const candidates = [{ id: "legacy-ide-runtime", phase: "antigravity", path: antigravityRuntimeLocatorPath(legacyAntigravityHome), type: "file", operation: "remove" }];
+  for (const name of skillNames()) {
+    candidates.push({ id: `legacy-ide-skill-${name}`, phase: "antigravity", path: join(legacyAntigravityHome, "skills", name), type: "tree", operation: "remove" });
+    candidates.push({ id: `legacy-cli-skill-${name}`, phase: "antigravity", path: join(antigravityCliHome, "skills", name), type: "tree", operation: "remove" });
+  }
+  for (const name of commandNames()) candidates.push({ id: `legacy-ide-workflow-${name}`, phase: "antigravity", path: join(legacyAntigravityHome, "workflows", `cairn-${name}.md`), type: "file", operation: "remove" });
+  const present = [];
+  for (const candidate of candidates) if (await exists(candidate.path)) present.push(candidate);
+  return present;
+}
+
+async function copyPluginCandidate(destination, runtimeRoot) {
+  await copyPluginTree(pluginRoot, destination);
+  const manifestPath = join(destination, ".codex-plugin", "plugin.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  manifest.hooks = "./hooks/hooks.json";
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  await writeLocator(join(destination, ".cairn-runtime.json"), runtimeRoot);
+  for (const name of skillNames()) await writeLocator(join(destination, "skills", name, "references", "cairn-runtime.json"), runtimeRoot);
+}
+
+async function copyPluginTree(source, destination) {
+  if (!shouldCopyPluginPath(source, pluginRoot)) return;
+  const info = await lstat(source);
+  if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile())) {
+    throw new Error(`Plugin source must contain only regular files and directories: ${source}`);
+  }
+  if (info.isFile()) {
+    await mkdir(dirname(destination), { recursive: true });
+    await copyFile(source, destination);
+    return;
+  }
+  await mkdir(destination, { recursive: true });
+  const entries = await readdir(source);
+  entries.sort();
+  for (const entry of entries) await copyPluginTree(join(source, entry), join(destination, entry));
+}
+
+
+  return { legacyMigrationTargets, stageInstall };
+
+  async function exists(path) {
+    try { await lstat(path); return true; }
+    catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  }
+}
+
+export function pathHasSegment(path, segment) { return path.split(/[\\/]+/).includes(segment); }
+
+export function shouldCopyPluginPath(source, pluginRoot) {
+  const name = source.split(/[\\/]+/).at(-1);
+  if ([".git", "node_modules", ".cairn"].includes(name)) return false;
+  if (sep === "/" && source.includes("\\")) return true;
+  const relativePath = relative(pluginRoot, source);
+  if (isAbsolute(relativePath)) return true;
+  const path = relativePath.split(sep).join("/");
+  if (path === "") return true;
+  if (path.startsWith("../") || path === "..") return true;
+  if (/^(package\.json|LICENSE|README(?:\.[^.]+)?\.md)$/.test(path)) return true;
+  if (path === "docs") return true;
+  if (path.startsWith("docs/")) return path === "docs/model-guidance" || path.startsWith("docs/model-guidance/");
+  return [".agents", ".claude", ".codex-plugin", "agents", "commands", "hooks", "scripts", "skills", "templates"]
+    .some((directory) => path === directory || path.startsWith(`${directory}/`));
+}