@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.48

package/scripts/lib/run-repo-install.mjs

@@ -0,0 +1,1651 @@
+/**
+ * Repo-local install: `enact-extensions install <bundle> --repo <path>`.
+ *
+ * Writes a bundle into a git repository as COMMITTED, RELATIVE files that
+ * follow each host's documented project-scope standard. Nothing is written
+ * under $HOME. Every COMMITTED file is relative; the single absolute-path
+ * exception is the gitignored `.claude/settings.local.json` env block (see
+ * the claude adapter), which cannot work any other way.
+ *
+ *   claude   — plugin root copied to `.claude-plugin/<name>/` (its `skills/` is
+ *              a RELATIVE SYMLINK to the shared `.agents/skills/` tree, not a
+ *              copy — see "Shared skills" below); repo marketplace
+ *              `.claude-plugin/marketplace.json` (marketplace root = repo root,
+ *              the dir CONTAINING .claude-plugin/, so the plugin entry is
+ *              `source: "./.claude-plugin/<name>"`); `.claude/settings.json`
+ *              merged with `extraKnownMarketplaces` (directory source, path "./")
+ *              and `enabledPlugins`; `.claude/settings.local.json` merged with
+ *              the absolute LEAN_CTX_*_DIR env block (gitignored via
+ *              `.claude/.gitignore`). Loads only after the user trusts the folder.
+ *   codex    — `.codex/config.toml` `[mcp_servers.<name>]` tables in a
+ *              marker-delimited block (user TOML and comments untouched) +
+ *              `.codex/hooks.json` (canonical nested schema, `--host=codex`).
+ *              Loads only after the user trusts the project and reviews hooks.
+ *   cursor   — `.cursor/hooks.json` (version 1, camelCase, `--host=cursor`) +
+ *              `.cursor/mcp.json` (`type: "stdio"`).
+ *   kimi     — `.kimi-code/mcp.json`. Kimi hooks are global-only (enact-vps),
+ *              so NO hook file is written here.
+ *   opencode — one generated `.opencode/plugins/<name>.ts` (hooks + MCP via the
+ *              `config` hook, NO skills path: OpenCode reads `.agents/skills/`).
+ *
+ * Shared skills: ONE real copy, in `.agents/skills/<skill>/`, written
+ * UNCONDITIONALLY for every host (`.agents` is universal — every host,
+ * including a claude-only install, needs it present so nothing dangles).
+ * Claude's plugin-bundled `skills/` is a relative symlink to that same tree
+ * (`../../.agents/skills`), not a second copy: Claude Code dereferences a
+ * within-marketplace symlink (see `plan.symlinks` / the claude adapter below).
+ *
+ * State: `.agents/<name>.lock.json` records every managed file (sha256) and
+ * every entry merged into a user file. Re-runs are idempotent.
+ *
+ * Owner decision (Tarun): hooks, mcp and skills content is ALWAYS force-
+ * installed -- our own generated content and our own entries in a shared
+ * file are repaired to match the bundle on every install, no `--force` flag
+ * needed and no "not managed"/"edited" refusal. Two kinds:
+ *   - Whole files we exclusively generate (`.claude-plugin/<name>/**`,
+ *     `.agents/skills/**`, `.opencode/plugins/<name>.ts`, the claude skills
+ *     symlink): nothing user-authored can live there, so drift or a stale
+ *     pre-existing entry is just silently overwritten -- no displace/restore,
+ *     nothing worth preserving. `plan.forcedFiles` marks exactly this subset
+ *     of `plan.files`.
+ *   - Merged surfaces shared with the user (`.cursor/hooks.json`,
+ *     `.cursor/mcp.json`, `.kimi-code/mcp.json`, `.codex/hooks.json`,
+ *     `.claude/settings.json`, the marker block in `.codex/config.toml`):
+ *     ONLY our own entries are force-rewritten; a user's own keys/hooks/mcp
+ *     servers are left completely untouched. A foreign entry that happens to
+ *     share OUR key/server name is taken over and its original captured into
+ *     `displaced` for a byte-exact restore on uninstall, exactly like a
+ *     `--force` takeover always has -- it just no longer needs the flag.
+ * `--force` still gates the two surfaces OUTSIDE that scope: the repo-root
+ * `.claude-plugin/marketplace.json` and the lean-ctx baseline config files
+ * (`.agents/lean-ctx/config/lean-ctx/*.toml`) -- both can plausibly hold
+ * independent user content, so a pre-existing foreign file there is still a
+ * refused conflict until `--force` takes it over (with restore-on-uninstall,
+ * unchanged).
+ * Uninstall removes exactly what the lock records; uninstall's OWN drift
+ * check (refusing to remove content edited since install without --force)
+ * is unaffected by any of the above -- that gate is about safe removal, not
+ * install-time repair.
+ */
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  lstatSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import * as TOML from "@iarna/toml";
+import {
+  applyHostFlagToHooksDoc,
+  assertSupportedHookEvents,
+  clampHookTimeoutsForHost,
+  cutBlock,
+  cutExtensionsBlock,
+  cutLegacySkillsBlock,
+  declaredExtensionsFrom,
+  declareExtension,
+  deriveOpenCodePlugin,
+  EXTENSIONS_BLOCK,
+  ensureContainer,
+  entryPresent,
+  extractTomlTable,
+  findBlock,
+  getAt,
+  MANIFEST_BY_PLATFORM,
+  makeFileOps,
+  materializeCodexSkillMetadata,
+  pathKey,
+  projectClaudePluginRoot,
+  projectCursorHooks,
+  projectPluginRoot,
+  reinsertTomlSpans,
+  removeExtensionBlock,
+  removeJsonEntries,
+  renderTomlBlock,
+  siblingOwnersOf,
+  siblingOwnsPrefix,
+  siblingRecordsJsonEntry,
+  unmappedCursorHookEvents,
+  unmappedCursorHookMatchers,
+  valueHash,
+} from "../../dist/index.js";
+
+export const REPO_HOSTS = ["claude", "codex", "cursor", "kimi", "opencode"];
+// OpenCode is the ONLY host left needing a flat skills directory: per
+// spec/opencode.json its "documented plugin surface has no skills/agents/
+// commands concept", so a plugin root cannot carry them. Every other host
+// gets skills INSIDE its plugin root, namespaced by plugin name.
+//
+// `.opencode/skills/` is OpenCode's own documented project location, not a
+// shared cross-host pool -- so a collision here is scoped to one host instead
+// of every host, and nothing else reads it.
+const SHARED_SKILLS_DIR = ".opencode/skills";
+/** Declared extension names from `[extensions.<name>]` sub-tables, or []. */
+export function readDeclaredExtensions(configText) {
+  if (typeof configText !== "string" || configText.length === 0) return [];
+  return declaredExtensionsFrom(parseConfigText(configText, "reading [extensions]"));
+}
+// Shared repo config at the repo root; its presence marks a repo as managed
+// (enact-hook's contract). One owner per root table: enact-hook owns
+// `version`/[hooks]/[rules]/[repo], enact-repo-controls owns [controls], this
+// package owns [extensions]. We never parse or rewrite anyone else's table:
+// the [extensions] block is appended once at text level and cut at text level.
+export const CONFIG_PATH = "enact-config.toml";
+const GITIGNORE_PATH = ".agents/.gitignore";
+// The global `enact-hook` runtime (not this installer) writes two per-repo
+// logs under `.agents/hooks/` in any managed repo: the deny log (hooks.log)
+// and the activity log (hooks-activity.log), both append-only CSV. They are
+// the runtime's own state -- never written by install -- so they get the
+// SAME managed-gitignore-line treatment as the lean-ctx runtime dirs below:
+// a plain uninstall keeps the lines while a log file is still present, and
+// `--purge` removes the log files themselves before the lines.
+export const HOOK_LOG_FILES = ["hooks.log", "hooks-activity.log"].map((f) => `.agents/hooks/${f}`);
+
+// ---------------------------------------------------------------------------
+// Repo-local lean-ctx directory layout — ONE source of truth for BOTH uses:
+// where the installer writes/ignores these directories, and the environment
+// variables that tell the `lean-ctx` binary to use them.
+//
+//   rel      repo-relative directory
+//   env      the variable lean-ctx reads to find it (null = no variable)
+//   runtime  lean-ctx creates it itself while in use (never the installer),
+//            so it is gitignored rather than committed
+//
+// Without the `env` variables lean-ctx resolves ~/.config/lean-ctx, finds
+// nothing, and silently enforces its built-in command set instead of the
+// repo config we just installed (measured: 223 built-ins vs the repo's 249).
+// ---------------------------------------------------------------------------
+const LEAN_CTX_ROOT = ".agents/lean-ctx";
+const LEAN_CTX_DIRS = [
+  { rel: `${LEAN_CTX_ROOT}/config/lean-ctx`, env: "LEAN_CTX_CONFIG_DIR", runtime: false },
+  { rel: `${LEAN_CTX_ROOT}/data`, env: "LEAN_CTX_DATA_DIR", runtime: true },
+  { rel: `${LEAN_CTX_ROOT}/cache`, env: "LEAN_CTX_CACHE_DIR", runtime: true },
+  { rel: `${LEAN_CTX_ROOT}/state`, env: "LEAN_CTX_STATE_DIR", runtime: true },
+  { rel: `${LEAN_CTX_ROOT}/bin`, env: null, runtime: true },
+];
+// lean-ctx config (config.toml, layout.toml) stays committed; only its
+// runtime-generated dirs are ignored.
+const LEAN_CTX_CONFIG_DIR = LEAN_CTX_DIRS[0].rel;
+// RUNTIME dirs lean-ctx itself creates while the plugin is in use (never
+// written by the installer) -- these are exactly what GITIGNORE_LINES hides.
+// A plain uninstall must not remove those gitignore lines while any of these
+// dirs still exist on disk (it would surface them as untracked); `--purge`
+// removes the dirs themselves first (they are OUR runtime's own state, not
+// user data), then the gitignore lines.
+const LEAN_CTX_RUNTIME_DIRS = LEAN_CTX_DIRS.filter((d) => d.runtime).map((d) => d.rel);
+// `.agents/.gitignore` is itself inside `.agents/`, so its patterns are
+// anchored one level down (`.agents/lean-ctx/data` -> `/lean-ctx/data/`).
+const agentsGitignoreLine = (rel) => rel.slice(".agents".length);
+const GITIGNORE_LINES = [
+  ...LEAN_CTX_RUNTIME_DIRS.map((rel) => `${agentsGitignoreLine(rel)}/`),
+  ...HOOK_LOG_FILES.map(agentsGitignoreLine),
+];
+
+// No `.claude/settings.local.json` env carrier, and therefore no
+// `.claude/.gitignore` line to hide it. Both were removed with the carrier:
+// absolute paths in an installed file are machine-specific and go stale
+// silently on a rename or a fresh clone at a different path.
+// OpenCode's own auto-generated project-local files (verified 2026-09-14,
+// this session, against a live `.opencode/` created by a real OpenCode run
+// -- .scratch/opencode-plugin-example/.opencode/.gitignore lists exactly
+// these as what OpenCode itself manages: "node_modules\npackage.json\n
+// package-lock.json\nbun.lock\n.gitignore"). We never write these
+// ourselves; `--purge` removes them ONLY when nothing else user-owned
+// remains under `.opencode/` (besides our own now-removed `plugins/*.ts`).
+const OPENCODE_AUTOGEN_ENTRIES = new Set([
+  "node_modules",
+  "package.json",
+  "package-lock.json",
+  "bun.lock",
+  ".gitignore",
+]);
+// ONE marketplace per repo, listing every installed plugin -- not one per
+// plugin. A marketplace.json carries exactly one `name` field, so per-plugin
+// names cannot coexist in it; the previous `<plugin>-local` scheme meant the
+// file's identity was "whoever installed last", and the second plugin silently
+// erased the first's entry (measured: installing enact-repo then enact-wiki
+// with --force left `name: enact-wiki-local`, `plugins: [enact-wiki]`).
+// Claude: "To publish multiple plugins under one marketplace name, list them
+// all in a single marketplace.json." Codex reads this file too, as a
+// legacy-compatible repo marketplace.
+const MARKETPLACE_NAME = "enact-local";
+const MARKETPLACE_PATH = ".claude-plugin/marketplace.json";
+const LOCK_VERSION = 1;
+
+const CONFIG_ROOT_CONTENT = "version = 1\n";
+
+// ---------------------------------------------------------------------------
+// small utils
+// ---------------------------------------------------------------------------
+
+export const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+const has = (obj, key) => Object.hasOwn(obj, key);
+
+export const abs = (repo, rel) => join(repo, ...rel.split("/"));
+
+export function readJsonStrict(path, label) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new Error(`Cannot parse ${label}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function listFilesRecursive(root, rel = "") {
+  const out = [];
+  for (const entry of readdirSync(join(root, rel), { withFileTypes: true })) {
+    if (entry.name === ".DS_Store") continue;
+    const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listFilesRecursive(root, childRel));
+    else if (entry.isFile()) out.push(childRel);
+  }
+  return out.sort();
+}
+
+function detectJsonFormat(text) {
+  const match = /^[\t ]+(?=")/m.exec(text);
+  return { indent: match ? match[0] : "  ", trailingNewline: text.endsWith("\n") };
+}
+
+function serializeJson(doc, format) {
+  return `${JSON.stringify(doc, null, format.indent)}${format.trailingNewline ? "\n" : ""}`;
+}
+
+function sortObject(obj) {
+  return Object.fromEntries(
+    Object.keys(obj)
+      .sort()
+      .map((k) => [k, obj[k]]),
+  );
+}
+
+// Drop empty per-rel entries before persisting `displaced` to the lock.
+function pruneDisplaced(displaced) {
+  const json = {};
+  for (const [rel, m] of Object.entries(displaced.json)) if (Object.keys(m).length > 0) json[rel] = m;
+  const toml = {};
+  for (const [rel, spans] of Object.entries(displaced.toml)) if (spans.length > 0) toml[rel] = spans;
+  return { files: sortObject(displaced.files), json: sortObject(json), toml: sortObject(toml) };
+}
+
+// ---------------------------------------------------------------------------
+// repo + bundle resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Every real path this process could reasonably mean by "the home directory".
+ *
+ * `os.homedir()` alone is not enough, because runtimes disagree about it.
+ * Measured: node 26 resolves it from `$HOME` on POSIX, bun 1.4.2 does NOT --
+ * after `process.env.HOME = "/tmp/pretend-home"`, node reports the override and
+ * bun still reports the real account home. So a guard reading only `homedir()`
+ * quietly stops matching wherever HOME is overridden: CI images, containers,
+ * `sudo -E`, and this repo's own test suite.
+ *
+ * Refusing all of the candidates is strictly safer than betting on one of them,
+ * and makes the guard mean the same thing on every runtime.
+ */
+function homeDirectories() {
+  const found = new Set();
+  for (const candidate of [homedir(), process.env.HOME, process.env.USERPROFILE]) {
+    if (typeof candidate !== "string" || candidate === "") continue;
+    found.add(resolve(candidate));
+    try {
+      found.add(realpathSync(candidate));
+    } catch {
+      // A HOME that does not resolve cannot be the directory being installed
+      // into -- `repo` is realpath'd above, so it always exists. Nothing is
+      // being suppressed here: the candidate simply cannot match.
+    }
+  }
+  return found;
+}
+
+export function resolveRepoRoot(repoArg) {
+  if (!repoArg || typeof repoArg !== "string") {
+    throw new Error("--repo <path> is required for a repo-local install");
+  }
+  if (!existsSync(repoArg) || !statSync(repoArg).isDirectory()) {
+    throw new Error(`--repo ${repoArg} is not a directory`);
+  }
+  const repo = realpathSync(resolve(repoArg));
+  if (homeDirectories().has(repo)) {
+    throw new Error(`--repo ${repoArg} is the home directory; repo-local installs must target a git repository root`);
+  }
+  // Filesystem check, deliberately NOT `git rev-parse --show-toplevel`. A
+  // subprocess inherits ambient git state -- global identity, GIT_DIR,
+  // core.hooksPath, the agent's git version -- so every fixture that merely
+  // wanted a directory this function accepts became a test of the machine it
+  // ran on. The check is equivalent to what the subprocess established:
+  // rev-parse followed by `root !== repo` accepts a path exactly when that
+  // path itself holds `.git` (a directory normally, a file in a worktree or
+  // submodule).
+  if (!existsSync(join(repo, ".git"))) {
+    throw new Error(`--repo ${repoArg} is not a git repository root`);
+  }
+  return repo;
+}
+
+export function parseRepoHosts(host, manifest) {
+  const targets = Array.isArray(manifest.targets) ? manifest.targets : REPO_HOSTS;
+  if (!host) return REPO_HOSTS.filter((h) => targets.includes(h));
+  const parts = [
+    ...new Set(
+      String(host)
+        .split(",")
+        .map((p) => p.trim())
+        .filter(Boolean),
+    ),
+  ];
+  for (const part of parts) {
+    if (!REPO_HOSTS.includes(part)) {
+      throw new Error(`Unknown repo host: "${part}". Valid: ${REPO_HOSTS.join(", ")}`);
+    }
+    if (!targets.includes(part)) {
+      throw new Error(`Plugin ${manifest.name} does not target host: ${part}`);
+    }
+  }
+  return REPO_HOSTS.filter((h) => parts.includes(h));
+}
+
+export function readBundle(pluginRoot) {
+  const manifestPath = join(pluginRoot, ".agents", "plugin.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error(`Repo install requires a canonical manifest at ${manifestPath}`);
+  }
+  const manifest = readJsonStrict(manifestPath, manifestPath);
+  if (typeof manifest.name !== "string" || !manifest.name) throw new Error(`${manifestPath} is missing name`);
+  const component = (field) => {
+    const value = manifest[field];
+    if (typeof value !== "string" || !value.trim()) return null;
+    const path = resolve(pluginRoot, value.replace(/^\.\//, ""));
+    return existsSync(path) ? path : null;
+  };
+  const hooksPath = component("hooks");
+  const mcpPath = component("mcpServers");
+  const mcpServers = {};
+  for (const [name, def] of Object.entries(mcpPath ? (readJsonStrict(mcpPath, mcpPath).mcpServers ?? {}) : {})) {
+    // Only stdio servers (with a command) have a documented project-file form on every host.
+    if (def && typeof def === "object" && typeof def.command === "string") mcpServers[name] = def;
+  }
+  return {
+    manifest,
+    name: manifest.name,
+    version: typeof manifest.version === "string" ? manifest.version : "0.0.0",
+    skillsDir: component("skills"),
+    hooks: hooksPath ? readJsonStrict(hooksPath, hooksPath) : null,
+    mcpServers,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// plan: the desired repo state
+//   files  Map<rel, Buffer>                         whole managed files
+//   json   Map<rel, {scaffold, keys, items}>        entries merged into user JSON
+//   toml   Map<rel, {tables}>                       mcp_servers tables merged into user TOML
+// ---------------------------------------------------------------------------
+
+function jsonMerge(plan, rel) {
+  if (!plan.json.has(rel)) plan.json.set(rel, { scaffold: [], keys: [], items: [] });
+  return plan.json.get(rel);
+}
+
+function stageDir(prefix, fn) {
+  const staging = mkdtempSync(join(tmpdir(), prefix));
+  try {
+    return fn(staging);
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+// The bundle ships a baseline lean-ctx config (config.toml, layout.toml) at
+// `<pluginRoot>/lean-ctx/`. Installed as managed whole files regardless of
+// which hosts are selected: every host wires `enact-hook lean-ctx mcp` /
+// `lean-ctx pre-tool-use` / `lean-ctx post-tool-use`.
+//
+// Writing the file is only half the job -- something must also POINT the
+// `lean-ctx` binary at it, and that carrier is per-host. Only CLAUDE is wired
+// today (`.claude/settings.local.json` `env`, see the claude adapter below).
+// codex/cursor/kimi/opencode currently get the config file WITHOUT a carrier,
+// so lean-ctx still resolves ~/.config/lean-ctx there and runs on its
+// built-in defaults -- an open gap, not a finished design.
+//
+// Returns whether a config was actually staged: the env carrier is written
+// only when there is a repo-local config for it to point at.
+function addLeanCtxConfig(plan, pluginRoot) {
+  let added = false;
+  for (const name of ["config.toml", "layout.toml"]) {
+    const src = join(pluginRoot, "lean-ctx", name);
+    if (existsSync(src)) {
+      plan.files.set(`${LEAN_CTX_CONFIG_DIR}/${name}`, readFileSync(src));
+      added = true;
+    }
+  }
+  return added;
+}
+
+function addSharedSkills(plan, bundle, codexPolicy) {
+  if (!bundle.skillsDir) return;
+  for (const entry of readdirSync(bundle.skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    plan.skills.add(entry.name);
+    for (const rel of listFilesRecursive(join(bundle.skillsDir, entry.name))) {
+      // Skill content is force-installed (owner decision): always ours, see
+      // file-header comment.
+      const fileRel = `${SHARED_SKILLS_DIR}/${entry.name}/${rel}`;
+      plan.files.set(fileRel, readFileSync(join(bundle.skillsDir, entry.name, rel)));
+      plan.forcedFiles.add(fileRel);
+    }
+  }
+  if (!codexPolicy) return;
+  stageDir("enact-repo-codex-skills-", (staging) => {
+    materializeCodexSkillMetadata(bundle.skillsDir, staging);
+    for (const rel of listFilesRecursive(staging)) {
+      const fileRel = `${SHARED_SKILLS_DIR}/${rel}`;
+      plan.files.set(fileRel, readFileSync(join(staging, rel)));
+      plan.forcedFiles.add(fileRel);
+    }
+  });
+}
+
+// Project a self-contained plugin root for a host that has a plugin format,
+// and stage it into the plan. Every such host namespaces a plugin's skills by
+// the plugin name, which is what lets two extensions ship the same skill name
+// safely -- the reason loose per-host files needed a flat shared skills pool.
+function addPluginRoot(plan, pluginRoot, bundle, platform) {
+  const rootRel = `${MANIFEST_BY_PLATFORM[platform].directory}/${bundle.name}`;
+  stageDir(`enact-repo-${platform}-`, (staging) => {
+    const target = join(staging, "plugin");
+    projectPluginRoot(pluginRoot, target, platform);
+    // Codex reads per-skill invocation policy from `agents/openai.yaml` beside
+    // each SKILL.md. It used to be written into the shared pool; it belongs
+    // inside the plugin root now, next to the skills it governs.
+    if (platform === "codex" && bundle.skillsDir) {
+      materializeCodexSkillMetadata(bundle.skillsDir, join(target, "skills"));
+    }
+    for (const rel of listFilesRecursive(target)) {
+      const fileRel = `${rootRel}/${rel}`;
+      plan.files.set(fileRel, readFileSync(join(target, rel)));
+      plan.forcedFiles.add(fileRel);
+    }
+  });
+  return rootRel;
+}
+
+// Host adapters. Codex is a direct-file adapter like Cursor: a committed repo
+// marketplace is not auto-discovered by Codex, so none is written.
+const HOST_ADAPTERS = {
+  claude(plan, bundle, pluginRoot, ctx) {
+    const pluginRel = `.claude-plugin/${bundle.name}`;
+    stageDir("enact-repo-claude-", (staging) => {
+      const target = join(staging, "plugin");
+      // Skills are carried INSIDE the plugin root, like every other host with
+      // a plugin format -- that is what namespaces them by plugin name. The
+      // earlier symlink into a shared `.agents/skills/` pool existed only
+      // because that pool existed; it is retired with it.
+      projectClaudePluginRoot(pluginRoot, target);
+      for (const rel of listFilesRecursive(target)) {
+        // The whole projected plugin root is exclusively our own generated
+        // content -- force-installed, never gated (see file-header comment).
+        const fileRel = `${pluginRel}/${rel}`;
+        plan.files.set(fileRel, readFileSync(join(target, rel)));
+        plan.forcedFiles.add(fileRel);
+      }
+    });
+    const author = bundle.manifest.author;
+    plan.files.set(
+      MARKETPLACE_PATH,
+      Buffer.from(
+        `${JSON.stringify(
+          {
+            name: MARKETPLACE_NAME,
+            owner: { name: typeof author?.name === "string" ? author.name : bundle.name },
+            // Seeded from the entry already on disk so a sibling's description
+            // and version survive OUR install; only our own entry is rebuilt.
+            // Regeneration must not quietly strip fields it did not author.
+            plugins: ctx.declaredExtensions.map((name) =>
+              name === bundle.name
+                ? {
+                    name,
+                    source: `./.claude-plugin/${name}`,
+                    ...(typeof bundle.manifest.description === "string"
+                      ? { description: bundle.manifest.description }
+                      : {}),
+                    version: bundle.version,
+                  }
+                : (ctx.existingMarketplaceEntries.get(name) ?? { name, source: `./.claude-plugin/${name}` }),
+            ),
+          },
+          null,
+          2,
+        )}\n`,
+      ),
+    );
+    // NOT forced: a pre-existing FOREIGN marketplace must still be refused
+    // until --force, with restore-on-uninstall, because it can plausibly be
+    // the user's own. But it IS derived -- we regenerate it whenever the
+    // declared set changes, including from a sibling's uninstall -- so it is
+    // exempt from the uninstall drift check, which would otherwise read our
+    // own regeneration as damage.
+    plan.derivedFiles.add(MARKETPLACE_PATH);
+    const settings = jsonMerge(plan, ".claude/settings.json");
+    settings.keys.push({
+      path: ["extraKnownMarketplaces", MARKETPLACE_NAME],
+      value: { source: { source: "directory", path: "./" } },
+    });
+    settings.keys.push({ path: ["enabledPlugins", `${bundle.name}@${MARKETPLACE_NAME}`], value: true });
+    // NOTE: the installer deliberately writes NO lean-ctx env carrier here.
+    // Scoping lean-ctx to the repo config is done by `enact-hook`, which
+    // prefixes LEAN_CTX_CONFIG_DIR/DATA_DIR/STATE_DIR/CACHE_DIR onto the
+    // rewritten command, derived from `inv.root` at invocation time. Nothing
+    // is stored, so nothing can go stale, and it is not Claude-specific.
+    // A settings.local.json `env` block was tried and rejected: it is
+    // Claude-only, machine-local, gitignored, and does not travel with the
+    // repo. Do not reintroduce it.
+  },
+
+  codex(plan, bundle, pluginRoot) {
+    addPluginRoot(plan, pluginRoot, bundle, "codex");
+    if (Object.keys(bundle.mcpServers).length > 0) plan.toml.set(".codex/config.toml", { tables: bundle.mcpServers });
+    if (bundle.hooks) {
+      const merge = jsonMerge(plan, ".codex/hooks.json");
+      // clampHookTimeoutsForHost keeps every host's canonical timeout intent
+      // (e.g. SessionEnd: 10) UNCHANGED in the source -- it only clamps what
+      // gets WRITTEN into .codex/hooks.json down to Codex's own documented
+      // per-event maximum (SessionEnd/Interrupt: 3s; see
+      // HOST_HOOK_TIMEOUT_MAX_SECONDS in src/internal/hooks.ts), so Codex
+      // never has to silently downgrade a value we shipped it.
+      const clamped = clampHookTimeoutsForHost(bundle.hooks, "codex");
+      for (const [event, entries] of Object.entries(applyHostFlagToHooksDoc(clamped, "codex").hooks ?? {})) {
+        for (const entry of entries) merge.items.push({ path: ["hooks", event], value: entry });
+      }
+    }
+  },
+
+  cursor(plan, bundle, pluginRoot) {
+    addPluginRoot(plan, pluginRoot, bundle, "cursor");
+    if (bundle.hooks) {
+      const dropped = unmappedCursorHookEvents(bundle.hooks);
+      if (dropped.length > 0) {
+        throw new Error(`Cursor hook projection drops unmapped events with active hooks: ${dropped.join(", ")}`);
+      }
+      const unmappedMatchers = unmappedCursorHookMatchers(bundle.hooks);
+      if (unmappedMatchers.length > 0) {
+        throw new Error(
+          `Cursor hook projection drops unmapped matcher tokens with active hooks: ${unmappedMatchers.join("; ")}`,
+        );
+      }
+      const merge = jsonMerge(plan, ".cursor/hooks.json");
+      merge.scaffold.push({ path: ["version"], value: 1 });
+      for (const [event, entries] of Object.entries(projectCursorHooks(bundle.hooks).hooks)) {
+        for (const entry of entries) merge.items.push({ path: ["hooks", event], value: entry });
+      }
+    }
+    const mcp = jsonMerge(plan, ".cursor/mcp.json");
+    for (const [name, def] of Object.entries(bundle.mcpServers)) {
+      mcp.keys.push({ path: ["mcpServers", name], value: { type: "stdio", ...def } });
+    }
+  },
+
+  kimi(plan, bundle, pluginRoot) {
+    addPluginRoot(plan, pluginRoot, bundle, "kimi");
+    const mcp = jsonMerge(plan, ".kimi-code/mcp.json");
+    for (const [name, def] of Object.entries(bundle.mcpServers)) {
+      mcp.keys.push({ path: ["mcpServers", name], value: def });
+    }
+  },
+
+  opencode(plan, bundle) {
+    // No skillsDir on purpose: OpenCode natively reads the shared .agents/skills/
+    // copy; a skills.paths entry would list every skill twice.
+    const source = deriveOpenCodePlugin(
+      { hooks: bundle.hooks ?? undefined, mcpServers: { mcpServers: bundle.mcpServers } },
+      bundle.name,
+    );
+    // Generated whole file (hooks + mcp): force-installed, see file-header comment.
+    const fileRel = `.opencode/plugins/${bundle.name}.ts`;
+    plan.files.set(fileRel, Buffer.from(source));
+    plan.forcedFiles.add(fileRel);
+  },
+};
+
+// `repo` is the ABSOLUTE repo root, required (not optional): the Claude env
+// block carries absolute LEAN_CTX_* paths, and a relative or missing value
+// would silently degrade into lean-ctx resolving ~/.config/lean-ctx again.
+export function buildPlan(pluginRoot, bundle, hosts, repo) {
+  if (typeof repo !== "string" || !isAbsolute(repo)) {
+    throw new Error(`buildPlan requires the absolute repo root, got ${JSON.stringify(repo)}`);
+  }
+  const plan = {
+    files: new Map(),
+    // Subset of `files` keys that are owner-forced (hooks/mcp/skills content
+    // exclusively generated by us): always overwritten, never gated behind
+    // `--force`, never captured for a displaced-content restore. See the
+    // file-header doc comment.
+    forcedFiles: new Set(),
+    // Files we REGENERATE from a source of truth (today: the marketplace, built
+    // from the declared extension set). Still conflict-gated on install, but
+    // exempt from the uninstall drift check -- a sibling's install or uninstall
+    // legitimately rewrites them.
+    derivedFiles: new Set(),
+    json: new Map(),
+    toml: new Map(),
+    gitignore: new Map(),
+    symlinks: new Map(),
+    skills: new Set(),
+  };
+  plan.gitignore.set(GITIGNORE_PATH, GITIGNORE_LINES);
+  const leanCtxConfig = addLeanCtxConfig(plan, pluginRoot);
+
+  // The repo's DECLARED extension set, from the `[extensions.<name>]` tables. Installing a
+  // plugin declares it: the file is the user-editable statement of what this
+  // repo should have, and install reconciles the repo to it. Order is stable
+  // (declaration order, ours appended last) so regenerating the marketplace
+  // does not churn the diff.
+  const configPath = abs(repo, CONFIG_PATH);
+  const configText = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  const declared = readDeclaredExtensions(configText);
+  const declaredExtensions = declared.includes(bundle.name) ? declared : [...declared, bundle.name];
+
+  // Existing marketplace entries, so regeneration preserves fields belonging to
+  // plugins other than the one being installed.
+  const existingMarketplaceEntries = new Map();
+  const mktPath = abs(repo, MARKETPLACE_PATH);
+  if (existsSync(mktPath)) {
+    try {
+      for (const entry of JSON.parse(readFileSync(mktPath, "utf8")).plugins ?? []) {
+        if (entry && typeof entry.name === "string") existingMarketplaceEntries.set(entry.name, entry);
+      }
+    } catch {
+      // Unparsable or foreign: the ordinary conflict gate handles it below.
+    }
+  }
+
+  const ctx = { repo, leanCtxConfig, declaredExtensions, existingMarketplaceEntries };
+  for (const host of hosts) HOST_ADAPTERS[host](plan, bundle, pluginRoot, ctx);
+  plan.declaredExtensions = declaredExtensions;
+  // `.agents/skills` is written UNCONDITIONALLY -- .agents is universal, and a
+  // claude-only install still needs the real tree its plugin skills/ symlink
+  // points at, or the link dangles and Claude Code drops the skills silently.
+  // Only for OpenCode. `.agents/skills/` is retired: it was a flat pool shared
+  // by every host precisely because we were not building plugin roots, and a
+  // flat pool is what made two extensions shipping one skill name unsafe.
+  if (hosts.includes("opencode")) addSharedSkills(plan, bundle, false);
+  for (const [rel, merge] of [...plan.json]) {
+    if (merge.keys.length + merge.items.length === 0) plan.json.delete(rel);
+  }
+  return plan;
+}
+
+// ---------------------------------------------------------------------------
+// JSON merge helpers
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// TOML block helpers — text level, so user content and comments are untouched
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// lock + filesystem helpers
+// ---------------------------------------------------------------------------
+
+export const lockRel = (name) => `.agents/${name}.lock.json`;
+
+export function readLock(repo, name) {
+  const path = abs(repo, lockRel(name));
+  if (!existsSync(path)) return null;
+  const lock = readJsonStrict(path, lockRel(name));
+  if (lock.plugin !== name) throw new Error(`${lockRel(name)} belongs to plugin ${lock.plugin}, not ${name}`);
+  return lock;
+}
+
+/**
+ * Every OTHER enact plugin installed in this repo, as `{ name, lock }`.
+ *
+ * Until this existed, ownership was resolved against ONE lock -- the plugin
+ * being installed -- so a second plugin saw the first plugin's legitimate
+ * output as foreign. `.agents/skills/` is a flat pool shared by every host that
+ * reads it, and real bundles collide there (enact-repo and engineering ship 23
+ * of the same skill names), so "is this path mine?" is the wrong question. The
+ * right one is "does ANY installed plugin own it?".
+ *
+ * Reads only `.agents/*.lock.json`, skipping `exclude` and any file whose
+ * `plugin` field disagrees with its filename (readLock throws on that, and a
+ * malformed sibling must not break an unrelated install -- it is reported by
+ * that plugin's own doctor instead).
+ */
+export function readSiblingLocks(repo, exclude) {
+  const dir = abs(repo, ".agents");
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".lock.json")) continue;
+    const name = entry.name.slice(0, -".lock.json".length);
+    if (name === exclude) continue;
+    let lock;
+    try {
+      lock = readLock(repo, name);
+    } catch {
+      continue;
+    }
+    if (lock) out.push({ name, lock });
+  }
+  return out;
+}
+
+export const fileSha = (repo, rel) => sha256(readFileSync(abs(repo, rel)));
+
+/**
+ * Replace any ANCESTOR directory of `rel` that is a symlink with a real
+ * directory, before writing into it.
+ *
+ * `mkdirSync(..., {recursive:true})` follows a symlinked ancestor, so writing a
+ * managed file under a path that is (or was) a link silently writes THROUGH it
+ * -- the content lands wherever the link points and the link survives, so the
+ * result looks fine from the plugin root. This bit on upgrade from the layout
+ * where `.claude-plugin/<name>/skills` linked into a shared pool: the new real
+ * skills were written into the old pool instead.
+ *
+ * Scoped to ancestors strictly inside the repo, and only those that are links.
+ */
+function replaceSymlinkAncestors(repo, rel, ops) {
+  const parts = rel.split("/").slice(0, -1);
+  for (let i = 1; i <= parts.length; i++) {
+    const dirRel = parts.slice(0, i).join("/");
+    const st = lstatSync(abs(repo, dirRel), { throwIfNoEntry: false });
+    if (st?.isSymbolicLink()) ops.removeSymlink(dirRel, "replacing a symlinked directory with real content");
+  }
+}
+
+function recordMissingDirs(repo, rel, createdDirs) {
+  const parts = rel.split("/").slice(0, -1);
+  for (let i = 1; i <= parts.length; i++) {
+    const dir = parts.slice(0, i).join("/");
+    if (!existsSync(abs(repo, dir)) && !createdDirs.includes(dir)) createdDirs.push(dir);
+  }
+}
+
+function removeEmptyDirs(repo, dirs, ops) {
+  for (const dir of [...dirs].sort((a, b) => b.split("/").length - a.split("/").length)) {
+    ops.rmdirIfEmpty(dir);
+  }
+}
+
+// Strip the lines this plugin's install added to a managed `.gitignore` (per
+// `ginfo` = one entry of a lock's `gitignore` map: {created, lines,
+// appended}), same convention as the TOML-block / displaced-content removal
+// elsewhere in this file: prefer stripping the exact byte-appended tail, fall
+// back to a line-by-line filter over the owned set. Any line NOT in
+// `ginfo.lines` (including a user's own pre-existing content) is left
+// untouched. Removes the file entirely when it was created by us and is now
+// empty. Returns whether anything changed on disk.
+function removeManagedGitignoreLines(repo, rel, ginfo, ops) {
+  const path = abs(repo, rel);
+  if (!existsSync(path)) return false;
+  const text = readFileSync(path, "utf8");
+  const appended = ginfo.appended;
+  const out =
+    typeof appended === "string" && text.endsWith(appended)
+      ? text.slice(0, text.length - appended.length)
+      : text
+          .split("\n")
+          .filter((l) => !new Set(ginfo.lines ?? []).has(l.trim()))
+          .join("\n");
+  if (ginfo.created && out.trim() === "") return ops.remove(rel, "gitignore lines removed (file now empty)");
+  return ops.write(rel, out, "gitignore lines removed");
+}
+
+// ---------------------------------------------------------------------------
+// enact-config.toml [extensions] — text-level only. The document is parsed
+// solely to refuse invalid TOML and to learn which extensions are declared; no
+// other table is read, and the document is never re-serialized.
+// ---------------------------------------------------------------------------
+
+function parseConfigText(text, action) {
+  try {
+    return TOML.parse(text);
+  } catch (err) {
+    throw new Error(`Cannot parse ${CONFIG_PATH} (${action}): ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/**
+ * `uninstall --purge` rule for `.opencode/`: OpenCode auto-generates
+ * `node_modules/`, `package.json`, `package-lock.json`, `bun.lock` and
+ * `.gitignore` there the first time it loads a project plugin (verified
+ * 2026-09-14, this session -- see OPENCODE_AUTOGEN_ENTRIES' doc comment).
+ * We never write those files ourselves (only `plugins/<name>.ts`, already
+ * removed by the managed-file removal loop above). Remove them ONLY when
+ * every remaining entry under `.opencode/` is one of OpenCode's own
+ * auto-generated names (and `plugins/`, if present, is now empty) --
+ * i.e. nothing user-owned is left that could be silently destroyed.
+ */
+function purgeOpenCodeAutogenIfClean(repo, ops) {
+  const dir = abs(repo, ".opencode");
+  if (!existsSync(dir)) return;
+  const entries = readdirSync(dir);
+  // `plugins/` and `skills/` are both OURS: the generated TS plugin and, since
+  // OpenCode is the only host whose plugin surface cannot carry skills, its
+  // flat skills directory. Both are emptied by the managed-file removal above,
+  // so an empty one is not user content -- but this check runs before
+  // removeEmptyDirs, so the now-empty directories are still on disk here.
+  // Recursive: removing our managed files leaves the skill directories behind
+  // as empty shells until removeEmptyDirs runs (after this), so a top-level
+  // listing would report them as user content. What matters is whether any FILE
+  // survives, not whether the directory is literally empty.
+  const hasAnyFile = (d) =>
+    existsSync(d) &&
+    readdirSync(d, { withFileTypes: true }).some((e) => (e.isDirectory() ? hasAnyFile(join(d, e.name)) : true));
+  const ourDirs = ["plugins", "skills"];
+  const notEmpty = ourDirs.filter((d) => hasAnyFile(join(dir, d)));
+  const leftover = entries.filter((e) => !ourDirs.includes(e) && !OPENCODE_AUTOGEN_ENTRIES.has(e));
+  if (leftover.length > 0 || notEmpty.length > 0) {
+    console.log(
+      `kept .opencode/ auto-generated files (user-owned content present: ${[...leftover, ...notEmpty.map((d) => `${d}/*`)].join(", ")})`,
+    );
+    return;
+  }
+  for (const e of entries) ops.removeDir(`.opencode/${e}`, "OpenCode auto-generated file (--purge)");
+  ops.rmdirIfEmpty(".opencode");
+  console.log(
+    "purged .opencode/ auto-generated files (node_modules/package.json/package-lock.json/bun.lock/.gitignore -- matched OpenCode's own auto-generated shape, nothing else present)",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// install
+// ---------------------------------------------------------------------------
+
+export function runRepoInstall(pluginRoot, options = {}) {
+  const repo = resolveRepoRoot(options.repo);
+  const force = options.force === true;
+  const dryRun = options.dryRun === true;
+  const actions = [];
+  const ops = makeFileOps(repo, dryRun, actions);
+  assertSupportedHookEvents(pluginRoot);
+  const bundle = readBundle(pluginRoot);
+  const hosts = parseRepoHosts(options.host, bundle.manifest);
+  if (hosts.length === 0) throw new Error(`Plugin ${bundle.name} targets no repo host (${REPO_HOSTS.join(", ")})`);
+  const plan = buildPlan(pluginRoot, bundle, hosts, repo);
+  // Other enact plugins already installed here. Ownership of a shared path is
+  // a question about ALL of them, not just this one -- see readSiblingLocks.
+  const siblings = readSiblingLocks(repo, bundle.name);
+  const prev = readLock(repo, bundle.name) ?? {
+    files: {},
+    merged: {},
+    toml: {},
+    gitignore: {},
+    symlinks: {},
+    config: null,
+    createdDirs: [],
+  };
+  const prevSymlinks = prev.symlinks ?? {};
+  const prevDisplaced = prev.displaced ?? { files: {}, json: {}, toml: {} };
+  // Originals displaced by a --force takeover of pre-existing foreign content,
+  // carried forward from the previous lock and extended below. Re-running
+  // install never overwrites an already-recorded original (see per-surface
+  // "already recorded" guards): the FIRST takeover is the only one that ever
+  // writes here. Uninstall restores exactly what is recorded here.
+  const displaced = {
+    files: { ...prevDisplaced.files },
+    json: Object.fromEntries(Object.entries(prevDisplaced.json ?? {}).map(([rel, m]) => [rel, { ...m }])),
+    toml: Object.fromEntries(Object.entries(prevDisplaced.toml ?? {}).map(([rel, spans]) => [rel, [...spans]])),
+  };
+
+  // -- preflight: enact-config.toml must be valid TOML before we append to it
+  const configExists = existsSync(abs(repo, CONFIG_PATH));
+  const configText = configExists ? readFileSync(abs(repo, CONFIG_PATH), "utf8") : null;
+  const configHasExtensions =
+    configExists && parseConfigText(configText, "refusing to append [extensions]").extensions !== undefined;
+  // -- preflight: the legacy `[skills]` marker is cut here, not carried. It
+  // refuses rather than guesses when the table is not the one install wrote,
+  // and it runs BEFORE any file is touched so a refusal leaves the repo
+  // untouched instead of half-installed.
+  const configLegacyCut = configExists ? cutLegacySkillsBlock(configText) : null;
+
+  // -- preflight: skills never overwrite a USER-AUTHORED skill dir (not even
+  // with --force). A dir owned by THIS plugin, or by any SIBLING plugin
+  // installed in the same repo, is fine: `.agents/skills/` is one flat pool
+  // shared across plugins by design, and bundles legitimately ship the same
+  // skill name (enact-repo and engineering share 23). Checking only `prev`
+  // made every sibling-owned dir look foreign, which refused the install with
+  // a false "non-managed" claim and advised deleting files another plugin
+  // depends on.
+  const skillConflicts = [...plan.skills]
+    .map((skill) => `${SHARED_SKILLS_DIR}/${skill}`)
+    .filter(
+      (dirRel) =>
+        existsSync(abs(repo, dirRel)) &&
+        !Object.keys(prev.files).some((f) => f.startsWith(`${dirRel}/`)) &&
+        !siblingOwnsPrefix(siblings, dirRel),
+    );
+  if (skillConflicts.length > 0) {
+    throw new Error(
+      `Refusing to overwrite existing user-authored skill dir(s); rename or remove them first:\n  ${skillConflicts.join("\n  ")}`,
+    );
+  }
+
+  // A sibling owning the SAME path with DIFFERENT bytes is the genuinely
+  // dangerous case, and it used to pass silently: skill files are forcedFiles,
+  // so plugin B simply overwrote plugin A's `handoff/SKILL.md` with an
+  // unrelated skill and nothing warned. `.agents/skills/` is flat on every host
+  // that reads it, so two plugins cannot ship different skills under one name.
+  // Refuse, and do NOT let --force through -- forcing would leave the other
+  // plugin's lock pointing at bytes it did not write.
+  // `.claude-plugin/marketplace.json` is excluded: it is a multi-plugin
+  // REGISTRY, so differing content there is expected and correct -- every
+  // plugin adds its own entry. It is still written as a whole file today, so
+  // the second install is refused by the ordinary foreign-content gate below;
+  // Phase 2 turns it into a merged surface keyed by `plugins[].name`. Listing
+  // it here would report a real collision with useless advice ("rename one").
+  const SHARED_CONTENT_EXEMPT = new Set([".claude-plugin/marketplace.json"]);
+  const divergent = [];
+  // Every repo-relative path this run changed, in write order. Declared HERE
+  // rather than beside the other `-- apply` locals because the stale-symlink
+  // sweep below already pushes to it, and that sweep has to run before any file
+  // is written. `const` further down put this in its temporal dead zone, so the
+  // sweep threw `Cannot access 'written' before initialization` on exactly the
+  // runs where it had a symlink to drop -- see install-stale-symlink-crash.test.mjs.
+  const written = [];
+  // BEFORE any file is written: drop a recorded symlink that is no longer in
+  // the plan. A managed directory that is still a symlink from an earlier
+  // layout would otherwise be FOLLOWED by the writes below -- the skills a
+  // plugin root should now own would land wherever the old link pointed, and
+  // the link would survive, so nothing looked wrong.
+  for (const rel of Object.keys(prevSymlinks)) {
+    if (plan.symlinks.has(rel)) continue;
+    if (ops.removeSymlink(rel, "symlink dropped out of plan")) written.push(rel);
+  }
+  for (const [rel, content] of plan.files) {
+    if (SHARED_CONTENT_EXEMPT.has(rel)) continue;
+    for (const { name: owner, lock } of siblings) {
+      const theirs = lock.files?.[rel]?.sha256;
+      if (theirs && theirs !== sha256(content)) divergent.push({ rel, owner });
+    }
+  }
+  if (divergent.length > 0) {
+    throw new Error(
+      `Refusing to install: another plugin already provides these paths with different content.\n` +
+        `Two plugins cannot ship different content under the same shared path.\n` +
+        divergent.map(({ rel, owner }) => `  ${rel} (installed by ${owner})`).join("\n") +
+        `\nRename one of them.`,
+    );
+  }
+
+  const edited = [];
+  const conflicts = [];
+  // Structured tracking (in parallel with the human-readable `conflicts`
+  // strings above) of exactly which foreign whole files / JSON keys a
+  // --force takeover is about to overwrite, so their original content can be
+  // captured before it's lost.
+  const foreignFileRels = new Set();
+  const foreignJsonKeys = [];
+
+  // -- preflight: whole managed files. `forcedFiles` (hooks/mcp/skills
+  // content, exclusively ours -- see file-header comment) is skipped
+  // entirely: drift or a stale pre-existing entry there is never a blocking
+  // conflict, just silently overwritten by the apply loop below.
+  for (const rel of new Set([...plan.files.keys(), ...Object.keys(prev.files)])) {
+    if (plan.forcedFiles.has(rel)) continue;
+    if (!existsSync(abs(repo, rel))) continue;
+    if (prev.files[rel]) {
+      // A derived file is regenerated from the declared set, so a sibling's
+      // install legitimately changed it since ours -- not drift.
+      if (!prev.files[rel].derived && fileSha(repo, rel) !== prev.files[rel].sha256) edited.push(rel);
+    } else if (siblingOwnersOf(siblings, rel).length > 0) {
+      // Owned by another installed extension, not by a user. Ownership is a
+      // question about every installed plugin, not just this one.
+    } else {
+      conflicts.push(`${rel} (file exists and is not managed by ${bundle.name})`);
+      foreignFileRels.add(rel);
+    }
+  }
+
+  // -- preflight: symlinks. The claude skills symlink is in the same
+  // owner-forced scope as `forcedFiles` above (skills content, exclusively
+  // generated by us) -- no preflight gate at all. `ops.symlink` in the apply
+  // phase below already replaces whatever it finds (a stale pre-symlink real
+  // directory, a wrong target, nothing) unconditionally.
+
+  // -- preflight: JSON merges
+  const jsonRels = [...new Set([...plan.json.keys(), ...Object.keys(prev.merged)])].sort();
+  const jsonDocs = new Map();
+  for (const rel of jsonRels) {
+    const path = abs(repo, rel);
+    const exists = existsSync(path);
+    const text = exists ? readFileSync(path, "utf8") : null;
+    const doc = exists ? readJsonStrict(path, rel) : {};
+    if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw new Error(`${rel} must contain a JSON object`);
+    jsonDocs.set(rel, { exists, text, doc });
+    // Hooks/mcp/plugin-enablement merges are owner-forced (see file-header
+    // comment): our own entries are always repaired to match the bundle on
+    // the write below, whether or not they drifted since the last install --
+    // never a preflight refusal, never gated behind --force.
+    const record = prev.merged[rel];
+    // Owned by US or by any SIBLING enact plugin. A key another installed
+    // extension wrote is not foreign: capturing it as a "displaced original"
+    // made uninstall RESTORE it instead of deleting it, so a shared
+    // registration key (`extraKnownMarketplaces.<marketplace>`) survived the
+    // last uninstall forever.
+    const ownedKeys = new Set([
+      ...(record?.entries ?? []).filter((e) => e.type === "key").map((e) => pathKey(e.path)),
+      ...siblings.flatMap(({ lock: l }) =>
+        (l.merged?.[rel]?.entries ?? []).filter((e) => e.type === "key").map((e) => pathKey(e.path)),
+      ),
+    ]);
+    for (const key of plan.json.get(rel)?.keys ?? []) {
+      if (getAt(doc, key.path) !== undefined && !ownedKeys.has(pathKey(key.path))) {
+        // A foreign entry sharing OUR key: taken over unconditionally below
+        // (captured into `displaced` for a byte-exact restore on uninstall,
+        // exactly like a --force takeover always has -- just without needing
+        // the flag). A user's OTHER keys are never touched by any of this.
+        foreignJsonKeys.push({ rel, dKey: pathKey(key.path) });
+      }
+    }
+  }
+
+  // -- preflight: TOML blocks. Same owner-forced scope as the JSON merges
+  // above (.codex/config.toml's mcp_servers block) -- no edited/conflict
+  // gating; `foreign` below still drives the unconditional takeover in the
+  // apply phase.
+  const tomlRels = [...new Set([...plan.toml.keys(), ...Object.keys(prev.toml)])].sort();
+  const tomlDocs = new Map();
+  for (const rel of tomlRels) {
+    const path = abs(repo, rel);
+    const exists = existsSync(path);
+    const text = exists ? readFileSync(path, "utf8") : "";
+    const found = findBlock(text, bundle.name);
+    let outside;
+    try {
+      outside = TOML.parse(found ? text.slice(0, found.start) + text.slice(found.stop) : text);
+    } catch (err) {
+      throw new Error(`Cannot parse ${rel}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const foreign = Object.keys(plan.toml.get(rel)?.tables ?? {}).filter((s) => outside.mcp_servers?.[s] !== undefined);
+    tomlDocs.set(rel, { exists, text, foreign });
+  }
+
+  const problems = [];
+  if (edited.length > 0) {
+    problems.push(
+      `Managed content was edited since the last install (re-run with --force to overwrite):\n  ${edited.join("\n  ")}`,
+    );
+  }
+  if (conflicts.length > 0) {
+    problems.push(
+      `Conflict with existing entries not owned by ${bundle.name} (re-run with --force to take them over):\n  ${conflicts.join("\n  ")}`,
+    );
+  }
+  if (problems.length > 0 && !force) throw new Error(problems.join("\n"));
+
+  // -- apply
+  const createdDirs = prev.createdDirs.filter((d) => existsSync(abs(repo, d)));
+  const writeRepoFile = (rel, content, reason) => {
+    replaceSymlinkAncestors(repo, rel, ops);
+    recordMissingDirs(repo, rel, createdDirs);
+    if (ops.write(rel, content, reason)) written.push(rel);
+  };
+  const removeRepoFile = (rel, reason) => {
+    if (ops.remove(rel, reason)) written.push(rel);
+  };
+
+  const files = {};
+  for (const rel of Object.keys(prev.files)) {
+    if (plan.files.has(rel) || !existsSync(abs(repo, rel))) continue;
+    // This managed file is dropping out of the plan (e.g. --host narrowed).
+    // If it took over foreign content, restore it instead of deleting it.
+    const displacedFile = displaced.files[rel];
+    if (displacedFile) {
+      const storedPath = abs(repo, displacedFile.storedAt);
+      if (!existsSync(storedPath)) throw new Error(`Missing recorded original for ${rel} at ${displacedFile.storedAt}`);
+      writeRepoFile(rel, readFileSync(storedPath));
+      removeRepoFile(displacedFile.storedAt);
+      delete displaced.files[rel];
+    } else {
+      removeRepoFile(rel);
+    }
+  }
+  // -- capture originals for whole files taking over pre-existing foreign
+  // content this run, BEFORE they get overwritten below. Never recapture: if
+  // an original is already recorded (from an earlier --force takeover), keep it.
+  for (const rel of foreignFileRels) {
+    if (displaced.files[rel]) continue;
+    const storedRel = `.agents/enact-repo-originals/${bundle.name}/${rel}`;
+    writeRepoFile(storedRel, readFileSync(abs(repo, rel)));
+    displaced.files[rel] = { storedAt: storedRel };
+  }
+  for (const [rel, content] of plan.files) {
+    writeRepoFile(rel, content);
+    files[rel] = { sha256: sha256(content), ...(plan.derivedFiles.has(rel) ? { derived: true } : {}) };
+  }
+
+  const symlinks = {};
+  for (const [rel, target] of plan.symlinks) {
+    recordMissingDirs(repo, rel, createdDirs);
+    if (ops.symlink(rel, target)) written.push(rel);
+    symlinks[rel] = { target, created: prevSymlinks[rel]?.created ?? true };
+  }
+
+  const merged = {};
+  for (const rel of jsonRels) {
+    const { exists, text, doc } = jsonDocs.get(rel);
+    const record = prev.merged[rel];
+    const want = plan.json.get(rel);
+    const format = exists ? detectJsonFormat(text) : { indent: "  ", trailingNewline: true };
+    const containers = [...(record?.containers ?? [])];
+    const scaffold = [...(record?.scaffold ?? [])];
+
+    if (!want) {
+      const relDisplaced = displaced.json[rel] ?? {};
+      removeJsonEntries(doc, { entries: record.entries, containers, scaffold }, relDisplaced);
+      delete displaced.json[rel];
+      if (!exists) continue;
+      if (record.created && Object.keys(doc).length === 0) removeRepoFile(rel);
+      else writeRepoFile(rel, serializeJson(doc, format));
+      continue;
+    }
+
+    const wanted = new Set([
+      ...want.keys.map((k) => `key${pathKey(k.path)}`),
+      ...want.items.map((i) => `item${pathKey(i.path)}${valueHash(i.value)}`),
+    ]);
+    const stale = (record?.entries ?? []).filter((e) =>
+      e.type === "key" ? !wanted.has(`key${pathKey(e.path)}`) : !wanted.has(`item${pathKey(e.path)}${e.sha256}`),
+    );
+    const relDisplaced = displaced.json[rel] ?? {};
+    removeJsonEntries(doc, { entries: stale }, relDisplaced);
+
+    const created = [];
+    for (const s of want.scaffold) {
+      if (getAt(doc, s.path) === undefined) doc[s.path[0]] = s.value;
+      // Recorded whether or not WE created it. Scaffold is shared repo-level
+      // framing (a marketplace's `name`/`owner`), so recording it only in the
+      // creator's lock left the LAST plugin out with nothing to prune: it
+      // removed its own entry, `plugins` emptied, and `{name, owner}` stayed
+      // behind forever in a marketplace listing no plugins. The prune is
+      // already conditional on nothing else remaining, so recording it in
+      // every owner's lock is safe.
+      if (!scaffold.some((x) => pathKey(x.path) === pathKey(s.path))) scaffold.push({ path: s.path });
+    }
+    const entries = [];
+    for (const key of want.keys) {
+      const parent = ensureContainer(doc, key.path.slice(0, -1), "object", created);
+      const k = key.path[key.path.length - 1];
+      const h = valueHash(key.value);
+      const dKey = pathKey(key.path);
+      const isTakeover = foreignJsonKeys.some((f) => f.rel === rel && f.dKey === dKey);
+      if (isTakeover && has(parent, k) && !has(relDisplaced, dKey)) relDisplaced[dKey] = parent[k];
+      if (!has(parent, k) || valueHash(parent[k]) !== h) parent[k] = key.value;
+      entries.push({ type: "key", path: key.path, sha256: h });
+    }
+    if (Object.keys(relDisplaced).length > 0) displaced.json[rel] = relDisplaced;
+    else delete displaced.json[rel];
+    for (const item of want.items) {
+      const arr = ensureContainer(doc, item.path, "array", created);
+      const h = valueHash(item.value);
+      if (!arr.some((v) => valueHash(v) === h)) arr.push(item.value);
+      entries.push({ type: "item", path: item.path, sha256: h });
+    }
+    // Containers WE created, plus any a sibling enact plugin recorded creating.
+    // Inheriting matters because the second plugin to write into a shared file
+    // creates nothing, so it recorded no container and left an empty `{}`
+    // behind when it uninstalled last. Recording a container the USER created
+    // would be worse -- uninstall would prune a key of theirs -- so this is
+    // deliberately limited to containers enact is known to have created.
+    const siblingContainers = siblings.flatMap(({ lock: l }) => l.merged?.[rel]?.containers ?? []);
+    for (const c of [...created, ...siblingContainers]) {
+      if (c.length > 0 && !containers.some((x) => pathKey(x) === pathKey(c))) containers.push(c);
+    }
+    writeRepoFile(rel, serializeJson(doc, format));
+    // `created` is inherited: if ANY installed enact plugin created this file,
+    // it is ours to remove once the last of us leaves. Recording only our own
+    // creation left the second plugin believing a user owned the file, so an
+    // empty `{}` stayed behind forever.
+    const createdByEnact =
+      record?.created ?? (!exists || siblings.some(({ lock: l }) => l.merged?.[rel]?.created === true));
+    merged[rel] = { created: createdByEnact, containers, scaffold, entries };
+  }
+
+  const toml = {};
+  for (const rel of tomlRels) {
+    const { exists, foreign } = tomlDocs.get(rel);
+    let { text } = tomlDocs.get(rel);
+    const record = prev.toml[rel];
+    const want = plan.toml.get(rel);
+
+    // Cut foreign tables sharing one of OUR managed server names, recording
+    // (byte-exact, incl. comments) any not already recorded from an earlier
+    // takeover -- unconditional (mcp is owner-forced), not gated by --force.
+    const displacedSpans = [...(displaced.toml[rel] ?? [])];
+    for (const s of foreign) {
+      const already = displacedSpans.some((d) => d.server === s);
+      const extracted = extractTomlTable(text, s);
+      text = extracted.text;
+      if (!already && extracted.removed) displacedSpans.push({ server: s, ...extracted.removed });
+    }
+
+    const current = findBlock(text, bundle.name);
+    if (!want) {
+      if (current) text = cutBlock(text, current, record?.prefix ?? "");
+      text = reinsertTomlSpans(text, displacedSpans);
+      delete displaced.toml[rel];
+      if (record?.created && text === "") removeRepoFile(rel);
+      else if (exists || displacedSpans.length > 0) writeRepoFile(rel, text);
+      continue;
+    }
+    if (displacedSpans.length > 0) displaced.toml[rel] = displacedSpans;
+    else delete displaced.toml[rel];
+
+    const block = renderTomlBlock(bundle.name, want.tables);
+    let prefix = record?.prefix ?? "";
+    if (current) {
+      text = text.slice(0, current.start) + block + text.slice(current.stop);
+    } else {
+      prefix = text.length === 0 ? "" : text.endsWith("\n") ? "\n" : "\n\n";
+      text = `${text}${prefix}${block}`;
+    }
+    try {
+      TOML.parse(text);
+    } catch (err) {
+      throw new Error(`Refusing to write invalid TOML to ${rel}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    writeRepoFile(rel, text);
+    toml[rel] = { created: record ? record.created : !exists, prefix, sha256: sha256(block) };
+  }
+
+  // Managed .gitignore files, keyed by repo-relative path:
+  //   .agents/.gitignore  keeps the repo-local lean-ctx runtime dirs
+  //                       (data/cache/state/bin) and the enact-hook logs out
+  //                       of git; the lean-ctx config/ dir stays committed.
+  //   .claude/.gitignore  keeps settings.local.json (absolute, machine-
+  //                       specific LEAN_CTX_*_DIR values) out of git.
+  // Only lines we actually add are ever recorded/owned — a line a user
+  // already has (even one of ours, verbatim) is left unclaimed and survives
+  // uninstall untouched.
+  const gitignore = { ...(prev.gitignore ?? {}) };
+  for (const rel of Object.keys(gitignore)) {
+    // A managed .gitignore that dropped out of the plan (e.g. --host narrowed
+    // away from claude): strip our lines, exactly as uninstall would.
+    if (plan.gitignore.has(rel)) continue;
+    if (removeManagedGitignoreLines(repo, rel, gitignore[rel], ops)) written.push(rel);
+    delete gitignore[rel];
+  }
+  for (const [rel, lines] of plan.gitignore) {
+    const path = abs(repo, rel);
+    const exists = existsSync(path);
+    const text = exists ? readFileSync(path, "utf8") : "";
+    const currentLines = new Set(text.split("\n").map((l) => l.trim()));
+    const missing = lines.filter((l) => !currentLines.has(l));
+    if (missing.length === 0) continue;
+    const prefix = text.length === 0 || text.endsWith("\n") ? "" : "\n";
+    const block = missing.map((l) => `${l}\n`).join("");
+    writeRepoFile(rel, `${text}${prefix}${block}`);
+    const owned = new Set([...(prev.gitignore?.[rel]?.lines ?? []), ...missing]);
+    // `appended` is the exact byte span (prefix + block) this run tacked onto
+    // the end of the file — lets uninstall strip it byte-exact (matching the
+    // TOML block / displaced-content restore convention elsewhere in this
+    // file) when nothing else touched the file afterward. Only reflects the
+    // MOST RECENT append; `lines` (the full owned set) is the correctness
+    // fallback if a later edit moved our lines away from the tail.
+    gitignore[rel] = {
+      created: prev.gitignore?.[rel]?.created ?? !exists,
+      lines: [...owned].sort(),
+      appended: `${prefix}${block}`,
+    };
+  }
+
+  // enact-config.toml — the managed-repo marker AND the declared extension
+  // roster. `[extensions]` is created (with `version = 1`) when missing and
+  // appended at text level when the file exists without it; this extension is
+  // then declared as its own `[extensions.<name>]` table. Both steps are
+  // computed IN MEMORY and written once: re-reading the file between them
+  // would make a dry-run plan differently from the real run, because the first
+  // write has not happened on disk yet. `appended` is the exact span we added,
+  // so `--purge` can cut only that.
+  let config;
+  {
+    let text;
+    // The legacy `[skills]` table is already gone from `base` when one was
+    // present; `configText` stays the ORIGINAL so the "did anything change"
+    // comparison below still sees the cut.
+    const base = configLegacyCut ?? configText;
+    if (!configExists) {
+      const appended = `\n${EXTENSIONS_BLOCK}`;
+      text = `${CONFIG_ROOT_CONTENT}${appended}`;
+      config = { created: true, appended };
+    } else if (!configHasExtensions) {
+      const appended = `${base.length === 0 ? "" : base.endsWith("\n") ? "\n" : "\n\n"}${EXTENSIONS_BLOCK}`;
+      text = `${base}${appended}`;
+      config = { created: prev.config?.created ?? false, appended };
+    } else {
+      text = base;
+      config = prev.config ?? { created: false, appended: null };
+    }
+    // Insert-once: null means already declared (or no [extensions] to write
+    // into), and an existing declaration is never rewritten -- see declareExtension.
+    const declared = declareExtension(text, bundle.name);
+    if (declared !== null) text = declared;
+    if (text !== configText) {
+      parseConfigText(text, "refusing to write invalid TOML");
+      writeRepoFile(CONFIG_PATH, text, `managed-repo marker with [extensions.${bundle.name}]`);
+    }
+  }
+
+  removeEmptyDirs(repo, createdDirs, ops);
+  recordMissingDirs(repo, lockRel(bundle.name), createdDirs);
+  const lock = {
+    lockVersion: LOCK_VERSION,
+    plugin: bundle.name,
+    version: bundle.version,
+    hosts,
+    files: sortObject(files),
+    symlinks: sortObject(symlinks),
+    merged: sortObject(merged),
+    toml: sortObject(toml),
+    gitignore: sortObject(gitignore),
+    config,
+    createdDirs: [...new Set(createdDirs)].filter((d) => d === ".agents" || existsSync(abs(repo, d))).sort(),
+    displaced: pruneDisplaced(displaced),
+  };
+  writeRepoFile(lockRel(bundle.name), `${JSON.stringify(lock, null, 2)}\n`, "install lock file");
+
+  const tag = dryRun ? "[dry-run] " : "";
+  console.log(`${tag}repo install ${bundle.name}@${bundle.version} -> ${repo} (hosts: ${hosts.join(", ")})`);
+  console.log(
+    written.length > 0 ? `${dryRun ? "would change" : "changed"} ${written.length} file(s)` : "up to date (no changes)",
+  );
+  // Live-testing finding (2026-09-14): even after trusting the folder, hooks
+  // and skills were observed NOT active in the very FIRST Claude Code
+  // session in this trusted folder (the newly-added extraKnownMarketplaces
+  // entry + enabledPlugins registers on that first launch, but does not
+  // finish activating in time for that same session) -- the SECOND session
+  // works. This matches Claude Code's own documented plugin-activation
+  // caveats (code.claude.com/docs/en/discover-plugins, "Apply plugin
+  // changes without restarting"). Told explicitly here so a user isn't left
+  // thinking the install failed.
+  if (hosts.includes("claude")) {
+    console.log(
+      "claude: the plugin loads after you trust this folder in Claude Code -- if hooks/skills are missing in that FIRST session, start a NEW Claude Code session in this folder (the marketplace registers on first launch; the second session has it active)",
+    );
+  }
+  if (hosts.includes("codex"))
+    console.log("codex: config and hooks load after you trust this project and review hooks (/hooks)");
+  if (hosts.includes("kimi"))
+    console.log("kimi: hooks are global-only (installed by enact-vps); no repo hook file written");
+  return { repo, name: bundle.name, version: bundle.version, hosts, changed: written, actions, dryRun };
+}
+
+// ---------------------------------------------------------------------------
+// uninstall
+// ---------------------------------------------------------------------------
+
+export function runRepoUninstall(name, options = {}) {
+  const repo = resolveRepoRoot(options.repo);
+  const force = options.force === true;
+  const dryRun = options.dryRun === true;
+  const actions = [];
+  const ops = makeFileOps(repo, dryRun, actions);
+  const lock = readLock(repo, name);
+  if (!lock) throw new Error(`${name} is not installed in ${repo} (no lock at ${lockRel(name)})`);
+  // Other plugins still installed here; their claims outlive this uninstall.
+  const siblings = readSiblingLocks(repo, name);
+
+  // Captured BEFORE the removal loop deletes the file: uninstalling one
+  // extension must leave a marketplace listing the ones that remain, so the
+  // surviving entries have to be read while they still exist.
+  const uninstallConfigPath = abs(repo, CONFIG_PATH);
+  const uninstallConfigText = existsSync(uninstallConfigPath) ? readFileSync(uninstallConfigPath, "utf8") : "";
+  const survivingMarketplace = (() => {
+    const p = abs(repo, MARKETPLACE_PATH);
+    if (!existsSync(p)) return null;
+    try {
+      const doc = JSON.parse(readFileSync(p, "utf8"));
+      const kept = (doc.plugins ?? []).filter((e) => e && e.name !== name);
+      return kept.length > 0 ? { ...doc, plugins: kept } : null;
+    } catch {
+      return null;
+    }
+  })();
+
+  const edited = [];
+  for (const [rel, record] of Object.entries(lock.files)) {
+    // Derived files are regenerated whenever the declared set changes -- a
+    // sibling's install or uninstall rewrites them legitimately, so a hash
+    // mismatch here is expected, not user damage.
+    if (record.derived) continue;
+    if (existsSync(abs(repo, rel)) && fileSha(repo, rel) !== record.sha256) edited.push(rel);
+  }
+  for (const [rel, record] of Object.entries(lock.symlinks ?? {})) {
+    // lstat, not existsSync: existsSync follows the link and would silently
+    // skip a dangling one instead of flagging that something is off.
+    const st = lstatSync(abs(repo, rel), { throwIfNoEntry: false });
+    if (st && !(st.isSymbolicLink() && readlinkSync(abs(repo, rel)) === record.target)) edited.push(rel);
+  }
+  const jsonDocs = new Map();
+  for (const [rel, record] of Object.entries(lock.merged)) {
+    const path = abs(repo, rel);
+    if (!existsSync(path)) {
+      edited.push(`${rel} (file removed)`);
+      continue;
+    }
+    const text = readFileSync(path, "utf8");
+    const doc = readJsonStrict(path, rel);
+    for (const entry of record.entries) {
+      // An entry a SIBLING also records is shared registration, not drift:
+      // both plugins legitimately claim `extraKnownMarketplaces.<marketplace>`
+      // and the marketplace's own `name`/`owner`. Whichever uninstalls first
+      // removes it, and the second must not then report it as edited -- that
+      // read the shared state as damage and refused the uninstall outright.
+      if (siblingRecordsJsonEntry(siblings, rel, entry)) continue;
+      if (!entryPresent(doc, entry)) edited.push(`${rel} (${entry.path.join(".")})`);
+    }
+    jsonDocs.set(rel, { text, doc });
+  }
+  for (const [rel, record] of Object.entries(lock.toml)) {
+    const path = abs(repo, rel);
+    const found = existsSync(path) ? findBlock(readFileSync(path, "utf8"), name) : null;
+    if (!found || sha256(found.block) !== record.sha256) edited.push(rel);
+  }
+  // --purge cuts our [extensions] block from enact-config.toml; plan it up front so
+  // an edited block is refused like any other edited managed content.
+  let configCut = null;
+  if (options.purge && typeof lock.config?.appended === "string" && existsSync(abs(repo, CONFIG_PATH))) {
+    const text = readFileSync(abs(repo, CONFIG_PATH), "utf8");
+    configCut = cutExtensionsBlock(text, lock.config.appended);
+    if (configCut === null) edited.push(`${CONFIG_PATH} ([extensions] block edited since install)`);
+  }
+  if (edited.length > 0 && !force) {
+    throw new Error(
+      `Managed content was edited since install (re-run with --force to remove anyway):\n  ${edited.join("\n  ")}`,
+    );
+  }
+
+  // Originals displaced by a --force takeover during install; restored below
+  // instead of being dropped along with the rest of the managed content.
+  const lockDisplaced = lock.displaced ?? { files: {}, json: {}, toml: {} };
+
+  for (const rel of Object.keys(lock.files)) {
+    // Reference counting: a path another installed plugin still claims is not
+    // ours to delete. Bundles ship byte-identical skills (cmux-send,
+    // cmux-leader and remove-deadcode are identical across bundles today), so
+    // without this, uninstalling one plugin silently removes a skill a
+    // surviving plugin's lock still points at -- which its doctor then reports
+    // as a missing managed file.
+    const alsoOwnedBy = siblingOwnersOf(siblings, rel);
+    if (alsoOwnedBy.length > 0) {
+      ops.skip?.(rel, `still owned by ${alsoOwnedBy.join(", ")}`);
+      continue;
+    }
+    const displacedFile = lockDisplaced.files[rel];
+    if (displacedFile) {
+      const storedPath = abs(repo, displacedFile.storedAt);
+      if (!existsSync(storedPath)) throw new Error(`Missing recorded original for ${rel} at ${displacedFile.storedAt}`);
+      ops.write(rel, readFileSync(storedPath), "restoring pre-install original content");
+      ops.remove(displacedFile.storedAt, "captured original no longer needed");
+    } else {
+      ops.remove(rel, "managed file");
+    }
+  }
+  for (const rel of Object.keys(lock.symlinks ?? {})) {
+    ops.removeSymlink(rel, "managed symlink");
+  }
+  // Put the marketplace back if other extensions are still declared. The
+  // removal loop above deleted it as one of our managed files; regenerating it
+  // from the survivors is what keeps the remaining plugins loadable.
+  if (survivingMarketplace) {
+    ops.write(
+      MARKETPLACE_PATH,
+      `${JSON.stringify(survivingMarketplace, null, 2)}\n`,
+      `marketplace regenerated without ${name}`,
+    );
+  }
+  // Undeclare this extension: remove its own `[extensions.<name>]` table. The
+  // `[extensions]` root table is cut only by --purge, and only once no other
+  // extension is declared.
+  if (uninstallConfigText.length > 0) {
+    const next = removeExtensionBlock(uninstallConfigText, name);
+    if (next !== uninstallConfigText) {
+      parseConfigText(next, "refusing to write invalid TOML");
+      ops.write(CONFIG_PATH, next, `undeclared [extensions.${name}]`);
+    }
+  }
+  for (const [rel, record] of Object.entries(lock.merged)) {
+    if (!jsonDocs.has(rel)) continue;
+    const { text, doc } = jsonDocs.get(rel);
+    // Reference counting, same law as managed files: an entry a sibling still
+    // records is shared repo-level registration, not ours to delete. Without
+    // this the FIRST uninstall removed `extraKnownMarketplaces.<marketplace>`
+    // and the marketplace's `name`/`owner`, leaving the surviving plugin
+    // unregistered -- and its own uninstall then refused, reporting the
+    // missing shared entry as drift.
+    const retained = record.entries.filter((e) => siblingRecordsJsonEntry(siblings, rel, e));
+    const ours = { ...record, entries: record.entries.filter((e) => !retained.includes(e)) };
+    for (const e of retained) ops.skip(`${rel} (${e.path.join(".")})`, "still registered by another installed plugin");
+    removeJsonEntries(doc, ours, { ...(lockDisplaced.json[rel] ?? {}) });
+    // Remove only a file WE created -- never one the user already had, even if
+    // our entries were the last thing in it. `created` is inherited across
+    // siblings at install time (see below), so the second plugin to write a
+    // shared file still knows enact created it and can clean it up when it is
+    // the last one out.
+    if (record.created && Object.keys(doc).length === 0) ops.remove(rel, "json merge file (now empty)");
+    else ops.write(rel, serializeJson(doc, detectJsonFormat(text)), "json merge entries removed");
+  }
+  for (const [rel, record] of Object.entries(lock.toml)) {
+    const path = abs(repo, rel);
+    if (!existsSync(path)) continue;
+    const text = readFileSync(path, "utf8");
+    const found = findBlock(text, name);
+    if (!found) continue;
+    const out = reinsertTomlSpans(cutBlock(text, found, record.prefix), lockDisplaced.toml[rel] ?? []);
+    if (record.created && out === "") ops.remove(rel, "toml block removed (file now empty)");
+    else ops.write(rel, out, "toml mcp_servers block removed");
+  }
+  // Whether this uninstall must leave managed content behind that only
+  // `--purge` can remove: the lean-ctx runtime dirs AND the enact-hook log
+  // files (both our own runtime's state, never user data) are still
+  // present, so the `.agents/.gitignore` lines hiding them from git must
+  // stay too (removing them would surface those paths as untracked in
+  // `git status`).
+  //
+  // Only `.agents/.gitignore` is ever retained: it is the one hiding that
+  // runtime state. Every other managed .gitignore (today: `.claude/.gitignore`,
+  // hiding settings.local.json) has its lines stripped unconditionally, and
+  // the file itself goes when we created it and nothing else is left in it.
+  const lockGitignore = lock.gitignore ?? {};
+  for (const [rel, ginfo] of Object.entries(lockGitignore)) {
+    if (rel === GITIGNORE_PATH) continue;
+    removeManagedGitignoreLines(repo, rel, ginfo, ops);
+  }
+  let retainedGitignore = false;
+  if (lockGitignore[GITIGNORE_PATH]) {
+    const presentRuntimeDirs = LEAN_CTX_RUNTIME_DIRS.filter((rel) => existsSync(abs(repo, rel)));
+    const presentHookLogFiles = HOOK_LOG_FILES.filter((rel) => existsSync(abs(repo, rel)));
+    if (options.purge) {
+      // Runtime state OUR OWN runtime created (not user data): safe to
+      // remove outright, before the gitignore lines that were hiding it.
+      for (const rel of presentRuntimeDirs) ops.removeDir(rel, "lean-ctx runtime dir (--purge)");
+      for (const rel of presentHookLogFiles) ops.remove(rel, "enact-hook log file (--purge)");
+    }
+    const presentRuntimePaths = [...presentRuntimeDirs, ...presentHookLogFiles];
+    retainedGitignore = !options.purge && presentRuntimePaths.length > 0;
+    if (retainedGitignore) {
+      const kept = [
+        GITIGNORE_PATH,
+        ...(typeof lock.config?.appended === "string" ? [`${CONFIG_PATH} [extensions]`] : []),
+      ];
+      console.log(
+        `kept ${kept.join(" and ")} -- lean-ctx runtime dirs / enact-hook log files still present (${presentRuntimePaths.join(", ")}); re-run uninstall --purge to remove them too`,
+      );
+    } else {
+      removeManagedGitignoreLines(repo, GITIGNORE_PATH, lockGitignore[GITIGNORE_PATH], ops);
+    }
+  }
+
+  if (options.purge || !retainedGitignore) {
+    ops.remove(lockRel(name), "uninstall lock file");
+  } else {
+    // Something above is still waiting on `--purge`: rewrite the SAME lock
+    // file (same path, same schema) down to a minimal residual -- no
+    // managed files/json/toml left (those were already fully removed
+    // above), just the gitignore/config bookkeeping a later STANDALONE
+    // `uninstall --purge` call needs in order to find and finish the job.
+    // This is what makes the printed "re-run uninstall --purge" message
+    // above actually true: readLock() at the top of that later call will
+    // find this file (and see it as belonging to `name`), not nothing --
+    // this is the fix for the bug where a plain uninstall unconditionally
+    // deleted the lock even while retaining content, so a follow-up
+    // `uninstall --purge` had nothing to read and refused with "not
+    // installed ... (no lock)". `install` re-run against this residual
+    // lock adopts `gitignore`/`config`/`createdDirs` from it unchanged
+    // (see `runRepoInstall`'s `prev = readLock(...) ?? {...}`) and
+    // overwrites it with a full lock again -- idempotent either way.
+    const residual = {
+      lockVersion: LOCK_VERSION,
+      plugin: name,
+      version: lock.version,
+      hosts: [],
+      files: {},
+      symlinks: {},
+      merged: {},
+      toml: {},
+      // Only the still-retained `.agents/.gitignore` record: every other
+      // managed .gitignore was already stripped above, so a later standalone
+      // `--purge` must not try to strip it a second time.
+      gitignore: { [GITIGNORE_PATH]: lockGitignore[GITIGNORE_PATH] },
+      config: lock.config,
+      createdDirs: lock.createdDirs,
+      displaced: { files: {}, json: {}, toml: {} },
+    };
+    ops.write(
+      lockRel(name),
+      `${JSON.stringify(residual, null, 2)}\n`,
+      "residual lock (gitignore/config retained pending --purge)",
+    );
+  }
+
+  if (options.purge) {
+    if (configCut !== null) {
+      if (lock.config.created && configCut.trim() === CONFIG_ROOT_CONTENT.trim()) {
+        ops.remove(CONFIG_PATH, "managed-repo marker created by install ([extensions] removed, only version = 1 left)");
+      } else {
+        ops.write(CONFIG_PATH, configCut, "[extensions] block removed (--purge)");
+      }
+    } else if (typeof lock.config?.appended === "string" && existsSync(abs(repo, CONFIG_PATH))) {
+      console.log(`kept ${CONFIG_PATH} [extensions] block (edited since install; --force never cuts an edited block)`);
+    } else if (existsSync(abs(repo, CONFIG_PATH))) {
+      console.log(`kept ${CONFIG_PATH} (install did not write its [extensions] block)`);
+    }
+    purgeOpenCodeAutogenIfClean(repo, ops);
+  }
+  removeEmptyDirs(repo, lock.createdDirs, ops);
+  console.log(`${dryRun ? "[dry-run] " : ""}repo uninstall ${name} <- ${repo}${options.purge ? " (purged)" : ""}`);
+  return { repo, name, removedFiles: Object.keys(lock.files).length, actions, dryRun };
+}