@litfamily/lithermes 1.0.0

package/src/lib/install.js

@@ -0,0 +1,559 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  applyModelConfigPlan,
+  configHasLitHermes,
+  disableLitHermesConfig,
+  enableLitHermesConfig,
+  inspectHermesCapabilities,
+  planModelConfig,
+  readConfig,
+  setTuiAgentsNudgeConfig,
+  revalidateModelConfigPlan,
+  writeConfig,
+} = require("./config");
+const { copyTree, removeEmptyDirs, sha256, writeFileAtomic } = require("./files");
+const { assertStateParent, assertPluginParent, defaultHermesHome, defaultHermesRepo, detectHermesRuntimeRepo, detectHermesVersion, ensureHermesHome, inspectHermesHostCapabilities, LitHermesError } = require("./hermesDiscovery");
+const { patchInstalledHermes, rollbackPatches } = require("./patch");
+const {
+  formatManagedRoute,
+  managedRequest,
+  missingCredentialWarning,
+  unavailableReviewerRouteName,
+  unavailableReviewerRoutes,
+  unavailableTuiRouteVisibility,
+} = require("./modelRoutePolicy");
+const { installSkins } = require("./skins");
+
+const packageRoot = path.resolve(__dirname, "..", "..");
+const assetRoot = path.join(packageRoot, "assets", "lithermes-plugin");
+const LEGACY_VENDOR_DIRS = new Map([
+  ["vendor/022_handoff", "vendor/handoff"],
+  ["vendor/045_scientific-visualization", "vendor/scientific-visualization"],
+]);
+
+function manifestPath(hermesHome) {
+  return path.join(hermesHome, "lithermes", "install-manifest.json");
+}
+
+function pluginDest(hermesHome) {
+  return path.join(hermesHome, "plugins", "lithermes");
+}
+
+function withLock(hermesHome, fn, expectedState) {
+  assertStateParent(hermesHome, expectedState);
+  const lock = path.join(hermesHome, "lithermes", "install.lock");
+  fs.mkdirSync(path.dirname(lock), { recursive: true });
+  const state = assertStateParent(hermesHome, expectedState || undefined);
+  const checkState = () => assertStateParent(hermesHome, state);
+  let fd;
+  let lockStat;
+  try {
+    try {
+      checkState();
+      fd = fs.openSync(lock, "wx");
+      lockStat = fs.fstatSync(fd);
+      fs.writeFileSync(fd, String(process.pid));
+    } catch (error) {
+      if (error.code === "EEXIST") throw new LitHermesError(`LitHermes install lock already exists at ${lock}`, 3);
+      throw error;
+    }
+    checkState();
+    const result = fn(checkState);
+    checkState();
+    return result;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    try {
+      checkState();
+      const current = fs.lstatSync(lock, { throwIfNoEntry: false });
+      if (current?.isFile() && lockStat && current.dev === lockStat.dev && current.ino === lockStat.ino) fs.unlinkSync(lock);
+    } catch {
+      // A moved state directory retains its lock for manual recovery.
+    }
+  }
+}
+
+function loadManifest(hermesHome) {
+  const state = assertStateParent(hermesHome);
+  const file = manifestPath(hermesHome);
+  const before = fs.lstatSync(file, { throwIfNoEntry: false });
+  if (!before) return null;
+  if (!before.isFile()) throw new LitHermesError(`Unsafe install manifest at ${file}.`, 5);
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | (fs.constants.O_NONBLOCK || 0));
+  try {
+    const opened = fs.fstatSync(fd);
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino) throw new LitHermesError(`Replaced install manifest at ${file}.`, 5);
+    assertStateParent(hermesHome, state);
+    const text = fs.readFileSync(fd, "utf8");
+    assertStateParent(hermesHome, state);
+    const after = fs.lstatSync(file);
+    if (!after.isFile() || after.dev !== before.dev || after.ino !== before.ino) throw new LitHermesError(`Replaced install manifest at ${file}.`, 5);
+    return JSON.parse(text);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function validManifestFiles(manifest) {
+  return Array.isArray(manifest?.files) && manifest.files.every((entry) =>
+    typeof entry?.path === "string" && entry.path.length > 0
+    && !path.isAbsolute(entry.path) && !entry.path.includes("\\") && !entry.path.includes("\0")
+    && entry.path.split("/").every((part) => part && part !== "." && part !== "..")
+    && /^[a-f0-9]{64}$/.test(entry.sha256))
+    && new Set(manifest.files.map((entry) => entry.path)).size === manifest.files.length;
+}
+
+function installedMatchesManifest(hermesHome, manifest, caches = []) {
+  if (!validManifestFiles(manifest)) return false;
+  const dest = pluginDest(hermesHome);
+  const owned = new Map(manifest.files.map((entry) => [entry.path, entry.sha256]));
+  let matched = 0;
+  const matches = (dir) => fs.readdirSync(dir, { withFileTypes: true }).every((entry) => {
+    const file = path.join(dir, entry.name);
+    const relative = path.relative(dest, file).split(path.sep).join("/");
+    if (entry.isDirectory()) {
+      if (entry.name === "__pycache__") {
+        const entries = fs.readdirSync(file, { withFileTypes: true });
+        if (!entries.length || !entries.every((cache) => {
+          const name = /^([^.]+)\.[a-zA-Z][a-zA-Z0-9_-]*(?:\.opt-[0-9]+)?\.pyc$/.exec(cache.name);
+          const source = name && path.relative(dest, path.join(dir, `${name[1]}.py`)).split(path.sep).join("/");
+          return cache.isFile() && name && owned.has(source);
+        })) return false;
+        const stat = fs.lstatSync(file);
+        caches.push({ path: relative, dev: stat.dev, ino: stat.ino, files: entries.map((cache) => ({
+          path: cache.name, sha256: sha256(path.join(file, cache.name)),
+        })) });
+        return true;
+      }
+      return [...owned.keys()].some((name) => name.startsWith(`${relative}/`)) && matches(file);
+    }
+    if (!entry.isFile() || !owned.has(relative) || sha256(file) !== owned.get(relative)) return false;
+    matched += 1;
+    return true;
+  });
+  return fs.lstatSync(dest).isDirectory() && matches(dest) && matched === owned.size;
+}
+
+// A pre-canonical installation may be replaced only when both numbered vendor
+// roots are ordinary directories whose complete tree is already covered by the
+// install receipt. This reuses the existing manifest guard, while explicitly
+// rejecting mixed old/new layouts before the destination is removed.
+function validateLegacyVendorMigration(hermesHome, manifest) {
+  const dest = pluginDest(hermesHome);
+  let foundLegacy = false;
+  for (const [legacy, canonical] of LEGACY_VENDOR_DIRS) {
+    const legacyPath = path.join(dest, legacy);
+    const legacyStat = fs.lstatSync(legacyPath, { throwIfNoEntry: false });
+    if (!legacyStat) continue;
+    foundLegacy = true;
+    if (!legacyStat.isDirectory() || legacyStat.isSymbolicLink()) {
+      throw new LitHermesError(`Unsafe legacy vendor path at ${legacyPath}; refusing migration.`, 5);
+    }
+    if (fs.lstatSync(path.join(dest, canonical), { throwIfNoEntry: false })) {
+      throw new LitHermesError(`Mixed legacy and canonical vendor paths at ${dest}; refusing migration.`, 5);
+    }
+  }
+  if (!foundLegacy) return false;
+  if (!installedMatchesManifest(hermesHome, manifest)) {
+    throw new LitHermesError("Legacy vendor payload is not pristine and manifest-owned; refusing migration.", 5);
+  }
+  return true;
+}
+
+function retainPythonCaches(hermesHome, manifest, caches) {
+  const parent = path.join(hermesHome, "lithermes");
+  const parentStat = assertStateParent(hermesHome);
+  const current = [];
+  if (!installedMatchesManifest(hermesHome, manifest, current) || JSON.stringify(current) !== JSON.stringify(caches)) {
+    throw new LitHermesError("Installed payload or Python cache changed before retention; refusing replacement.", 5);
+  }
+  const backup = fs.mkdtempSync(path.join(parent, "retained-python-cache-"));
+  const backupStat = fs.lstatSync(backup);
+  const safeBackup = () => {
+    const nowParent = fs.lstatSync(parent);
+    const nowBackup = fs.lstatSync(backup);
+    return nowParent.isDirectory() && nowParent.dev === parentStat.dev && nowParent.ino === parentStat.ino
+      && nowBackup.isDirectory() && nowBackup.dev === backupStat.dev && nowBackup.ino === backupStat.ino
+      && (nowBackup.mode & 0o077) === 0;
+  };
+  try {
+    if (path.dirname(backup) !== parent || !path.basename(backup).startsWith("retained-python-cache-")
+      || !safeBackup() || fs.readdirSync(backup).length) throw new Error("Unsafe Python cache backup destination");
+    writeFileAtomic(path.join(backup, "retention.json"), JSON.stringify({ pluginPath: pluginDest(hermesHome), caches }, null, 2), "utf8");
+    for (const cache of caches) {
+      const source = path.join(pluginDest(hermesHome), cache.path);
+      const stat = fs.lstatSync(source);
+      if (!safeBackup() || !stat.isDirectory() || stat.dev !== cache.dev || stat.ino !== cache.ino
+        || fs.readdirSync(source).length !== cache.files.length
+        || !cache.files.every((file) => {
+          const cached = path.join(source, file.path);
+          return fs.lstatSync(cached).isFile() && sha256(cached) === file.sha256;
+        })) throw new Error("Python cache changed during retention");
+      const target = path.join(backup, cache.path);
+      let ancestor = backup;
+      for (const part of cache.path.split("/").slice(0, -1)) {
+        ancestor = path.join(ancestor, part);
+        if (!fs.lstatSync(ancestor, { throwIfNoEntry: false })) fs.mkdirSync(ancestor, { mode: 0o700 });
+        if (!safeBackup() || !fs.lstatSync(ancestor).isDirectory()) throw new Error("Unsafe Python cache backup ancestor");
+      }
+      if (!safeBackup() || fs.lstatSync(target, { throwIfNoEntry: false })) throw new Error("Python cache backup target already exists");
+      fs.renameSync(source, target);
+    }
+    return backup;
+  } catch (error) {
+    throw new LitHermesError(`${error.message}\nRetained Python cache backup: ${backup}`, 5);
+  }
+}
+
+function isInstalledRegularFile(dest, relative) {
+  let file = dest;
+  if (!fs.lstatSync(file, { throwIfNoEntry: false })?.isDirectory()) return false;
+  const parts = relative.split("/");
+  return parts.every((part, index) => {
+    file = path.join(file, part);
+    const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+    return index === parts.length - 1 ? stat?.isFile() : stat?.isDirectory();
+  });
+}
+
+// Version-aware install status (NOT a manifest-integrity check): distinguish a
+// fresh install, a same-version reinstall, and a real upgrade so the message
+// never claims "already up to date" while actually replacing an older version.
+function installStatusLine(installedVersion, packageVersion) {
+  if (!installedVersion) return `Installed LitHermes ${packageVersion}`;
+  if (installedVersion === packageVersion) return `LitHermes already up to date (${packageVersion})`;
+  return `Upgraded LitHermes ${installedVersion} → ${packageVersion}`;
+}
+
+function capabilityLines(plan, { dryRun = false } = {}) {
+  const {
+    autoCompaction,
+    concurrency,
+    delegationRoute,
+    leadRoute,
+    modelSafety,
+    ordinaryWorkerRoute,
+    recursion,
+    reviewerRoutes,
+    runtime,
+    tuiRouteVisibility,
+  } = plan.capabilities;
+  const request = plan.request || managedRequest();
+  const auto = autoCompaction.status === "hard"
+    ? `hard (${autoCompaction.limit} tokens)`
+    : `unavailable (${autoCompaction.reason.replace(/^Hermes 0\.17\.0 exposes /, "")})`;
+  const sync = concurrency.status === "hard"
+    ? `hard (per batch ${concurrency.limit}; async batches ${concurrency.asyncBatchLimit}; potential children ${concurrency.potentialChildCeiling})`
+    : `${concurrency.status} (${concurrency.reason})`;
+  const nesting = recursion.status === "hard"
+    ? recursion.flatBy === "depth"
+      ? `hard (depth ${recursion.limit}, flat)`
+      : `hard (configured depth ${recursion.limit}, flat via orchestrator kill switch)`
+    : `${recursion.status} (${recursion.reason})`;
+  const wire = runtime.status === "hard"
+    ? `hard (${runtime.provider} ${runtime.apiMode})`
+    : `${runtime.status} (${runtime.reason})`;
+  const routeLine = (label, route) => route.status === "configured"
+    ? `${label}: configured (${route.model}, effort ${route.effort})`
+    : `${label}: ${route.status} (${route.reason})`;
+  const routeLines = dryRun
+    ? [
+      `lead route: requested (${request.model}, effort ${request.effort}; unapplied)`,
+      `ordinary worker route: requested (${request.childModel}, effort ${request.childEffort}; unapplied)`,
+      `${unavailableReviewerRouteName()} route: unavailable (${unavailableReviewerRoutes().reason})`,
+      `litwork-reviewer route: unavailable (${unavailableReviewerRoutes().reason})`,
+      `TUI route visibility: unavailable (${unavailableTuiRouteVisibility().reason})`,
+    ]
+    : [
+      routeLine("lead route", leadRoute),
+      routeLine("ordinary worker route", ordinaryWorkerRoute),
+      routeLine(`${unavailableReviewerRouteName()} route`, reviewerRoutes),
+      routeLine("litwork-reviewer route", reviewerRoutes),
+      routeLine("TUI route visibility", tuiRouteVisibility),
+    ];
+  return [
+    `auto-compaction: ${auto}`,
+    `concurrency: ${sync}`,
+    `recursion: ${nesting}`,
+    `model route safety: ${modelSafety.status}${modelSafety.code ? ` (${modelSafety.code}; ${modelSafety.reason})` : ` (${modelSafety.reason})`}`,
+    `runtime: ${wire}`,
+    `global child route: ${formatManagedRoute(delegationRoute)}`,
+    ...routeLines,
+  ];
+}
+
+// Installer flags → managedRequest options (contract §Non-interactive defaults).
+function routeOptions(flags = {}) {
+  return {
+    childEffort: flags["child-effort"],
+    childModel: flags["child-model"],
+    childProvider: flags["child-provider"],
+    effort: flags.effort,
+    model: flags.model,
+    provider: flags.provider,
+  };
+}
+
+// Tells the CLI whether the model prompts apply: only a fresh/unconfigured
+// config or an explicit --reconfigure-model may rewrite the managed route.
+// Read-only — nothing may touch the disk before the summary-card consent.
+function previewModelRoute(flags = {}) {
+  const hermesHome = defaultHermesHome(flags);
+  assertStateParent(hermesHome);
+  const hermesRepo = defaultHermesRepo(flags, hermesHome);
+  const plan = planModelConfig(readConfig(hermesHome), {
+    ...routeOptions(flags),
+    hostCapabilities: inspectHermesHostCapabilities(hermesRepo || detectHermesRuntimeRepo()),
+    hostVersion: detectHermesVersion(),
+    reconfigure: Boolean(flags["reconfigure-model"]),
+  });
+  return {
+    action: plan.action,
+    configPath: path.join(hermesHome, "config.yaml"),
+    reason: plan.reason,
+    request: plan.request || null,
+  };
+}
+
+function installLitHermes(flags = {}) {
+  const dryRun = Boolean(flags["dry-run"]);
+  const homeInfo = dryRun
+    ? (() => {
+      const hermesHome = defaultHermesHome(flags);
+      return { hermesHome, hermesRepo: defaultHermesRepo(flags, hermesHome) };
+    })()
+    : ensureHermesHome(flags, { forInstall: true });
+  const { hermesHome, hermesRepo } = homeInfo;
+  const state = assertStateParent(hermesHome);
+  const dest = pluginDest(hermesHome);
+  const onProgress = typeof flags.onProgress === "function" ? flags.onProgress : () => {};
+  const beforeConfig = readConfig(hermesHome);
+  const capabilityRepo = hermesRepo || (dryRun ? null : detectHermesRuntimeRepo());
+  const modelPlan = planModelConfig(beforeConfig, {
+    ...routeOptions(flags),
+    hostCapabilities: inspectHermesHostCapabilities(capabilityRepo),
+    hostVersion: dryRun ? "" : detectHermesVersion(),
+    reconfigure: Boolean(flags["reconfigure-model"]),
+  });
+  if (modelPlan.action === "stop") {
+    throw new LitHermesError(
+      `${modelPlan.stop.code}: ${modelPlan.reason}; update the existing route with \`hermes model\` before installing.`,
+      10,
+    );
+  }
+  if (dryRun) {
+    const selectedModel = modelPlan.request?.model || "gpt-6-astra";
+    const selectedEffort = modelPlan.request?.effort || "xhigh";
+    return {
+      message: [
+        "DRY RUN: would install LitHermes",
+        `plugin: ${dest}`,
+        `config: ${path.join(hermesHome, "config.yaml")}`,
+        `manifest: ${manifestPath(hermesHome)}`,
+        "Hermes CLI discovery: skipped (dry-run does not execute Hermes)",
+        `model config: ${modelPlan.action === "preserve" ? "preserved" : modelPlan.action}`,
+        ...(modelPlan.action === "write"
+          ? [`model: ${selectedModel}`, `effort: ${selectedEffort}`]
+          : [
+            `requested model (unapplied): ${selectedModel}`,
+            `requested effort (unapplied): ${selectedEffort}`,
+          ]),
+        ...(modelPlan.action === "fallback" ? [`reason: ${modelPlan.reason}`, `fallback: ${modelPlan.fallbackCommand}`] : []),
+        ...capabilityLines(modelPlan, { dryRun: true }),
+      ].join("\n"),
+    };
+  }
+  if (!flags.yes) {
+    throw new LitHermesError("Refusing to mutate Hermes config without --yes. Re-run with --dry-run to inspect changes.", 4);
+  }
+  onProgress("Preparing Hermes config");
+  let retainedPythonCache = null;
+  try {
+  return withLock(hermesHome, (checkState) => {
+    assertPluginParent(hermesHome);
+    onProgress("Inspecting existing plugin");
+    checkState();
+    const existingManifest = loadManifest(hermesHome);
+    const packageVersion = require(path.join(packageRoot, "package.json")).version;
+    const destinationExists = Boolean(fs.lstatSync(dest, { throwIfNoEntry: false }));
+    const installedVersion = destinationExists && existingManifest ? existingManifest.version : null;
+    const caches = [];
+    if (destinationExists && !installedMatchesManifest(hermesHome, existingManifest, caches) && !flags.force) {
+      throw new LitHermesError(`Existing LitHermes plugin at ${dest} is not manifest-owned. Use --force after backing it up.`, 5);
+    }
+    if (destinationExists && existingManifest && !flags.force) validateLegacyVendorMigration(hermesHome, existingManifest);
+    onProgress("Copying LitHermes payload");
+    checkState();
+    if (!flags.force && destinationExists) {
+      if (caches.length) retainedPythonCache = retainPythonCaches(hermesHome, existingManifest, caches);
+      assertPluginParent(hermesHome);
+      const remainingCaches = [];
+      if (!installedMatchesManifest(hermesHome, existingManifest, remainingCaches) || remainingCaches.length) {
+        throw new LitHermesError("Installed payload changed before replacement; refusing to remove files.", 5);
+      }
+    }
+    // Replacing the manifest-owned tree also migrates renamed skills: old
+    // directories disappear and the new inventory becomes the install receipt.
+    checkState();
+    assertPluginParent(hermesHome);
+    fs.rmSync(dest, { recursive: true, force: true });
+    const files = copyTree(assetRoot, dest);
+    onProgress("Writing Hermes config");
+    checkState();
+    let afterConfig = beforeConfig;
+    let configAddedLitHermes = false;
+    let effectiveModelAction = modelPlan.action;
+    let effectiveCapabilities = modelPlan.capabilities;
+    let modelReceipt = { backupPath: null, written: false };
+    if (modelPlan.action === "write") {
+      const plannedConfig = enableLitHermesConfig(modelPlan.text);
+      modelReceipt = applyModelConfigPlan(hermesHome, { ...modelPlan, text: plannedConfig });
+      if (modelReceipt.written) {
+        afterConfig = plannedConfig;
+        configAddedLitHermes = !configHasLitHermes(beforeConfig) && configHasLitHermes(afterConfig);
+      } else if (modelReceipt.drifted) {
+        afterConfig = readConfig(hermesHome);
+        effectiveModelAction = "aborted";
+        effectiveCapabilities = inspectHermesCapabilities(afterConfig);
+      }
+    } else if (modelPlan.action === "preserve") {
+      const validation = revalidateModelConfigPlan(hermesHome, modelPlan);
+      if (validation.ok) {
+        afterConfig = enableLitHermesConfig(validation.current);
+        if (afterConfig !== validation.current) {
+          writeConfig(hermesHome, afterConfig);
+          configAddedLitHermes = true;
+        }
+      } else {
+        afterConfig = validation.current;
+        modelReceipt = { backupPath: null, drifted: true, reason: validation.reason, written: false };
+        effectiveModelAction = "aborted";
+        effectiveCapabilities = inspectHermesCapabilities(afterConfig);
+      }
+    }
+    if (!configAddedLitHermes && !configHasLitHermes(afterConfig)) {
+      afterConfig = enableLitHermesConfig(afterConfig);
+      writeConfig(hermesHome, afterConfig);
+      configAddedLitHermes = true;
+    }
+    // Managed helper-visibility key, written only alongside a config write this
+    // install already made — a preserved user config stays byte-identical
+    // (Hermes defaults display.tui_agents_nudge to true anyway).
+    if (configAddedLitHermes || (modelPlan.action === "write" && modelReceipt.written)) {
+      const nudgedConfig = setTuiAgentsNudgeConfig(afterConfig);
+      if (nudgedConfig !== afterConfig) {
+        afterConfig = nudgedConfig;
+        writeConfig(hermesHome, afterConfig);
+      }
+    }
+    onProgress("Installing HUD skins");
+    checkState();
+    let skinFiles = [];
+    try {
+      skinFiles = installSkins(hermesHome);
+    } catch {
+      // HUD skins are optional polish; never fail the install over them.
+    }
+    onProgress("Recording install manifest");
+    checkState();
+    const manifest = {
+      version: packageVersion,
+      installedAt: new Date().toISOString(),
+      pluginPath: dest,
+      configPath: path.join(hermesHome, "config.yaml"),
+      files,
+      configAddedLitHermes,
+      modelConfigAction: effectiveModelAction,
+      modelConfigReason: modelPlan.reason,
+      ...(retainedPythonCache ? { retainedPythonCache } : {}),
+    };
+    fs.mkdirSync(path.dirname(manifestPath(hermesHome)), { recursive: true });
+    writeFileAtomic(manifestPath(hermesHome), JSON.stringify(manifest, null, 2), "utf8");
+    let patchResult = null;
+    let patchWarning = null;
+    const shouldPatch = Boolean(flags["patch-installed-hermes"] || (!flags["no-patch-installed-hermes"] && hermesRepo));
+    if (shouldPatch) {
+      onProgress("Checking Hermes compatibility patches");
+    checkState();
+      try {
+        patchResult = patchInstalledHermes({ hermesHome, hermesRepo, force: flags.force });
+      } catch (error) {
+        if (flags["patch-installed-hermes"]) throw error;
+        patchWarning = error.message;
+      }
+    }
+    const lines = [
+      installStatusLine(installedVersion, packageVersion),
+      `plugin: ${dest}`,
+      ...(retainedPythonCache ? [`Retained Python cache backup: ${retainedPythonCache}`] : []),
+      `model config: ${effectiveModelAction === "write" ? "updated" : effectiveModelAction === "preserve" ? "preserved" : effectiveModelAction}`,
+      ...(modelReceipt.backupPath ? [`model backup: ${modelReceipt.backupPath}`] : []),
+      ...(modelReceipt.drifted ? [`model write: aborted (${modelReceipt.reason})`] : []),
+      ...(modelPlan.action === "fallback" ? [
+        `model reason: ${modelPlan.reason}`,
+        `model fallback: ${modelPlan.fallbackCommand}`,
+        ...(modelPlan.credentialKey
+          ? [`credential guard: ${modelPlan.credentialKey} detected; use \`hermes model\` to manage it; installer left config untouched`]
+          : []),
+      ] : []),
+      ...capabilityLines({ capabilities: effectiveCapabilities }),
+    ];
+    if (patchResult) lines.push(`patches: ${patchResult.changed.length ? patchResult.changed.join(", ") : "none needed"}`);
+    if (patchWarning) lines.push(`patches: skipped (${patchWarning})`);
+    const credentialWarning = modelPlan.request && effectiveModelAction === "write"
+      ? missingCredentialWarning(modelPlan.request, process.env)
+      : null;
+    if (credentialWarning) lines.push(`warning: ${credentialWarning}`);
+    if (skinFiles.length) lines.push(`HUD skins: ${skinFiles.length} accents installed — pick one with \`npx --package @litfamily/lithermes -- lithermes hud <accent>\``);
+    lines.push("Restart any running Hermes gateway to load new plugins.");
+    return { message: lines.join("\n") };
+  }, state);
+  } catch (error) {
+    if (retainedPythonCache) error.message += `\nRetained Python cache backup: ${retainedPythonCache}`;
+    throw error;
+  }
+}
+
+function uninstallLitHermes(flags = {}) {
+  const { hermesHome } = ensureHermesHome(flags);
+  const state = assertStateParent(hermesHome);
+  if (!flags.yes) {
+    throw new LitHermesError("Refusing to uninstall without --yes.", 4);
+  }
+  return withLock(hermesHome, (checkState) => {
+    assertPluginParent(hermesHome);
+    const rollback = flags["rollback-patches"] ? rollbackPatches({ hermesHome }) : null;
+    const manifest = loadManifest(hermesHome);
+    checkState();
+    if (!manifest) return { message: rollback ? `LitHermes is not installed by this installer.\n${rollback.message}` : "LitHermes is not installed by this installer." };
+    if (!validManifestFiles(manifest)) throw new LitHermesError("Invalid LitHermes install manifest; refusing to remove files.", 5);
+    const dest = pluginDest(hermesHome);
+    for (const entry of [...manifest.files].reverse()) {
+      checkState();
+      assertPluginParent(hermesHome);
+      const file = path.join(dest, entry.path);
+      if (isInstalledRegularFile(dest, entry.path) && sha256(file) === entry.sha256) {
+        fs.unlinkSync(file);
+        removeEmptyDirs(path.dirname(file), dest);
+      }
+    }
+    if (fs.lstatSync(dest, { throwIfNoEntry: false })?.isDirectory() && fs.readdirSync(dest).length === 0) fs.rmdirSync(dest);
+    checkState();
+    writeConfig(hermesHome, disableLitHermesConfig(readConfig(hermesHome)));
+    checkState();
+    fs.unlinkSync(manifestPath(hermesHome));
+    return { message: rollback ? `Uninstalled LitHermes\n${rollback.message}` : "Uninstalled LitHermes" };
+  }, state);
+}
+
+module.exports = {
+  assetRoot,
+  installLitHermes,
+  installStatusLine,
+  loadManifest,
+  manifestPath,
+  pluginDest,
+  previewModelRoute,
+  uninstallLitHermes,
+};

package/src/lib/litMark.js

@@ -0,0 +1,68 @@
+// Approved Ignition B geometry and per-cell colors are local to this package.
+const data = require("../../assets/lithermes-plugin/lit_mark_rows.json");
+const standard = Object.freeze(data.standard.map((row) => row.text));
+const banner = Object.freeze(data.banner.map((row) => row.text));
+const micro = Object.freeze(data.micro.map((row) => row.text));
+const GLYPHS = new Set("█▓▀▄▌▐▖▗▘▝▙▛▜▟▚▞");
+const INDEXED = Object.freeze({ "#FF6337": 203, "#D7F75B": 191, "#F2EFDF": 230 });
+
+function lockup(productName, rows = standard) {
+  if (typeof productName !== "string" || !/^[a-zA-Z0-9 .·_-]+$/.test(productName)) {
+    throw new TypeError("product name must be a plain single line");
+  }
+  // Preserve the native eight-space gap after the full mark envelope.
+  const column = Math.max(...rows.map((row) => row.length)) + 8;
+  const middle = Math.floor(rows.length / 2);
+  return rows.map((row, i) => i === middle ? row.padEnd(column) + productName : row);
+}
+
+function cellsFor(rows) {
+  return Object.values(data).find((cells) => cells.length === rows.length
+    && cells.every((cell, i) => rows[i].startsWith(cell.text)));
+}
+
+function colorize(rows, { mode = "none" } = {}) {
+  if (!["none", "256", "truecolor"].includes(mode)) throw new TypeError("invalid color mode");
+  if (mode === "none") return [...rows];
+  const cells = cellsFor(rows);
+  return rows.map((row, i) => [...row].map((ch, column) => {
+    if (!GLYPHS.has(ch)) return ch;
+    const hex = cells ? cells[i].colors[column] : "#F2EFDF";
+    if (!hex) return ch;
+    const ink = mode === "256" ? `38;5;${INDEXED[hex]}`
+      : `38;2;${[1, 3, 5].map((offset) => parseInt(hex.slice(offset, offset + 2), 16)).join(";")}`;
+    return `\x1b[${ink}m${ch}\x1b[0m`;
+  }).join(""));
+}
+
+function utf8Terminal(env = process.env) {
+  const locale = env.LC_ALL || env.LC_CTYPE || env.LANG || "";
+  return env.TERM !== "dumb" && (!locale || /utf-?8/i.test(locale));
+}
+
+function colorMode({ stream = process.stdout, env = process.env, json = false } = {}) {
+  if (json || "NO_COLOR" in env || "CI" in env || !stream?.isTTY || !utf8Terminal(env)) return "none";
+  return /truecolor|24bit/i.test(env.COLORTERM || "") || /direct/i.test(env.TERM || "") ? "truecolor" : "256";
+}
+
+function render(rows, options = {}) {
+  if (!utf8Terminal(options.env)) return ["LIT"];
+  const detected = colorMode(options);
+  return colorize(rows, { ...options, mode: detected === "none" ? "none" : options.mode || detected });
+}
+
+// Hermes' native branding surfaces consume Rich markup, not raw ANSI escapes.
+function richLogo(rows) {
+  return rows.map((row) => [...row.text].map((ch, column) =>
+    row.colors[column] ? `[${row.colors[column]}]${ch}[/]` : ch).join(""));
+}
+
+function skinLogo() {
+  return richLogo(data.standard);
+}
+
+function microLogo() {
+  return richLogo(data.micro);
+}
+
+module.exports = { standard, banner, micro, lockup, colorize, colorMode, utf8Terminal, render, skinLogo, microLogo };