@comento/pota-harness 0.0.0-stage → 1.0.0

package/scripts/pota-lifecycle-transaction-journal.mjs

@@ -0,0 +1,244 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { potaConfigProjection, readSharedConfigSnapshot, removePotaConfig } from "./pota-lifecycle-config.mjs";
+
+export function createTransactionJournal(context) {
+  const {
+    layout, ownershipPath, transactionPath,
+    transactionRoot, expectedManagedTarget, targetDigest,
+  } = context;
+  // Journal-only id that removes the Codex cache runtime a version change leaves behind when it is not retained.
+  const previousRuntimeParents = { "previous-codex-runtime": layout.codexRuntimeParent };
+  // The versioned runtimes of any release (the installation's, not only this CLI's): a rollback or recovery by a CLI
+  // of another version still has to read them.
+  const versionedRuntimeIds = ["runtime", "codex-runtime"];
+  // Journal-only ids that remove a retained runtime: `retired-<runtime|codex-runtime>-<version>`, during install
+  // cleanup or uninstall core.
+  const retiredRuntimeRoots = { runtime: layout.runtimeRootFor, "codex-runtime": layout.codexRuntimeRootFor };
+async function createTransaction() {
+  const id = randomUUID();
+  const root = join(transactionRoot, id);
+  const transaction = {
+    schemaVersion: 1,
+    id,
+    state: "active",
+    root,
+    stageRoot: join(root, "stage"),
+    backupRoot: join(root, "backup"),
+    entries: [],
+  };
+  await mkdir(transaction.backupRoot, { recursive: true });
+  await writeTransactionJournal(transaction);
+  return transaction;
+}
+
+async function rollback(transaction) {
+  await rollbackEntries(transaction);
+  await rm(transaction.root, { recursive: true, force: true });
+  await rm(transactionPath, { force: true });
+}
+
+async function finishTransaction(transaction) {
+  transaction.state = "committed";
+  try {
+    await writeTransactionJournal(transaction);
+  } catch (error) {
+    transaction.state = "active";
+    throw error;
+  }
+  await rm(transaction.root, { recursive: true, force: true });
+  await rm(transactionPath, { force: true });
+}
+
+async function writeTransactionJournal(transaction) {
+  const durable = {
+    schemaVersion: transaction.schemaVersion,
+    id: transaction.id,
+    state: transaction.state,
+    entries: transaction.entries,
+  };
+  await durableReplaceFile(transactionPath, `${JSON.stringify(durable, null, 2)}\n`, transaction.id);
+}
+
+async function durableReplaceFile(path, content, nonce = randomUUID()) {
+  await mkdir(dirname(path), { recursive: true });
+  const candidate = `${path}.${nonce}.tmp`;
+  const file = await open(candidate, "w", 0o600);
+  try {
+    await file.writeFile(content, "utf8");
+    await file.sync();
+  } finally {
+    await file.close();
+  }
+  await rename(candidate, path);
+  // Directory fsync is unavailable on some Windows/filesystem combinations. The
+  // file fsync+atomic rename remains the portable floor; directory sync is best effort.
+  try {
+    const directory = await open(dirname(path), "r");
+    try { await directory.sync(); } finally { await directory.close(); }
+  } catch (error) {
+    if (!(["EINVAL", "ENOTSUP", "EISDIR", "EPERM", "EACCES"].includes(error?.code))) throw error;
+  }
+}
+
+async function recoverInterruptedTransaction() {
+  if (!(await exists(transactionPath))) return;
+  let journal;
+  try {
+    journal = JSON.parse(await readFile(transactionPath, "utf8"));
+  } catch {
+    throw new Error(`Lifecycle transaction journal is invalid: ${transactionPath}`);
+  }
+  validateTransactionJournal(journal, { strict: true });
+  if (journal.state === "committed") {
+    await rm(join(transactionRoot, journal.id), { recursive: true, force: true });
+    await rm(transactionPath, { force: true });
+    return;
+  }
+  await rollbackEntries(journal);
+  await rm(join(transactionRoot, journal.id), { recursive: true, force: true });
+  await rm(transactionPath, { force: true });
+}
+
+function validateTransactionJournal(journal, { strict = false } = {}) {
+  if (journal?.schemaVersion !== 1 || typeof journal.id !== "string" || !/^[a-f0-9-]{20,}$/i.test(journal.id)
+      || !["active", "committed"].includes(journal.state) || !Array.isArray(journal.entries)) {
+    throw new Error("Lifecycle transaction journal has an invalid schema.");
+  }
+  if (strict && !sameKeys(journal, ["schemaVersion", "id", "state", "entries"])) throw new Error("Lifecycle transaction journal has unknown fields.");
+  const allowedBackupRoot = resolve(transactionRoot, journal.id, "backup");
+  const ids = new Set();
+  const paths = new Set();
+  for (const entry of journal.entries) {
+    const expected = entry.id === "ownership"
+      ? { phase: "manifest", path: ownershipPath, type: "file" }
+      : Object.hasOwn(previousRuntimeParents, entry.id)
+        ? previousRuntimeTarget(previousRuntimeParents[entry.id], entry.path)
+      : typeof entry.id === "string" && entry.id.startsWith("retired-")
+        ? (entry.operation === "remove" ? retiredRuntimeTarget(entry.id, entry.phase) : null)
+      : versionedRuntimeIds.includes(entry.id)
+        ? versionedRuntimeTarget(entry.id, entry.path)
+      : expectedManagedTarget(entry.id);
+    if (!expected || expected.path !== entry.path || expected.phase !== entry.phase || expected.type !== entry.type
+        || !["prepared", "applied"].includes(entry.status)
+        || !["replace", "remove"].includes(entry.operation)
+        || typeof entry.existed !== "boolean"
+        || !isInside(allowedBackupRoot, entry.backup)
+        || typeof entry.expectedNewDigest !== "string" || typeof entry.previousDigest !== "string") {
+      throw new Error(`Lifecycle transaction journal contains an unsafe entry: ${entry?.id ?? "unknown"}`);
+    }
+    if (strict && !sameKeys(entry, ["id", "phase", "path", "type", "backup", "existed", "previousDigest", "expectedNewDigest", "operation", "status"])) {
+      throw new Error(`Lifecycle transaction journal entry has unknown fields: ${entry.id}`);
+    }
+    if (ids.has(entry.id) || paths.has(entry.path)) throw new Error(`Lifecycle transaction journal contains duplicate targets: ${entry.id}`);
+    if (entry.operation === "remove" && entry.expectedNewDigest !== "missing") throw new Error(`Lifecycle remove entry has an invalid new digest: ${entry.id}`);
+    ids.add(entry.id);
+    paths.add(entry.path);
+  }
+}
+
+// A direct `<version>` child of `parent`; the version is any release, because the journal may come from a CLI of
+// another version than this one.
+function previousRuntimeTarget(parent, path) {
+  const relation = versionedChild(parent, path);
+  return relation ? { phase: "cleanup", path: join(parent, relation), type: "tree" } : null;
+}
+
+// `runtime` and `codex-runtime` keep their phase and type; only the version directory may differ from this release.
+function versionedRuntimeTarget(id, path) {
+  const expected = expectedManagedTarget(id);
+  if (!expected) return null;
+  const parent = dirname(expected.path);
+  const relation = versionedChild(parent, path);
+  return relation ? { ...expected, path: join(parent, relation) } : null;
+}
+
+function versionedChild(parent, path) {
+  if (typeof path !== "string") return null;
+  const relation = relative(parent, resolve(path));
+  if (!relation || relation.includes(sep) || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(relation)) return null;
+  return relation;
+}
+
+function retiredRuntimeTarget(id, phase) {
+  const match = /^retired-(runtime|codex-runtime)-(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/.exec(id);
+  if (!match || !Object.hasOwn(retiredRuntimeRoots, match[1]) || !["core", "cleanup"].includes(phase)) return null;
+  return { phase, path: retiredRuntimeRoots[match[1]](match[2]), type: "tree" };
+}
+
+function sameKeys(value, expected) {
+  return Object.keys(value).sort().join("\0") === [...expected].sort().join("\0");
+}
+
+async function rollbackEntries(transaction) {
+  validateTransactionJournal(transaction);
+  for (const entry of [...transaction.entries].reverse()) {
+    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, `${removePotaConfig(currentConfig)}${potaConfigProjection(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}`);
+      }
+      if (destinationExists) {
+        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 readSharedConfigSnapshot(entry.path)).text;
+          const previousConfig = (await readSharedConfigSnapshot(entry.backup)).text;
+          await writeFile(entry.path, `${removePotaConfig(currentConfig)}${potaConfigProjection(previousConfig)}`);
+          await rm(entry.backup, { force: true });
+          continue;
+        }
+        await rm(entry.path, { recursive: true, force: true });
+      }
+      await mkdir(dirname(entry.path), { recursive: true });
+      await rename(entry.backup, entry.path);
+    } else if (entry.status === "prepared") {
+      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 = removePotaConfig((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 });
+      }
+    } else {
+      if (!destinationExists || await targetDigest(entry.path, entry.type) !== entry.previousDigest) {
+        throw new Error(`Cannot recover transaction because its durable backup is missing: ${entry.path}`);
+      }
+    }
+  }
+}
+
+  return {
+    createTransaction, finishTransaction, recoverInterruptedTransaction, rollback,
+    writeTransactionJournal,
+  };
+
+  async function exists(path) {
+    try { await lstat(path); return true; }
+    catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  }
+
+  function isInside(root, candidate) {
+    const path = resolve(candidate);
+    return path === root || path.startsWith(`${root}${sep}`);
+  }
+}

package/scripts/pota-lifecycle-transaction-targets.mjs

@@ -0,0 +1,119 @@
+import { lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { potaConfigProjection, readSharedConfigSnapshot, removePotaConfig } from "./pota-lifecycle-config.mjs";
+
+export function createTransactionTargets(context) {
+  const { targetDigest, writeTransactionJournal } = context;
+async function replaceTarget(target, transaction) {
+  let configProjection = null;
+  if (target.type === "config") {
+    const snapshot = await readSharedConfigSnapshot(target.path);
+    configProjection = potaConfigProjection((await readSharedConfigSnapshot(target.staged)).text);
+    if (snapshot.digest !== target.configSourceDigest) {
+      await writeFile(target.staged, `${removePotaConfig(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 });
+  const entry = {
+    id: target.id,
+    phase: target.phase,
+    path: target.path,
+    type: target.type,
+    backup,
+    existed,
+    previousDigest: existed ? await targetDigest(target.path, target.type) : "missing",
+    expectedNewDigest: await targetDigest(target.staged, target.type),
+    operation: "replace",
+    status: "prepared",
+  };
+  transaction.entries.push(entry);
+  await writeTransactionJournal(transaction);
+  if (process.env.POTA_TEST_MUTATE_AFTER_PREFLIGHT_ID === target.id) {
+    await writeFile(target.path, process.env.POTA_TEST_MUTATION_CONTENT ?? "concurrent mutation\n");
+  }
+  if (target.type !== "config" && target.preflightDigest !== undefined
+      && await targetDigest(target.path, target.type) !== target.preflightDigest) {
+    throw new Error(`Managed artifact changed after lifecycle preflight: ${target.path}`);
+  }
+  if (target.type === "config" && process.env.POTA_TEST_APPEND_CONFIG_BEFORE_REPLACE) {
+    const snapshot = await readSharedConfigSnapshot(target.path);
+    await writeFile(target.path, `${snapshot.text}${process.env.POTA_TEST_APPEND_CONFIG_BEFORE_REPLACE}`);
+  }
+  if (target.type === "config" && process.env.POTA_TEST_REMOVE_CONFIG_BEFORE_REPLACE === "1") {
+    await rm(target.path, { force: true });
+  }
+  if (target.type === "config") {
+    let capturedExists = true;
+    try {
+      await renameLifecycleTarget(target.path, backup, target.id);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      capturedExists = false;
+    }
+    if (process.env.POTA_TEST_CRASH_AFTER_CONFIG_CAPTURE === "1") process.exit(86);
+    const captured = await readSharedConfigSnapshot(backup);
+    if (capturedExists) await writeFile(target.staged, `${removePotaConfig(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 renameLifecycleTarget(target.path, backup, target.id);
+  await mkdir(dirname(target.path), { recursive: true });
+  await renameStagedLifecycleTarget(target.staged, target.path, target.id);
+  entry.status = "applied";
+  await writeTransactionJournal(transaction);
+}
+
+async function renameStagedLifecycleTarget(source, destination, targetId) {
+  if (process.env.POTA_TEST_FORCE_EXDEV_ID === targetId) {
+    throw new Error(`Cross-device replacement is not supported safely for lifecycle target: ${targetId}`);
+  }
+  await renameLifecycleTarget(source, destination, targetId);
+}
+
+async function renameLifecycleTarget(source, destination, targetId) {
+  try {
+    await rename(source, destination);
+  } catch (error) {
+    if (error?.code === "EXDEV") {
+      throw new Error(`Cross-device replacement is not supported safely for lifecycle target: ${targetId}`);
+    }
+    throw error;
+  }
+}
+
+async function removeManagedTarget(target, transaction) {
+  if (!(await exists(target.path))) throw new Error(`Managed uninstall target is missing: ${target.path}`);
+  const backup = join(transaction.backupRoot, String(transaction.entries.length));
+  await mkdir(dirname(backup), { recursive: true });
+  const entry = {
+    id: target.id,
+    phase: target.phase,
+    path: target.path,
+    type: target.type,
+    backup,
+    existed: true,
+    previousDigest: await targetDigest(target.path, target.type),
+    expectedNewDigest: "missing",
+    operation: "remove",
+    status: "prepared",
+  };
+  transaction.entries.push(entry);
+  await writeTransactionJournal(transaction);
+  await renameLifecycleTarget(target.path, backup, target.id);
+  entry.status = "applied";
+  await writeTransactionJournal(transaction);
+}
+
+
+  return { removeManagedTarget, replaceTarget };
+
+  async function exists(path) {
+    try { await lstat(path); return true; }
+    catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  }
+}

package/scripts/pota-lifecycle-transaction.mjs

@@ -0,0 +1,12 @@
+import { createLifecycleLock, DEFAULT_LIFECYCLE_LOCK_TIMEOUT_MS } from "./pota-lifecycle-lock.mjs";
+import { createTransactionJournal } from "./pota-lifecycle-transaction-journal.mjs";
+import { createTransactionTargets } from "./pota-lifecycle-transaction-targets.mjs";
+
+export { DEFAULT_LIFECYCLE_LOCK_TIMEOUT_MS };
+
+export function createTransactionManager(context) {
+  const lock = createLifecycleLock(context);
+  const journal = createTransactionJournal(context);
+  const targets = createTransactionTargets({ ...context, writeTransactionJournal: journal.writeTransactionJournal });
+  return { ...journal, ...lock, ...targets };
+}

package/scripts/pota-lifecycle.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { lstat, readFile, rmdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { resolvePluginRoot } from "./pota-paths.mjs";
+import {
+  canonical, ensureSetting, hasSetting, hookHash, removePotaConfig, splitSections,
+  updateConfig as projectConfig,
+} from "./pota-lifecycle-config.mjs";
+import { createCommands } from "./pota-lifecycle-commands.mjs";
+import { createIntegrity } from "./pota-lifecycle-integrity.mjs";
+import { HOSTS, isHostSelection, parseHostsOption, promptHosts } from "./pota-lifecycle-hosts.mjs";
+import { createLayout } from "./pota-lifecycle-layout.mjs";
+import { removeUpdateState } from "./pota-update-state.mjs";
+import {
+  antigravityRuntimeLocatorPath, quoteShellArg, renderInstalledMirror as projectMirror,
+} from "./pota-lifecycle-mirror.mjs";
+import {
+  pathHasSegment, shouldCopyPluginPath as projectShouldCopyPluginPath,
+} from "./pota-lifecycle-staging.mjs";
+import { createStaging } from "./pota-lifecycle-staging.mjs";
+import {
+  createTransactionManager, DEFAULT_LIFECYCLE_LOCK_TIMEOUT_MS,
+} from "./pota-lifecycle-transaction.mjs";
+
+export {
+  canonical, DEFAULT_LIFECYCLE_LOCK_TIMEOUT_MS, ensureSetting, hasSetting, hookHash,
+  pathHasSegment, quoteShellArg, removePotaConfig, splitSections,
+};
+
+const pluginRoot = resolvePluginRoot(import.meta.url);
+const homeRoot = process.env.HOME ?? process.env.USERPROFILE ?? homedir() ?? ".";
+const claudeHomeOverridden = typeof process.env.CLAUDE_HOME === "string" && process.env.CLAUDE_HOME.length > 0;
+const claudeHome = resolve(process.env.CLAUDE_HOME ?? join(homeRoot, ".claude"));
+const antigravityHome = resolve(process.env.ANTIGRAVITY_HOME ?? join(homeRoot, ".gemini", "config"));
+const antigravityCliHome = resolve(process.env.ANTIGRAVITY_CLI_HOME ?? join(homeRoot, ".gemini", "antigravity-cli"));
+const marketplaceName = "pota";
+const pluginName = "pota";
+const claudeRuntimeLocatorPath = join(claudeHome, "pota", "runtime.json");
+const sourceManifest = JSON.parse(await readFile(join(pluginRoot, ".codex-plugin", "plugin.json"), "utf8"));
+const releaseVersion = sourceManifest.version;
+const layout = createLayout({ env: process.env, releaseVersion, marketplaceName, pluginName });
+const {
+  potaHomeRoot, claudePluginMarketplaceRoot, codexCacheRoot, codexHome, codexRuntimeRoot, installRoot,
+  installedPluginRoot, lifecycleLockPath, marketplaceJsonPath, marketplaceRoot, ownershipPath, runtimeRoot,
+  transactionPath, transactionRoot,
+} = layout;
+const configPath = resolve(process.env.CODEX_CONFIG_PATH ?? join(codexHome, "config.toml"));
+const installedRuntimeLocatorPath = join(runtimeRoot, ".pota-runtime.json");
+const phases = ["core", "codex", "claude", "antigravity", "config", "cleanup"];
+const MAX_LIFECYCLE_LOCK_TIMEOUT_MS = 2_147_483_647;
+
+const lifecycleContext = {
+  agentNames, antigravityCliHome, antigravityHome, claudeHome, claudeHomeOverridden,
+  claudePluginMarketplaceRoot, claudeRuntimeLocatorPath, codexCacheRoot, codexRuntimeRoot,
+  codexHome, commandNames, configPath, installRoot, installedPluginRoot, installedRuntimeLocatorPath,
+  layout, lifecycleLockPath, marketplaceJsonPath, marketplaceName,
+  marketplaceRoot, ownershipPath, phases, pluginName, pluginRoot, releaseVersion, runtimeRoot,
+  samePath, skillNames, transactionPath, transactionRoot, updateConfig,
+};
+const integrity = createIntegrity(lifecycleContext);
+const transaction = createTransactionManager({ ...lifecycleContext, ...integrity });
+const staging = createStaging({ ...lifecycleContext, assertRegularTree: integrity.assertRegularTree });
+const commands = createCommands({
+  ...lifecycleContext, integrity,
+  pruneUninstallScaffolds: () => pruneUninstallScaffolds(layout), staging, t, transaction,
+});
+
+if (isCliEntry()) {
+  try {
+    const { command, hosts: requestedHosts, auto, allowDowngrade } = parseLifecycleInvocation(process.argv.slice(2));
+    if (command === "install" || command === "upgrade") {
+      // The prompt runs before any lock is taken so a waiting answer never blocks another lifecycle run.
+      const hosts = requestedHosts ?? (command === "install" && await shouldPromptHosts() ? await promptHosts({ input: process.stdin, output: process.stdout, ko: localeFamily() === "ko" }) : null);
+      await assertLifecycleMutationPaths(hosts);
+      await withLifecycleLocks(() => commands.install(command, { hosts, auto, allowDowngrade }), { afterRelease: pruneUninstallRoots });
+    } else if (command === "doctor") {
+      await assertNoSymlinkAncestor(potaHomeRoot, lifecycleLockPath);
+      await transaction.withLifecycleLock(commands.doctor, { timeoutMs: lifecycleLockTimeout(), afterRelease: pruneUninstallRoots });
+    } else if (command === "uninstall") {
+      await assertLifecycleMutationPaths(null);
+      // Auto-upgrade state goes with the installation; config.json and goal state stay.
+      await withLifecycleLocks(commands.uninstall, { afterRelease: async () => { await pruneUninstallRoots(); await removeUpdateState(process.env); } });
+    } else help();
+  } catch (error) {
+    console.error(`Pota lifecycle error: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+// Only install and upgrade take options: `--hosts <list>` or `--hosts=<list>`, and `--allow-downgrade` (replace an
+// installation of a newer version). upgrade also takes `--auto` (the auto-upgrade runner's call, which keeps the
+// recorded hosts and never downgrades); every other trailing argument (including --help) is rejected before any lock
+// or stage, as before.
+function parseLifecycleInvocation(args) {
+  if (args.length === 0) return { command: "help", hosts: null, auto: false, allowDowngrade: false };
+  const [command, ...trailing] = args;
+  if (!["install", "upgrade", "doctor", "uninstall", "help"].includes(command)) throw new Error(`Unknown lifecycle command: ${command}`);
+  const unexpected = [];
+  let hostsValue;
+  let hostsGiven = false;
+  let auto = false;
+  let allowDowngrade = false;
+  for (let index = 0; index < trailing.length; index += 1) {
+    const arg = trailing[index];
+    if (command === "upgrade" && arg === "--auto" && !auto) { auto = true; continue; }
+    if ((command === "install" || command === "upgrade") && arg === "--allow-downgrade" && !allowDowngrade) { allowDowngrade = true; continue; }
+    const hostsArg = command === "install" || command === "upgrade" ? arg === "--hosts" || arg.startsWith("--hosts=") : false;
+    if (!hostsArg) { unexpected.push(arg); continue; }
+    if (hostsGiven) throw new Error("Invalid --hosts value: --hosts may only be provided once");
+    hostsGiven = true;
+    if (arg === "--hosts") { hostsValue = trailing[index + 1]; index += 1; } else hostsValue = arg.slice("--hosts=".length);
+  }
+  if (unexpected.length > 0) {
+    // doctor, uninstall, and help keep the original message listing every trailing argument.
+    const listed = command === "install" || command === "upgrade" ? unexpected : trailing;
+    throw new Error(`Lifecycle command ${command} does not accept arguments: ${listed.join(" ")}`);
+  }
+  if (auto && hostsGiven) throw new Error("--auto cannot be combined with --hosts");
+  if (auto && allowDowngrade) throw new Error("--auto cannot be combined with --allow-downgrade");
+  return { command, hosts: hostsGiven ? parseHostsOption(hostsValue) : null, auto, allowDowngrade };
+}
+
+// install asks only when nothing is installed yet (no ownership manifest), a person is at a terminal, and
+// CI is not set. POTA_TEST_HOSTS_PROMPT_TTY stands in for the terminal check so tests can answer through a pipe.
+async function shouldPromptHosts() {
+  if (process.env.CI) return false;
+  const terminal = process.env.POTA_TEST_HOSTS_PROMPT_TTY === "1" || (process.stdin.isTTY && process.stdout.isTTY);
+  if (!terminal) return false;
+  return !(await pathExists(ownershipPath));
+}
+
+// The hosts whose paths an install, upgrade, or uninstall may touch: the requested selection plus whatever the
+// current manifest records. Without a readable selection every host is checked.
+async function hostsInScope(requested) {
+  let recorded = null;
+  try { recorded = JSON.parse(await readFile(ownershipPath, "utf8")).hosts; } catch { recorded = null; }
+  if (!isHostSelection(recorded)) recorded = (await pathExists(ownershipPath)) ? [...HOSTS] : null;
+  const scope = new Set([...(requested ?? []), ...(recorded ?? [])]);
+  if (!requested && !recorded) for (const host of HOSTS) scope.add(host);
+  return scope;
+}
+
+function lifecycleLockTimeout() {
+  const raw = process.env.POTA_LIFECYCLE_LOCK_TIMEOUT_MS;
+  if (raw === undefined) return DEFAULT_LIFECYCLE_LOCK_TIMEOUT_MS;
+  if (!/^[1-9]\d*$/.test(raw)) throw new Error(`POTA_LIFECYCLE_LOCK_TIMEOUT_MS must be an integer between 1 and ${MAX_LIFECYCLE_LOCK_TIMEOUT_MS}`);
+  const timeoutMs = Number(raw);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs > MAX_LIFECYCLE_LOCK_TIMEOUT_MS) throw new Error(`POTA_LIFECYCLE_LOCK_TIMEOUT_MS must be an integer between 1 and ${MAX_LIFECYCLE_LOCK_TIMEOUT_MS}`);
+  return timeoutMs;
+}
+
+async function withLifecycleLocks(operation, { afterRelease } = {}) {
+  return transaction.withLifecycleLock(operation, { timeoutMs: lifecycleLockTimeout(), afterRelease });
+}
+
+// Symlinked ancestors are checked only for the hosts in scope, so a symlinked home of a host the user did not select
+// never blocks the others.
+async function assertLifecycleMutationPaths(requestedHosts) {
+  const hosts = await hostsInScope(requestedHosts);
+  const roots = [
+    [potaHomeRoot, lifecycleLockPath], [potaHomeRoot, transactionRoot], [potaHomeRoot, runtimeRoot],
+    ...(hosts.has("codex") ? [
+      [potaHomeRoot, installedPluginRoot], [potaHomeRoot, marketplaceJsonPath],
+      [codexHome, codexRuntimeRoot], [isInside(codexHome, configPath) ? codexHome : dirname(configPath), configPath],
+    ] : []),
+    ...(hosts.has("claude") ? [
+      [potaHomeRoot, claudePluginMarketplaceRoot],
+      [claudeHome, join(claudeHome, "commands")], [claudeHome, join(claudeHome, "agents")], [claudeHome, claudeRuntimeLocatorPath],
+    ] : []),
+    ...(hosts.has("antigravity") ? [
+      [antigravityHome, join(antigravityHome, "skills")],
+      ...skillNames().map((name) => [antigravityHome, join(antigravityHome, "skills", name)]),
+      [antigravityHome, join(antigravityHome, "workflows")], [antigravityHome, antigravityRuntimeLocatorPath(antigravityHome)],
+      [antigravityCliHome, join(antigravityCliHome, "skills")], [antigravityCliHome, join(antigravityCliHome, "workflows")],
+      [antigravityCliHome, antigravityRuntimeLocatorPath(antigravityCliHome)],
+    ] : []),
+  ];
+  for (const [root, destination] of roots) await assertNoSymlinkAncestor(root, destination);
+}
+
+async function assertNoSymlinkAncestor(root, destination) {
+  const relation = relative(root, destination);
+  if (relation === ".." || relation.startsWith(`..${sep}`) || isAbsolute(relation)) return;
+  const paths = [resolve(root)];
+  let current = resolve(root);
+  for (const segment of relation.split(sep).filter(Boolean)) { current = join(current, segment); paths.push(current); }
+  for (const path of paths) {
+    let info;
+    try { info = await lstat(path); }
+    catch (error) { if (error?.code === "ENOENT") continue; throw error; }
+    if (info.isSymbolicLink()) {
+      if (path === configPath) throw new Error(`Managed config is not a regular file: ${path}`);
+      throw new Error(`Lifecycle path ancestor must not be a symlink: ${path}`);
+    }
+  }
+}
+
+async function pruneUninstallScaffolds(paths) {
+  for (const path of [
+    join(paths.marketplaceRoot, "plugins"), join(paths.marketplaceRoot, ".agents", "plugins"), join(paths.marketplaceRoot, ".agents"),
+    paths.marketplaceRoot, paths.runtimeParent, paths.transactionRoot, paths.codexRuntimeParent,
+  ]) await removeEmptyDirectory(path);
+}
+
+// Only empty managed roots are removed; POTA_HOME itself also holds goal state and is left in place.
+async function pruneUninstallRoots() {
+  await removeEmptyDirectory(installRoot);
+  await removeEmptyDirectory(codexCacheRoot);
+}
+
+async function pathExists(path) {
+  try { await lstat(path); return true; }
+  catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+}
+
+async function removeEmptyDirectory(path) {
+  try { await rmdir(path); }
+  // ENOTDIR: a symlinked scaffold of a host that was never selected is not Pota's to prune.
+  catch (error) { if (!["ENOENT", "ENOTEMPTY", "EEXIST", "ENOTDIR"].includes(error?.code)) throw error; }
+}
+
+function isInside(root, candidate) {
+  const path = resolve(candidate);
+  return path === root || path.startsWith(`${root}${sep}`);
+}
+
+export async function targetDigest(path, type) { return integrity.targetDigest(path, type); }
+export function updateConfig(config, hookStates, options = {}) { return projectConfig(config, hookStates, { marketplacePath: options.marketplacePath ?? marketplaceRoot }); }
+export function shouldCopyPluginPath(source) { return projectShouldCopyPluginPath(source, pluginRoot); }
+export function samePath(left, right) { try { return realpathSync(left) === realpathSync(right); } catch { return resolve(left) === resolve(right); } }
+export function commandNames() { return ["install", "upgrade", "doctor", "uninstall", "memory", "plan", "work", "review", "toolcheck"]; }
+export function agentNames() { return ["explorer", "worker"]; }
+export function skillNames() { return ["pota-memory", "pota-plan", "pota-work", "pota-review"]; }
+export function renderInstalledMirror(content, options = {}) { return projectMirror(content, { runtimeRoot: options.runtimeRoot ?? runtimeRoot, locatorPath: options.locatorPath ?? installedRuntimeLocatorPath, platform: options.platform ?? process.platform }); }
+export function findPluginStatus(value, id) { const entries = Array.isArray(value) ? value : value?.installed ?? value?.plugins ?? value?.data ?? []; return entries.find((entry) => entry.pluginId === id || entry.id === id || entry.name === id || `${entry.name}@${entry.marketplaceName ?? entry.marketplace}` === id) ?? null; }
+export function parseCodexFeatureList(output) { if (typeof output !== "string" || output.trim().length === 0) return null; const features = {}; for (const line of output.split(/\r?\n/)) { const match = line.trim().match(/^([A-Za-z0-9_]+)\s+.+?\s+(true|false)$/); if (match) features[match[1]] = match[2] === "true"; } return Object.keys(features).length > 0 ? features : null; }
+export function localeFamily() { const locale = [process.env.LC_ALL, process.env.LC_MESSAGES, process.env.LANG].find((value) => typeof value === "string" && value.length > 0) ?? Intl.DateTimeFormat().resolvedOptions().locale; return locale.toLowerCase().startsWith("ko") ? "ko" : "en"; }
+
+function help() { console.log(t("usage")); }
+function t(key) { const messages = { en: { installComplete: "Pota install complete", upgradeComplete: "Pota upgrade complete", uninstallComplete: "Pota uninstall complete", usage: "Usage: pota install|upgrade [--hosts all|codex,claude,antigravity] [--allow-downgrade] | doctor | uninstall | toolcheck" }, ko: { installComplete: "Pota 설치 완료", upgradeComplete: "Pota 업그레이드 완료", uninstallComplete: "Pota 언인스톨 완료", usage: "사용법: pota install|upgrade [--hosts all|codex,claude,antigravity] [--allow-downgrade] | doctor | uninstall | toolcheck" } }; return messages[localeFamily()]?.[key] ?? messages.en[key]; }
+function isCliEntry() { if (!process.argv[1]) return false; try { return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]); } catch { return import.meta.url === pathToFileURL(process.argv[1]).href; } }