@mutmutco/hub 4.1.3 → 4.1.4

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  acquireSharedDocLock: () => acquireSharedDocLock,
   buildWatcherCommand: () => buildWatcherCommand,
   clearPending: () => clearPending,
   enumerateSurfaces: () => enumerateSurfaces,
@@ -28,6 +29,7 @@ __export(index_exports, {
   formatReconcileReport: () => formatReconcileReport,
   hermesArm: () => hermesArm,
   hermesHome: () => hermesHome,
+  hermesHostEvidence: () => hermesHostEvidence,
   hubStatus: () => hubStatus,
   launchdPlist: () => launchdPlist,
   launcherSh: () => launcherSh,
@@ -36,28 +38,36 @@ __export(index_exports, {
   lockShaped: () => lockShaped,
   main: () => main,
   noteBusyDefer: () => noteBusyDefer,
+  npmStringField: () => npmStringField,
   ownVersion: () => ownVersion,
+  parseNpmDistIntegrity: () => parseNpmDistIntegrity,
   pendingPath: () => pendingPath,
   pidAlive: () => pidAlive,
   probeHermesInstallation: () => probeHermesInstallation,
   progressiveRow: () => progressiveRow,
   readPending: () => readPending,
   reconcileCursorUserHooks: () => reconcileCursorUserHooks,
+  reconcileKimiInstalledPlugin: () => reconcileKimiInstalledPlugin,
+  releaseSharedDocLock: () => releaseSharedDocLock,
   reportFooterLines: () => reportFooterLines,
   retryHint: () => retryHint,
   schedulePendingWatcher: () => schedulePendingWatcher,
   schedulerStatus: () => schedulerStatus,
+  sharedDocLockPath: () => sharedDocLockPath,
+  sharedDocLockTimeoutReceipt: () => sharedDocLockTimeoutReceipt,
   startSpinner: () => startSpinner,
   systemdServiceUnit: () => systemdServiceUnit,
   systemdTimerUnit: () => systemdTimerUnit,
   taskXml: () => taskXml,
   updateHeader: () => updateHeader,
+  validateKimiInstalledPlugin: () => validateKimiInstalledPlugin,
   watcherLockPath: () => watcherLockPath,
+  withSharedDocLock: () => withSharedDocLock,
   wrapWords: () => wrapWords,
   writePending: () => writePending
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_fs17 = require("node:fs");
+var import_node_fs18 = require("node:fs");
 var import_node_path14 = require("node:path");
 
 // src/state.ts
@@ -258,6 +268,16 @@ function npmView(spec, field, env = process.env) {
     return null;
   }
 }
+function parseNpmDistIntegrity(value) {
+  if (typeof value === "string") return value.length > 0 ? value : null;
+  if (!Array.isArray(value) || value.length !== 1) return null;
+  const only = value[0];
+  return typeof only === "string" && only.length > 0 ? only : null;
+}
+var npmStringField = parseNpmDistIntegrity;
+function npmDistIntegrity(spec, env = process.env) {
+  return parseNpmDistIntegrity(npmView(spec, "dist.integrity", env));
+}
 function npmVersions(packageName, env = process.env) {
   const versions = npmView(packageName, "versions", env);
   return Array.isArray(versions) ? versions.filter((v) => typeof v === "string") : [];
@@ -769,27 +789,7 @@ function claudeMmi(runner, env) {
 function claudeMarketplacesPath(env) {
   return env.MMI_UPDATER_CLAUDE_MARKETPLACES || (0, import_node_path7.join)((0, import_node_os3.homedir)(), ".claude", "plugins", "known_marketplaces.json");
 }
-var CLAUDE_PROCESS_SEGMENT = /^claude(-code|-cli)?(\.(exe|cmd|bat|ps1|js|mjs|cjs|py))?$/;
-function claudeProcessSegment(line) {
-  for (const token of line.replace(/["']/g, " ").split(/\s+/)) {
-    for (const segment of token.split(/[/\\]/)) {
-      if (CLAUDE_PROCESS_SEGMENT.test(segment)) return segment;
-    }
-  }
-  return null;
-}
-function claudeHostRunning(env) {
-  const marker = env.CLAUDE_CODE_SESSION_ID?.trim() ? "CLAUDE_CODE_SESSION_ID" : env.CLAUDECODE?.trim() ? "CLAUDECODE" : env.CLAUDE_PLUGIN_ROOT?.trim() ? "CLAUDE_PLUGIN_ROOT" : null;
-  if (marker) return { running: true, evidence: `${marker} is set \u2014 this process is itself inside a Claude hook` };
-  const result = process.platform === "win32" ? (0, import_node_child_process6.spawnSync)("powershell.exe", ["-NoProfile", "-Command", "Get-CimInstance Win32_Process | ForEach-Object { $_.Name + ' ' + $_.CommandLine }"], { encoding: "utf8", windowsHide: true, timeout: 15e3 }) : (0, import_node_child_process6.spawnSync)("ps", ["-eo", "args="], { encoding: "utf8", windowsHide: true, timeout: 15e3 });
-  if (result.status !== 0 || !(result.stdout ?? "").trim()) return { running: true, evidence: "the process list is unreadable \u2014 unsafe to write" };
-  for (const line of result.stdout.split(/\r?\n/)) {
-    const segment = claudeProcessSegment(line);
-    if (segment) return { running: true, evidence: `a live process names claude (${segment})` };
-  }
-  return { running: false, evidence: "no claude-named process in the process list" };
-}
-function ensureClaudeSingleWriter(env, dryRun) {
+function ensureClaudeMarketplace(env) {
   const path = claudeMarketplacesPath(env);
   let body;
   try {
@@ -811,22 +811,7 @@ function ensureClaudeSingleWriter(env, dryRun) {
       detail: `mutmutco marketplace is registered to ${registeredRepo ?? "a non-github source"}, not ${MMI_MARKETPLACE_REPO} \u2014 a retired or foreign repo is squatting the name; re-register it (claude plugin marketplace remove mutmutco && claude plugin marketplace add ${MMI_MARKETPLACE_REPO}) before the updater can trust it`
     };
   }
-  if (registration.autoUpdate !== true) return { ok: true };
-  if (dryRun) return { ok: true, detail: "would disable Claude background autoUpdate (updater is the single writer)" };
-  const quiescence = claudeHostRunning(env);
-  if (quiescence.running) {
-    return { ok: false, detail: `Claude background autoUpdate is on, but Claude Code is running and would overwrite the registration \u2014 defer until the host is absent: ${quiescence.evidence}` };
-  }
-  registration.autoUpdate = false;
-  const tmp = `${path}.tmp-${process.pid}`;
-  try {
-    (0, import_node_fs8.writeFileSync)(tmp, JSON.stringify(body, null, 2) + "\n", "utf8");
-    (0, import_node_fs8.renameSync)(tmp, path);
-    const reread = JSON.parse((0, import_node_fs8.readFileSync)(path, "utf8"));
-    return reread?.mutmutco?.autoUpdate === false ? { ok: true, detail: "disabled Claude background autoUpdate (updater is the single writer)" } : { ok: false, detail: "Claude background autoUpdate write did not persist" };
-  } catch (error) {
-    return { ok: false, detail: `cannot disable Claude background autoUpdate: ${error?.message ?? error}` };
-  }
+  return { ok: true };
 }
 function claudeArm(options) {
   const env = options.env ?? process.env;
@@ -835,16 +820,15 @@ function claudeArm(options) {
   const before = claudeMmi(runner, env);
   if (before.error) return { surface: "claude", from: null, to: options.target, verdict: "defer", detail: before.error };
   const from = before.row?.version ?? null;
-  let singleWriter = ensureClaudeSingleWriter(env, options.dryRun);
-  if (!singleWriter.ok && singleWriter.unregistered) {
+  let marketplaceTrust = ensureClaudeMarketplace(env);
+  if (!marketplaceTrust.ok && marketplaceTrust.unregistered) {
     const add = runner("claude", ["plugin", "marketplace", "add", repoUrl], env);
     if (add.status !== 0) return { surface: "claude", from, to: options.target, verdict: "defer", detail: `mutmutco marketplace was not registered and marketplace add failed: ${failure(add)}` };
-    singleWriter = ensureClaudeSingleWriter(env, options.dryRun);
+    marketplaceTrust = ensureClaudeMarketplace(env);
   }
-  if (!singleWriter.ok) return { surface: "claude", from, to: options.target, verdict: "defer", detail: singleWriter.detail ?? "cannot establish updater as the single writer" };
+  if (!marketplaceTrust.ok) return { surface: "claude", from, to: options.target, verdict: "defer", detail: marketplaceTrust.detail ?? "cannot trust the mutmutco marketplace registration" };
   if (options.dryRun) {
-    const writer = singleWriter.detail ? `; ${singleWriter.detail}` : "";
-    return { surface: "claude", from, to: options.target, verdict: "ok", detail: `dry-run: would refresh mutmutco and converge mmi@mutmutco ${from ?? "absent"} -> ${options.target}${writer}` };
+    return { surface: "claude", from, to: options.target, verdict: "ok", detail: `dry-run: would refresh mutmutco and converge mmi@mutmutco ${from ?? "absent"} -> ${options.target}` };
   }
   const marketplace = runner("claude", ["plugin", "marketplace", "update", "mutmutco"], env);
   if (marketplace.status !== 0) {
@@ -853,8 +837,7 @@ function claudeArm(options) {
   let observed = claudeMmi(runner, env);
   if (observed.error) return { surface: "claude", from, to: options.target, verdict: "defer", detail: observed.error };
   if (observed.row?.version === options.target && observed.row.enabled === true) {
-    const writer = singleWriter.detail ? `${singleWriter.detail}; ` : "";
-    return { surface: "claude", from, to: options.target, verdict: "ok", detail: `${writer}catalog refreshed; installed+enabled at target ${options.target}` };
+    return { surface: "claude", from, to: options.target, verdict: "ok", detail: `catalog refreshed; installed+enabled at target ${options.target}` };
   }
   const scope = observed.row?.scope || before.row?.scope || "user";
   const command = observed.row ? ["plugin", "update", "mmi@mutmutco", "--scope", scope] : ["plugin", "install", "mmi@mutmutco", "--scope", scope];
@@ -1025,7 +1008,7 @@ function kiloArm(options) {
 
 // src/arm-kimi.ts
 var import_node_child_process7 = require("node:child_process");
-var import_node_fs10 = require("node:fs");
+var import_node_fs11 = require("node:fs");
 var import_node_path8 = require("node:path");
 
 // src/compat.ts
@@ -1039,6 +1022,131 @@ function readManifestCompat(manifestPath) {
   }
 }
 
+// src/kimi-registration.ts
+function validateKimiInstalledPlugin(document, pluginRoot, id) {
+  if (!document || typeof document !== "object" || Array.isArray(document)) return "malformed-document";
+  const plugins = document.plugins;
+  if (!Array.isArray(plugins)) return "malformed-document";
+  const entry = plugins.find(
+    (candidate) => candidate && typeof candidate === "object" && !Array.isArray(candidate) && candidate.id === id
+  );
+  if (!entry) return "absent-record";
+  const record = entry;
+  if (typeof record.root !== "string") return "malformed-record";
+  if (record.root !== pluginRoot) return "foreign-root";
+  return record.enabled ? "healthy" : "disabled";
+}
+
+// src/host-doc-lock.ts
+var import_node_fs10 = require("node:fs");
+var import_node_os4 = require("node:os");
+var SHARED_DOC_LOCK_STALE_MS = 3e4;
+var SHARED_DOC_LOCK_ATTEMPTS = 50;
+var SHARED_DOC_LOCK_INTERVAL_MS = 100;
+function sharedDocLockPath(documentPath) {
+  return `${documentPath}.jerv-lock`;
+}
+function lockContent(options) {
+  return `${JSON.stringify(options, null, 2)}
+`;
+}
+function readHolder(lockPath) {
+  try {
+    const parsed = JSON.parse((0, import_node_fs10.readFileSync)(lockPath, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function lockAgeMs(lockPath, now) {
+  const holder = readHolder(lockPath);
+  const declared = typeof holder?.acquiredAt === "string" ? Date.parse(holder.acquiredAt) : Number.NaN;
+  if (!Number.isNaN(declared)) return Math.max(0, now - declared);
+  try {
+    return Math.max(0, now - (0, import_node_fs10.statSync)(lockPath).mtimeMs);
+  } catch {
+    return 0;
+  }
+}
+function sharedDocLockTimeoutReceipt(documentPath, lockPath, holder, waitedMs) {
+  const named = holder && typeof holder === "object";
+  const who = named ? `held by ${String(holder.owner ?? "unknown")} (pid ${String(holder.pid ?? "?")}, host ${String(holder.host ?? "?")})` : `held by an unreadable lock at ${lockPath}`;
+  return `shared-document lock timeout: ${documentPath} is ${who} \u2014 waited ${waitedMs}ms, nothing was written \u2014 retry next tick or remove ${lockPath} if stale`;
+}
+function acquireSharedDocLock(documentPath, options) {
+  const lockPath = sharedDocLockPath(documentPath);
+  const staleAfterMs = options.staleAfterMs ?? SHARED_DOC_LOCK_STALE_MS;
+  const attempts = options.attempts ?? SHARED_DOC_LOCK_ATTEMPTS;
+  const intervalMs = options.intervalMs ?? SHARED_DOC_LOCK_INTERVAL_MS;
+  const identity = { owner: options.owner, pid: process.pid, host: options.host ?? (0, import_node_os4.hostname)(), acquiredAt: (/* @__PURE__ */ new Date()).toISOString() };
+  const content = lockContent(identity);
+  const sleep = (ms) => {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  };
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    let fd;
+    try {
+      fd = (0, import_node_fs10.openSync)(lockPath, "wx");
+      (0, import_node_fs10.writeSync)(fd, content);
+      (0, import_node_fs10.closeSync)(fd);
+      return {
+        documentPath,
+        lockPath,
+        owner: identity.owner,
+        pid: identity.pid,
+        host: identity.host,
+        acquiredAt: identity.acquiredAt,
+        release: () => releaseSharedDocLock({ lockPath, owner: identity.owner, pid: identity.pid })
+      };
+    } catch (error) {
+      if (fd !== void 0) {
+        try {
+          (0, import_node_fs10.closeSync)(fd);
+        } catch {
+        }
+        try {
+          (0, import_node_fs10.unlinkSync)(lockPath);
+        } catch {
+        }
+      }
+      if (error?.code !== "EEXIST") throw error;
+    }
+    if (lockAgeMs(lockPath, Date.now()) >= staleAfterMs) {
+      const aside = `${lockPath}.stale-${Date.now()}`;
+      try {
+        (0, import_node_fs10.renameSync)(lockPath, aside);
+      } catch {
+        continue;
+      }
+      try {
+        (0, import_node_fs10.rmSync)(aside, { force: true });
+      } catch {
+      }
+      continue;
+    }
+    if (attempt < attempts - 1) sleep(intervalMs);
+  }
+  throw new Error(sharedDocLockTimeoutReceipt(documentPath, lockPath, readHolder(lockPath), Math.max(0, attempts * intervalMs)));
+}
+function releaseSharedDocLock(handle) {
+  try {
+    const holder = readHolder(handle.lockPath);
+    if (holder && holder.owner === handle.owner && Number(holder.pid) === handle.pid) {
+      (0, import_node_fs10.unlinkSync)(handle.lockPath);
+    }
+  } catch {
+  }
+}
+function withSharedDocLock(documentPath, options, fn) {
+  const lock = acquireSharedDocLock(documentPath, options);
+  try {
+    return fn(lock.documentPath);
+  } finally {
+    lock.release();
+  }
+}
+
 // src/arm-kimi.ts
 var KIMI_PACKAGE = "@mutmutco/kimi-plugin";
 var TREE_MARKERS = [".kimi-plugin/plugin.json", "skills/mmi/SKILL.md", "scripts/hook-run.mjs"];
@@ -1047,7 +1155,7 @@ function treeHealthy(root) {
 }
 function markerVersion(root) {
   try {
-    const version = JSON.parse((0, import_node_fs10.readFileSync)((0, import_node_path8.join)(root, ".kimi-plugin", "plugin.json"), "utf8")).version;
+    const version = JSON.parse((0, import_node_fs11.readFileSync)((0, import_node_path8.join)(root, ".kimi-plugin", "plugin.json"), "utf8")).version;
     return typeof version === "string" ? version : null;
   } catch {
     return null;
@@ -1055,12 +1163,58 @@ function markerVersion(root) {
 }
 function packageVersion(root) {
   try {
-    const version = JSON.parse((0, import_node_fs10.readFileSync)((0, import_node_path8.join)(root, "package.json"), "utf8")).version;
+    const version = JSON.parse((0, import_node_fs11.readFileSync)((0, import_node_path8.join)(root, "package.json"), "utf8")).version;
     return typeof version === "string" ? version : null;
   } catch {
     return null;
   }
 }
+var KIMI_REGISTRATION_LOCK_OWNER = "mmi-hub:kimi-registration";
+function reconcileKimiInstalledPlugin(kimiHomeDir, pluginRoot, id, lock = {}) {
+  const path = (0, import_node_path8.join)(kimiHomeDir, "plugins", "installed.json");
+  (0, import_node_fs11.mkdirSync)((0, import_node_path8.join)(kimiHomeDir, "plugins"), { recursive: true });
+  return withSharedDocLock(path, { owner: KIMI_REGISTRATION_LOCK_OWNER, ...lock }, () => mergeKimiInstalledPlugin(path, pluginRoot, id));
+}
+function mergeKimiInstalledPlugin(path, pluginRoot, id) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const fresh = { id, root: pluginRoot, enabled: true, installedAt: now, updatedAt: now, originalSource: pluginRoot, source: "local-path" };
+  let document = { version: 1, plugins: [] };
+  if ((0, import_node_fs11.existsSync)(path)) {
+    let parsed;
+    try {
+      parsed = JSON.parse((0, import_node_fs11.readFileSync)(path, "utf8"));
+    } catch {
+      return "conflict";
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !Array.isArray(parsed.plugins)) return "conflict";
+    document = parsed;
+  }
+  const plugins = [...document.plugins];
+  const registration = validateKimiInstalledPlugin(document, pluginRoot, id);
+  const index = plugins.findIndex((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry) && entry.id === id);
+  if (registration === "malformed-record" || registration === "foreign-root") return "conflict";
+  if (index === -1) {
+    plugins.push(fresh);
+  } else {
+    const prior = plugins[index];
+    const next = {
+      ...prior,
+      root: pluginRoot,
+      // A user's explicit disable is their choice and survives; anything else converges to enabled.
+      enabled: prior.enabled === false ? false : true,
+      installedAt: typeof prior.installedAt === "string" ? prior.installedAt : now,
+      originalSource: pluginRoot,
+      source: "local-path"
+    };
+    if (JSON.stringify(next) === JSON.stringify(prior)) return "current";
+    plugins[index] = { ...next, updatedAt: now };
+  }
+  const tmp = `${path}.tmp-${process.pid}`;
+  (0, import_node_fs11.writeFileSync)(tmp, `${JSON.stringify({ ...document, version: 1, plugins }, null, 2)}
+`, "utf8");
+  (0, import_node_fs11.renameSync)(tmp, path);
+  return "updated";
+}
 function probeKimiInstallation(env = process.env) {
   const location = (0, import_node_path8.join)(kimiHome(env), "plugins", "managed", "mmi");
   const version = markerVersion(location);
@@ -1074,10 +1228,10 @@ function scratchRoot(env) {
 }
 function pruneScratchDir(root, keep) {
   try {
-    for (const name of (0, import_node_fs10.readdirSync)(root)) {
+    for (const name of (0, import_node_fs11.readdirSync)(root)) {
       if (name === keep) continue;
       try {
-        (0, import_node_fs10.rmSync)((0, import_node_path8.join)(root, name), { recursive: true, force: true });
+        (0, import_node_fs11.rmSync)((0, import_node_path8.join)(root, name), { recursive: true, force: true });
       } catch {
       }
     }
@@ -1103,11 +1257,11 @@ function kimiHostRunning(env) {
 }
 function restoreQuarantine(quarantine, live) {
   try {
-    (0, import_node_fs10.renameSync)(quarantine, live);
+    (0, import_node_fs11.renameSync)(quarantine, live);
   } catch (error) {
     return { restored: false, detail: `${error?.message ?? error}` };
   }
-  if (!(0, import_node_fs10.existsSync)(live)) return { restored: false, detail: `${live} is still absent after the restore rename` };
+  if (!(0, import_node_fs11.existsSync)(live)) return { restored: false, detail: `${live} is still absent after the restore rename` };
   return { restored: true, detail: `marker ${markerVersion(live) ?? "unreadable"}` };
 }
 function kimiArm(options) {
@@ -1126,15 +1280,32 @@ function kimiArm(options) {
   const managedParent = (0, import_node_path8.join)(kimiHome(env), "plugins", "managed");
   const live = (0, import_node_path8.join)(managedParent, "mmi");
   const installed = markerVersion(live);
+  const ensureRegistered = (detail) => {
+    if (!(0, import_node_fs11.existsSync)(live) || !treeHealthy(live)) return { detail };
+    if (dryRun) return { detail: `${detail}; installed.json untouched (dry-run)` };
+    let registration;
+    try {
+      registration = reconcileKimiInstalledPlugin(kimiHome(env), live, "mmi");
+    } catch (error) {
+      return { fail: true, detail: `${detail}; installed.json registration FAILED: ${error?.message ?? error}` };
+    }
+    if (registration === "conflict") {
+      return { fail: true, detail: `${detail}; installed.json carries an unparsable or foreign mmi record \u2014 the tree is INERT until a human resolves it; the file was never touched` };
+    }
+    return { detail: `${detail}; installed.json record ${registration === "updated" ? "written" : "already current"}` };
+  };
   if (installed && compareSemver(installed, target) > 0) {
-    return result(installed, installed, "skip", `installed ${installed} is above candidate ${target} (monotonic)`);
+    const reg2 = ensureRegistered(`installed ${installed} is above candidate ${target} (monotonic)`);
+    return result(installed, installed, reg2.fail ? "fail" : "skip", reg2.detail);
   }
   const highWater = journalHighWater(paths.journalPath, "kimi");
   if (highWater && compareSemver(highWater, target) > 0) {
-    return result(installed, highWater, "skip", `journal high-water ${highWater} is above candidate ${target} (monotonic)`);
+    const reg2 = ensureRegistered(`journal high-water ${highWater} is above candidate ${target} (monotonic)`);
+    return result(installed, highWater, reg2.fail ? "fail" : "skip", reg2.detail);
   }
   if (installed === target && treeHealthy(live)) {
-    return result(installed, target, "ok", `already at target ${target}`);
+    const reg2 = ensureRegistered(`already at target ${target}`);
+    return result(installed, target, reg2.fail ? "fail" : "ok", reg2.detail);
   }
   if (dryRun) {
     return result(installed, target, "ok", `dry-run: would converge ${installed ?? "absent"} -> ${target} (tarball generation switch while Kimi is absent)`);
@@ -1142,8 +1313,8 @@ function kimiArm(options) {
   const stageRoot = (0, import_node_path8.join)(paths.staging, "kimi", target);
   const staged = (0, import_node_path8.join)(stageRoot, "node_modules", ...KIMI_PACKAGE.split("/"));
   if (!treeHealthy(staged)) {
-    (0, import_node_fs10.mkdirSync)(stageRoot, { recursive: true });
-    (0, import_node_fs10.writeFileSync)((0, import_node_path8.join)(stageRoot, "package.json"), JSON.stringify({ name: "mmi-updater-stage", private: true }) + "\n");
+    (0, import_node_fs11.mkdirSync)(stageRoot, { recursive: true });
+    (0, import_node_fs11.writeFileSync)((0, import_node_path8.join)(stageRoot, "package.json"), JSON.stringify({ name: "mmi-updater-stage", private: true }) + "\n");
     const install = runNpm(["install", "--prefix", stageRoot, "--no-audit", "--no-fund", "--no-package-lock", `${KIMI_PACKAGE}@${target}`], env);
     if (install.status !== 0) {
       return result(installed, target, "defer", `staging install failed: ${tail2(install.stderr || install.stdout)}`);
@@ -1171,22 +1342,22 @@ function kimiArm(options) {
   const quarantineRoot = (0, import_node_path8.join)(scratch, "quarantine");
   const rejectedRoot = (0, import_node_path8.join)(scratch, "rejected");
   try {
-    (0, import_node_fs10.mkdirSync)(managedParent, { recursive: true });
-    (0, import_node_fs10.mkdirSync)(quarantineRoot, { recursive: true });
-    (0, import_node_fs10.rmSync)(incomingRoot, { recursive: true, force: true });
-    (0, import_node_fs10.cpSync)(staged, incoming, { recursive: true });
+    (0, import_node_fs11.mkdirSync)(managedParent, { recursive: true });
+    (0, import_node_fs11.mkdirSync)(quarantineRoot, { recursive: true });
+    (0, import_node_fs11.rmSync)(incomingRoot, { recursive: true, force: true });
+    (0, import_node_fs11.cpSync)(staged, incoming, { recursive: true });
   } catch (error) {
     return result(installed, target, "defer", `cannot place the incoming generation under ${scratch}: ${error?.message ?? error}`);
   }
   if (markerVersion(incoming) !== target || !treeHealthy(incoming)) {
     return result(installed, target, "defer", `incoming generation verifies as ${markerVersion(incoming) ?? "unreadable"}, expected ${target}`);
   }
-  const hadLive = (0, import_node_fs10.existsSync)(live);
+  const hadLive = (0, import_node_fs11.existsSync)(live);
   const generation = `${installed ?? "unknown"}-${Date.now()}`;
   const quarantine = (0, import_node_path8.join)(quarantineRoot, generation);
   if (hadLive) {
     try {
-      (0, import_node_fs10.renameSync)(live, quarantine);
+      (0, import_node_fs11.renameSync)(live, quarantine);
     } catch (error) {
       const reason = String(error?.message ?? error);
       const pending = lockShaped(reason) ? ` \u2014 ${noteBusyDefer(options.paths, env, { surface: "kimi", target, reason, dirs: ["kimi"] })}` : "";
@@ -1194,7 +1365,7 @@ function kimiArm(options) {
     }
   }
   try {
-    (0, import_node_fs10.renameSync)(incoming, live);
+    (0, import_node_fs11.renameSync)(incoming, live);
   } catch (error) {
     const failed = `cannot switch the new generation in: ${error?.message ?? error}`;
     if (!hadLive) {
@@ -1209,8 +1380,8 @@ function kimiArm(options) {
     const observed = `post-switch marker is ${switched ?? "unreadable"}, expected ${target}`;
     const rejectedName = `${target}-${Date.now()}`;
     try {
-      (0, import_node_fs10.mkdirSync)(rejectedRoot, { recursive: true });
-      (0, import_node_fs10.renameSync)(live, (0, import_node_path8.join)(rejectedRoot, rejectedName));
+      (0, import_node_fs11.mkdirSync)(rejectedRoot, { recursive: true });
+      (0, import_node_fs11.renameSync)(live, (0, import_node_path8.join)(rejectedRoot, rejectedName));
     } catch (error) {
       return result(installed, switched ?? "unknown", "fail", `${observed} \u2014 the unverified tree could NOT be moved aside (${error?.message ?? error}) and is STILL LIVE at ${live}${hadLive ? `; the previous generation is intact at ${quarantine}` : ""}`);
     }
@@ -1224,16 +1395,17 @@ function kimiArm(options) {
   pruneScratchDir(quarantineRoot, hadLive ? generation : null);
   pruneScratchDir(rejectedRoot, null);
   try {
-    (0, import_node_fs10.rmSync)(incomingRoot, { recursive: true, force: true });
+    (0, import_node_fs11.rmSync)(incomingRoot, { recursive: true, force: true });
   } catch {
   }
-  return result(installed, target, "ok", `converged ${installed ?? "absent"} -> ${target} (staged, verified, switched${hadLive ? `; previous generation quarantined at ${quarantine}` : ""})`);
+  const reg = ensureRegistered(`converged ${installed ?? "absent"} -> ${target} (staged, verified, switched${hadLive ? `; previous generation quarantined at ${quarantine}` : ""})`);
+  return result(installed, target, reg.fail ? "fail" : "ok", reg.detail);
 }
 
 // src/arm-cursor.ts
-var import_node_fs11 = require("node:fs");
+var import_node_fs12 = require("node:fs");
 var import_node_child_process8 = require("node:child_process");
-var import_node_os4 = require("node:os");
+var import_node_os5 = require("node:os");
 var import_node_path9 = require("node:path");
 var PACKAGE = "@mutmutco/cursor-plugin";
 var MANIFEST = ".cursor-plugin/plugin.json";
@@ -1243,14 +1415,14 @@ var KEEP_GENERATIONS = 2;
 var STRANDED_TMP_AGE_MS = 24 * 60 * 6e4;
 var TREE_FILES = [MANIFEST, "skills/mmi/SKILL.md", "hooks/cursor-hooks.json", "scripts/hook-run.mjs", "scripts/hook-policy.mjs"];
 function cursorPluginsRoot() {
-  return (0, import_node_path9.join)((0, import_node_os4.homedir)(), ".cursor", "plugins");
+  return (0, import_node_path9.join)((0, import_node_os5.homedir)(), ".cursor", "plugins");
 }
 function treeHealthy2(root) {
-  return TREE_FILES.every((rel) => (0, import_node_fs11.existsSync)((0, import_node_path9.join)(root, ...rel.split("/"))));
+  return TREE_FILES.every((rel) => (0, import_node_fs12.existsSync)((0, import_node_path9.join)(root, ...rel.split("/"))));
 }
 function readJson(root, rel) {
   try {
-    return JSON.parse((0, import_node_fs11.readFileSync)((0, import_node_path9.join)(root, ...rel.split("/")), "utf8"));
+    return JSON.parse((0, import_node_fs12.readFileSync)((0, import_node_path9.join)(root, ...rel.split("/")), "utf8"));
   } catch {
     return null;
   }
@@ -1274,7 +1446,7 @@ function message(error) {
 }
 function discard(path) {
   try {
-    (0, import_node_fs11.rmSync)(path, { recursive: true, force: true });
+    (0, import_node_fs12.rmSync)(path, { recursive: true, force: true });
   } catch {
   }
 }
@@ -1312,7 +1484,7 @@ function resolveCommand(command, pluginRoot) {
 }
 function desiredUserHooks(pluginRoot) {
   try {
-    const doc = JSON.parse((0, import_node_fs11.readFileSync)((0, import_node_path9.join)(pluginRoot, ...PLUGIN_HOOKS_REL), "utf8"));
+    const doc = JSON.parse((0, import_node_fs12.readFileSync)((0, import_node_path9.join)(pluginRoot, ...PLUGIN_HOOKS_REL), "utf8"));
     const hooks = doc.hooks;
     if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks)) return null;
     const desired = /* @__PURE__ */ new Map();
@@ -1345,30 +1517,41 @@ function mergeUserHooks(existing, desired, pluginRoot) {
   merged.hooks = nextHooks;
   return merged;
 }
-function reconcileCursorUserHooks(pluginRoot, homeDir) {
+var CURSOR_HOOKS_LOCK_OWNER = "mmi-hub:cursor-hooks";
+function reconcileCursorUserHooks(pluginRoot, homeDir, lock = {}) {
   const desired = desiredUserHooks(pluginRoot);
   if (!desired) return "source-unreadable";
   const path = (0, import_node_path9.join)(homeDir, ".cursor", USER_HOOKS_FILE);
-  if (!(0, import_node_fs11.existsSync)(path)) {
-    (0, import_node_fs11.writeFileSync)(path, JSON.stringify({ version: 1, hooks: Object.fromEntries(desired) }, null, 2) + "\n", "utf8");
+  return withSharedDocLock(path, { owner: CURSOR_HOOKS_LOCK_OWNER, ...lock }, () => {
+    if (!(0, import_node_fs12.existsSync)(path)) {
+      const fresh = `${path}.tmp-${process.pid}`;
+      (0, import_node_fs12.writeFileSync)(fresh, JSON.stringify({ version: 1, hooks: Object.fromEntries(desired) }, null, 2) + "\n", "utf8");
+      (0, import_node_fs12.renameSync)(fresh, path);
+      return "updated";
+    }
+    let existing;
+    try {
+      existing = JSON.parse((0, import_node_fs12.readFileSync)(path, "utf8"));
+    } catch {
+      return "user-conflict";
+    }
+    const merged = mergeUserHooks(existing, desired, pluginRoot);
+    if (!merged) return "user-conflict";
+    if (JSON.stringify(merged) === JSON.stringify(existing)) return "current";
+    const tmp = `${path}.tmp-${process.pid}`;
+    (0, import_node_fs12.writeFileSync)(tmp, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    (0, import_node_fs12.renameSync)(tmp, path);
     return "updated";
-  }
-  let existing;
-  try {
-    existing = JSON.parse((0, import_node_fs11.readFileSync)(path, "utf8"));
-  } catch {
-    return "user-conflict";
-  }
-  const merged = mergeUserHooks(existing, desired, pluginRoot);
-  if (!merged) return "user-conflict";
-  if (JSON.stringify(merged) === JSON.stringify(existing)) return "current";
-  const tmp = `${path}.tmp-${process.pid}`;
-  (0, import_node_fs11.writeFileSync)(tmp, JSON.stringify(merged, null, 2) + "\n", "utf8");
-  (0, import_node_fs11.renameSync)(tmp, path);
-  return "updated";
+  });
 }
 function userHooksDetail(pluginRoot, homeDir) {
-  switch (reconcileCursorUserHooks(pluginRoot, homeDir)) {
+  let verdict;
+  try {
+    verdict = reconcileCursorUserHooks(pluginRoot, homeDir);
+  } catch (error) {
+    return `; ${error?.message ?? error}`;
+  }
+  switch (verdict) {
     case "updated":
       return "; user hooks bridged into ~/.cursor/hooks.json";
     case "user-conflict":
@@ -1383,15 +1566,15 @@ function writeRollbackPointer(root, entry) {
   const path = (0, import_node_path9.join)(root, "quarantine", "rollback.json");
   const tmp = `${path}.tmp-${process.pid}`;
   try {
-    (0, import_node_fs11.writeFileSync)(tmp, JSON.stringify({ surface: "cursor", ts: (/* @__PURE__ */ new Date()).toISOString(), ...entry }, null, 2) + "\n", "utf8");
-    (0, import_node_fs11.renameSync)(tmp, path);
+    (0, import_node_fs12.writeFileSync)(tmp, JSON.stringify({ surface: "cursor", ts: (/* @__PURE__ */ new Date()).toISOString(), ...entry }, null, 2) + "\n", "utf8");
+    (0, import_node_fs12.renameSync)(tmp, path);
   } catch {
     discard(tmp);
   }
 }
 function mtimeMs(path) {
   try {
-    return (0, import_node_fs11.statSync)(path).mtimeMs;
+    return (0, import_node_fs12.statSync)(path).mtimeMs;
   } catch {
     return 0;
   }
@@ -1400,13 +1583,13 @@ function pruneQuarantine(root, keep) {
   const dir = (0, import_node_path9.join)(root, "quarantine");
   let generations;
   try {
-    generations = (0, import_node_fs11.readdirSync)(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && entry.name.startsWith("mmi-")).map((entry) => (0, import_node_path9.join)(dir, entry.name)).sort((a, b) => mtimeMs(b) - mtimeMs(a));
+    generations = (0, import_node_fs12.readdirSync)(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && entry.name.startsWith("mmi-")).map((entry) => (0, import_node_path9.join)(dir, entry.name)).sort((a, b) => mtimeMs(b) - mtimeMs(a));
   } catch {
     return 0;
   }
   let stranded = 0;
   try {
-    for (const entry of (0, import_node_fs11.readdirSync)(dir, { withFileTypes: true })) {
+    for (const entry of (0, import_node_fs12.readdirSync)(dir, { withFileTypes: true })) {
       if (!entry.isFile() || !/^rollback\.json\.tmp-\d+$/.test(entry.name)) continue;
       const path = (0, import_node_path9.join)(dir, entry.name);
       if (Date.now() - mtimeMs(path) < STRANDED_TMP_AGE_MS) continue;
@@ -1426,16 +1609,16 @@ function pruneQuarantine(root, keep) {
 }
 function restorePrevious(live, quarantined, broken) {
   try {
-    (0, import_node_fs11.renameSync)(live, broken);
+    (0, import_node_fs12.renameSync)(live, broken);
   } catch {
     return "kept-broken";
   }
   try {
-    (0, import_node_fs11.renameSync)(quarantined, live);
+    (0, import_node_fs12.renameSync)(quarantined, live);
     return "restored";
   } catch {
     try {
-      (0, import_node_fs11.renameSync)(broken, live);
+      (0, import_node_fs12.renameSync)(broken, live);
       return "kept-broken";
     } catch {
       return "lost";
@@ -1467,9 +1650,9 @@ function cursorArm(options) {
     return result(installed, highWater, "skip", `journal high-water ${highWater} is above candidate ${target} (monotonic)`);
   }
   if (installed === target && treeHealthy2(live)) {
-    return result(installed, target, "ok", `already at target ${target}${userHooksDetail(live, (0, import_node_os4.homedir)())}`);
+    return result(installed, target, "ok", `already at target ${target}${userHooksDetail(live, (0, import_node_os5.homedir)())}`);
   }
-  if ((0, import_node_fs11.existsSync)(live) && !mmiOwned(live)) {
+  if ((0, import_node_fs12.existsSync)(live) && !mmiOwned(live)) {
     return result(installed, target, "defer", `${live} carries no MMI ownership marker (plugin manifest name, or a ${PACKAGE} package.json) \u2014 refusing to displace an unmanaged directory (mmi-cli plugin heal adopts it)`);
   }
   if (dryRun) {
@@ -1491,10 +1674,10 @@ function cursorArm(options) {
   const stamp = Date.now();
   const incoming = (0, import_node_path9.join)(root, "staging", `mmi-${safeSegment(target)}-${stamp}`);
   const quarantined = (0, import_node_path9.join)(root, "quarantine", `mmi-${safeSegment(installed ?? "unknown")}-${stamp}`);
-  for (const dir of ["local", "staging", "quarantine"]) (0, import_node_fs11.mkdirSync)((0, import_node_path9.join)(root, dir), { recursive: true });
+  for (const dir of ["local", "staging", "quarantine"]) (0, import_node_fs12.mkdirSync)((0, import_node_path9.join)(root, dir), { recursive: true });
   try {
     discard(incoming);
-    (0, import_node_fs11.cpSync)(staged.packageRoot, incoming, { recursive: true });
+    (0, import_node_fs12.cpSync)(staged.packageRoot, incoming, { recursive: true });
   } catch (error) {
     discard(incoming);
     return result(installed, target, "defer", `copy into ${root} failed: ${message(error)}`);
@@ -1511,15 +1694,15 @@ function cursorArm(options) {
   }
   let displaced = false;
   try {
-    if ((0, import_node_fs11.existsSync)(live)) {
-      (0, import_node_fs11.renameSync)(live, quarantined);
+    if ((0, import_node_fs12.existsSync)(live)) {
+      (0, import_node_fs12.renameSync)(live, quarantined);
       displaced = true;
     }
-    (0, import_node_fs11.renameSync)(incoming, live);
+    (0, import_node_fs12.renameSync)(incoming, live);
   } catch (error) {
-    if (displaced && !(0, import_node_fs11.existsSync)(live)) {
+    if (displaced && !(0, import_node_fs12.existsSync)(live)) {
       try {
-        (0, import_node_fs11.renameSync)(quarantined, live);
+        (0, import_node_fs12.renameSync)(quarantined, live);
       } catch {
       }
     }
@@ -1539,11 +1722,11 @@ function cursorArm(options) {
   writeRollbackPointer(root, { installed: target, previous: installed, generation: displaced ? quarantined : null });
   const pruned = pruneQuarantine(root, displaced ? quarantined : null);
   const previous = displaced ? `previous generation quarantined at ${quarantined}` : "no previous generation to quarantine";
-  return result(installed, target, "ok", `switched ${installed ?? "absent"} -> ${target}; ${previous}${pruned ? `; pruned ${pruned} older generation${pruned === 1 ? "" : "s"}` : ""}${userHooksDetail(live, (0, import_node_os4.homedir)())}`);
+  return result(installed, target, "ok", `switched ${installed ?? "absent"} -> ${target}; ${previous}${pruned ? `; pruned ${pruned} older generation${pruned === 1 ? "" : "s"}` : ""}${userHooksDetail(live, (0, import_node_os5.homedir)())}`);
 }
 
 // src/arm-jervcode.ts
-var import_node_fs12 = require("node:fs");
+var import_node_fs13 = require("node:fs");
 var import_node_path10 = require("node:path");
 var PI_PACKAGE = "@mutmutco/pi-plugin";
 function hostEnv(env) {
@@ -1555,7 +1738,7 @@ function hostCommands(_env) {
 }
 function readPackageSpecs(env) {
   try {
-    const settings = JSON.parse((0, import_node_fs12.readFileSync)((0, import_node_path10.join)(jervcodeAgentDir(env), "settings.json"), "utf8"));
+    const settings = JSON.parse((0, import_node_fs13.readFileSync)((0, import_node_path10.join)(jervcodeAgentDir(env), "settings.json"), "utf8"));
     return Array.isArray(settings.packages) ? settings.packages.filter((entry) => typeof entry === "string") : [];
   } catch {
     return null;
@@ -1563,7 +1746,7 @@ function readPackageSpecs(env) {
 }
 function installedVersion(env) {
   try {
-    const manifest2 = JSON.parse((0, import_node_fs12.readFileSync)((0, import_node_path10.join)(jervcodeAgentDir(env), "npm", "node_modules", ...PI_PACKAGE.split("/"), "package.json"), "utf8"));
+    const manifest2 = JSON.parse((0, import_node_fs13.readFileSync)((0, import_node_path10.join)(jervcodeAgentDir(env), "npm", "node_modules", ...PI_PACKAGE.split("/"), "package.json"), "utf8"));
     return typeof manifest2.version === "string" ? manifest2.version : null;
   } catch {
     return null;
@@ -1646,7 +1829,7 @@ function jervcodeArm(options) {
 }
 
 // src/arm-hermes.ts
-var import_node_fs13 = require("node:fs");
+var import_node_fs14 = require("node:fs");
 var import_node_child_process9 = require("node:child_process");
 var import_node_path11 = require("node:path");
 var PACKAGE2 = "@mutmutco/hermes-plugin";
@@ -1654,7 +1837,7 @@ var MANIFEST2 = "plugin.yaml";
 var TREE_MARKERS2 = [MANIFEST2, "__init__.py", "skills"];
 function yamlVersion(root) {
   try {
-    const text = (0, import_node_fs13.readFileSync)((0, import_node_path11.join)(root, MANIFEST2), "utf8");
+    const text = (0, import_node_fs14.readFileSync)((0, import_node_path11.join)(root, MANIFEST2), "utf8");
     try {
       const version = JSON.parse(text).version;
       if (typeof version === "string" && version.trim()) return version.trim();
@@ -1667,9 +1850,9 @@ function yamlVersion(root) {
   }
 }
 function treeHealthy3(root) {
-  return TREE_MARKERS2.slice(0, 2).every((file) => (0, import_node_fs13.existsSync)((0, import_node_path11.join)(root, file))) && (() => {
+  return TREE_MARKERS2.slice(0, 2).every((file) => (0, import_node_fs14.existsSync)((0, import_node_path11.join)(root, file))) && (() => {
     try {
-      return (0, import_node_fs13.statSync)((0, import_node_path11.join)(root, "skills")).isDirectory();
+      return (0, import_node_fs14.statSync)((0, import_node_path11.join)(root, "skills")).isDirectory();
     } catch {
       return false;
     }
@@ -1677,7 +1860,7 @@ function treeHealthy3(root) {
 }
 function packageIdentity(root) {
   try {
-    return JSON.parse((0, import_node_fs13.readFileSync)((0, import_node_path11.join)(root, "package.json"), "utf8")).name === PACKAGE2;
+    return JSON.parse((0, import_node_fs14.readFileSync)((0, import_node_path11.join)(root, "package.json"), "utf8")).name === PACKAGE2;
   } catch {
     return false;
   }
@@ -1692,7 +1875,7 @@ function mmiOwned2(root) {
 }
 function discard2(path) {
   try {
-    (0, import_node_fs13.rmSync)(path, { recursive: true, force: true });
+    (0, import_node_fs14.rmSync)(path, { recursive: true, force: true });
   } catch {
   }
 }
@@ -1708,10 +1891,14 @@ function hermesProcessToken(line, home) {
   }
   return null;
 }
-function hermesHostEvidence(env, home) {
+function realProcessListing() {
   const result = process.platform === "win32" ? (0, import_node_child_process9.spawnSync)("powershell.exe", ["-NoProfile", "-Command", "Get-CimInstance Win32_Process | ForEach-Object { $_.Name + ' ' + $_.CommandLine }"], { encoding: "utf8", windowsHide: true, timeout: 15e3 }) : (0, import_node_child_process9.spawnSync)("ps", ["-eo", "args="], { encoding: "utf8", windowsHide: true, timeout: 15e3 });
-  if (result.status !== 0 || !(result.stdout ?? "").trim()) return "the process list is unreadable (unsafe to write)";
-  for (const line of result.stdout.split(/\r?\n/)) {
+  return result.status === 0 ? result.stdout ?? "" : null;
+}
+function hermesHostEvidence(env, home, processListProvider) {
+  const listing = processListProvider ? processListProvider() : realProcessListing();
+  if (listing === null || !listing.trim()) return "the process list is unreadable (unsafe to write)";
+  for (const line of listing.split(/\r?\n/)) {
     const token = hermesProcessToken(line, home);
     if (token) return `a live process names hermes (${token})`;
   }
@@ -1722,15 +1909,15 @@ function materializeHermesSkills(home) {
   const skillsRoot = (0, import_node_path11.join)(home, "skills");
   const targetRoot = (0, import_node_path11.join)(skillsRoot, "mmi");
   try {
-    if (!(0, import_node_fs13.existsSync)(pluginSkills)) return { ok: false, detail: `plugin skills tree missing at ${pluginSkills}` };
-    const names = (0, import_node_fs13.readdirSync)(pluginSkills, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith("_")).map((entry) => entry.name);
+    if (!(0, import_node_fs14.existsSync)(pluginSkills)) return { ok: false, detail: `plugin skills tree missing at ${pluginSkills}` };
+    const names = (0, import_node_fs14.readdirSync)(pluginSkills, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith("_")).map((entry) => entry.name);
     if (!names.length) return { ok: false, detail: `plugin skills tree is empty at ${pluginSkills}` };
-    (0, import_node_fs13.mkdirSync)(skillsRoot, { recursive: true });
+    (0, import_node_fs14.mkdirSync)(skillsRoot, { recursive: true });
     const incoming = (0, import_node_path11.join)(skillsRoot, ".mmi-incoming");
     discard2(incoming);
-    (0, import_node_fs13.cpSync)(pluginSkills, incoming, { recursive: true });
+    (0, import_node_fs14.cpSync)(pluginSkills, incoming, { recursive: true });
     discard2(targetRoot);
-    (0, import_node_fs13.renameSync)(incoming, targetRoot);
+    (0, import_node_fs14.renameSync)(incoming, targetRoot);
     return { ok: true, detail: `provisioned ${names.length} skills to ${targetRoot}` };
   } catch (error) {
     return { ok: false, detail: message2(error) };
@@ -1749,8 +1936,8 @@ function hermesArm(options) {
     verdict,
     detail
   });
-  if (!(0, import_node_fs13.existsSync)(home)) return result(null, options.target, "skip", `absent (${home}) \u2014 skipped without writes`);
-  if ((0, import_node_fs13.existsSync)(live) && !mmiOwned2(live)) {
+  if (!(0, import_node_fs14.existsSync)(home)) return result(null, options.target, "skip", `absent (${home}) \u2014 skipped without writes`);
+  if ((0, import_node_fs14.existsSync)(live) && !mmiOwned2(live)) {
     return result(installed, options.target, "defer", `${live} carries no ${PACKAGE2} package identity \u2014 refusing to displace an unmanaged Hermes mmi plugin`);
   }
   if (installed && compareSemver(installed, options.target) > 0) return result(installed, installed, "skip", `installed ${installed} is above candidate ${options.target} (monotonic)`);
@@ -1772,10 +1959,10 @@ function hermesArm(options) {
   const incoming = (0, import_node_path11.join)(incomingRoot, options.target);
   const quarantine = (0, import_node_path11.join)(scratch, "quarantine", `${installed ?? "unknown"}-${Date.now()}`);
   try {
-    (0, import_node_fs13.mkdirSync)(parent, { recursive: true });
-    (0, import_node_fs13.mkdirSync)((0, import_node_path11.join)(scratch, "quarantine"), { recursive: true });
+    (0, import_node_fs14.mkdirSync)(parent, { recursive: true });
+    (0, import_node_fs14.mkdirSync)((0, import_node_path11.join)(scratch, "quarantine"), { recursive: true });
     discard2(incomingRoot);
-    (0, import_node_fs13.cpSync)(staged.packageRoot, incoming, { recursive: true });
+    (0, import_node_fs14.cpSync)(staged.packageRoot, incoming, { recursive: true });
   } catch (error) {
     return result(installed, options.target, "defer", `cannot place incoming Hermes generation: ${message2(error)}`);
   }
@@ -1783,19 +1970,19 @@ function hermesArm(options) {
     discard2(incomingRoot);
     return result(installed, options.target, "defer", "incoming Hermes generation did not reproduce the verified payload");
   }
-  const busy = hermesHostEvidence(env, home);
+  const busy = hermesHostEvidence(env, home, options.processListProvider);
   if (busy) {
     discard2(incomingRoot);
     const pending = noteBusyDefer(options.paths, env, { surface: "hermes", target: options.target, reason: busy, images: ["hermes"], dirs: [home] });
     return result(installed, options.target, "defer", `Hermes may be running \u2014 the plugin tree is only swapped while the host is absent: ${busy} \u2014 ${pending}`);
   }
-  const displaced = (0, import_node_fs13.existsSync)(live);
+  const displaced = (0, import_node_fs14.existsSync)(live);
   try {
-    if (displaced) (0, import_node_fs13.renameSync)(live, quarantine);
-    (0, import_node_fs13.renameSync)(incoming, live);
+    if (displaced) (0, import_node_fs14.renameSync)(live, quarantine);
+    (0, import_node_fs14.renameSync)(incoming, live);
   } catch (error) {
-    if (displaced && !(0, import_node_fs13.existsSync)(live)) try {
-      (0, import_node_fs13.renameSync)(quarantine, live);
+    if (displaced && !(0, import_node_fs14.existsSync)(live)) try {
+      (0, import_node_fs14.renameSync)(quarantine, live);
     } catch {
     }
     discard2(incomingRoot);
@@ -1806,9 +1993,9 @@ function hermesArm(options) {
   if (yamlVersion(live) !== options.target || !treeHealthy3(live)) {
     const broken = (0, import_node_path11.join)(scratch, "rejected", `${options.target}-${Date.now()}`);
     try {
-      (0, import_node_fs13.mkdirSync)((0, import_node_path11.join)(scratch, "rejected"), { recursive: true });
-      (0, import_node_fs13.renameSync)(live, broken);
-      if (displaced) (0, import_node_fs13.renameSync)(quarantine, live);
+      (0, import_node_fs14.mkdirSync)((0, import_node_path11.join)(scratch, "rejected"), { recursive: true });
+      (0, import_node_fs14.renameSync)(live, broken);
+      if (displaced) (0, import_node_fs14.renameSync)(quarantine, live);
     } catch (error) {
       return result(installed, yamlVersion(live) ?? "unknown", "fail", `post-switch Hermes verification failed and recovery failed: ${message2(error)}`);
     }
@@ -1822,7 +2009,7 @@ function hermesArm(options) {
 
 // src/reap.ts
 var import_node_child_process10 = require("node:child_process");
-var import_node_fs14 = require("node:fs");
+var import_node_fs15 = require("node:fs");
 var import_node_path12 = require("node:path");
 var KEEP_GENERATIONS2 = 2;
 var SCRATCH_AGE_MS = 24 * 60 * 6e4;
@@ -1831,7 +2018,7 @@ var SNAPSHOT_TIMEOUT_MS = 2e4;
 var MAX_UNWIND_ROUNDS = 4;
 function listDirs(path) {
   try {
-    return (0, import_node_fs14.readdirSync)(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    return (0, import_node_fs15.readdirSync)(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
   } catch {
     return [];
   }
@@ -1852,7 +2039,7 @@ function pruneGenerations(root, category, dryRun) {
         continue;
       }
       try {
-        (0, import_node_fs14.rmSync)((0, import_node_path12.join)(set, version), { recursive: true, force: true });
+        (0, import_node_fs15.rmSync)((0, import_node_path12.join)(set, version), { recursive: true, force: true });
         reaped += 1;
       } catch (error) {
         failures.push(`${version}: ${error?.code ?? error?.message ?? error}`);
@@ -1885,7 +2072,7 @@ function reapScratch(context, dryRun) {
   for (const [dir, patterns] of scanned) {
     let entries;
     try {
-      entries = (0, import_node_fs14.readdirSync)(dir, { withFileTypes: true });
+      entries = (0, import_node_fs15.readdirSync)(dir, { withFileTypes: true });
     } catch {
       unreadable.push(dir);
       continue;
@@ -1896,7 +2083,7 @@ function reapScratch(context, dryRun) {
       const path = (0, import_node_path12.join)(dir, entry.name);
       let ageMs;
       try {
-        ageMs = now - (0, import_node_fs14.statSync)(path).mtimeMs;
+        ageMs = now - (0, import_node_fs15.statSync)(path).mtimeMs;
       } catch {
         continue;
       }
@@ -1906,7 +2093,7 @@ function reapScratch(context, dryRun) {
         continue;
       }
       try {
-        (0, import_node_fs14.rmSync)(path, { force: true });
+        (0, import_node_fs15.rmSync)(path, { force: true });
         reaped += 1;
       } catch (error) {
         failures.push(`${entry.name}: ${error?.code ?? error?.message ?? error}`);
@@ -2183,10 +2370,7 @@ function reconcile(options) {
           continue;
         }
         const atomicity = checkAtomicity(paths.gitCache, gate.tagCommit, gate.bom, candidate, {
-          distIntegrity: (spec) => {
-            const integrity = npmView(spec, "dist.integrity", env);
-            return typeof integrity === "string" ? integrity : null;
-          }
+          distIntegrity: (spec) => npmDistIntegrity(spec, env)
         });
         if (!atomicity.ok) {
           journal({ kind: "candidate-reject", to: candidate, verdict: "skip", detail: `atomicity: ${atomicity.rows.filter((row) => !row.ok).map((row) => row.detail).join("; ")}` });
@@ -2254,8 +2438,8 @@ function reconcile(options) {
 
 // src/scheduler.ts
 var import_node_child_process11 = require("node:child_process");
-var import_node_fs15 = require("node:fs");
-var import_node_os5 = require("node:os");
+var import_node_fs16 = require("node:fs");
+var import_node_os6 = require("node:os");
 var import_node_path13 = require("node:path");
 var TASK_NAME = "MMI Fleet Updater";
 var LAUNCHER_FILE = "reconcile-hidden.vbs";
@@ -2414,7 +2598,7 @@ WantedBy=timers.target
 }
 function readFileOrNull(path) {
   try {
-    return (0, import_node_fs15.readFileSync)(path, "utf8");
+    return (0, import_node_fs16.readFileSync)(path, "utf8");
   } catch {
     return null;
   }
@@ -2488,7 +2672,7 @@ function windowsSchedulerStatus(env) {
   return { ok: true, supported: true, enabled: true, ...runInfo, detail: `"${TASK_NAME}" registered ${CADENCE}; ${points}; ${ran}; next ${runInfo.nextRunTime ?? "unscheduled"}` };
 }
 function darwinSchedulerStatus(env) {
-  const plistPath = (0, import_node_path13.join)((0, import_node_os5.homedir)(), "Library", "LaunchAgents", LAUNCHD_PLIST_NAME);
+  const plistPath = (0, import_node_path13.join)((0, import_node_os6.homedir)(), "Library", "LaunchAgents", LAUNCHD_PLIST_NAME);
   const plist = readFileOrNull(plistPath);
   if (!plist) {
     return { ok: false, supported: true, enabled: false, ...EMPTY_RUN_INFO, detail: `"${LAUNCHD_LABEL}" is not registered \u2014 run \`mmi-hub autoupdate on\`` };
@@ -2514,7 +2698,7 @@ function darwinSchedulerStatus(env) {
   return { ok: true, supported: true, enabled: true, ...EMPTY_RUN_INFO, detail: `"${LAUNCHD_LABEL}" registered ${POSIX_CADENCE}; ${points}` };
 }
 function linuxSchedulerStatus(env) {
-  const unitDir = (0, import_node_path13.join)((0, import_node_os5.homedir)(), ".config", "systemd", "user");
+  const unitDir = (0, import_node_path13.join)((0, import_node_os6.homedir)(), ".config", "systemd", "user");
   const timerPath = (0, import_node_path13.join)(unitDir, SYSTEMD_TIMER_NAME);
   const timer = readFileOrNull(timerPath);
   const service = readFileOrNull((0, import_node_path13.join)(unitDir, SYSTEMD_SERVICE_NAME));
@@ -2562,9 +2746,9 @@ function installWindowsTask(env) {
   const userId = `${env.USERDOMAIN || env.COMPUTERNAME || ""}\\${env.USERNAME || ""}`.replace(/^\\/, "");
   if (!env.USERNAME) return { ok: false, detail: "cannot resolve the registering user (USERNAME unset) \u2014 the task principal must be explicit" };
   const launcherPath = (0, import_node_path13.join)(paths.root, LAUNCHER_FILE);
-  (0, import_node_fs15.writeFileSync)(launcherPath, launcherVbs(process.execPath, hubDist), "utf8");
+  (0, import_node_fs16.writeFileSync)(launcherPath, launcherVbs(process.execPath, hubDist), "utf8");
   const xmlPath = (0, import_node_path13.join)(paths.root, "task.xml");
-  (0, import_node_fs15.writeFileSync)(xmlPath, "\uFEFF" + taskXml(launcherPath, paths.root, userId, localStartBoundary(/* @__PURE__ */ new Date())), "utf16le");
+  (0, import_node_fs16.writeFileSync)(xmlPath, "\uFEFF" + taskXml(launcherPath, paths.root, userId, localStartBoundary(/* @__PURE__ */ new Date())), "utf16le");
   const create = schtasks(["/create", "/tn", TASK_NAME, "/xml", xmlPath, "/f"]);
   if (create.status !== 0) {
     const denied = /access is denied/i.test(create.stderr + create.stdout);
@@ -2583,8 +2767,8 @@ function refreshPosixLauncher(env) {
   const launcherPath = (0, import_node_path13.join)(paths.root, POSIX_LAUNCHER_FILE);
   const desired = launcherSh(process.execPath, hubDist);
   if (readFileOrNull(launcherPath) === desired) return null;
-  (0, import_node_fs15.writeFileSync)(launcherPath, desired, "utf8");
-  (0, import_node_fs15.chmodSync)(launcherPath, 493);
+  (0, import_node_fs16.writeFileSync)(launcherPath, desired, "utf8");
+  (0, import_node_fs16.chmodSync)(launcherPath, 493);
   return launcherPath;
 }
 function installLaunchd(env) {
@@ -2597,12 +2781,12 @@ function installLaunchd(env) {
   if (!hubDist) return { ok: false, detail: "cannot resolve the global @mutmutco/hub dist \u2014 run `npm install -g @mutmutco/hub` first" };
   const paths = ensureState(env);
   const launcherPath = (0, import_node_path13.join)(paths.root, POSIX_LAUNCHER_FILE);
-  (0, import_node_fs15.writeFileSync)(launcherPath, launcherSh(process.execPath, hubDist), "utf8");
-  (0, import_node_fs15.chmodSync)(launcherPath, 493);
-  const agentsDir = (0, import_node_path13.join)((0, import_node_os5.homedir)(), "Library", "LaunchAgents");
-  (0, import_node_fs15.mkdirSync)(agentsDir, { recursive: true });
+  (0, import_node_fs16.writeFileSync)(launcherPath, launcherSh(process.execPath, hubDist), "utf8");
+  (0, import_node_fs16.chmodSync)(launcherPath, 493);
+  const agentsDir = (0, import_node_path13.join)((0, import_node_os6.homedir)(), "Library", "LaunchAgents");
+  (0, import_node_fs16.mkdirSync)(agentsDir, { recursive: true });
   const plistPath = (0, import_node_path13.join)(agentsDir, LAUNCHD_PLIST_NAME);
-  (0, import_node_fs15.writeFileSync)(plistPath, launchdPlist(launcherPath, paths.root), "utf8");
+  (0, import_node_fs16.writeFileSync)(plistPath, launchdPlist(launcherPath, paths.root), "utf8");
   launchctl(["bootout", `gui/${uid()}/${LAUNCHD_LABEL}`]);
   const load = launchctl(["bootstrap", `gui/${uid()}`, plistPath]);
   if (load.status !== 0) {
@@ -2621,12 +2805,12 @@ function installSystemdTimer(env) {
   if (!hubDist) return { ok: false, detail: "cannot resolve the global @mutmutco/hub dist \u2014 run `npm install -g @mutmutco/hub` first" };
   const paths = ensureState(env);
   const launcherPath = (0, import_node_path13.join)(paths.root, POSIX_LAUNCHER_FILE);
-  (0, import_node_fs15.writeFileSync)(launcherPath, launcherSh(process.execPath, hubDist), "utf8");
-  (0, import_node_fs15.chmodSync)(launcherPath, 493);
-  const unitDir = (0, import_node_path13.join)((0, import_node_os5.homedir)(), ".config", "systemd", "user");
-  (0, import_node_fs15.mkdirSync)(unitDir, { recursive: true });
-  (0, import_node_fs15.writeFileSync)((0, import_node_path13.join)(unitDir, SYSTEMD_SERVICE_NAME), systemdServiceUnit(launcherPath, paths.root), "utf8");
-  (0, import_node_fs15.writeFileSync)((0, import_node_path13.join)(unitDir, SYSTEMD_TIMER_NAME), systemdTimerUnit(), "utf8");
+  (0, import_node_fs16.writeFileSync)(launcherPath, launcherSh(process.execPath, hubDist), "utf8");
+  (0, import_node_fs16.chmodSync)(launcherPath, 493);
+  const unitDir = (0, import_node_path13.join)((0, import_node_os6.homedir)(), ".config", "systemd", "user");
+  (0, import_node_fs16.mkdirSync)(unitDir, { recursive: true });
+  (0, import_node_fs16.writeFileSync)((0, import_node_path13.join)(unitDir, SYSTEMD_SERVICE_NAME), systemdServiceUnit(launcherPath, paths.root), "utf8");
+  (0, import_node_fs16.writeFileSync)((0, import_node_path13.join)(unitDir, SYSTEMD_TIMER_NAME), systemdTimerUnit(), "utf8");
   const reload = systemctlUser(["daemon-reload"]);
   if (reload.status !== 0) {
     return { ok: false, detail: `systemctl --user daemon-reload failed: ${(reload.stderr || reload.stdout).trim() || "unknown error \u2014 is a user systemd instance running?"}` };
@@ -2664,28 +2848,28 @@ function uninstallWindowsTask(env) {
   return { ok: true, detail: `automatic updates off \u2014 removed "${TASK_NAME}"; installed tooling was kept` };
 }
 function uninstallLaunchd(env) {
-  const plistPath = (0, import_node_path13.join)((0, import_node_os5.homedir)(), "Library", "LaunchAgents", LAUNCHD_PLIST_NAME);
+  const plistPath = (0, import_node_path13.join)((0, import_node_os6.homedir)(), "Library", "LaunchAgents", LAUNCHD_PLIST_NAME);
   const boot = launchctl(["bootout", `gui/${uid()}/${LAUNCHD_LABEL}`]);
-  if (boot.status !== 0 && (0, import_node_fs15.existsSync)(plistPath)) {
+  if (boot.status !== 0 && (0, import_node_fs16.existsSync)(plistPath)) {
     return { ok: false, detail: `launchctl bootout failed: ${(boot.stderr || boot.stdout).trim() || "unknown error"}` };
   }
   try {
-    (0, import_node_fs15.rmSync)(plistPath, { force: true });
+    (0, import_node_fs16.rmSync)(plistPath, { force: true });
   } catch {
   }
   dropLauncher(env, POSIX_LAUNCHER_FILE);
   return { ok: true, detail: `automatic updates off \u2014 removed "${LAUNCHD_LABEL}"; installed tooling was kept` };
 }
 function uninstallSystemdTimer(env) {
-  const unitDir = (0, import_node_path13.join)((0, import_node_os5.homedir)(), ".config", "systemd", "user");
+  const unitDir = (0, import_node_path13.join)((0, import_node_os6.homedir)(), ".config", "systemd", "user");
   const timerPath = (0, import_node_path13.join)(unitDir, SYSTEMD_TIMER_NAME);
   const disable = systemctlUser(["disable", "--now", SYSTEMD_TIMER_NAME]);
-  if (disable.status !== 0 && (0, import_node_fs15.existsSync)(timerPath)) {
+  if (disable.status !== 0 && (0, import_node_fs16.existsSync)(timerPath)) {
     return { ok: false, detail: `systemctl --user disable --now ${SYSTEMD_TIMER_NAME} failed: ${(disable.stderr || disable.stdout).trim() || "unknown error"}` };
   }
   try {
-    (0, import_node_fs15.rmSync)(timerPath, { force: true });
-    (0, import_node_fs15.rmSync)((0, import_node_path13.join)(unitDir, SYSTEMD_SERVICE_NAME), { force: true });
+    (0, import_node_fs16.rmSync)(timerPath, { force: true });
+    (0, import_node_fs16.rmSync)((0, import_node_path13.join)(unitDir, SYSTEMD_SERVICE_NAME), { force: true });
   } catch {
   }
   systemctlUser(["daemon-reload"]);
@@ -2700,16 +2884,16 @@ function uninstallTask(env = process.env) {
 }
 function dropLauncher(env, file) {
   try {
-    (0, import_node_fs15.rmSync)((0, import_node_path13.join)(statePaths(env).root, file), { force: true });
+    (0, import_node_fs16.rmSync)((0, import_node_path13.join)(statePaths(env).root, file), { force: true });
   } catch {
   }
 }
 
 // src/status.ts
-var import_node_fs16 = require("node:fs");
+var import_node_fs17 = require("node:fs");
 function readJournal(path) {
   try {
-    const events = (0, import_node_fs16.readFileSync)(path, "utf8").split("\n").filter((line) => line.trim()).map((line) => {
+    const events = (0, import_node_fs17.readFileSync)(path, "utf8").split("\n").filter((line) => line.trim()).map((line) => {
       try {
         return JSON.parse(line);
       } catch {
@@ -3087,7 +3271,7 @@ function startSpinner(enabled) {
 // src/index.ts
 function ownVersion() {
   try {
-    return JSON.parse((0, import_node_fs17.readFileSync)((0, import_node_path14.join)(__dirname, "..", "package.json"), "utf8")).version;
+    return JSON.parse((0, import_node_fs18.readFileSync)((0, import_node_path14.join)(__dirname, "..", "package.json"), "utf8")).version;
   } catch {
     return "0.0.0";
   }
@@ -3213,6 +3397,7 @@ if (typeof require !== "undefined" && require.main === module) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  acquireSharedDocLock,
   buildWatcherCommand,
   clearPending,
   enumerateSurfaces,
@@ -3220,6 +3405,7 @@ if (typeof require !== "undefined" && require.main === module) {
   formatReconcileReport,
   hermesArm,
   hermesHome,
+  hermesHostEvidence,
   hubStatus,
   launchdPlist,
   launcherSh,
@@ -3228,23 +3414,31 @@ if (typeof require !== "undefined" && require.main === module) {
   lockShaped,
   main,
   noteBusyDefer,
+  npmStringField,
   ownVersion,
+  parseNpmDistIntegrity,
   pendingPath,
   pidAlive,
   probeHermesInstallation,
   progressiveRow,
   readPending,
   reconcileCursorUserHooks,
+  reconcileKimiInstalledPlugin,
+  releaseSharedDocLock,
   reportFooterLines,
   retryHint,
   schedulePendingWatcher,
   schedulerStatus,
+  sharedDocLockPath,
+  sharedDocLockTimeoutReceipt,
   startSpinner,
   systemdServiceUnit,
   systemdTimerUnit,
   taskXml,
   updateHeader,
+  validateKimiInstalledPlugin,
   watcherLockPath,
+  withSharedDocLock,
   wrapWords,
   writePending
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/hub",
-  "version": "4.1.3",
+  "version": "4.1.4",
   "description": "Install and maintain the MMI CLI and every present host surface from one release-gated Hub command.",
   "type": "module",
   "license": "UNLICENSED",