@amsterdamdatalabs/enact-extensions 0.1.55 → 0.1.57

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

@@ -1,11 +1,9 @@
 /**
  * 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.
+ * Rebuilds a bundle's declared repo-local roots from source as COMMITTED,
+ * RELATIVE files. It runs only in a repository already marked by root
+ * `enact-config.toml`; enrollment is deliberately a separate concern.
  *
  * Every host receives only its native project files:
  *   claude   — `.claude/agents`, `.claude/skills`, `.mcp.json`, and hooks in
@@ -17,84 +15,39 @@
  *   kimi     — `.kimi-code/agents`, `.kimi-code/skills`, and `.kimi-code/mcp.json`.
  *              Kimi hooks remain global-only and are not owned here.
  *   opencode — `.opencode/agents`, `.opencode/skills`, and `opencode.json` MCP.
- *              OpenCode has no native project hook surface, so a hook-bearing
- *              bundle fails before writes and names enact-vps' global plugin path.
+ *              Its process-level hook carrier is global, while this installer
+ *              owns every repo-local artifact and legacy-root migration.
  *
  * Repo installation never writes a plugin root, marketplace, or plugin
  * registration. Those belong exclusively to explicit global installation.
  *
- * 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): merged hooks and MCP entries are always repaired.
- * Direct native agent and skill files are lock-owned files: user collisions
- * fail loudly and the lock makes uninstall remove only this bundle's files.
- *
- * Two kinds:
- *   - Whole files in host-native agent/skill locations, which are conflict
- *     checked and recorded as 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` gates native whole-file drift and baseline lean-ctx config files
- * (`.agents/lean-ctx/config/lean-ctx/*.toml`), preserving displaced content
- * for byte-exact restoration on uninstall.
- * 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.
+ * State: `.agents/<name>.lock.json` records the exact projected files plus
+ * the owned-root map. User/foreign/drifted content in an owned root is not
+ * retained: the next reconciliation deletes it and recreates the canonical
+ * projection. Explicit runtime boundaries
+ * under `.agents/` are the sole exception and are owned by their writers.
  */
 import { createHash } from "node:crypto";
-import {
-  existsSync,
-  lstatSync,
-  mkdtempSync,
-  readdirSync,
-  readFileSync,
-  readlinkSync,
-  realpathSync,
-  rmSync,
-  statSync,
-} from "node:fs";
+import { existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, 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,
   deriveOpenCodeMcp,
   EXTENSIONS_BLOCK,
-  ensureContainer,
-  entryPresent,
-  extractTomlTable,
-  findBlock,
-  getAt,
   makeFileOps,
   materializeCodexSkillMetadata,
-  pathKey,
   projectCursorHooks,
   projectNativeAgentsDir,
-  reinsertTomlSpans,
   removeExtensionBlock,
-  removeJsonEntries,
   renderTomlBlock,
-  siblingOwnersOf,
-  siblingOwnsPrefix,
-  siblingRecordsJsonEntry,
   unmappedCursorHookEvents,
   unmappedCursorHookMatchers,
-  valueHash,
 } from "../../dist/index.js";
 
 export const REPO_HOSTS = ["claude", "codex", "cursor", "kimi", "opencode"];
@@ -112,10 +65,66 @@ const HOST_AGENTS_DIR = {
   kimi: ".kimi-code/agents",
   opencode: ".opencode/agents",
 };
+/**
+ * Inspect only enact-extensions' own TOML table as text.
+ *
+ * `enact-config.toml` is shared: accepting or rejecting it based on a parser
+ * that reads `[hooks]`, `[controls]`, or another owner's syntax would make us
+ * an accidental validator for that owner.  This deliberately limited scanner
+ * recognises our headers and the basic `key = value` shape inside them; every
+ * other table is an opaque boundary.
+ */
+export function inspectExtensionsScope(configText, action = "reading [extensions]") {
+  if (typeof configText !== "string") throw new Error(`Cannot inspect ${CONFIG_PATH} (${action}): expected text`);
+  const declarations = [];
+  let present = false;
+  let inScope = false;
+  let table = null;
+  for (const [index, line] of configText.split("\n").entries()) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("[")) {
+      if (trimmed === "[extensions]") {
+        if (present)
+          throw new Error(
+            `Invalid [extensions] scope in ${CONFIG_PATH} (${action}): duplicate [extensions] at line ${index + 1}`,
+          );
+        present = true;
+        inScope = true;
+        table = "root";
+        continue;
+      }
+      if (trimmed.startsWith("[extensions")) {
+        const match = /^\[extensions\.([A-Za-z0-9][A-Za-z0-9_-]*)\]$/.exec(trimmed);
+        if (!match || !present) {
+          throw new Error(
+            `Invalid [extensions] scope in ${CONFIG_PATH} (${action}): malformed header at line ${index + 1}`,
+          );
+        }
+        declarations.push(match[1]);
+        inScope = true;
+        table = "declaration";
+        continue;
+      }
+      // An unrelated header ends our table span.  Its syntax and contents are
+      // owned elsewhere and intentionally never inspected here.
+      inScope = false;
+      table = null;
+      continue;
+    }
+    if (!inScope || trimmed === "" || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0 || trimmed.slice(eq + 1).trim() === "") {
+      throw new Error(
+        `Invalid [extensions] scope in ${CONFIG_PATH} (${action}): malformed ${table ?? "table"} entry at line ${index + 1}`,
+      );
+    }
+  }
+  return { present, declarations };
+}
+
 /** 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]"));
+  return inspectExtensionsScope(configText).declarations;
 }
 // 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
@@ -127,10 +136,8 @@ 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.
+// the runtime's own state -- never written, removed, or restored by this
+// installer. They are explicit unmanaged boundaries during root rebuild.
 export const HOOK_LOG_FILES = ["hooks.log", "hooks-activity.log"].map((f) => `.agents/hooks/${f}`);
 
 // ---------------------------------------------------------------------------
@@ -158,12 +165,8 @@ const LEAN_CTX_DIRS = [
 // 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.
+// Runtime dirs are never part of the projection. They remain explicit
+// unmanaged boundaries during install and both uninstall modes.
 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/`).
@@ -177,26 +180,13 @@ const GITIGNORE_LINES = [
 // `.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. We never write these;
-// `--purge` removes them only when no user-owned content remains under
-// `.opencode/` after the lock-owned native files are removed.
-const OPENCODE_AUTOGEN_ENTRIES = new Set([
-  "node_modules",
-  "package.json",
-  "package-lock.json",
-  "bun.lock",
-  ".gitignore",
-]);
 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("/"));
 
@@ -219,15 +209,6 @@ function listFilesRecursive(root, rel = "") {
   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)
@@ -236,15 +217,6 @@ function sortObject(obj) {
   );
 }
 
-// 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
 // ---------------------------------------------------------------------------
@@ -358,8 +330,8 @@ export function readBundle(pluginRoot) {
 // ---------------------------------------------------------------------------
 // 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
+//   json   Map<rel, {scaffold, keys, items}>        canonical JSON file content
+//   toml   Map<rel, {tables}>                       canonical TOML file content
 // ---------------------------------------------------------------------------
 
 function jsonMerge(plan, rel) {
@@ -507,11 +479,6 @@ const HOST_ADAPTERS = {
   },
 
   opencode(plan, bundle, pluginRoot) {
-    if (bundle.hooks) {
-      throw new Error(
-        "OpenCode repo-local installation cannot install hooks: install the explicit global OpenCode plugin through enact-vps first",
-      );
-    }
     addNativeAgents(plan, pluginRoot, "opencode");
     addNativeSkills(plan, bundle, "opencode");
     const mcp = jsonMerge(plan, "opencode.json");
@@ -532,8 +499,7 @@ export function buildPlan(pluginRoot, bundle, hosts, repo) {
     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.
+    // File content is always materialized from the canonical bundle.
     forcedFiles: new Set(),
     // Files regenerated from a source of truth. They are exempt from uninstall
     // drift checks when a sibling can legitimately rewrite them.
@@ -563,11 +529,189 @@ export function buildPlan(pluginRoot, bundle, hosts, repo) {
 }
 
 // ---------------------------------------------------------------------------
-// JSON merge helpers
+// authoritative repo-root reconciliation
 // ---------------------------------------------------------------------------
 
+function jsonValue(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function assignJsonPath(doc, path, value) {
+  let at = doc;
+  for (const key of path.slice(0, -1)) {
+    if (!at[key] || typeof at[key] !== "object" || Array.isArray(at[key])) at[key] = {};
+    at = at[key];
+  }
+  at[path.at(-1)] = jsonValue(value);
+}
+
+/** Build the exact native files from the bundle, without reading a repo file. */
+function materializeAuthoritativeFiles(plan, bundle) {
+  const files = new Map(plan.files);
+  for (const [rel, merge] of plan.json) {
+    const doc = {};
+    for (const entry of merge.scaffold) assignJsonPath(doc, entry.path, entry.value);
+    for (const entry of merge.keys) assignJsonPath(doc, entry.path, entry.value);
+    for (const entry of merge.items) {
+      let at = doc;
+      for (const key of entry.path.slice(0, -1)) {
+        if (!at[key] || typeof at[key] !== "object" || Array.isArray(at[key])) at[key] = {};
+        at = at[key];
+      }
+      const key = entry.path.at(-1);
+      if (!Array.isArray(at[key])) at[key] = [];
+      at[key].push(jsonValue(entry.value));
+    }
+    files.set(rel, Buffer.from(`${JSON.stringify(doc, null, 2)}\n`));
+  }
+  for (const [rel, toml] of plan.toml) files.set(rel, Buffer.from(renderTomlBlock(bundle.name, toml.tables)));
+  for (const [rel, lines] of plan.gitignore) files.set(rel, Buffer.from(`${lines.join("\n")}\n`));
+  return files;
+}
+
+function rootForHost(host) {
+  return host === "kimi" ? ".kimi-code" : `.${host}`;
+}
+
+function isBoundaryOrAncestor(rel, boundaries) {
+  return boundaries.some(
+    (boundary) => boundary === rel || boundary.startsWith(`${rel}/`) || rel.startsWith(`${boundary}/`),
+  );
+}
+
+function clearOwnedRoot(repo, root, boundaries, ops) {
+  const rootPath = abs(repo, root);
+  const rootState = lstatSync(rootPath, { throwIfNoEntry: false });
+  if (!rootState) return;
+  if (!rootState.isDirectory() || rootState.isSymbolicLink()) {
+    ops.removeSymlink(root, "replacing non-directory owned root");
+    return;
+  }
+  if (boundaries.length === 0) {
+    ops.removeDir(root, "rebuilding authoritative owned root");
+    return;
+  }
+  const visit = (rel) => {
+    const path = abs(repo, rel);
+    const state = lstatSync(path, { throwIfNoEntry: false });
+    if (!state) return;
+    // A boundary is entirely outside this deployment.  Do not descend into it:
+    // logs/caches are owned by their runtime, not by this installer.
+    if (boundaries.some((boundary) => rel === boundary || rel.startsWith(`${boundary}/`))) return;
+    if (!state.isDirectory() || state.isSymbolicLink()) {
+      ops.remove(rel, "removing stale content from authoritative owned root");
+      return;
+    }
+    if (!isBoundaryOrAncestor(rel, boundaries)) {
+      ops.removeDir(rel, "rebuilding authoritative owned root");
+      return;
+    }
+    for (const entry of readdirSync(path, { withFileTypes: true })) visit(`${rel}/${entry.name}`);
+    ops.rmdirIfEmpty(rel);
+  };
+  for (const entry of readdirSync(rootPath, { withFileTypes: true })) visit(`${root}/${entry.name}`);
+  ops.rmdirIfEmpty(root);
+}
+
+function assertMarkedRepo(repo) {
+  const configPath = abs(repo, CONFIG_PATH);
+  // `existsSync` follows a symlink.  The central marker is a repo-root
+  // ownership boundary, so following one could make text surgery mutate a
+  // config owned outside this checkout.  Inspect the directory entry itself
+  // before any read or write.
+  const state = lstatSync(configPath, { throwIfNoEntry: false });
+  if (!state) {
+    throw new Error(
+      `Refusing to reconcile unmarked repository ${repo}: ${CONFIG_PATH} is the required central-management marker`,
+    );
+  }
+  if (!state.isFile() || state.isSymbolicLink()) {
+    throw new Error(
+      `Refusing to reconcile repository ${repo}: root ${CONFIG_PATH} must be a regular, non-symlink file`,
+    );
+  }
+  inspectExtensionsScope(readFileSync(configPath, "utf8"), "checking central-management marker");
+}
+
+function runAuthoritativeRepoInstall(pluginRoot, options, context) {
+  const { repo, bundle, hosts, plan, prev, siblings, ops, actions, dryRun } = context;
+  if (siblings.length > 0) {
+    throw new Error(
+      `Refusing incomplete authoritative reconciliation: ${bundle.name} cannot rebuild shared owned roots while sibling locks exist (${siblings.map(({ name }) => name).join(", ")})`,
+    );
+  }
+
+  // A reconciliation owns the complete declared component surface, not just
+  // the hosts selected for this invocation.  Otherwise a previous host's
+  // root would become an accidental preservation zone when the host list is
+  // narrowed.
+  const roots = new Set(OWNED_REPO_ROOTS);
+  const desired = materializeAuthoritativeFiles(plan, bundle);
+  for (const root of roots) {
+    const boundaries = UNMANAGED_RUNTIME_BOUNDARIES.filter((path) => path.startsWith(`${root}/`));
+    clearOwnedRoot(repo, root, boundaries, ops);
+  }
+  for (const root of RETIRED_REPO_ROOTS) ops.removeDir(root, "retired Enact plugin root");
+
+  // Root-level native config is also wholly generated.  enact-config.toml is
+  // intentionally excluded: only its [extensions] table belongs to us.
+  for (const rel of [".mcp.json", "opencode.json"]) {
+    if (desired.has(rel)) ops.remove(rel, "rebuilding authoritative owned file");
+  }
+
+  const files = {};
+  for (const [rel, content] of desired) {
+    replaceSymlinkAncestors(repo, rel, ops);
+    ops.write(rel, content, "authoritative bundle projection");
+    files[rel] = { sha256: sha256(content) };
+  }
+
+  // This is the single partial-file boundary in the ownership map.  The
+  // document marker pre-existed (assertMarkedRepo), and text surgery touches
+  // only the table owned by enact-extensions.
+  const originalConfig = readFileSync(abs(repo, CONFIG_PATH), "utf8");
+  const base = cutLegacySkillsBlock(originalConfig) ?? originalConfig;
+  let config = prev.config ?? { created: false, appended: null };
+  let nextConfig = base;
+  if (!inspectExtensionsScope(nextConfig, "reading [extensions]").present) {
+    const appended = `${nextConfig.length === 0 ? "" : nextConfig.endsWith("\n") ? "\n" : "\n\n"}${EXTENSIONS_BLOCK}`;
+    nextConfig += appended;
+    config = { created: false, appended };
+  }
+  const declared = declareExtension(nextConfig, bundle.name);
+  if (declared !== null) nextConfig = declared;
+  if (nextConfig !== originalConfig)
+    ops.write(CONFIG_PATH, nextConfig, `managed-repo marker with [extensions.${bundle.name}]`);
+
+  const lock = {
+    lockVersion: LOCK_VERSION,
+    plugin: bundle.name,
+    version: bundle.version,
+    hosts,
+    files: sortObject(files),
+    symlinks: {},
+    toml: {},
+    gitignore: {},
+    config,
+    createdDirs: [],
+    ownedRoots: [...roots].sort(),
+    unmanagedBoundaries: UNMANAGED_RUNTIME_BOUNDARIES,
+  };
+  ops.write(lockRel(bundle.name), `${JSON.stringify(lock, null, 2)}\n`, "authoritative install lock file");
+  console.log(
+    `${dryRun ? "[dry-run] " : ""}repo install ${bundle.name}@${bundle.version} -> ${repo} (authoritative roots: ${[...roots].join(", ")})`,
+  );
+  if (options.force === true) {
+    console.log(`${dryRun ? "[dry-run] " : ""}force: authoritative repair requested; no owned content is preserved`);
+  }
+  if (hosts.includes("claude")) {
+    console.log("claude: trust this folder and review its project hooks before using the installed agents and skills");
+  }
+  return { repo, name: bundle.name, version: bundle.version, hosts, changed: actions, actions, dryRun };
+}
+
 // ---------------------------------------------------------------------------
-// TOML block helpers — text level, so user content and comments are untouched
+// JSON merge helpers
 // ---------------------------------------------------------------------------
 
 // ---------------------------------------------------------------------------
@@ -594,10 +738,8 @@ export function readLock(repo, name) {
  * 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).
+ * Reads every sibling lock. A malformed claim is fatal: proceeding would make
+ * the ownership map incomplete and could erase another extension's files.
  */
 export function readSiblingLocks(repo, exclude) {
   const dir = abs(repo, ".agents");
@@ -607,12 +749,7 @@ export function readSiblingLocks(repo, exclude) {
     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;
-    }
+    const lock = readLock(repo, name);
     if (lock) out.push({ name, lock });
   }
   return out;
@@ -642,43 +779,25 @@ function replaceSymlinkAncestors(repo, rel, ops) {
   }
 }
 
-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");
-}
+// Repo-local agent roots are an authoritative deployment, not a merge point.
+// A marked repo grants enact-extensions sole ownership of these roots.  The
+// only exceptions are runtime state written by a different process; they are
+// named here so a future writer cannot silently claim the same paths.
+export const OWNED_REPO_ROOTS = [".agents", ".claude", ".codex", ".cursor", ".kimi-code", ".opencode"];
+export const RETIRED_REPO_ROOTS = [
+  ".claude-plugin",
+  ".codex-plugin",
+  ".cursor-plugin",
+  ".kimi-plugin",
+  ".opencode/plugins",
+];
+export const UNMANAGED_RUNTIME_BOUNDARIES = [
+  ".agents/hooks",
+  ".agents/lean-ctx/data",
+  ".agents/lean-ctx/cache",
+  ".agents/lean-ctx/state",
+  ".agents/lean-ctx/bin",
+];
 
 // ---------------------------------------------------------------------------
 // enact-config.toml [extensions] — text-level only. The document is parsed
@@ -686,67 +805,19 @@ function removeManagedGitignoreLines(repo, rel, ginfo, ops) {
 // 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);
+  // Reconciliation is deliberately not enrollment.  The scheduler may point
+  // at arbitrary git checkouts, so the centrally managed marker must already
+  // exist before this command is allowed to alter anything.
+  assertMarkedRepo(repo);
   assertSupportedHookEvents(pluginRoot);
   const bundle = readBundle(pluginRoot);
   const hosts = parseRepoHosts(options.host, bundle.manifest);
@@ -757,485 +828,23 @@ export function runRepoInstall(pluginRoot, options = {}) {
   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].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.
-  const SHARED_CONTENT_EXEMPT = new Set();
-  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
-    // legacy registration key survives migration only while another installed
-    // extension still records it; otherwise the final uninstall removes it.
-    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;
-      // Record shared framing whether or not we created it. This is retained
-      // for lock migration: all current install projections are direct native
-      // files, but an old lock can still name shared metadata that must be
-      // removed only after its final owner uninstalls.
-      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 nothing to change (already declared with no
-    // stale version key, or no [extensions] to write into) -- 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,
+  return runAuthoritativeRepoInstall(pluginRoot, options, {
+    repo,
+    bundle,
     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)",
-  );
-  if (hosts.includes("claude")) {
-    console.log("claude: trust this folder and review the project hooks before using the installed agents and skills");
-  }
-  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 };
+    plan,
+    prev,
+    siblings,
+    ops,
+    actions,
+    dryRun,
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -1244,234 +853,32 @@ export function runRepoInstall(pluginRoot, options = {}) {
 
 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);
+  assertMarkedRepo(repo);
   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);
-
-  const uninstallConfigPath = abs(repo, CONFIG_PATH);
-  const uninstallConfigText = existsSync(uninstallConfigPath) ? readFileSync(uninstallConfigPath, "utf8") : "";
-
-  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 lock-owned metadata, not
-      // drift. This only matters while uninstalling historical lock content;
-      // current installs create no plugin registration or marketplace data.
-      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");
-  }
-  // 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}]`);
-    }
+  const roots = lock.ownedRoots ?? [".agents", ...(lock.hosts ?? []).map(rootForHost)];
+  for (const root of roots) {
+    const boundaries = UNMANAGED_RUNTIME_BOUNDARIES.filter((path) => path.startsWith(`${root}/`));
+    clearOwnedRoot(repo, root, boundaries, ops);
   }
-  for (const [rel, record] of Object.entries(lock.merged)) {
-    if (!jsonDocs.has(rel)) continue;
-    const { text, doc } = jsonDocs.get(rel);
-    // Reference-count historical shared metadata just as managed files. A
-    // sibling lock can still own an old registration during migration, so the
-    // first uninstall must leave it for the final owner to remove.
-    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 root of RETIRED_REPO_ROOTS) ops.removeDir(root, "retired Enact plugin root");
+  for (const rel of [".mcp.json", "opencode.json"]) {
+    if (lock.files?.[rel]) ops.remove(rel, "authoritative owned file removed on uninstall");
   }
-  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 };
+  const configPath = abs(repo, CONFIG_PATH);
+  const configText = readFileSync(configPath, "utf8");
+  const withoutDeclaration = removeExtensionBlock(configText, name);
+  let nextConfig = withoutDeclaration;
+  if (options.purge && typeof lock.config?.appended === "string") {
+    nextConfig = cutExtensionsBlock(nextConfig, lock.config.appended) ?? nextConfig;
+  }
+  if (nextConfig !== configText) {
+    inspectExtensionsScope(nextConfig, "removing [extensions] declaration");
+    ops.write(CONFIG_PATH, nextConfig, `removed [extensions.${name}]`);
+  }
+  console.log(`${dryRun ? "[dry-run] " : ""}repo uninstall ${name} <- ${repo} (authoritative roots removed)`);
+  return { repo, name, removedFiles: Object.keys(lock.files ?? {}).length, actions, dryRun };
 }