@comento/pota-harness 0.0.0-stage → 1.0.0

package/scripts/pota-lifecycle-config.mjs

@@ -0,0 +1,153 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { lstat, open, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export function updateConfig(config, hookStates, { marketplacePath } = {}) {
+  if (marketplacePath === undefined) throw new Error("Pota marketplace path is required");
+  let next = removePotaConfig(config);
+  next = append(next, `[marketplaces.pota]\nlast_updated = ${JSON.stringify(new Date().toISOString().replace(/\.\d{3}Z$/, "Z"))}\nsource_type = "local"\nsource = ${JSON.stringify(marketplacePath)}\n`);
+  next = append(next, '[plugins."pota@pota"]\nenabled = true\n');
+  for (const state of hookStates) next = append(next, `[hooks.state.${JSON.stringify(state.key)}]\ntrusted_hash = ${JSON.stringify(state.trustedHash)}\n`);
+  return next;
+}
+
+export function removePotaConfig(config) {
+  return splitSections(config).map((section) => isPotaConfigSection(section)
+    ? splitTrailingTomlTrivia(section.text).trivia
+    : section.text).join("");
+}
+
+export function potaConfigProjection(config) {
+  return splitSections(config).filter(isPotaConfigSection)
+    .map((section) => splitTrailingTomlTrivia(section.text).body).join("");
+}
+
+function isPotaConfigSection(section) {
+  return section.header === "marketplaces.pota"
+    || section.header === 'plugins."pota@pota"'
+    || (section.header?.startsWith("hooks.state.") && section.header.includes("pota@pota:"));
+}
+
+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("") };
+}
+
+export 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) {
+  const sections = splitSections(config);
+  const index = sections.findIndex((section) => section.header === sectionName);
+  if (index === -1) return append(config, `[${sectionName}]\n${key} = ${value}\n`);
+  const lines = sections[index].text.trimEnd().split("\n");
+  const settingIndex = lines.findIndex((line) => line.trim().startsWith(`${key} =`));
+  if (settingIndex === -1) lines.push(`${key} = ${value}`);
+  else lines[settingIndex] = `${key} = ${value}`;
+  sections[index].text = `${lines.join("\n")}\n`;
+  return sections.map((section) => section.text).join("");
+}
+
+export function hasSetting(config, sectionName, key, value) {
+  const section = splitSections(config).find((candidate) => candidate.header === sectionName);
+  return section?.text.split("\n").some((line) => line.trim() === `${key} = ${value}`) ?? false;
+}
+
+export function splitSections(config) {
+  const result = [];
+  let current = { header: null, text: "" };
+  let multiline = null;
+  for (const line of config.split(/(?<=\n)/)) {
+    const delimiterCount = (delimiter) => line.split(delimiter).length - 1;
+    if (multiline) {
+      current.text += line;
+      if (delimiterCount(multiline) % 2 === 1) multiline = null;
+      continue;
+    }
+    const doubleCount = delimiterCount('"""');
+    const singleCount = delimiterCount("'''");
+    // Array-of-tables and headers with trailing comments start a new section too; otherwise a foreign section
+    // after Pota's would be absorbed into it and deleted on upgrade/uninstall.
+    const trimmed = line.trim();
+    const arrayMatch = trimmed.match(/^\[\[([^\[\]]+)\]\]\s*(?:#.*)?$/);
+    const match = arrayMatch ? null : trimmed.match(/^\[([^\[\]]+)\]\s*(?:#.*)?$/);
+    if (arrayMatch || match) {
+      if (current.text.length > 0) result.push(current);
+      current = { header: arrayMatch ? `[${arrayMatch[1].trim()}]` : match[1].trim(), text: line };
+    } else current.text += line;
+    if (doubleCount % 2 === 1) multiline = '"""';
+    else if (singleCount % 2 === 1) multiline = "'''";
+  }
+  if (current.text.length > 0) result.push(current);
+  return result;
+}
+
+export async function trustedHookStates(root) {
+  const parsed = JSON.parse(await readFile(join(root, "hooks", "hooks.json"), "utf8"));
+  const states = [];
+  const labels = { SessionStart: "session_start", UserPromptSubmit: "user_prompt_submit", PostToolUse: "post_tool_use", Stop: "stop", SubagentStop: "subagent_stop" };
+  for (const [eventName, groups] of Object.entries(parsed?.hooks ?? {})) {
+    const eventLabel = labels[eventName];
+    if (!eventLabel || !Array.isArray(groups)) continue;
+    for (const [groupIndex, group] of groups.entries()) for (const [handlerIndex, handler] of (group.hooks ?? []).entries()) {
+      states.push({ key: `pota@pota:hooks/hooks.json:${eventLabel}:${groupIndex}:${handlerIndex}`, trustedHash: hookHash(eventLabel, group.matcher, handler) });
+    }
+  }
+  return states;
+}
+
+export function hookHash(eventName, matcher, handler) {
+  const normalized = { type: "command", command: handler.command, timeout: Math.max(Number(handler.timeout ?? 600), 1), async: false };
+  if (typeof handler.statusMessage === "string") normalized.statusMessage = handler.statusMessage;
+  const identity = { event_name: eventName, hooks: [normalized] };
+  if (typeof matcher === "string") identity.matcher = matcher;
+  return sha(JSON.stringify(canonical(identity)));
+}
+
+export function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+}
+
+function append(config, block) {
+  if (config.length === 0) return `${block.trimEnd()}\n`;
+  return `${config}${config.endsWith("\n") ? "" : "\n"}${block.trimEnd()}\n`;
+}
+
+function sha(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}

package/scripts/pota-lifecycle-hosts.mjs

@@ -0,0 +1,98 @@
+import { createInterface } from "node:readline";
+
+// Hosts Pota can install into, in canonical order. The ownership manifest records a non-empty subset in this order.
+export const HOSTS = ["codex", "claude", "antigravity"];
+const HOST_LABELS = { codex: "Codex", claude: "Claude Code", antigravity: "Antigravity" };
+const PROMPT_ATTEMPTS = 3;
+
+export function isHostSelection(hosts) {
+  return Array.isArray(hosts) && hosts.length > 0 && hosts.length <= HOSTS.length
+    && hosts.every((host, index) => HOSTS.includes(host) && (index === 0 || HOSTS.indexOf(hosts[index - 1]) < HOSTS.indexOf(host)));
+}
+
+// `all` or a comma-separated list of host ids; the result is in canonical order. Missing, empty, unknown, and
+// duplicate values are rejected so nothing is locked or staged for a selection the user did not mean.
+export function parseHostsOption(value) {
+  if (typeof value !== "string" || value.length === 0) throw new Error(`Invalid --hosts value: ${value === undefined ? "missing" : "empty"}`);
+  if (value === "all") return [...HOSTS];
+  const names = value.split(",").map((name) => name.trim());
+  const seen = new Set();
+  for (const name of names) {
+    if (name.length === 0) throw new Error(`Invalid --hosts value: ${value} (empty host name)`);
+    if (!HOSTS.includes(name)) throw new Error(`Invalid --hosts value: ${value} (unknown host ${name}; use all or ${HOSTS.join(",")})`);
+    if (seen.has(name)) throw new Error(`Invalid --hosts value: ${value} (duplicate host ${name})`);
+    seen.add(name);
+  }
+  return HOSTS.filter((host) => seen.has(host));
+}
+
+// The host a managed or journal-only target belongs to; `core` targets are installed for every selection.
+export function hostOfTarget(id) {
+  if (id === "runtime" || id === "ownership" || id.startsWith("retired-runtime-")) return "core";
+  if (["codex-source", "marketplace", "codex-runtime", "codex-config", "previous-codex-runtime"].includes(id)
+      || id.startsWith("retired-codex-runtime-")) return "codex";
+  if (id.startsWith("claude-")) return "claude";
+  if (/^(?:ide|cli)-/.test(id)) return "antigravity";
+  return null;
+}
+
+export function hostLabels(hosts) {
+  return hosts.map((host) => HOST_LABELS[host]).join(", ");
+}
+
+function promptText(ko) {
+  return ko ? [
+    "Pota를 설치할 호스트를 선택하세요.",
+    "  1) 전체 — Codex, Claude Code, Antigravity (기본)",
+    "  2) Claude Code만",
+    "  3) Codex만",
+    "  4) Antigravity만",
+    "번호를 입력하거나 호스트 이름을 쉼표로 구분해 입력하세요 (codex,claude,antigravity) [1]: ",
+  ] : [
+    "Select the hosts to install Pota into.",
+    "  1) All — Codex, Claude Code, Antigravity (default)",
+    "  2) Claude Code only",
+    "  3) Codex only",
+    "  4) Antigravity only",
+    "Enter a number, or host names separated by commas (codex,claude,antigravity) [1]: ",
+  ];
+}
+
+export function parseHostsAnswer(answer) {
+  const value = answer.trim();
+  const choices = { "": HOSTS, 1: HOSTS, 2: ["claude"], 3: ["codex"], 4: ["antigravity"] };
+  if (Object.hasOwn(choices, value)) return [...choices[value]];
+  return parseHostsOption(value);
+}
+
+// Asks once, re-asks after an invalid answer, and gives up after three attempts or at end of input. An empty answer
+// selects every host. The caller asks before taking the lifecycle lock, so a waiting prompt never blocks another run.
+export async function promptHosts({ input, output, ko = false }) {
+  const lines = promptText(ko);
+  const question = lines.at(-1);
+  const reader = createInterface({ input, terminal: false });
+  const answers = reader[Symbol.asyncIterator]();
+  try {
+    output.write(lines.join("\n"));
+    for (let attempt = 1; attempt <= PROMPT_ATTEMPTS; attempt += 1) {
+      if (attempt > 1) output.write(question);
+      const next = await answers.next();
+      if (next.done) {
+        output.write("\n");
+        break;
+      }
+      try {
+        const hosts = parseHostsAnswer(next.value);
+        output.write(ko
+          ? `선택한 호스트: ${hostLabels(hosts)}. 나중에 바꾸려면: pota install --hosts <목록>\n`
+          : `Selected hosts: ${hostLabels(hosts)}. To change later: pota install --hosts <list>\n`);
+        return hosts;
+      } catch {
+        output.write(ko ? `잘못된 입력입니다: ${next.value.trim()}\n` : `Invalid selection: ${next.value.trim()}\n`);
+      }
+    }
+  } finally {
+    reader.close();
+  }
+  throw new Error("No valid host selection was entered.");
+}

package/scripts/pota-lifecycle-integrity.mjs

@@ -0,0 +1,272 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+import { potaConfigProjection, readSharedConfigSnapshot } from "./pota-lifecycle-config.mjs";
+import { HOSTS, hostOfTarget, isHostSelection } from "./pota-lifecycle-hosts.mjs";
+import { antigravityRuntimeLocatorPath } from "./pota-lifecycle-mirror.mjs";
+
+export const OWNERSHIP_SCHEMA_VERSION = 2;
+export const OWNERSHIP_ORIGINS = ["checkout", "package"];
+// Runtimes a version change leaves behind stay for open sessions: at most this many per id, for this long.
+export const RETAINED_RUNTIME_IDS = ["runtime", "codex-runtime"];
+export const RETAINED_RUNTIME_LIMIT = 3;
+export const RETAINED_RUNTIME_GRACE_MS = 3 * 24 * 60 * 60 * 1000;
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+// Orders release versions by major.minor.patch; a prerelease suffix compares equal to its release.
+export function compareVersions(left, right) {
+  const parse = (value) => String(value).split("-")[0].split(".").map(Number);
+  const [a, b] = [parse(left), parse(right)];
+  for (let index = 0; index < 3; index += 1) if (a[index] !== b[index]) return a[index] - b[index];
+  return 0;
+}
+
+export function createIntegrity(context) {
+  const {
+    antigravityCliHome, antigravityHome, claudeHome, claudePluginMarketplaceRoot, claudeRuntimeLocatorPath,
+    commandNames, configPath, installedPluginRoot, layout,
+    marketplaceJsonPath, ownershipPath, phases, pluginName,
+    releaseVersion, skillNames,
+  } = context;
+// A journal-only removal (previous runtime) names the record it removes with `ownedBy` and must match
+// that record's path, type, and digest. A record claimed that way moves away from its id, so the new target with the
+// same id at a different path starts unowned. A retired-runtime removal carries its `retained` entry instead.
+async function assertTargetsReplaceable(targets, ownership) {
+  const records = new Map((ownership?.targets ?? []).map((record) => [record.id, record]));
+  const moved = new Set(targets.filter((target) => target.ownedBy).map((target) => target.ownedBy));
+  for (const target of targets) {
+    if (!(await exists(target.path))) {
+      target.preflightDigest = "missing";
+      continue;
+    }
+    const current = await targetDigest(target.path, target.type);
+    target.preflightDigest = current;
+    if (target.ownedBy || target.retained) {
+      const owner = target.retained ? { ...target.retained, type: "tree" } : records.get(target.ownedBy);
+      if (!owner || owner.path !== target.path || owner.type !== target.type) throw new Error(`Removal target does not match ownership manifest: ${target.id}`);
+      if (target.type !== "config" && current !== owner.installedDigest) throw new Error(`Managed artifact was modified: ${target.path}`);
+      continue;
+    }
+    const claimed = records.get(target.id);
+    const record = claimed && !(moved.has(target.id) && claimed.path !== target.path) ? claimed : undefined;
+    const versionedRuntime = target.id === "runtime" || target.id === "codex-runtime";
+    // After a version change the release's runtime is owned only when an earlier upgrade retained it. A removal
+    // (a deselected host's record) is checked against its own record below.
+    if (versionedRuntime && target.operation !== "remove" && ownership && ownership.version !== releaseVersion) {
+      const retained = (ownership.retained ?? []).find((entry) => entry.id === target.id && entry.version === releaseVersion);
+      if (!retained || retained.path !== target.path || target.type !== "tree") {
+        throw new Error(`Refusing to overwrite unmanaged current-version runtime: ${target.path}`);
+      }
+      if (current !== retained.installedDigest) throw new Error(`Managed artifact was modified: ${target.path}`);
+      continue;
+    }
+    if (!record) {
+      if (target.type === "config" && potaConfigProjection((await readSharedConfigSnapshot(target.path)).text).length === 0) continue;
+      if (claimed && versionedRuntime) throw new Error(`Refusing to overwrite unmanaged current-version runtime: ${target.path}`);
+      throw new Error(`Refusing to overwrite unmanaged artifact: ${target.path}`);
+    }
+    if (record.path !== target.path || record.type !== target.type) throw new Error(`Ownership manifest target mismatch: ${target.id}`);
+    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, ...(ownership.retained ?? []).map((entry) => ({ ...entry, type: "tree" }))]) {
+    const current = await targetDigest(record.path, record.type);
+    if (record.type !== "config" && current !== record.installedDigest) {
+      throw new Error(`Managed artifact was modified: ${record.path}`);
+    }
+  }
+}
+
+// A retained runtime that no longer exists was removed outside Pota (by Codex or the user) and counts as already
+// gone: install, upgrade, and uninstall drop it from the manifest instead of removing or recording it, and doctor does
+// not report it. One that exists with other content is still a modified managed artifact.
+async function withoutMissingRetained(ownership) {
+  if (!Array.isArray(ownership?.retained)) return ownership;
+  const retained = [];
+  for (const entry of ownership.retained) if (await exists(entry.path)) retained.push(entry);
+  return { ...ownership, retained };
+}
+
+async function targetRecord(target) {
+  return { id: target.id, phase: target.phase, path: target.path, type: target.type, installedDigest: await targetDigest(target.path, target.type), previous: null };
+}
+
+async function readOwnership({ required = false } = {}) {
+  if (!(await exists(ownershipPath))) {
+    if (required) throw new Error(`Ownership manifest is missing: ${ownershipPath}`);
+    return null;
+  }
+  try {
+    return JSON.parse(await readFile(ownershipPath, "utf8"));
+  } catch {
+    throw new Error(`Ownership manifest is invalid: ${ownershipPath}`);
+  }
+}
+
+function validateOwnershipShape(ownership, { required = false } = {}) {
+  if (!ownership) {
+    if (required) throw new Error("Ownership manifest is required.");
+    return;
+  }
+  if (!sameKeys(ownership, ["schemaVersion", "plugin", "version", "transactionId", "installedAt", "origin", "hosts", "targets", "retained"])
+      || ownership.schemaVersion !== OWNERSHIP_SCHEMA_VERSION || ownership.plugin !== pluginName
+      || typeof ownership.version !== "string" || !VERSION_PATTERN.test(ownership.version)
+      || typeof ownership.transactionId !== "string" || !/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(ownership.transactionId)
+      || typeof ownership.installedAt !== "string" || Number.isNaN(Date.parse(ownership.installedAt))
+      || !OWNERSHIP_ORIGINS.includes(ownership.origin)
+      || !isHostSelection(ownership.hosts)
+      || !Array.isArray(ownership.targets) || !Array.isArray(ownership.retained)) {
+    throw new Error("Ownership manifest schema or plugin identity is invalid.");
+  }
+  const retainedKeys = new Set();
+  for (const record of ownership.retained ?? []) {
+    if (!record || !sameKeys(record, ["id", "version", "path", "installedDigest", "retiredAt"])
+        || !RETAINED_RUNTIME_IDS.includes(record.id) || typeof record.version !== "string" || !VERSION_PATTERN.test(record.version)
+        || record.version === ownership.version || retainedKeys.has(`${record.id}\0${record.version}`)
+        || record.path !== retainedRuntimePath(record.id, record.version)
+        || typeof record.installedDigest !== "string" || !/^sha256:[a-f0-9]{64}$/.test(record.installedDigest)
+        || typeof record.retiredAt !== "string" || Number.isNaN(Date.parse(record.retiredAt))
+        || ownership.retained.filter((entry) => entry?.id === record.id).length > RETAINED_RUNTIME_LIMIT
+        || (record.id === "codex-runtime" && !ownership.hosts.includes("codex"))) {
+      throw new Error("Ownership manifest contains an invalid retained runtime.");
+    }
+    retainedKeys.add(`${record.id}\0${record.version}`);
+  }
+  const ids = new Set();
+  const paths = new Set();
+  for (const record of ownership.targets) {
+    if (!record || !sameKeys(record, ["id", "phase", "path", "type", "installedDigest", "previous"])
+        || typeof record.id !== "string" || record.id.length === 0 || ids.has(record.id)
+        || typeof record.path !== "string" || record.path.length === 0 || paths.has(record.path)
+        || typeof record.phase !== "string" || !phases.includes(record.phase)
+        || typeof record.type !== "string" || !["file", "tree", "config"].includes(record.type)
+        || typeof record.installedDigest !== "string" || !/^sha256:[a-f0-9]{64}$/.test(record.installedDigest)
+        || record.previous !== null) {
+      throw new Error("Ownership manifest contains an invalid or duplicate target.");
+    }
+    const expected = expectedManagedTarget(record.id, ownership.version);
+    if (!expected || expected.path !== record.path || expected.phase !== record.phase || expected.type !== record.type) {
+      throw new Error(`Ownership manifest target is outside the Pota allowlist: ${record.id}`);
+    }
+    ids.add(record.id);
+    paths.add(record.path);
+  }
+  const hosts = ownership.hosts;
+  const unselected = [...ids].find((id) => !hosts.includes(hostOfTarget(id)) && hostOfTarget(id) !== "core");
+  if (unselected) throw new Error(`Ownership manifest schema is inconsistent: ${unselected} belongs to a host that is not selected.`);
+  const requiredTargets = requiredOwnershipTargets(ownership.version, hosts);
+  if ([...ids].some((id) => !requiredTargets.has(id)) || [...requiredTargets.keys()].some((id) => !ids.has(id))) {
+    throw new Error("Ownership manifest does not contain the complete managed target set.");
+  }
+}
+
+function retainedRuntimePath(id, version) {
+  return id === "runtime" ? layout.runtimeRootFor(version) : layout.codexRuntimeRootFor(version);
+}
+
+// The core runtime is always required; every other required target belongs to one selected host.
+function requiredOwnershipTargets(version = releaseVersion, hosts = HOSTS) {
+  const ids = ["runtime", "codex-source", "codex-runtime", "marketplace", "claude-runtime", "claude-plugin", "ide-runtime", "cli-runtime", "codex-config"];
+  for (const name of commandNames()) ids.push(`claude-command-${name}`, `ide-workflow-${name}`, `cli-workflow-${name}`);
+  for (const name of ["explorer", "worker"]) ids.push(`claude-agent-${name}`);
+  for (const name of skillNames()) ids.push(`ide-skill-${name}`, `cli-skill-${name}`);
+  const selected = ids.filter((id) => hostOfTarget(id) === "core" || hosts.includes(hostOfTarget(id)));
+  return new Map(selected.map((id) => [id, expectedManagedTarget(id, version)]));
+}
+
+function expectedManagedTarget(id, version = releaseVersion) {
+  const exact = {
+    runtime: { phase: "core", path: layout.runtimeRootFor(version), type: "tree" },
+    "codex-source": { phase: "codex", path: installedPluginRoot, type: "tree" },
+    "codex-runtime": { phase: "codex", path: layout.codexRuntimeRootFor(version), type: "tree" },
+    marketplace: { phase: "codex", path: marketplaceJsonPath, type: "file" },
+    "claude-runtime": { phase: "claude", path: claudeRuntimeLocatorPath, type: "file" },
+    "claude-plugin": { phase: "claude", path: claudePluginMarketplaceRoot, type: "tree" },
+    "ide-runtime": { phase: "antigravity", path: antigravityRuntimeLocatorPath(antigravityHome), type: "file" },
+    "cli-runtime": { phase: "antigravity", path: antigravityRuntimeLocatorPath(antigravityCliHome), type: "file" },
+    "codex-config": { phase: "config", path: configPath, type: "config" },
+  };
+  if (exact[id]) return exact[id];
+  for (const name of commandNames()) {
+    if (id === `claude-command-${name}`) return { phase: "claude", path: join(claudeHome, "commands", `pota-${name}.md`), type: "file" };
+    if (id === `ide-workflow-${name}`) return { phase: "antigravity", path: join(antigravityHome, "workflows", `pota-${name}.md`), type: "file" };
+    if (id === `cli-workflow-${name}`) return { phase: "antigravity", path: join(antigravityCliHome, "workflows", `pota-${name}.md`), type: "file" };
+  }
+  for (const name of ["explorer", "worker"]) if (id === `claude-agent-${name}`) return { phase: "claude", path: join(claudeHome, "agents", `pota-${name}.md`), type: "file" };
+  for (const name of skillNames()) {
+    if (id === `ide-skill-${name}`) return { phase: "antigravity", path: join(antigravityHome, "skills", name), type: "tree" };
+    if (id === `cli-skill-${name}`) return { phase: "antigravity", path: join(antigravityCliHome, "skills", `${name}.md`), type: "file" };
+  }
+  return null;
+}
+
+async function targetDigest(path, type) {
+  if (!(await exists(path))) return "missing";
+  if (type === "config") return sha(potaConfigProjection((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));
+  const files = await regularFiles(path);
+  const hash = createHash("sha256");
+  for (const file of files) {
+    hash.update(file).update("\0").update(await readFile(join(path, file))).update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+async function regularFiles(root) {
+  const output = [];
+  async function walk(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name);
+      if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) throw new Error(`Symlink or special file is not allowed in managed tree: ${path}`);
+      if (entry.isDirectory()) await walk(path);
+      else output.push(relative(root, path).split(sep).join("/"));
+    }
+  }
+  const info = await lstat(root);
+  if (info.isSymbolicLink()) throw new Error(`Symlink is not allowed: ${root}`);
+  if (info.isFile()) return [basename(root)];
+  await walk(root);
+  return output.sort();
+}
+
+async function assertRegularTree(path) {
+  await regularFiles(path);
+}
+
+function sha(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+  async function ownershipDigestsValid(ownership) {
+    try {
+      validateOwnershipShape(ownership, { required: true });
+      for (const record of ownership.targets) if (await targetDigest(record.path, record.type) !== record.installedDigest) return false;
+      for (const record of ownership.retained ?? []) {
+        const digest = await targetDigest(record.path, "tree");
+        if (digest !== "missing" && digest !== record.installedDigest) return false;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  return {
+    assertOwnershipDigests, assertRegularTree,
+    assertTargetsReplaceable, expectedManagedTarget, ownershipDigestsValid, readOwnership,
+    targetDigest, targetRecord, validateOwnershipShape, withoutMissingRetained,
+  };
+
+  function sameKeys(value, expected) {
+    return Object.keys(value).sort().join("\0") === [...expected].sort().join("\0");
+  }
+
+  async function exists(path) {
+    try { await lstat(path); return true; }
+    catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  }
+}

package/scripts/pota-lifecycle-layout.mjs

@@ -0,0 +1,52 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { potaHome, installRoot as potaInstallRoot, installManifestPath } from "./pota-paths.mjs";
+
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+// Path constants for the lifecycle: everything lives under <potaHome>/install, except the Codex plugin cache.
+// Codex only treats pota@pota as installed when its own plugin cache holds pota/<version>, so that host
+// cache stays under CODEX_HOME.
+export function createLayout({ env = process.env, releaseVersion, marketplaceName = "pota", pluginName = "pota" }) {
+  if (typeof releaseVersion !== "string" || !VERSION_PATTERN.test(releaseVersion)) throw new Error(`Invalid Pota release version: ${releaseVersion}`);
+  const homeRoot = env.HOME ?? env.USERPROFILE ?? homedir() ?? ".";
+  const codexHome = resolve(env.CODEX_HOME ?? join(homeRoot, ".codex"));
+  const potaHomeRoot = potaHome(env);
+  const codexCacheRoot = join(codexHome, "plugins", "cache", marketplaceName);
+  const codexRuntimeParent = join(codexCacheRoot, pluginName);
+  const shared = { potaHomeRoot, codexHome, codexCacheRoot, codexRuntimeParent };
+
+  const installRoot = potaInstallRoot(env);
+  const codexMarketplaceRoot = join(installRoot, "codex");
+  return layoutPaths({
+    ...shared,
+    installRoot,
+    stateRoot: installRoot,
+    ownershipPath: installManifestPath(env),
+    marketplaceRoot: codexMarketplaceRoot,
+    installedPluginRoot: join(codexMarketplaceRoot, "plugins", pluginName),
+    marketplaceJsonPath: join(codexMarketplaceRoot, ".agents", "plugins", "marketplace.json"),
+    claudePluginMarketplaceRoot: join(installRoot, "claude"),
+    runtimeParent: join(installRoot, "runtime"),
+  }, releaseVersion);
+}
+
+function layoutPaths(paths, releaseVersion) {
+  const runtimeRootFor = (version) => versionedChild(paths.runtimeParent, version);
+  const codexRuntimeRootFor = (version) => versionedChild(paths.codexRuntimeParent, version);
+  return {
+    ...paths,
+    transactionPath: join(paths.stateRoot, "transaction.json"),
+    transactionRoot: join(paths.stateRoot, "transactions"),
+    lifecycleLockPath: join(paths.stateRoot, "lifecycle.lock"),
+    runtimeRoot: runtimeRootFor(releaseVersion),
+    codexRuntimeRoot: codexRuntimeRootFor(releaseVersion),
+    runtimeRootFor,
+    codexRuntimeRootFor,
+  };
+}
+
+function versionedChild(parent, version) {
+  if (typeof version !== "string" || !VERSION_PATTERN.test(version)) throw new Error(`Invalid Pota runtime version: ${version}`);
+  return join(parent, version);
+}