npm - @amsterdamdatalabs/enact-extensions - Versions diffs - 0.1.37 → 0.1.47 - Mend

@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (577) hide show

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

@@ -0,0 +1,1579 @@
+/**
+ * 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,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  rmdirSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import * as TOML from "@iarna/toml";
+import {
+  applyHostFlagToHooksDoc,
+  assertSupportedHookEvents,
+  clampHookTimeoutsForHost,
+  deriveOpenCodePlugin,
+  materializeCodexSkillMetadata,
+  MANIFEST_BY_PLATFORM,
+  EXTENSIONS_BLOCK,
+  blockMarkers,
+  cutExtensionsBlock,
+  declaredExtensionsFrom,
+  extensionBlock,
+  removeExtensionBlock,
+  upsertExtensionBlock,
+  cutBlock,
+  ensureContainer,
+  extractTomlTable,
+  findBlock,
+  makeFileOps,
+  reinsertTomlSpans,
+  renderTomlBlock,
+  siblingOwnersOf,
+  siblingOwnsPrefix,
+  siblingRecordsJsonEntry,
+  entryPresent,
+  getAt,
+  pathKey,
+  removeJsonEntries,
+  valueHash,
+  projectClaudePluginRoot,
+  projectPluginRoot,
+  projectCursorHooks,
+  unmappedCursorHookEvents,
+  unmappedCursorHookMatchers,
+} 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 [skills]. We never parse or rewrite anyone else's table: the
+// [skills] 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.prototype.hasOwnProperty.call(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
+// ---------------------------------------------------------------------------
+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 (repo === realpathSync(homedir())) {
+    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 `[skills].extensions`. 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 [skills] — text-level only. The document is parsed solely
+// to refuse invalid TOML and to learn whether OUR `skills` key exists; 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: 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 = [];
+  // 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 written = [];
+  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;
+    if (!configExists) {
+      const appended = `\n${EXTENSIONS_BLOCK}`;
+      text = `${CONFIG_ROOT_CONTENT}${appended}`;
+      config = { created: true, appended };
+    } else if (!configHasExtensions) {
+      const appended = `${configText.length === 0 ? "" : configText.endsWith("\n") ? "\n" : "\n\n"}${EXTENSIONS_BLOCK}`;
+      text = `${configText}${appended}`;
+      config = { created: prev.config?.created ?? false, appended };
+    } else {
+      text = configText;
+      config = prev.config ?? { created: false, appended: null };
+    }
+    const declared = upsertExtensionBlock(text, bundle.name, bundle.version);
+    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 remainingExtensions = readDeclaredExtensions(uninstallConfigText).filter((n) => n !== name);
+  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 [skills] 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} [skills]`] : [])];
+      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 ([skills] removed, only version = 1 left)");
+      } else {
+        ops.write(CONFIG_PATH, configCut, "[skills] block removed (--purge)");
+      }
+    } else if (typeof lock.config?.appended === "string" && existsSync(abs(repo, CONFIG_PATH))) {
+      console.log(`kept ${CONFIG_PATH} [skills] 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 [skills] 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 };
+}