@remnic/core 9.7.6 → 9.7.8

package/dist/{chunk-H67QFYUK.js → chunk-UJBESW6X.js}

@@ -32,15 +32,310 @@ import {
 } from "./chunk-37CTGERM.js";
 
 // src/connectors/index.ts
-import fs2 from "fs";
-import path2 from "path";
+import fs3 from "fs";
+import path3 from "path";
 import os from "os";
 import { createRequire } from "module";
 import { fileURLToPath } from "url";
 
-// src/connectors/codex-marketplace.ts
+// src/connectors/hermes-shim.ts
 import fs from "fs";
 import path from "path";
+var HERMES_SHIM_MARKER = "generated by `remnic connectors install hermes`";
+function resolveHermesRoot() {
+  const envHome = readEnvVar("HERMES_HOME");
+  if (typeof envHome === "string" && envHome.trim().length > 0) {
+    const expanded = path.resolve(expandTildePath(envHome.trim()));
+    try {
+      const stat = fs.lstatSync(expanded);
+      if (stat.isSymbolicLink()) {
+        throw new Error(`HERMES_HOME must not be a symbolic link: ${expanded}`);
+      }
+      if (!stat.isDirectory()) {
+        throw new Error(`HERMES_HOME is not a directory: ${expanded}`);
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        throw err;
+      }
+    }
+    return expanded;
+  }
+  if (process.platform === "win32") {
+    const localAppData = (readEnvVar("LOCALAPPDATA") ?? "").trim();
+    const base = localAppData.length > 0 ? path.resolve(localAppData) : path.join(resolveHomeDir(), "AppData", "Local");
+    return resolveDefaultRoot(path.join(base, "hermes"));
+  }
+  return resolveDefaultRoot(path.resolve(resolveHomeDir(), ".hermes"));
+}
+function resolveDefaultRoot(candidate) {
+  try {
+    return fs.realpathSync.native(candidate);
+  } catch {
+    return candidate;
+  }
+}
+function hermesShimPath() {
+  return path.join(resolveHermesRoot(), "plugins", "remnic", "__init__.py");
+}
+function writePlainFileAtomicSync(filePath, data) {
+  const dir = path.dirname(filePath);
+  const base = path.basename(filePath);
+  const tmpPath = path.join(dir, `.${base}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+  let wroteTemp = false;
+  try {
+    fs.writeFileSync(tmpPath, data, { mode: 420, flag: "wx" });
+    wroteTemp = true;
+    fs.renameSync(tmpPath, filePath);
+    try {
+      fs.chmodSync(filePath, 420);
+    } catch {
+    }
+  } catch (err) {
+    if (wroteTemp) {
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+      }
+    }
+    throw err;
+  }
+}
+function assertShimComponentsNotSymlinked(shimPath) {
+  const remnicDir = path.dirname(shimPath);
+  const pluginsDir = path.dirname(remnicDir);
+  for (const component of [pluginsDir, remnicDir, shimPath]) {
+    let isLink = false;
+    try {
+      isLink = fs.lstatSync(component).isSymbolicLink();
+    } catch {
+      continue;
+    }
+    if (isLink) {
+      throw new Error(`refusing to operate through a symbolic link: ${component}`);
+    }
+  }
+}
+function materializeHermesShim(shimPath) {
+  assertShimComponentsNotSymlinked(shimPath);
+  if (fs.existsSync(shimPath)) {
+    let existing;
+    try {
+      existing = fs.readFileSync(shimPath, "utf8");
+    } catch (readErr) {
+      throw new Error(
+        `cannot read existing shim at ${shimPath}: ${readErr instanceof Error ? readErr.message : String(readErr)}`
+      );
+    }
+    if (!existing.includes(HERMES_SHIM_MARKER)) {
+      return {
+        note: `Hermes plugin shim already exists and was NOT generated by Remnic \u2014 left untouched: ${shimPath}. If the provider is not discovered, ensure that file imports remnic_hermes.register AND contains the literal text register_memory_provider (or MemoryProvider) \u2014 Hermes' discovery text-scan skips the directory without it.`,
+        wrote: false
+      };
+    }
+  }
+  fs.mkdirSync(path.dirname(shimPath), { recursive: true });
+  const content = [
+    `"""Remnic memory provider shim for Hermes Agent (${HERMES_SHIM_MARKER}).`,
+    "",
+    "Hermes memory-provider discovery calls register(collector);",
+    "collector.register_memory_provider() receives the provider.",
+    `"""`,
+    "",
+    "from remnic_hermes import register  # noqa: F401  (register() loads Hermes config itself)",
+    ""
+  ].join("\n");
+  writePlainFileAtomicSync(shimPath, content);
+  return { note: `Materialized Hermes plugin shim: ${shimPath}`, wrote: true };
+}
+function reconcileHermesShim(priorPersistedPath) {
+  const notes = [];
+  let target = null;
+  let materialized = false;
+  let createdNew = false;
+  try {
+    target = hermesShimPath();
+    const existedBefore = fs.existsSync(target);
+    const result = materializeHermesShim(target);
+    notes.push(result.note);
+    materialized = result.wrote;
+    createdNew = result.wrote && !existedBefore;
+  } catch (shimErr) {
+    const shimPathHint = target ?? "<hermesRoot>/plugins/remnic/__init__.py";
+    notes.push(
+      `Note: could not materialize the Hermes plugin shim (${shimErr instanceof Error ? shimErr.message : String(shimErr)}). Create ${shimPathHint} manually with exactly these two lines:
+    """Remnic memory provider shim. Calls collector.register_memory_provider()."""
+    from remnic_hermes import register`
+    );
+  }
+  if (!materialized || target === null) {
+    return {
+      notes,
+      persistPath: priorPersistedPath,
+      materializedAt: null,
+      createdNew: false,
+      priorCleanedAt: null
+    };
+  }
+  const confirmedTarget = target;
+  let priorCleanedAt = null;
+  if (priorPersistedPath !== null && !sameShimTarget(priorPersistedPath, confirmedTarget)) {
+    try {
+      const stale = removeHermesShim([priorPersistedPath]);
+      if (stale.notes.length > 0) {
+        notes.push(`Cleaned prior-install shim: ${stale.notes.join("; ")}`);
+      }
+      priorCleanedAt = stale.removedPaths.includes(priorPersistedPath) ? priorPersistedPath : null;
+    } catch {
+      notes.push(
+        `Note: could not clean the prior-install Hermes plugin shim at ${priorPersistedPath} \u2014 remove it manually if present.`
+      );
+    }
+  }
+  return { notes, persistPath: target, materializedAt: target, createdNew, priorCleanedAt };
+}
+function sameShimTarget(leftPath, rightPath) {
+  return resolveShimTarget(leftPath) === resolveShimTarget(rightPath);
+}
+function resolveShimTarget(candidate) {
+  try {
+    return fs.realpathSync.native(candidate);
+  } catch {
+    return path.resolve(candidate);
+  }
+}
+function removeHermesShim(candidatePaths) {
+  const notes = [];
+  const removedPaths = [];
+  for (const shimPath of new Set(candidatePaths)) {
+    if (!isPlausibleHermesShimPath(shimPath)) {
+      continue;
+    }
+    try {
+      assertShimComponentsNotSymlinked(shimPath);
+    } catch {
+      notes.push(`Hermes plugin shim left untouched (symlinked path component): ${shimPath}`);
+      continue;
+    }
+    if (!fs.existsSync(shimPath)) {
+      continue;
+    }
+    let content;
+    try {
+      content = fs.readFileSync(shimPath, "utf8");
+    } catch {
+      notes.push(`Hermes plugin shim left untouched (unreadable): ${shimPath}`);
+      continue;
+    }
+    if (!content.includes(HERMES_SHIM_MARKER)) {
+      notes.push(`Hermes plugin shim left untouched (not Remnic-generated): ${shimPath}`);
+      continue;
+    }
+    try {
+      fs.unlinkSync(shimPath);
+    } catch (unlinkErr) {
+      notes.push(
+        `Hermes plugin shim could not be removed (${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}): ${shimPath} \u2014 remove it manually or re-run after fixing permissions.`
+      );
+      continue;
+    }
+    removedPaths.push(shimPath);
+    try {
+      fs.rmdirSync(path.dirname(shimPath));
+    } catch {
+    }
+    notes.push(`Removed Hermes plugin shim: ${shimPath}`);
+  }
+  return { removedPaths, notes };
+}
+function isPlausibleHermesShimPath(candidate) {
+  if (typeof candidate !== "string" || candidate.length === 0 || !path.isAbsolute(candidate)) {
+    return false;
+  }
+  const dir = path.dirname(candidate);
+  return path.basename(candidate) === "__init__.py" && path.basename(dir) === "remnic" && path.basename(path.dirname(dir)) === "plugins";
+}
+function isPlausibleHermesConfigPath(candidate) {
+  if (typeof candidate !== "string" || candidate.length === 0 || !path.isAbsolute(candidate)) {
+    return false;
+  }
+  if (path.basename(candidate) !== "config.yaml") {
+    return false;
+  }
+  const dir = path.dirname(candidate);
+  const dirName = path.basename(dir).toLowerCase();
+  if (dirName === ".hermes" || dirName === "hermes") {
+    return true;
+  }
+  if (path.basename(path.dirname(dir)) === "profiles") {
+    return true;
+  }
+  if (["plugins", "profiles"].some((sibling) => {
+    try {
+      return fs.statSync(path.join(dir, sibling)).isDirectory();
+    } catch {
+      return false;
+    }
+  })) {
+    return true;
+  }
+  try {
+    const stat = fs.statSync(candidate);
+    if (!stat.isFile() || stat.size > 1024 * 1024) {
+      return false;
+    }
+    return /^remnic:/m.test(fs.readFileSync(candidate, "utf8"));
+  } catch {
+    return false;
+  }
+}
+function survivingMarkerShims(candidates, excludeTarget) {
+  const survivors = [];
+  for (const candidate of new Set(candidates)) {
+    if (!isPlausibleHermesShimPath(candidate)) {
+      continue;
+    }
+    if (excludeTarget !== null && sameShimTarget(candidate, excludeTarget)) {
+      continue;
+    }
+    if (survivors.some((kept) => sameShimTarget(kept, candidate))) {
+      continue;
+    }
+    let carriesMarker = false;
+    try {
+      carriesMarker = fs.readFileSync(candidate, "utf8").includes(HERMES_SHIM_MARKER);
+    } catch {
+      carriesMarker = false;
+    }
+    if (carriesMarker) {
+      survivors.push(candidate);
+    }
+  }
+  return survivors;
+}
+function assertConfigComponentsNotSymlinked(cfgPath) {
+  const dir = path.dirname(cfgPath);
+  const components = [cfgPath, dir];
+  const grandparent = path.dirname(dir);
+  if (path.basename(grandparent) === "profiles") {
+    components.push(grandparent);
+  }
+  for (const component of components) {
+    let isLink = false;
+    try {
+      isLink = fs.lstatSync(component).isSymbolicLink();
+    } catch {
+      continue;
+    }
+    if (isLink) {
+      throw new Error(`refusing to operate through a symbolic link: ${component}`);
+    }
+  }
+}
+
+// src/connectors/codex-marketplace.ts
+import fs2 from "fs";
+import path2 from "path";
 var MARKETPLACE_SCHEMA_VERSION = 1;
 var MARKETPLACE_MANIFEST_FILENAME = "marketplace.json";
 var VALID_INSTALL_TYPES = /* @__PURE__ */ new Set(["github", "git", "local", "url"]);
@@ -142,12 +437,12 @@ async function writeMarketplaceManifest(outputDir, manifest) {
       `Refusing to write invalid manifest: ${validation.errors.join("; ")}`
     );
   }
-  fs.mkdirSync(outputDir, { recursive: true });
-  const destPath = path.join(outputDir, MARKETPLACE_MANIFEST_FILENAME);
+  fs2.mkdirSync(outputDir, { recursive: true });
+  const destPath = path2.join(outputDir, MARKETPLACE_MANIFEST_FILENAME);
   const tmpPath = `${destPath}.tmp.${process.pid}`;
   const content = JSON.stringify(manifest, null, 2) + "\n";
-  fs.writeFileSync(tmpPath, content);
-  fs.renameSync(tmpPath, destPath);
+  fs2.writeFileSync(tmpPath, content);
+  fs2.renameSync(tmpPath, destPath);
 }
 async function installFromMarketplace(source, sourceType, config, logger) {
   const _log = logger ?? {
@@ -207,12 +502,12 @@ async function resolveManifest(source, sourceType, logger) {
   }
 }
 function resolveLocal(dirPath, logger) {
-  const manifestPath = path.join(dirPath, MARKETPLACE_MANIFEST_FILENAME);
-  if (!fs.existsSync(manifestPath)) {
+  const manifestPath = path2.join(dirPath, MARKETPLACE_MANIFEST_FILENAME);
+  if (!fs2.existsSync(manifestPath)) {
     throw new Error(`marketplace.json not found at ${manifestPath}`);
   }
   logger.debug?.(`reading local marketplace manifest: ${manifestPath}`);
-  const raw = fs.readFileSync(manifestPath, "utf-8");
+  const raw = fs2.readFileSync(manifestPath, "utf-8");
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -264,15 +559,15 @@ async function resolveGit(gitUrl, logger) {
 }
 function readPackageVersion() {
   const candidates = [
-    path.resolve(import.meta.dirname ?? ".", "../../../.."),
-    path.resolve(import.meta.dirname ?? ".", "../../../../.."),
-    path.resolve(import.meta.dirname ?? ".", "..")
+    path2.resolve(import.meta.dirname ?? ".", "../../../.."),
+    path2.resolve(import.meta.dirname ?? ".", "../../../../.."),
+    path2.resolve(import.meta.dirname ?? ".", "..")
   ];
   for (const candidate of candidates) {
-    const pkgPath = path.join(candidate, "package.json");
+    const pkgPath = path2.join(candidate, "package.json");
     try {
-      if (!fs.existsSync(pkgPath)) continue;
-      const raw = fs.readFileSync(pkgPath, "utf-8");
+      if (!fs2.existsSync(pkgPath)) continue;
+      const raw = fs2.readFileSync(pkgPath, "utf-8");
       const parsed = JSON.parse(raw);
       if (typeof parsed === "object" && parsed !== null && typeof parsed.version === "string") {
         return parsed.version;
@@ -642,7 +937,7 @@ function isConnectorManifest(value) {
 }
 function loadRegistry() {
   const regPath = getRegistryPath();
-  if (!fs2.existsSync(regPath)) {
+  if (!fs3.existsSync(regPath)) {
     const registry = {
       connectors: BUILTIN_CONNECTORS,
       registryPath: regPath
@@ -651,7 +946,7 @@ function loadRegistry() {
     return registry;
   }
   try {
-    const raw = fs2.readFileSync(regPath, "utf8");
+    const raw = fs3.readFileSync(regPath, "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.connectors)) {
       throw new Error("invalid registry schema");
@@ -674,19 +969,19 @@ function loadRegistry() {
 }
 function saveRegistry(registry) {
   const regPath = registry.registryPath;
-  fs2.mkdirSync(path2.dirname(regPath), { recursive: true });
-  fs2.writeFileSync(regPath, JSON.stringify({ connectors: registry.connectors }, null, 2));
+  fs3.mkdirSync(path3.dirname(regPath), { recursive: true });
+  fs3.writeFileSync(regPath, JSON.stringify({ connectors: registry.connectors }, null, 2));
 }
 function listConnectors() {
   const registry = loadRegistry();
   const connectorsDir = getConnectorsDir();
   const installedIds = /* @__PURE__ */ new Set();
-  if (fs2.existsSync(connectorsDir)) {
-    for (const entry of fs2.readdirSync(connectorsDir)) {
+  if (fs3.existsSync(connectorsDir)) {
+    for (const entry of fs3.readdirSync(connectorsDir)) {
       if (entry.endsWith(".json")) {
         try {
           const config = JSON.parse(
-            fs2.readFileSync(path2.join(connectorsDir, entry), "utf8")
+            fs3.readFileSync(path3.join(connectorsDir, entry), "utf8")
           );
           if (isValidConnectorId(config.connectorId)) {
             installedIds.add(config.connectorId);
@@ -702,9 +997,9 @@ function listConnectors() {
   }));
   const installed = [];
   for (const id of installedIds) {
-    const configPath = path2.join(connectorsDir, `${id}.json`);
+    const configPath = path3.join(connectorsDir, `${id}.json`);
     try {
-      const raw = JSON.parse(fs2.readFileSync(configPath, "utf8"));
+      const raw = JSON.parse(fs3.readFileSync(configPath, "utf8"));
       const { token: _redacted, ...config } = raw;
       installed.push({
         connectorId: id,
@@ -728,9 +1023,9 @@ function getConnectorToken(connectorId) {
   }
 }
 function readSavedConnectorConfig(configPath) {
-  if (!fs2.existsSync(configPath)) return {};
+  if (!fs3.existsSync(configPath)) return {};
   try {
-    const parsed = JSON.parse(fs2.readFileSync(configPath, "utf8"));
+    const parsed = JSON.parse(fs3.readFileSync(configPath, "utf8"));
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
     const {
       connectorId: _connectorId,
@@ -781,15 +1076,134 @@ function installConnector(options) {
     (c) => c.connectorId === options.connectorId
   );
   if (existing && !options.force) {
+    let backfillNote = "";
+    if (options.connectorId === "hermes") {
+      try {
+        const hermesJsonPath = path3.join(getConnectorsDir(), "hermes.json");
+        let parsed = null;
+        try {
+          const parsedRaw = JSON.parse(fs3.readFileSync(hermesJsonPath, "utf8"));
+          if (parsedRaw !== null && typeof parsedRaw === "object" && !Array.isArray(parsedRaw)) {
+            parsed = parsedRaw;
+          }
+        } catch {
+        }
+        const priorRaw = parsed?.pluginShimPath;
+        const priorPersisted = typeof priorRaw === "string" && priorRaw.length > 0 ? priorRaw : null;
+        const profileRaw = parsed?.profile;
+        let currentConfigPath = null;
+        let activeConfigHasBlock = false;
+        let configResolutionError = null;
+        try {
+          currentConfigPath = hermesConfigPath(
+            typeof profileRaw === "string" && profileRaw.length > 0 ? profileRaw : "default"
+          );
+          activeConfigHasBlock = fs3.existsSync(currentConfigPath) && /^remnic:/m.test(fs3.readFileSync(currentConfigPath, "utf8"));
+        } catch (resolveErr) {
+          configResolutionError = resolveErr instanceof Error ? resolveErr.message : String(resolveErr);
+          activeConfigHasBlock = false;
+        }
+        if (!activeConfigHasBlock) {
+          backfillNote = configResolutionError ? ` Note: could not resolve the active Hermes home (${configResolutionError}) \u2014 skipped the shim backfill. Fix the HERMES_HOME/profile configuration and re-run.` : " Note: the active Hermes home's config.yaml has no remnic: block \u2014 skipped the shim backfill so Hermes cannot discover an unconfigured provider. If Hermes was installed under a different HERMES_HOME, re-run with --force to rewrite the config (and token) and migrate the shim under the current home.";
+          return {
+            connectorId: options.connectorId,
+            status: "already_installed",
+            message: `Already installed. Use --force to reinstall.${backfillNote}`
+          };
+        }
+        const outcome = reconcileHermesShim(priorPersisted);
+        if (outcome.notes.length > 0) {
+          backfillNote = ` ${outcome.notes.join(" ")}`;
+        }
+        let configProvenanceAdded = false;
+        if (parsed !== null && currentConfigPath !== null && (typeof parsed.hermesConfigPath !== "string" || parsed.hermesConfigPath.length === 0)) {
+          parsed.hermesConfigPath = currentConfigPath;
+          configProvenanceAdded = true;
+        }
+        let shimPriorsChanged = false;
+        const cleanedInheritedBackfillShims = [];
+        if (parsed !== null) {
+          const shimPriorCandidates = [];
+          if (priorPersisted !== null) {
+            shimPriorCandidates.push(priorPersisted);
+          }
+          if (Array.isArray(parsed.priorPluginShimPaths)) {
+            for (const entry of parsed.priorPluginShimPaths) {
+              if (typeof entry === "string" && entry.length > 0) {
+                shimPriorCandidates.push(entry);
+              }
+            }
+          }
+          if (outcome.materializedAt !== null && shimPriorCandidates.length > 0) {
+            const cleanupTargets = shimPriorCandidates.filter(
+              (candidate) => outcome.persistPath === null || !sameShimTarget(candidate, outcome.persistPath)
+            );
+            if (cleanupTargets.length > 0) {
+              try {
+                const cleaned = removeHermesShim(cleanupTargets);
+                cleanedInheritedBackfillShims.push(...cleaned.removedPaths);
+              } catch {
+              }
+            }
+          }
+          const survivingShims = survivingMarkerShims(shimPriorCandidates, outcome.persistPath);
+          const persistedShimPriors = Array.isArray(parsed.priorPluginShimPaths) ? parsed.priorPluginShimPaths : null;
+          shimPriorsChanged = persistedShimPriors === null ? survivingShims.length > 0 : persistedShimPriors.length !== survivingShims.length || survivingShims.some((entry, index) => persistedShimPriors[index] !== entry);
+          if (survivingShims.length > 0) {
+            parsed.priorPluginShimPaths = survivingShims;
+          } else {
+            delete parsed.priorPluginShimPaths;
+          }
+        }
+        const shimPathChanged = parsed !== null && outcome.persistPath !== null && parsed.pluginShimPath !== outcome.persistPath;
+        if (parsed !== null && (shimPathChanged || configProvenanceAdded || shimPriorsChanged)) {
+          if (outcome.persistPath !== null) {
+            parsed.pluginShimPath = outcome.persistPath;
+          }
+          try {
+            writeSecretFileSync(hermesJsonPath, JSON.stringify(parsed, null, 2));
+          } catch (persistErr) {
+            const rollbackFailures = [];
+            if (outcome.materializedAt !== null && outcome.createdNew && (priorPersisted === null || !sameShimTarget(outcome.materializedAt, priorPersisted))) {
+              try {
+                removeHermesShim([outcome.materializedAt]);
+              } catch {
+                rollbackFailures.push(`remove ${outcome.materializedAt} manually`);
+              }
+            }
+            if (outcome.priorCleanedAt !== null) {
+              try {
+                materializeHermesShim(outcome.priorCleanedAt);
+              } catch {
+                rollbackFailures.push(`restore the shim at ${outcome.priorCleanedAt} manually`);
+              }
+            }
+            for (const cleanedPath of cleanedInheritedBackfillShims) {
+              if (outcome.priorCleanedAt !== null && sameShimTarget(cleanedPath, outcome.priorCleanedAt)) {
+                continue;
+              }
+              try {
+                materializeHermesShim(cleanedPath);
+              } catch {
+                rollbackFailures.push(`restore the shim at ${cleanedPath} manually`);
+              }
+            }
+            const persistMsg = persistErr instanceof Error ? persistErr.message : String(persistErr);
+            backfillNote = rollbackFailures.length === 0 ? ` Note: could not persist the shim path (${persistMsg}); shim changes were rolled back.` : ` Note: could not persist the shim path (${persistMsg}) and rollback was incomplete \u2014 ${rollbackFailures.join("; ")}.`;
+          }
+        }
+      } catch {
+      }
+    }
     return {
       connectorId: options.connectorId,
       status: "already_installed",
-      message: "Already installed. Use --force to reinstall."
+      message: `Already installed. Use --force to reinstall.${backfillNote}`
     };
   }
   const configDir = getConnectorsDir();
-  fs2.mkdirSync(configDir, { recursive: true });
-  const configPath = path2.join(configDir, `${options.connectorId}.json`);
+  fs3.mkdirSync(configDir, { recursive: true });
+  const configPath = path3.join(configDir, `${options.connectorId}.json`);
   const savedConnectorConfig = existing ? readSavedConnectorConfig(configPath) : {};
   let hermesSavedProfile;
   let hermesSavedHost;
@@ -798,9 +1212,9 @@ function installConnector(options) {
   let hermesResolvedHost;
   let hermesResolvedPort;
   if (options.connectorId === "hermes") {
-    if (fs2.existsSync(configPath)) {
+    if (fs3.existsSync(configPath)) {
       try {
-        const prev = JSON.parse(fs2.readFileSync(configPath, "utf8"));
+        const prev = JSON.parse(fs3.readFileSync(configPath, "utf8"));
         if (prev?.profile != null) {
           try {
             hermesSavedProfile = sanitizeHermesProfile(String(prev.profile));
@@ -927,6 +1341,15 @@ function installConnector(options) {
         message: "Hermes install aborted: token store unavailable. Run `remnic token generate hermes` then reinstall to complete setup."
       };
     }
+    {
+      const envHermesHome = readEnvVar("HERMES_HOME");
+      if (typeof envHermesHome === "string" && envHermesHome.trim().length > 0) {
+        try {
+          fs3.mkdirSync(path3.dirname(hermesConfigPath(hermesProfile)), { recursive: true });
+        } catch {
+        }
+      }
+    }
     let yamlResult;
     try {
       yamlResult = upsertHermesConfig({
@@ -967,7 +1390,7 @@ function installConnector(options) {
       let yamlRollbackErrMsg = "";
       try {
         if (yamlResult.priorContent === null) {
-          fs2.unlinkSync(yamlResult.configPath);
+          fs3.unlinkSync(yamlResult.configPath);
         } else if (typeof yamlResult.priorContent === "string") {
           writeSecretFileSync(yamlResult.configPath, yamlResult.priorContent);
         }
@@ -992,6 +1415,140 @@ function installConnector(options) {
         message
       };
     }
+    const priorShimPathRaw = savedConnectorConfig.pluginShimPath;
+    const shimOutcome = reconcileHermesShim(
+      typeof priorShimPathRaw === "string" && priorShimPathRaw.length > 0 ? priorShimPathRaw : null
+    );
+    if (shimOutcome.persistPath !== null) {
+      resolvedConfig.pluginShimPath = shimOutcome.persistPath;
+    }
+    const cleanedInheritedShims = [];
+    {
+      const shimPriorCandidates = [];
+      if (typeof priorShimPathRaw === "string" && priorShimPathRaw.length > 0) {
+        shimPriorCandidates.push(priorShimPathRaw);
+      }
+      const inheritedShimPriorsRaw = savedConnectorConfig.priorPluginShimPaths;
+      if (Array.isArray(inheritedShimPriorsRaw)) {
+        for (const entry of inheritedShimPriorsRaw) {
+          if (typeof entry === "string" && entry.length > 0) {
+            shimPriorCandidates.push(entry);
+          }
+        }
+      }
+      if (shimOutcome.materializedAt !== null && shimPriorCandidates.length > 0) {
+        const cleanupTargets = shimPriorCandidates.filter(
+          (candidate) => shimOutcome.persistPath === null || !sameShimTarget(candidate, shimOutcome.persistPath)
+        );
+        if (cleanupTargets.length > 0) {
+          try {
+            const cleaned = removeHermesShim(cleanupTargets);
+            cleanedInheritedShims.push(...cleaned.removedPaths);
+          } catch {
+          }
+        }
+      }
+      const survivingShims = survivingMarkerShims(shimPriorCandidates, shimOutcome.persistPath);
+      if (survivingShims.length > 0) {
+        resolvedConfig.priorPluginShimPaths = survivingShims;
+      } else {
+        delete resolvedConfig.priorPluginShimPaths;
+      }
+    }
+    resolvedConfig.hermesConfigPath = yamlResult.configPath;
+    const hermesPriorNotes = [];
+    const priorConfigPathRaw = savedConnectorConfig.hermesConfigPath;
+    const priorConfigPath = typeof priorConfigPathRaw === "string" && priorConfigPathRaw.length > 0 ? priorConfigPathRaw : null;
+    const priorConfigDiffers = priorConfigPath !== null && !sameHermesConfigTarget(priorConfigPath, yamlResult.configPath);
+    const hermesPriorConfigMutations = [];
+    if (priorConfigDiffers && priorConfigPath !== null && shimOutcome.materializedAt === null) {
+      let fallbackDetail = "";
+      if (isPlausibleHermesConfigPath(priorConfigPath)) {
+        try {
+          const beforeRefresh = fs3.readFileSync(priorConfigPath, "utf8");
+          const refresh = upsertHermesConfigAt(priorConfigPath, {
+            host: hermesHost,
+            port: hermesPort,
+            token: tokenEntry.token
+          });
+          if (refresh.updated) {
+            hermesPriorConfigMutations.push({ mutatedPath: priorConfigPath, priorContent: beforeRefresh });
+          }
+          fallbackDetail = refresh.updated ? " Its remnic: block was refreshed with the newly-issued token so it keeps working." : ` Note: its token could not be refreshed (${refresh.reason ?? "config not writable"}) \u2014 re-run install with HERMES_HOME pointing there to restore daemon auth.`;
+        } catch (refreshErr) {
+          fallbackDetail = ` Note: its token could not be refreshed (${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}) \u2014 re-run install with HERMES_HOME pointing there to restore daemon auth.`;
+        }
+      } else {
+        fallbackDetail = " Note: its token was rotated by this install \u2014 re-run install with HERMES_HOME pointing there to restore daemon auth.";
+      }
+      hermesPriorNotes.push(
+        `Note: left the prior-install Hermes config in place at ${priorConfigPath} \u2014 no Remnic shim could be written under the current Hermes home, so the prior installation remains the working fallback.${fallbackDetail} Resolve the shim collision/failure above and re-run with --force to complete the migration.`
+      );
+    }
+    {
+      const candidates = [];
+      if (priorConfigDiffers && priorConfigPath !== null) {
+        candidates.push(priorConfigPath);
+      }
+      const inheritedArrayRaw = savedConnectorConfig.priorHermesConfigPaths;
+      if (Array.isArray(inheritedArrayRaw)) {
+        for (const entry of inheritedArrayRaw) {
+          if (typeof entry === "string" && entry.length > 0) {
+            candidates.push(entry);
+          }
+        }
+      }
+      const inheritedLegacyRaw = savedConnectorConfig.priorHermesConfigPath;
+      if (typeof inheritedLegacyRaw === "string" && inheritedLegacyRaw.length > 0) {
+        candidates.push(inheritedLegacyRaw);
+      }
+      if (shimOutcome.materializedAt !== null) {
+        for (const candidate of candidates) {
+          if (sameHermesConfigTarget(candidate, yamlResult.configPath)) {
+            continue;
+          }
+          if (!isPlausibleHermesConfigPath(candidate)) {
+            continue;
+          }
+          try {
+            const beforeCleanup = fs3.readFileSync(candidate, "utf8");
+            const cleanup = removeHermesConfigFile(candidate);
+            if (cleanup.updated) {
+              hermesPriorConfigMutations.push({ mutatedPath: candidate, priorContent: beforeCleanup });
+              hermesPriorNotes.push(`Cleaned remnic: block from prior-install Hermes config: ${candidate}`);
+            }
+          } catch {
+            hermesPriorNotes.push(
+              `Note: could not clean the remnic: block from the prior-install Hermes config at ${candidate} \u2014 remove it manually.`
+            );
+          }
+        }
+      }
+      const survivingPriors = [];
+      for (const candidate of candidates) {
+        if (sameHermesConfigTarget(candidate, yamlResult.configPath)) {
+          continue;
+        }
+        if (survivingPriors.some((kept) => sameHermesConfigTarget(kept, candidate))) {
+          continue;
+        }
+        let blockSurvives = false;
+        try {
+          blockSurvives = /^remnic:/m.test(fs3.readFileSync(candidate, "utf8"));
+        } catch {
+          blockSurvives = false;
+        }
+        if (blockSurvives) {
+          survivingPriors.push(candidate);
+        }
+      }
+      if (survivingPriors.length > 0) {
+        resolvedConfig.priorHermesConfigPaths = survivingPriors;
+      } else {
+        delete resolvedConfig.priorHermesConfigPaths;
+      }
+      delete resolvedConfig.priorHermesConfigPath;
+    }
     try {
       writeSecretFileSync(configPath, JSON.stringify(resolvedConfig, null, 2));
     } catch (writeErr) {
@@ -1009,7 +1566,7 @@ function installConnector(options) {
           let unlinkSucceeded = false;
           let unlinkErr;
           try {
-            fs2.unlinkSync(yamlResult.configPath);
+            fs3.unlinkSync(yamlResult.configPath);
             unlinkSucceeded = true;
           } catch (err) {
             unlinkErr = err;
@@ -1027,15 +1584,70 @@ function installConnector(options) {
       } catch (yamlRollbackErr) {
         yamlRollbackMsg = `config.yaml rollback failed: ${yamlRollbackErr instanceof Error ? yamlRollbackErr.message : String(yamlRollbackErr)}`;
       }
+      let shimRollbackMsg = "no shim changes to roll back";
+      const shimRollbackFailures = [];
+      const priorPersisted = typeof priorShimPathRaw === "string" && priorShimPathRaw.length > 0 ? priorShimPathRaw : null;
+      if (shimOutcome.materializedAt !== null && shimOutcome.createdNew && (priorPersisted === null || !sameShimTarget(shimOutcome.materializedAt, priorPersisted))) {
+        try {
+          removeHermesShim([shimOutcome.materializedAt]);
+        } catch (err) {
+          shimRollbackFailures.push(
+            `could not remove the newly-written shim at ${shimOutcome.materializedAt} (${err instanceof Error ? err.message : String(err)})`
+          );
+        }
+      }
+      if (shimOutcome.priorCleanedAt !== null) {
+        try {
+          materializeHermesShim(shimOutcome.priorCleanedAt);
+        } catch (err) {
+          shimRollbackFailures.push(
+            `could not restore the prior shim at ${shimOutcome.priorCleanedAt} (${err instanceof Error ? err.message : String(err)})`
+          );
+        }
+      }
+      for (const cleanedPath of cleanedInheritedShims) {
+        if (shimOutcome.priorCleanedAt !== null && sameShimTarget(cleanedPath, shimOutcome.priorCleanedAt)) {
+          continue;
+        }
+        try {
+          materializeHermesShim(cleanedPath);
+        } catch (err) {
+          shimRollbackFailures.push(
+            `could not restore the prior shim at ${cleanedPath} (${err instanceof Error ? err.message : String(err)})`
+          );
+        }
+      }
+      if (shimOutcome.materializedAt !== null || shimOutcome.priorCleanedAt !== null || cleanedInheritedShims.length > 0) {
+        shimRollbackMsg = shimRollbackFailures.length === 0 ? "plugin shim changes rolled back" : `plugin shim rollback incomplete: ${shimRollbackFailures.join("; ")}`;
+      }
+      let priorConfigRollbackMsg = "no prior-config changes to roll back";
+      if (hermesPriorConfigMutations.length > 0) {
+        const priorConfigRollbackFailures = [];
+        for (const mutation of [...hermesPriorConfigMutations].reverse()) {
+          try {
+            writeSecretFileSync(mutation.mutatedPath, mutation.priorContent);
+          } catch (restoreErr) {
+            priorConfigRollbackFailures.push(
+              `could not restore ${mutation.mutatedPath} (${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)})`
+            );
+          }
+        }
+        priorConfigRollbackMsg = priorConfigRollbackFailures.length === 0 ? "prior-install config(s) restored" : `prior-install config rollback incomplete: ${priorConfigRollbackFailures.join("; ")}`;
+      }
       const urgentSuffix = tokenRollbackFailed ? ` tokens.json may be in an inconsistent state \u2014 manually restore hermes token with 'remnic token generate hermes'.` : "";
       return {
         connectorId: options.connectorId,
         status: "error",
-        message: `Hermes install aborted: connector config write failed \u2014 connector directory may not be writable. Rollback: ${tokenRollbackMsg}; ${yamlRollbackMsg}.${urgentSuffix} Resolve the permission issue, then reinstall.`
+        message: `Hermes install aborted: connector config write failed \u2014 connector directory may not be writable. Rollback: ${tokenRollbackMsg}; ${yamlRollbackMsg}; ${shimRollbackMsg}; ${priorConfigRollbackMsg}.${urgentSuffix} Resolve the permission issue, then reinstall.`
       };
     }
     const notes = [];
     notes.push(`Updated Hermes config: ${yamlResult.configPath}`);
+    notes.push(...shimOutcome.notes);
+    notes.push(...hermesPriorNotes);
+    notes.push(
+      "Next step: set `memory.provider: remnic` (and `memory_enabled: true`) in your Hermes config.yaml to activate the provider."
+    );
     if (hermesProfile === "default") {
       const legacyDefaultConfigPath = hermesDefaultProfileConfigPath();
       if (!sameHermesConfigTarget(yamlResult.configPath, legacyDefaultConfigPath)) {
@@ -1137,9 +1749,9 @@ function installConnector(options) {
   if (options.connectorId === "weclone") {
     try {
       let proxyConfigPath = null;
-      if (existing && fs2.existsSync(configPath)) {
+      if (existing && fs3.existsSync(configPath)) {
         try {
-          const savedRegistryConfig = JSON.parse(fs2.readFileSync(configPath, "utf8"));
+          const savedRegistryConfig = JSON.parse(fs3.readFileSync(configPath, "utf8"));
           if (typeof savedRegistryConfig.proxyConfigPath === "string" && savedRegistryConfig.proxyConfigPath.length > 0) {
             proxyConfigPath = savedRegistryConfig.proxyConfigPath;
           }
@@ -1155,12 +1767,12 @@ function installConnector(options) {
         priorConfig: prior ? safeParseJson(prior) : null,
         authToken: tokenEntry?.token
       });
-      fs2.mkdirSync(path2.dirname(proxyConfigPath), { recursive: true });
+      fs3.mkdirSync(path3.dirname(proxyConfigPath), { recursive: true });
       weCloneProxyHandleRollback = () => {
         try {
           if (prior === null) {
-            if (fs2.existsSync(proxyConfigPath)) {
-              fs2.unlinkSync(proxyConfigPath);
+            if (fs3.existsSync(proxyConfigPath)) {
+              fs3.unlinkSync(proxyConfigPath);
             }
           } else {
             writeSecretFileSync(proxyConfigPath, prior);
@@ -1270,13 +1882,13 @@ function removeConnector(connectorId) {
       message: `Removal aborted: invalid connector ID ${JSON.stringify(connectorId)}. Connector IDs must match [A-Za-z0-9][A-Za-z0-9._-]*.`
     };
   }
-  const configPath = path2.join(configDir, `${connectorId}.json`);
+  const configPath = path3.join(configDir, `${connectorId}.json`);
   let codexHomeOverride = null;
   let savedInstallExtension = void 0;
   let configParsed = false;
-  if (connectorId === "codex-cli" && fs2.existsSync(configPath)) {
+  if (connectorId === "codex-cli" && fs3.existsSync(configPath)) {
     try {
-      const parsed = JSON.parse(fs2.readFileSync(configPath, "utf8"));
+      const parsed = JSON.parse(fs3.readFileSync(configPath, "utf8"));
       configParsed = true;
       if (typeof parsed.codexHome === "string" && parsed.codexHome.length > 0) {
         codexHomeOverride = parsed.codexHome;
@@ -1291,7 +1903,50 @@ function removeConnector(connectorId) {
       );
     }
   }
-  if (!fs2.existsSync(configPath)) {
+  let savedHermesShimPath = null;
+  let savedHermesConfigPath = null;
+  const savedPriorHermesConfigPaths = [];
+  const savedPriorHermesShimPaths = [];
+  if (connectorId === "hermes" && fs3.existsSync(configPath)) {
+    try {
+      const parsedRaw = JSON.parse(fs3.readFileSync(configPath, "utf8"));
+      if (parsedRaw === null || typeof parsedRaw !== "object" || Array.isArray(parsedRaw)) {
+        throw new Error("hermes.json is not a JSON object");
+      }
+      const parsed = parsedRaw;
+      if (typeof parsed.pluginShimPath === "string" && parsed.pluginShimPath.length > 0) {
+        savedHermesShimPath = parsed.pluginShimPath;
+      }
+      if (Array.isArray(parsed.priorPluginShimPaths)) {
+        for (const entry of parsed.priorPluginShimPaths) {
+          if (typeof entry === "string" && entry.length > 0) {
+            savedPriorHermesShimPaths.push(entry);
+          }
+        }
+      }
+      if (typeof parsed.hermesConfigPath === "string" && parsed.hermesConfigPath.length > 0) {
+        savedHermesConfigPath = parsed.hermesConfigPath;
+      }
+      if (Array.isArray(parsed.priorHermesConfigPaths)) {
+        for (const entry of parsed.priorHermesConfigPaths) {
+          if (typeof entry === "string" && entry.length > 0) {
+            savedPriorHermesConfigPaths.push(entry);
+          }
+        }
+      }
+      if (typeof parsed.priorHermesConfigPath === "string" && parsed.priorHermesConfigPath.length > 0) {
+        savedPriorHermesConfigPaths.push(parsed.priorHermesConfigPath);
+      }
+    } catch {
+      return {
+        connectorId,
+        configPath,
+        status: "error",
+        message: `Removal aborted: ${configPath} is malformed and cannot be parsed. It records where the Hermes plugin shim was installed; removing the connector without it could orphan the shim. Fix or delete the file (and remove any plugins/remnic/__init__.py under your Hermes home manually), then re-run removal.`
+      };
+    }
+  }
+  if (!fs3.existsSync(configPath)) {
     let staleTokenRevoked = false;
     try {
       staleTokenRevoked = revokeToken(connectorId);
@@ -1308,7 +1963,7 @@ function removeConnector(connectorId) {
   let storedProfile = "default";
   if (connectorId === "hermes") {
     try {
-      const stored = JSON.parse(fs2.readFileSync(configPath, "utf8"));
+      const stored = JSON.parse(fs3.readFileSync(configPath, "utf8"));
       if (typeof stored?.profile === "string") storedProfile = stored.profile;
     } catch {
     }
@@ -1317,7 +1972,7 @@ function removeConnector(connectorId) {
   let weCloneRegistryParseFailed = false;
   if (connectorId === "weclone") {
     try {
-      const stored = JSON.parse(fs2.readFileSync(configPath, "utf8"));
+      const stored = JSON.parse(fs3.readFileSync(configPath, "utf8"));
       if (typeof stored.proxyConfigPath === "string" && stored.proxyConfigPath.length > 0) {
         weCloneProxyConfigPath = stored.proxyConfigPath;
       }
@@ -1343,7 +1998,7 @@ function removeConnector(connectorId) {
       reason: "config-parse-failed"
     };
   }
-  if (connectorId === "codex-cli" && fs2.existsSync(configPath) && !configParsed) {
+  if (connectorId === "codex-cli" && fs3.existsSync(configPath) && !configParsed) {
     console.warn(
       "[remnic/connectors] removeConnector: codex-cli.json is malformed \u2014 aborting removal to preserve provenance. Fix or delete " + configPath + " manually and retry."
     );
@@ -1366,8 +2021,57 @@ function removeConnector(connectorId) {
       extensionMessage = extResult.removed ? ` (memory extension removed: ${extResult.remnicExtensionDir})` : " (no memory extension present)";
     }
   }
+  if (connectorId === "hermes") {
+    const preflightCandidates = [];
+    try {
+      preflightCandidates.push(...hermesConfigCleanupPaths(storedProfile));
+    } catch {
+    }
+    if (savedHermesConfigPath !== null && isPlausibleHermesConfigPath(savedHermesConfigPath)) {
+      preflightCandidates.push(savedHermesConfigPath);
+    }
+    preflightCandidates.push(...savedPriorHermesConfigPaths.filter(isPlausibleHermesConfigPath));
+    const uniqueCandidates = [];
+    for (const candidate of preflightCandidates) {
+      if (!uniqueCandidates.some((kept) => sameHermesConfigTarget(kept, candidate))) {
+        uniqueCandidates.push(candidate);
+      }
+    }
+    const blocked = [];
+    for (const candidate of uniqueCandidates) {
+      let needsCleanup = false;
+      try {
+        needsCleanup = /^remnic:/m.test(fs3.readFileSync(candidate, "utf8"));
+      } catch {
+        needsCleanup = false;
+      }
+      if (!needsCleanup) {
+        continue;
+      }
+      try {
+        assertConfigComponentsNotSymlinked(candidate);
+      } catch {
+        blocked.push(`${candidate} (symlinked path component)`);
+        continue;
+      }
+      try {
+        fs3.accessSync(candidate, fs3.constants.W_OK);
+        fs3.accessSync(path3.dirname(candidate), fs3.constants.W_OK);
+      } catch {
+        blocked.push(`${candidate} (not writable)`);
+      }
+    }
+    if (blocked.length > 0) {
+      return {
+        connectorId,
+        configPath,
+        status: "error",
+        message: `Hermes remove aborted: the following config.yaml path(s) hold a remnic: block but cannot be cleaned: ${blocked.join(", ")}. The connector registry entry, provenance, and token were left untouched \u2014 fix the permissions or resolve the symlink and re-run removal.`
+      };
+    }
+  }
   try {
-    fs2.unlinkSync(configPath);
+    fs3.unlinkSync(configPath);
   } catch (unlinkErr) {
     const sanitizedErr = unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr);
     return {
@@ -1393,14 +2097,14 @@ function removeConnector(connectorId) {
         "WeClone proxy config cleanup skipped: no persisted path found in saved config (likely a legacy install predating proxyConfigPath provenance)."
       );
     } else {
-      const expectedSuffix = path2.join("connectors", "weclone.json");
-      const isSafePath = path2.isAbsolute(weCloneProxyConfigPath) && weCloneProxyConfigPath.endsWith(expectedSuffix);
+      const expectedSuffix = path3.join("connectors", "weclone.json");
+      const isSafePath = path3.isAbsolute(weCloneProxyConfigPath) && weCloneProxyConfigPath.endsWith(expectedSuffix);
       if (!isSafePath) {
         weCloneProxyDeleteFailed = `Proxy config path ${JSON.stringify(weCloneProxyConfigPath)} failed safety validation (must be absolute and end with "${expectedSuffix}"). Refusing to delete \u2014 remove the file manually if it exists.`;
       } else {
         try {
-          if (fs2.existsSync(weCloneProxyConfigPath)) {
-            fs2.unlinkSync(weCloneProxyConfigPath);
+          if (fs3.existsSync(weCloneProxyConfigPath)) {
+            fs3.unlinkSync(weCloneProxyConfigPath);
             notes.push(`Removed WeClone proxy config: ${weCloneProxyConfigPath}`);
           }
         } catch (err) {
@@ -1420,16 +2124,42 @@ function removeConnector(connectorId) {
   }
   if (connectorId === "hermes") {
     try {
-      const yamlResult = removeHermesConfig({ profile: storedProfile });
+      const shimCandidates = [];
+      if (savedHermesShimPath !== null) {
+        shimCandidates.push(savedHermesShimPath);
+      }
+      shimCandidates.push(...savedPriorHermesShimPaths);
+      try {
+        shimCandidates.push(hermesShimPath());
+      } catch {
+      }
+      const shimResult = removeHermesShim(shimCandidates);
+      if (shimResult.notes.length > 0) {
+        notes.push(shimResult.notes.join("; "));
+      }
+    } catch (shimErr) {
+      notes.push(
+        `Hermes plugin shim cleanup skipped: ${shimErr instanceof Error ? shimErr.message : String(shimErr)}`
+      );
+    }
+    try {
+      const yamlResult = removeHermesConfig({
+        profile: storedProfile,
+        extraConfigPaths: [
+          ...savedHermesConfigPath !== null ? [savedHermesConfigPath] : [],
+          ...savedPriorHermesConfigPaths
+        ]
+      });
       if (yamlResult.updated) {
         notes.push(`Removed remnic: block from Hermes config: ${yamlResult.configPath}`);
       } else if (yamlResult.reason?.startsWith("Hermes config cleanup partially failed:")) {
         const tokenStatus = tokenRevoked ? "the connector registry config was deleted and the token was revoked" : "the connector registry config was deleted but TOKEN REVOCATION ALSO FAILED \u2014 inspect ~/.remnic/tokens.json and revoke manually";
+        const shimSuffix = notes.length > 0 ? ` Completed cleanup: ${notes.join("; ")}.` : "";
         return {
           connectorId,
           configPath,
           status: "error",
-          message: `Hermes remove partially succeeded: ${tokenStatus}, but ${yamlResult.reason}. Updated paths: ${yamlResult.configPath}. Manually remove any stale remnic: block and token material from the failed Hermes config path.`
+          message: `Hermes remove partially succeeded: ${tokenStatus}, but ${yamlResult.reason}. Updated paths: ${yamlResult.configPath}. Manually remove any stale remnic: block and token material from the failed Hermes config path.` + shimSuffix
         };
       } else if (yamlResult.skipped) {
         notes.push(`Hermes config cleanup skipped: ${yamlResult.reason}`);
@@ -1465,18 +2195,18 @@ function sanitizeHermesProfile(profile) {
 }
 function hermesConfigPath(profile) {
   const safeProfile = sanitizeHermesProfile(profile);
-  const hermesRoot = path2.resolve(resolveHomeDir(), ".hermes");
-  const rootConfigPath = path2.join(hermesRoot, "config.yaml");
-  const profilesRoot = path2.join(hermesRoot, "profiles");
+  const hermesRoot = resolveHermesRoot();
+  const rootConfigPath = path3.join(hermesRoot, "config.yaml");
+  const profilesRoot = path3.join(hermesRoot, "profiles");
   if (safeProfile === "default") {
-    const defaultProfileDir = path2.join(profilesRoot, safeProfile);
-    if (isFile(rootConfigPath) || !fs2.existsSync(rootConfigPath) && !isDirectory(defaultProfileDir)) {
+    const defaultProfileDir = path3.join(profilesRoot, safeProfile);
+    if (isFile(rootConfigPath) || !fs3.existsSync(rootConfigPath) && !isDirectory(defaultProfileDir)) {
       return rootConfigPath;
     }
   }
-  const cfgPath = path2.resolve(profilesRoot, safeProfile, "config.yaml");
-  const rel = path2.relative(profilesRoot, cfgPath);
-  if (rel.startsWith("..") || path2.isAbsolute(rel)) {
+  const cfgPath = path3.resolve(profilesRoot, safeProfile, "config.yaml");
+  const rel = path3.relative(profilesRoot, cfgPath);
+  if (rel.startsWith("..") || path3.isAbsolute(rel)) {
     throw new Error(
       `Invalid Hermes profile path: resolved outside ${profilesRoot}`
     );
@@ -1485,31 +2215,30 @@ function hermesConfigPath(profile) {
 }
 function isDirectory(filePath) {
   try {
-    return fs2.statSync(filePath).isDirectory();
+    return fs3.statSync(filePath).isDirectory();
   } catch {
     return false;
   }
 }
 function isFile(filePath) {
   try {
-    return fs2.statSync(filePath).isFile();
+    return fs3.statSync(filePath).isFile();
   } catch {
     return false;
   }
 }
 function hermesConfigTarget(filePath) {
   try {
-    return fs2.realpathSync.native(filePath);
+    return fs3.realpathSync.native(filePath);
   } catch {
-    return path2.resolve(filePath);
+    return path3.resolve(filePath);
   }
 }
 function sameHermesConfigTarget(leftPath, rightPath) {
   return hermesConfigTarget(leftPath) === hermesConfigTarget(rightPath);
 }
 function hermesDefaultProfileConfigPath() {
-  const hermesRoot = path2.resolve(resolveHomeDir(), ".hermes");
-  return path2.join(hermesRoot, "profiles", "default", "config.yaml");
+  return path3.join(resolveHermesRoot(), "profiles", "default", "config.yaml");
 }
 function hermesConfigCleanupPaths(profile) {
   const cfgPath = hermesConfigPath(profile);
@@ -1565,29 +2294,29 @@ function sanitizeHermesPort(port) {
   return numeric;
 }
 function writeSecretFileSync(filePath, data) {
-  const dir = path2.dirname(filePath);
-  const base = path2.basename(filePath);
-  const tmpPath = path2.join(
+  const dir = path3.dirname(filePath);
+  const base = path3.basename(filePath);
+  const tmpPath = path3.join(
     dir,
     `.${base}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`
   );
   let wroteTemp = false;
   try {
-    fs2.writeFileSync(tmpPath, data, { mode: 384, flag: "wx" });
+    fs3.writeFileSync(tmpPath, data, { mode: 384, flag: "wx" });
     wroteTemp = true;
     try {
-      fs2.chmodSync(tmpPath, 384);
+      fs3.chmodSync(tmpPath, 384);
     } catch {
     }
-    fs2.renameSync(tmpPath, filePath);
+    fs3.renameSync(tmpPath, filePath);
     try {
-      fs2.chmodSync(filePath, 384);
+      fs3.chmodSync(filePath, 384);
     } catch {
     }
   } catch (err) {
     if (wroteTemp) {
       try {
-        fs2.unlinkSync(tmpPath);
+        fs3.unlinkSync(tmpPath);
       } catch {
       }
     }
@@ -1595,8 +2324,11 @@ function writeSecretFileSync(filePath, data) {
   }
 }
 function upsertHermesConfig(opts) {
-  const cfgPath = hermesConfigPath(opts.profile);
-  const profileDir = path2.dirname(cfgPath);
+  return upsertHermesConfigAt(hermesConfigPath(opts.profile), opts);
+}
+function upsertHermesConfigAt(cfgPath, opts) {
+  assertConfigComponentsNotSymlinked(cfgPath);
+  const profileDir = path3.dirname(cfgPath);
   const safeHost = sanitizeHermesHost(opts.host);
   const safePort = sanitizeHermesPort(opts.port);
   if (!/^[A-Za-z0-9_]+$/.test(opts.token)) {
@@ -1616,11 +2348,11 @@ function upsertHermesConfig(opts) {
     `  port: ${safePort}`,
     `  token: "${opts.token}"`
   ].join("\n");
-  if (!fs2.existsSync(cfgPath)) {
+  if (!fs3.existsSync(cfgPath)) {
     writeSecretFileSync(cfgPath, block + "\n");
     return { updated: true, skipped: false, configPath: cfgPath, priorContent: null };
   }
-  const raw = fs2.readFileSync(cfgPath, "utf8");
+  const raw = fs3.readFileSync(cfgPath, "utf8");
   const hasRemnicBlock = /^remnic:/m.test(raw);
   if (!hasRemnicBlock) {
     const separator = raw.endsWith("\n") ? "\n" : "\n\n";
@@ -1678,7 +2410,33 @@ function upsertHermesConfig(opts) {
   return { updated: true, skipped: false, configPath: cfgPath, priorContent: raw };
 }
 function removeHermesConfig(opts) {
-  const cfgPaths = hermesConfigCleanupPaths(opts.profile);
+  let envCfgPaths;
+  let envResolutionError = null;
+  try {
+    envCfgPaths = [...hermesConfigCleanupPaths(opts.profile)];
+  } catch (err) {
+    envCfgPaths = [];
+    envResolutionError = err instanceof Error ? err.message : String(err);
+  }
+  const cfgPaths = [];
+  for (const candidate of envCfgPaths) {
+    if (!cfgPaths.some((existing) => sameHermesConfigTarget(existing, candidate))) {
+      cfgPaths.push(candidate);
+    }
+  }
+  for (const extra of opts.extraConfigPaths ?? []) {
+    if (isPlausibleHermesConfigPath(extra) && !cfgPaths.some((existing) => sameHermesConfigTarget(existing, extra))) {
+      cfgPaths.push(extra);
+    }
+  }
+  if (cfgPaths.length === 0) {
+    return {
+      updated: false,
+      skipped: true,
+      reason: envResolutionError ? `Hermes config cleanup failed: ${envResolutionError}` : "Hermes config.yaml not found",
+      configPath: "<unresolved>"
+    };
+  }
   const results = cfgPaths.map((cfgPath) => {
     try {
       return removeHermesConfigFile(cfgPath);
@@ -1715,15 +2473,29 @@ function removeHermesConfig(opts) {
     return cleanupFailure;
   }
   const existingWithoutBlock = results.find((result) => result.reason !== "Hermes config.yaml not found");
-  return existingWithoutBlock ?? results[0] ?? {
+  const fallbackResult = existingWithoutBlock ?? results[0];
+  if (fallbackResult) {
+    return fallbackResult;
+  }
+  return {
     updated: false,
     skipped: true,
     reason: "Hermes config.yaml not found",
-    configPath: hermesConfigPath(opts.profile)
+    configPath: cfgPaths[0] ?? "<unresolved>"
   };
 }
 function removeHermesConfigFile(cfgPath) {
-  if (!fs2.existsSync(cfgPath)) {
+  try {
+    assertConfigComponentsNotSymlinked(cfgPath);
+  } catch (err) {
+    return {
+      updated: false,
+      skipped: true,
+      reason: `Hermes config cleanup skipped: ${err instanceof Error ? err.message : String(err)}`,
+      configPath: cfgPath
+    };
+  }
+  if (!fs3.existsSync(cfgPath)) {
     return {
       updated: false,
       skipped: true,
@@ -1731,7 +2503,7 @@ function removeHermesConfigFile(cfgPath) {
       configPath: cfgPath
     };
   }
-  const raw = fs2.readFileSync(cfgPath, "utf8");
+  const raw = fs3.readFileSync(cfgPath, "utf8");
   if (!/^remnic:/m.test(raw)) {
     return {
       updated: false,
@@ -1828,15 +2600,15 @@ async function doctorConnector(connectorId) {
       healthy: false
     };
   }
-  const configPath = path2.join(getConnectorsDir(), `${connectorId}.json`);
+  const configPath = path3.join(getConnectorsDir(), `${connectorId}.json`);
   const checks = [];
   checks.push({
     name: "Config file",
-    ok: fs2.existsSync(configPath),
+    ok: fs3.existsSync(configPath),
     detail: configPath
   });
   try {
-    const raw = fs2.readFileSync(configPath, "utf8");
+    const raw = fs3.readFileSync(configPath, "utf8");
     JSON.parse(raw);
     checks.push({ name: "Config valid", ok: true, detail: "OK" });
   } catch (e) {
@@ -1860,7 +2632,7 @@ async function doctorConnector(connectorId) {
   }
   const memoryDir = instance.config.memoryDir;
   if (memoryDir) {
-    if (fs2.existsSync(memoryDir)) {
+    if (fs3.existsSync(memoryDir)) {
       checks.push({ name: "Memory directory", ok: true, detail: memoryDir });
     } else {
       checks.push({ name: "Memory directory", ok: false, detail: `Not found: ${memoryDir}` });
@@ -1874,32 +2646,32 @@ var CODEX_EXTENSIONS_SUBDIR = "memories_extensions";
 var REMNIC_EXTENSION_DIR_NAME = "remnic";
 function resolveCodexHome(override) {
   if (override && typeof override === "string" && override.trim().length > 0) {
-    return path2.resolve(override.trim());
+    return path3.resolve(override.trim());
   }
   const envHome = readEnvVar("CODEX_HOME");
   if (envHome && envHome.trim().length > 0) {
-    return path2.resolve(envHome.trim());
+    return path3.resolve(envHome.trim());
   }
   const home = readEnvVar("HOME") || readEnvVar("USERPROFILE") || resolveHomeDir();
-  return path2.resolve(home, ".codex");
+  return path3.resolve(home, ".codex");
 }
 function resolveCodexMemoryExtensionPaths(codexHomeOverride) {
   const codexHome = resolveCodexHome(codexHomeOverride);
-  const memoriesDir = path2.join(codexHome, CODEX_MEMORIES_SUBDIR);
-  const extensionsRoot = path2.join(path2.dirname(memoriesDir), CODEX_EXTENSIONS_SUBDIR);
-  const remnicExtensionDir = path2.join(extensionsRoot, REMNIC_EXTENSION_DIR_NAME);
+  const memoriesDir = path3.join(codexHome, CODEX_MEMORIES_SUBDIR);
+  const extensionsRoot = path3.join(path3.dirname(memoriesDir), CODEX_EXTENSIONS_SUBDIR);
+  const remnicExtensionDir = path3.join(extensionsRoot, REMNIC_EXTENSION_DIR_NAME);
   return { codexHome, memoriesDir, extensionsRoot, remnicExtensionDir };
 }
 function locatePluginCodexExtensionSource(override) {
   if (override && typeof override === "string" && override.trim().length > 0) {
-    const resolved = path2.resolve(override.trim());
-    if (fs2.existsSync(resolved) && fs2.statSync(resolved).isDirectory()) {
+    const resolved = path3.resolve(override.trim());
+    if (fs3.existsSync(resolved) && fs3.statSync(resolved).isDirectory()) {
       return resolved;
     }
     throw new Error(`Codex extension source directory not found: ${resolved}`);
   }
-  const EXTENSION_SUBPATH = path2.join("memories_extensions", "remnic");
-  const WORKSPACE_RELATIVE_PATH = path2.join(
+  const EXTENSION_SUBPATH = path3.join("memories_extensions", "remnic");
+  const WORKSPACE_RELATIVE_PATH = path3.join(
     "packages",
     "plugin-codex",
     "memories_extensions",
@@ -1907,15 +2679,15 @@ function locatePluginCodexExtensionSource(override) {
   );
   const searched = [];
   try {
-    const moduleDir = path2.dirname(fileURLToPath(import.meta.url));
-    const bundledCandidate = path2.join(moduleDir, "codex");
+    const moduleDir = path3.dirname(fileURLToPath(import.meta.url));
+    const bundledCandidate = path3.join(moduleDir, "codex");
     searched.push(bundledCandidate);
-    if (fs2.existsSync(bundledCandidate) && fs2.statSync(bundledCandidate).isDirectory()) {
+    if (fs3.existsSync(bundledCandidate) && fs3.statSync(bundledCandidate).isDirectory()) {
       return bundledCandidate;
     }
-    const distConnectorsCandidate = path2.join(moduleDir, "connectors", "codex");
+    const distConnectorsCandidate = path3.join(moduleDir, "connectors", "codex");
     searched.push(distConnectorsCandidate);
-    if (fs2.existsSync(distConnectorsCandidate) && fs2.statSync(distConnectorsCandidate).isDirectory()) {
+    if (fs3.existsSync(distConnectorsCandidate) && fs3.statSync(distConnectorsCandidate).isDirectory()) {
       return distConnectorsCandidate;
     }
   } catch {
@@ -1923,19 +2695,19 @@ function locatePluginCodexExtensionSource(override) {
   try {
     const requireFromHere = createRequire(import.meta.url);
     const pluginPkgJsonPath = requireFromHere.resolve("@remnic/plugin-codex/package.json");
-    const pluginPkgRoot = path2.dirname(pluginPkgJsonPath);
-    const candidate = path2.join(pluginPkgRoot, EXTENSION_SUBPATH);
+    const pluginPkgRoot = path3.dirname(pluginPkgJsonPath);
+    const candidate = path3.join(pluginPkgRoot, EXTENSION_SUBPATH);
     searched.push(candidate);
-    if (fs2.existsSync(candidate) && fs2.statSync(candidate).isDirectory()) {
+    if (fs3.existsSync(candidate) && fs3.statSync(candidate).isDirectory()) {
       return candidate;
     }
   } catch {
   }
   try {
-    const moduleDir = path2.dirname(fileURLToPath(import.meta.url));
+    const moduleDir = path3.dirname(fileURLToPath(import.meta.url));
     let dir = moduleDir;
     for (let depth = 0; depth < 8; depth += 1) {
-      const candidate = path2.join(
+      const candidate = path3.join(
         dir,
         "node_modules",
         "@remnic",
@@ -1943,10 +2715,10 @@ function locatePluginCodexExtensionSource(override) {
         EXTENSION_SUBPATH
       );
       searched.push(candidate);
-      if (fs2.existsSync(candidate) && fs2.statSync(candidate).isDirectory()) {
+      if (fs3.existsSync(candidate) && fs3.statSync(candidate).isDirectory()) {
         return candidate;
       }
-      const parent = path2.dirname(dir);
+      const parent = path3.dirname(dir);
       if (parent === dir) break;
       dir = parent;
     }
@@ -1954,19 +2726,19 @@ function locatePluginCodexExtensionSource(override) {
   }
   const anchors = [];
   try {
-    anchors.push(path2.dirname(fileURLToPath(import.meta.url)));
+    anchors.push(path3.dirname(fileURLToPath(import.meta.url)));
   } catch {
   }
   anchors.push(process.cwd());
   for (const anchor of anchors) {
     let dir = anchor;
     for (let depth = 0; depth < 12; depth += 1) {
-      const candidate = path2.join(dir, WORKSPACE_RELATIVE_PATH);
+      const candidate = path3.join(dir, WORKSPACE_RELATIVE_PATH);
       searched.push(candidate);
-      if (fs2.existsSync(candidate) && fs2.statSync(candidate).isDirectory()) {
+      if (fs3.existsSync(candidate) && fs3.statSync(candidate).isDirectory()) {
         return candidate;
       }
-      const parent = path2.dirname(dir);
+      const parent = path3.dirname(dir);
       if (parent === dir) break;
       dir = parent;
     }
@@ -1977,15 +2749,15 @@ function locatePluginCodexExtensionSource(override) {
 }
 function copyDirRecursiveSync(src, dest) {
   let count = 0;
-  fs2.mkdirSync(dest, { recursive: true });
-  const entries = fs2.readdirSync(src, { withFileTypes: true });
+  fs3.mkdirSync(dest, { recursive: true });
+  const entries = fs3.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
-    const from = path2.join(src, entry.name);
-    const to = path2.join(dest, entry.name);
+    const from = path3.join(src, entry.name);
+    const to = path3.join(dest, entry.name);
     if (entry.isDirectory()) {
       count += copyDirRecursiveSync(from, to);
     } else if (entry.isFile()) {
-      fs2.copyFileSync(from, to);
+      fs3.copyFileSync(from, to);
       count += 1;
     }
   }
@@ -1994,29 +2766,29 @@ function copyDirRecursiveSync(src, dest) {
 function installCodexMemoryExtension(options = {}) {
   const paths = resolveCodexMemoryExtensionPaths(options.codexHome ?? null);
   const sourceDir = locatePluginCodexExtensionSource(options.sourceDir ?? null);
-  fs2.mkdirSync(paths.extensionsRoot, { recursive: true });
+  fs3.mkdirSync(paths.extensionsRoot, { recursive: true });
   const tmpPrefix = `.${REMNIC_EXTENSION_DIR_NAME}.tmp-`;
   const STALE_TMP_THRESHOLD_MS = 10 * 60 * 1e3;
   const now = Date.now();
   try {
-    const existingEntries = fs2.readdirSync(paths.extensionsRoot);
+    const existingEntries = fs3.readdirSync(paths.extensionsRoot);
     for (const entry of existingEntries) {
       if (!entry.startsWith(tmpPrefix)) continue;
-      const stalePath = path2.join(paths.extensionsRoot, entry);
+      const stalePath = path3.join(paths.extensionsRoot, entry);
       try {
-        const stat = fs2.statSync(stalePath);
+        const stat = fs3.statSync(stalePath);
         const ageMs = now - stat.mtimeMs;
         if (ageMs < STALE_TMP_THRESHOLD_MS) {
           continue;
         }
-        fs2.rmSync(stalePath, { recursive: true, force: true });
+        fs3.rmSync(stalePath, { recursive: true, force: true });
       } catch {
       }
     }
   } catch {
   }
   const tmpName = `${tmpPrefix}${process.pid}-${Date.now()}`;
-  const tmpDir = path2.join(paths.extensionsRoot, tmpName);
+  const tmpDir = path3.join(paths.extensionsRoot, tmpName);
   let filesCopied = 0;
   let commitFn = () => {
   };
@@ -2025,16 +2797,16 @@ function installCodexMemoryExtension(options = {}) {
   try {
     filesCopied = copyDirRecursiveSync(sourceDir, tmpDir);
     const backupDir = `${paths.remnicExtensionDir}.bak-${Date.now()}`;
-    const hadExisting = fs2.existsSync(paths.remnicExtensionDir);
+    const hadExisting = fs3.existsSync(paths.remnicExtensionDir);
     if (hadExisting) {
-      fs2.renameSync(paths.remnicExtensionDir, backupDir);
+      fs3.renameSync(paths.remnicExtensionDir, backupDir);
     }
     try {
-      fs2.renameSync(tmpDir, paths.remnicExtensionDir);
+      fs3.renameSync(tmpDir, paths.remnicExtensionDir);
     } catch (renameErr) {
       if (hadExisting) {
         try {
-          fs2.renameSync(backupDir, paths.remnicExtensionDir);
+          fs3.renameSync(backupDir, paths.remnicExtensionDir);
         } catch {
         }
       }
@@ -2043,7 +2815,7 @@ function installCodexMemoryExtension(options = {}) {
     commitFn = () => {
       if (hadExisting) {
         try {
-          fs2.rmSync(backupDir, { recursive: true, force: true });
+          fs3.rmSync(backupDir, { recursive: true, force: true });
         } catch {
         }
       }
@@ -2051,31 +2823,31 @@ function installCodexMemoryExtension(options = {}) {
     rollbackFn = () => {
       if (hadExisting) {
         try {
-          if (fs2.existsSync(paths.remnicExtensionDir)) {
-            fs2.rmSync(paths.remnicExtensionDir, { recursive: true, force: true });
+          if (fs3.existsSync(paths.remnicExtensionDir)) {
+            fs3.rmSync(paths.remnicExtensionDir, { recursive: true, force: true });
           }
-          fs2.renameSync(backupDir, paths.remnicExtensionDir);
+          fs3.renameSync(backupDir, paths.remnicExtensionDir);
         } catch {
         }
       } else {
         try {
-          if (fs2.existsSync(paths.remnicExtensionDir)) {
-            fs2.rmSync(paths.remnicExtensionDir, { recursive: true, force: true });
+          if (fs3.existsSync(paths.remnicExtensionDir)) {
+            fs3.rmSync(paths.remnicExtensionDir, { recursive: true, force: true });
           }
         } catch {
         }
       }
     };
   } catch (err) {
-    if (fs2.existsSync(tmpDir)) {
+    if (fs3.existsSync(tmpDir)) {
       try {
-        fs2.rmSync(tmpDir, { recursive: true, force: true });
+        fs3.rmSync(tmpDir, { recursive: true, force: true });
       } catch {
       }
     }
     throw err;
   }
-  const instructionsPath = path2.join(paths.remnicExtensionDir, "instructions.md");
+  const instructionsPath = path3.join(paths.remnicExtensionDir, "instructions.md");
   return {
     ...paths,
     instructionsPath,
@@ -2087,8 +2859,8 @@ function installCodexMemoryExtension(options = {}) {
 function removeCodexMemoryExtension(options = {}) {
   const paths = resolveCodexMemoryExtensionPaths(options.codexHome ?? null);
   let removed = false;
-  if (fs2.existsSync(paths.remnicExtensionDir)) {
-    fs2.rmSync(paths.remnicExtensionDir, { recursive: true, force: true });
+  if (fs3.existsSync(paths.remnicExtensionDir)) {
+    fs3.rmSync(paths.remnicExtensionDir, { recursive: true, force: true });
     removed = true;
   }
   return { ...paths, removed };
@@ -2099,11 +2871,11 @@ function resolveWeCloneProxyConfigPath() {
   const remnicHome = readEnvVar("REMNIC_HOME");
   const override = remnicHome && remnicHome.length > 0 ? remnicHome : readEnvVar("ENGRAM_HOME");
   if (override && override.length > 0) {
-    return path2.resolve(expandTildePath(override), "connectors", WECLONE_PROXY_CONFIG_FILENAME);
+    return path3.resolve(expandTildePath(override), "connectors", WECLONE_PROXY_CONFIG_FILENAME);
   }
   const envHome = readEnvVar("HOME");
   const home = envHome && envHome.length > 0 ? envHome : os.homedir();
-  return path2.resolve(
+  return path3.resolve(
     home,
     WECLONE_PROXY_CONFIG_DIRNAME,
     "connectors",
@@ -2112,8 +2884,8 @@ function resolveWeCloneProxyConfigPath() {
 }
 function readWeCloneProxyConfigIfExists(configPath) {
   try {
-    if (!fs2.existsSync(configPath)) return null;
-    return fs2.readFileSync(configPath, "utf8");
+    if (!fs3.existsSync(configPath)) return null;
+    return fs3.readFileSync(configPath, "utf8");
   } catch {
     return null;
   }
@@ -2257,4 +3029,4 @@ export {
   resolveWeCloneProxyConfigPath,
   buildWeCloneProxyConfig
 };
-//# sourceMappingURL=chunk-H67QFYUK.js.map
+//# sourceMappingURL=chunk-UJBESW6X.js.map