@litfamily/lithermes 1.0.0

package/assets/lithermes-plugin/vendor/scientific-visualization/tests/test_figure_export.py

@@ -0,0 +1,51 @@
+import unittest
+import sys
+from unittest.mock import Mock
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from scripts.figure_export import save_for_journal, save_publication_figure
+
+
+class FigureExportTests(unittest.TestCase):
+    def tearDown(self):
+        plt.close("all")
+
+    def test_publication_export_defaults_to_transparent_tight_high_dpi(self):
+        fig, _ = plt.subplots()
+        fig.savefig = Mock()
+
+        save_publication_figure(fig, "figure", formats=["png", "pdf"])
+
+        png_kwargs = fig.savefig.call_args_list[0].kwargs
+        pdf_kwargs = fig.savefig.call_args_list[1].kwargs
+        self.assertEqual(png_kwargs["bbox_inches"], "tight")
+        self.assertTrue(png_kwargs["transparent"])
+        self.assertEqual(png_kwargs["facecolor"], "none")
+        self.assertGreaterEqual(png_kwargs["dpi"], 600)
+        self.assertGreaterEqual(pdf_kwargs["dpi"], 600)
+
+    def test_journal_export_forces_nontransparent_background(self):
+        fig, _ = plt.subplots()
+        fig.savefig = Mock()
+
+        save_for_journal(fig, "figure", journal="nature", figure_type="combination")
+
+        kwargs = fig.savefig.call_args.kwargs
+        self.assertFalse(kwargs["transparent"])
+        self.assertEqual(kwargs["facecolor"], "white")
+        self.assertEqual(kwargs["bbox_inches"], "tight")
+
+    def test_publication_export_rejects_missing_output_parent(self):
+        fig, _ = plt.subplots()
+        missing_parent = Path("definitely_missing_parent") / "subdir" / "figure"
+
+        with self.assertRaises(FileNotFoundError):
+            save_publication_figure(fig, missing_parent, formats=["png"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/assets/lithermes-plugin/vendor/scientific-visualization/tests/test_style_presets.py

@@ -0,0 +1,114 @@
+import unittest
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from scripts import style_presets
+
+
+class DummyFont:
+    def __init__(self, name):
+        self.name = name
+
+
+class StylePresetTests(unittest.TestCase):
+    def tearDown(self):
+        mpl.rcdefaults()
+
+    def test_rcparams_uses_safe_font_stack_when_pretendard_and_arial_missing(self):
+        fonts = [DummyFont("DejaVu Sans"), DummyFont("AppleGothic")]
+
+        with patch.object(style_presets.font_manager.fontManager, "ttflist", fonts):
+            style_presets.rcparams()
+
+        self.assertEqual(mpl.rcParams["font.family"], ["sans-serif"])
+        self.assertEqual(mpl.rcParams["font.sans-serif"][:2], ["DejaVu Sans", "AppleGothic"])
+        self.assertEqual(mpl.rcParams["pdf.fonttype"], 42)
+        self.assertEqual(mpl.rcParams["ps.fonttype"], 42)
+        self.assertEqual(mpl.rcParams["svg.fonttype"], "none")
+
+    def test_rcparams_prioritizes_pretendard_then_arial_when_available(self):
+        fonts = [DummyFont("Arial"), DummyFont("Helvetica"), DummyFont("Pretendard"), DummyFont("DejaVu Sans")]
+
+        with patch.object(style_presets.font_manager.fontManager, "ttflist", fonts):
+            style_presets.rcparams()
+
+        self.assertEqual(mpl.rcParams["font.sans-serif"][:2], ["Pretendard", "Arial"])
+
+    def test_rcparams_forces_agent_safe_grid_and_transparent_export_defaults(self):
+        mpl.rcParams["axes.grid"] = True
+        mpl.rcParams["savefig.transparent"] = False
+
+        style_presets.rcparams()
+
+        self.assertFalse(mpl.rcParams["axes.grid"])
+        self.assertEqual(mpl.rcParams["savefig.bbox"], "tight")
+        self.assertTrue(mpl.rcParams["savefig.transparent"])
+
+    def test_configure_for_journal_validates_widths_and_supports_one_half_column(self):
+        style_presets.configure_for_journal("nature", "one_half")
+        width, height = mpl.rcParams["figure.figsize"]
+
+        self.assertAlmostEqual(width, 120 / 25.4, places=3)
+        self.assertLessEqual(height, 170 / 25.4)
+
+        with self.assertRaises(ValueError):
+            style_presets.configure_for_journal("nature", "poster")
+
+    def test_ensure_zero_origin_ticks_keeps_first_tick_at_zero(self):
+        style_presets.rcparams()
+        fig, ax = plt.subplots()
+        ax.plot([0, 1, 2], [0, 50, 100])
+        ax.set_ylim(0, 100)
+
+        style_presets.ensure_zero_origin_ticks(ax, y=True, nbins=5)
+
+        self.assertEqual(ax.get_ylim()[0], 0)
+        self.assertAlmostEqual(ax.get_yticks()[0], 0)
+        self.assertTrue(all(tick >= 0 for tick in ax.get_yticks()))
+        plt.close(fig)
+
+    def test_style_legend_keeps_black_text_for_nature_and_colored_text_when_requested(self):
+        style_presets.rcparams()
+        fig, ax = plt.subplots()
+        line_a, = ax.plot([0, 1], [0, 1], color="#E69F00", label="A")
+        line_b, = ax.plot([0, 1], [1, 0], color="#56B4E9", label="B")
+
+        legend = style_presets.style_legend(ax, color_text=False)
+        self.assertTrue(legend.get_frame_on())
+        self.assertEqual(legend.get_frame().get_alpha(), 1)
+        self.assertTrue(all(text.get_color() == "black" for text in legend.get_texts()))
+
+        legend = style_presets.style_legend(ax, color_text=True)
+        self.assertEqual([text.get_color() for text in legend.get_texts()], [line_a.get_color(), line_b.get_color()])
+        plt.close(fig)
+
+    def test_style_legend_colored_text_supports_bar_patch_handles(self):
+        style_presets.rcparams()
+        fig, ax = plt.subplots()
+        bars = ax.bar([0, 1], [1, 2], color=["#E69F00", "#56B4E9"], label="bars")
+
+        legend = style_presets.style_legend(ax, color_text=True)
+
+        self.assertEqual(legend.get_texts()[0].get_color(), bars.patches[0].get_facecolor())
+        plt.close(fig)
+
+    def test_plot_scatter_only_creates_no_connecting_line_artists(self):
+        style_presets.rcparams()
+        fig, ax = plt.subplots()
+
+        collection = style_presets.plot_scatter_only(ax, [0, 1, 2, 3], [1, 3, 2, 4], label="observations")
+
+        self.assertIn(collection, ax.collections)
+        self.assertEqual(len(ax.lines), 0)
+        self.assertEqual(collection.get_label(), "observations")
+        plt.close(fig)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/bin/lithermes.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+const { main } = require("../src/cli");
+
+main(process.argv.slice(2)).catch((error) => {
+  const code = Number.isInteger(error.exitCode) ? error.exitCode : 1;
+  console.error(error.message || String(error));
+  process.exit(code);
+});

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@litfamily/lithermes",
+  "version": "1.0.0",
+  "description": "npx/bunx installer for the LitHermes Hermes plugin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wjgoarxiv/lithermes.git",
+    "directory": "packages/lithermes-installer"
+  },
+  "homepage": "https://www.npmjs.com/package/@litfamily/lithermes",
+  "bugs": {
+    "url": "https://github.com/wjgoarxiv/lithermes/issues"
+  },
+  "bin": {
+    "lithermes": "bin/lithermes.js",
+    "lithermes-ai": "bin/lithermes.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "assets/lithermes-plugin/vendor/handoff/**",
+    "assets/lithermes-plugin/vendor/scientific-visualization/**",
+    "!assets/**/__pycache__/**",
+    "!assets/**/*.pyc",
+    "!assets/**/.[!.]*/**",
+    "!assets/**/.lit[o]pencode/**",
+    "!assets/**/upstream/**",
+    "README.md",
+    "README_Ko-KR.md",
+    "readme-assets"
+  ],
+  "scripts": {
+    "pretest": "npm run clean:payload",
+    "test": "node --test test/*.test.js",
+    "check:version": "node scripts/check-version-lockstep.js",
+    "test:python": "node scripts/test-python.js",
+    "qa:negative-matrix": "node qa/negative-gate-matrix.js",
+    "qa:negative-control": "node qa/negative-gate-matrix.js --self-check",
+    "qa:behaviors": "node qa/behavior-replacement-probe.js",
+    "qa:real-surface": "npm run qa:negative-matrix && npm run qa:behaviors && npm run qa:negative-control",
+    "sync-plugin": "node scripts/sync-plugin.js",
+    "pack:dry": "npm run clean:payload && npm pack --dry-run --ignore-scripts --json",
+    "clean:payload": "find assets -name __pycache__ -type d -prune -exec rm -rf {} + && find assets -name '*.py[co]' -delete",
+    "prepublishOnly": "node scripts/prepublish-guard.js",
+    "prepack": "npm run clean:payload"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/readme-assets/badge-license.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="78" height="20" role="img" aria-label="license: MIT"><title>license: MIT</title><g shape-rendering="crispEdges"><rect width="47" height="20" fill="#080d14"/><rect x="47" width="31" height="20" fill="#d7f75b"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="245" y="140" textLength="370" transform="scale(.1)">license</text><text x="615" y="140" textLength="210" transform="scale(.1)" fill="#333">MIT</text></g></svg>

package/readme-assets/badge-version.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.0"><title>release: 1.0.0</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.0</text></g></svg>

package/readme-assets/lithermes-wordmark.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1113" height="238" viewBox="0 0 1113 238" role="img" aria-labelledby="title">
+<title id="title">LITHERMES display type</title>
+<rect width="100%" height="100%" fill="#080D14"/>
+<g transform="translate(24 24) scale(1.235499 1.354962)"><path d="M0 0H28V112H78L62 140H0Z" fill="#F2EFDF" transform="translate(0 0)" fill-rule="evenodd" /><path d="M0 0H28V140H0Z" fill="#F2EFDF" transform="translate(90 0)" fill-rule="evenodd" /><path d="M0 0H94V28H61V140H33V28H0Z" fill="#F2EFDF" transform="translate(130 0)" fill-rule="evenodd" /><path d="M0 0H28V56H66V0H94V140H66V84H28V140H0Z" fill="#F2EFDF" transform="translate(236 0)" fill-rule="evenodd" /><path d="M0 0H86V28H28V56H74L59 84H28V112H86V140H0Z" fill="#F2EFDF" transform="translate(342 0)" fill-rule="evenodd" /><path d="M0 0H67L94 27V63L72 85L98 140H66L43 90H28V140H0Z M28 28V62H54L66 50V40L54 28Z" fill="#F2EFDF" transform="translate(440 0)" fill-rule="evenodd" /><path d="M0 140V0H26L54 48L82 0H108V140H80V51L54 91L28 51V140Z" fill="#F2EFDF" transform="translate(550 0)" fill-rule="evenodd" /><path d="M0 0H86V28H28V56H74L59 84H28V112H86V140H0Z" fill="#F2EFDF" transform="translate(670 0)" fill-rule="evenodd" /><path d="M94 0H25L0 25V60L22 82H66V105L59 112H0V140H69L94 115V78L71 55H28V35L35 28H94Z" fill="#F2EFDF" transform="translate(768 0)" fill-rule="evenodd" /></g>
+</svg>

package/src/cli.js

@@ -0,0 +1,396 @@
+const path = require("node:path");
+const readline = require("node:readline");
+const { installLitHermes, previewModelRoute, uninstallLitHermes } = require("./lib/install");
+const { promptModelRouteSession, renderInstallBanner, routeFromConfig } = require("./lib/modelPrompt");
+const { checkLitHermes, doctorLitHermes } = require("./lib/check");
+const { createSpinner, renderInstallReceipt, shouldUseSpinner } = require("./lib/spinner");
+const { listHud, applyHud, clearHud, promptAccent, resolveHome } = require("./lib/hud");
+const { supportsColor, findAccent, skinName } = require("./lib/skins");
+const { runSkillLoop } = require("./lib/skillLoop");
+const {
+  readConfig,
+  clearDisplaySkinConfig,
+  readDisplaySkinConfig,
+  readOutputStyleConfig,
+  setDisplaySkinConfig,
+  setOutputStyleConfig,
+  writeConfig,
+} = require("./lib/config");
+const {
+  runAutomaticUpdate,
+  scheduleUpdateCheck,
+  shouldAutoUpdate,
+} = require("./lib/updateNotifier");
+
+function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const item = argv[i];
+    if (!item.startsWith("--")) {
+      positionals.push(item);
+      continue;
+    }
+    const key = item.slice(2);
+    if (["yes", "offline", "json", "dry-run", "spinner", "no-spinner", "gateway-offline", "force", "patch-installed-hermes", "no-patch-installed-hermes", "rollback-patches", "list", "no-hud", "no-style", "no-auto-update", "reconfigure-model"].includes(key)) {
+      flags[key] = true;
+      continue;
+    }
+    const value = argv[i + 1];
+    if (!value || value.startsWith("--")) {
+      flags[key] = "";
+      continue;
+    }
+    flags[key] = value;
+    i += 1;
+  }
+  return { command: positionals[0] || "help", flags, positionals };
+}
+
+function packageVersion() {
+  const pkg = require(path.join(__dirname, "..", "package.json"));
+  // Print the command/brand name (the bin), not the npm package name — the
+  // command is `lithermes` even though the npm package is named `@litfamily/lithermes`.
+  const brand = Object.keys(pkg.bin || {})[0] || pkg.name;
+  return `${brand} ${pkg.version}`;
+}
+
+function printCommandBanner(command, flags, runtime = {}) {
+  // Keep machine-oriented routes byte-stable: their stdout is consumed as a
+  // version line or JSON receipt rather than a human-facing command report.
+  if (flags.json || command === "version" || command === "skill-loop" || command === "__auto-update") return;
+  const env = runtime.env || process.env;
+  const streams = runtime.streams || { stdout: process.stdout };
+  const output = streams.stdout || process.stdout;
+  const version = require(path.join(__dirname, "..", "package.json")).version;
+  output.write(`${renderInstallBanner({
+    version, env, stream: output,
+    color: !flags.yes && !flags["dry-run"] && supportsColor({ stream: output, env }),
+  })}\n`);
+}
+
+function scheduleUpdateSafely(command, flags, runtime = {}) {
+  try {
+    const pkg = require(path.join(__dirname, "..", "package.json"));
+    const schedule = runtime.scheduleUpdateCheck || scheduleUpdateCheck;
+    schedule({ command, flags, currentVersion: pkg.version });
+  } catch {
+    // Update advice must never change command output or exit behavior.
+  }
+}
+
+async function runLifecycleUpdateSafely(command, flags, runtime = {}) {
+  try {
+    const pkg = require(path.join(__dirname, "..", "package.json"));
+    const hermesHome = resolveHome(flags);
+    const gate = runtime.shouldAutoUpdate || shouldAutoUpdate;
+    const eligible = gate({
+      trigger: "cli",
+      command,
+      flags,
+      env: runtime.env || process.env,
+      streams: runtime.streams || { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr },
+      hermesHome,
+      existsSync: runtime.existsSync,
+      isNodeRuntime: runtime.isNodeRuntime,
+      isInteractive: runtime.isInteractive,
+    });
+    if (!eligible) return { status: "skipped", reason: "ineligible" };
+    const update = runtime.runAutomaticUpdate || runAutomaticUpdate;
+    return await update({
+      currentVersion: pkg.version,
+      hermesHome,
+      env: runtime.env || process.env,
+      now: runtime.now,
+      fetchLatestVersionFn: runtime.fetchLatestVersionFn,
+      spawnSync: runtime.spawnSync,
+      doctor: runtime.doctor,
+      timeoutMs: runtime.timeoutMs,
+    });
+  } catch {
+    // An update failure is fail-open for the requested management command. The
+    // transaction function itself records a redacted receipt when it got far
+    // enough to mutate a profile.
+    return { status: "failed", reason: "automatic-update-error" };
+  }
+}
+
+// Interactive model-route selection (installer choice contract). Runs only on
+// a real TTY without --yes, and presents the current route as the defaults for
+// both fresh and already-configured homes. Returns "chosen" when the prompts
+// ran and the user confirmed via the summary card, "aborted" on a refused card,
+// and null when the prompts do not apply. Consent is granted ONLY by that
+// explicit Enter: fallback and unsafe-stop previews leave the --yes gate
+// untouched.
+async function maybePromptModelRoute(flags, runtime = {}) {
+  if (flags.yes || flags["dry-run"] || flags.json) return null;
+  const env = runtime.env || process.env;
+  const streams = runtime.streams || { stdin: process.stdin, stdout: process.stdout };
+  const input = streams.stdin || process.stdin;
+  const output = streams.stdout || process.stdout;
+  const interactive = runtime.isInteractive ?? Boolean(input.isTTY && output.isTTY);
+  if (!interactive || "CI" in env) return null;
+  let preview;
+  try {
+    preview = previewModelRoute(flags);
+  } catch {
+    return null;
+  }
+  if (preview.action !== "write" && preview.action !== "preserve") return null;
+  const currentRoute = routeFromConfig(readConfig(resolveHome(flags)));
+  const { confirmed, route } = await promptModelRouteSession({
+    configPath: preview.configPath,
+    env,
+    input,
+    output,
+    preset: currentRoute,
+  });
+  if (!confirmed) return "aborted";
+  const routeChanged = ["provider", "model", "effort", "childProvider", "childModel", "childEffort"]
+    .some((key) => route[key] !== currentRoute[key]);
+  if (preview.action === "preserve" && routeChanged) flags["reconfigure-model"] = true;
+  flags.provider = route.provider;
+  flags.model = route.model;
+  flags.effort = route.effort;
+  flags["child-provider"] = route.childProvider;
+  flags["child-model"] = route.childModel;
+  flags["child-effort"] = route.childEffort;
+  flags.yes = true;
+  return "chosen";
+}
+
+const STYLE_MENU = [
+  { id: "asd-ste100",    label: "ASD-STE100 (English)" },
+  { id: "asd-ste100-ko", label: "ASD-STE100 (한국어)" },
+  { id: "eli5",          label: "ELI5 (English)" },
+  { id: "eli5-ko",       label: "ELI5 (한국어)" },
+];
+
+async function maybePickOutputStyle(flags) {
+  if (flags["dry-run"]) return;
+  const home = resolveHome(flags);
+  const current = readOutputStyleConfig(readConfig(home));
+  let chosen = null;
+  if (typeof flags.style === "string" && flags.style.trim()) {
+    const styleId = flags.style.trim();
+    if (!STYLE_MENU.some((s) => s.id === styleId)) {
+      console.error(`Output style: unknown id '${styleId}'; skipping (valid: ${STYLE_MENU.map((s) => s.id).join(", ")}).`);
+      return;
+    }
+    chosen = styleId;
+  } else if (flags["no-style"]) {
+    return;
+  } else if (process.stdin.isTTY && process.stdout.isTTY && !("CI" in process.env)) {
+    chosen = await (new Promise((resolve) => {
+      process.stdout.write("Choose an output style:\n");
+      process.stdout.write(`   0. None / keep current${current ? ` (${current})` : ""}\n`);
+      STYLE_MENU.forEach((s, i) => process.stdout.write(`   ${i + 1}. ${s.label}\n`));
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: supportsColor() });
+      rl.on("close", () => resolve(null));
+      rl.question("Pick 0-4 (Enter to skip): ", (answer) => {
+        const trimmed = answer.trim();
+        const num = parseInt(trimmed, 10);
+        if (!trimmed || trimmed === "0" || Number.isNaN(num)) { resolve(null); }
+        else if (num >= 1 && num <= STYLE_MENU.length) { resolve(STYLE_MENU[num - 1].id); }
+        else { resolve(null); }
+        rl.close();
+      });
+    }));
+  } else {
+    return;
+  }
+  if (chosen) {
+    const before = readConfig(home);
+    const after = setOutputStyleConfig(before, chosen);
+    if (after !== before) writeConfig(home, after);
+    console.log(`Output style set to '${chosen}'.`);
+  }
+}
+
+// Keep explicit HUD choices manual. On the prompted install path the accent
+// picker runs; the --yes path auto-applies the named Ignition skin on
+// a fresh interactive color-capable install.
+async function maybePickHudAccent(flags, runtime = {}, { promptForAccent = false } = {}) {
+  if (flags["dry-run"]) return;
+  let entry = null;
+  if (typeof flags.hud === "string" && flags.hud.trim()) {
+    entry = findAccent(flags.hud);
+    if (!entry) {
+      console.error(`HUD: unknown accent '${flags.hud}'; skipping (run \`lithermes hud --list\`).`);
+      return;
+    }
+  } else if (flags["no-hud"]) {
+    return;
+  } else if (promptForAccent) {
+    const streams = runtime.streams || { stdin: process.stdin, stdout: process.stdout };
+    const chosen = await promptAccent({
+      input: streams.stdin || process.stdin,
+      output: streams.stdout || process.stdout,
+      color: supportsColor({ stream: streams.stdout || process.stdout, env: runtime.env || process.env }),
+    });
+    if (chosen) {
+      console.log(applyHud(chosen.accent, flags));
+    }
+    return;
+  } else {
+    const env = runtime.env || process.env;
+    const streams = runtime.streams || { stdin: process.stdin, stdout: process.stdout };
+    const input = streams.stdin || process.stdin;
+    const output = streams.stdout || process.stdout;
+    const interactive = runtime.isInteractive ?? Boolean(input.isTTY && output.isTTY);
+    const color = supportsColor({ stream: output, env });
+    if (!interactive || env.CI || !color) return;
+
+    const home = resolveHome(flags);
+    const before = readConfig(home);
+    const normalized = `${before.replace(/\r\n/g, "\n").replace(/\n*$/, "")}\n`;
+    if (readDisplaySkinConfig(before) || clearDisplaySkinConfig(normalized) !== normalized) return;
+
+    entry = findAccent("ignition");
+    const name = skinName(entry.accent);
+    const after = setDisplaySkinConfig(before, name);
+    if (after !== before) writeConfig(home, after);
+    console.log(`LitHermes HUD set to ${entry.label} (${name}).`);
+    return;
+  }
+  if (entry) console.log(applyHud(entry.accent, flags));
+}
+
+async function main(argv, runtime = {}) {
+  const { command, flags, positionals } = parseArgs(argv);
+  printCommandBanner(command, flags, runtime);
+  if (command === "version" || command === "--version" || command === "-v") {
+    console.log(packageVersion());
+    return;
+  }
+  if (command === "hud") {
+    const accent = positionals[1];
+    if (flags.list || !accent) {
+      console.log(listHud({ color: supportsColor(), hermesHome: resolveHome(flags) }));
+      return;
+    }
+    if (accent === "off" || accent === "clear" || accent === "none") {
+      console.log(clearHud(flags));
+      return;
+    }
+    try {
+      console.log(applyHud(accent, flags));
+    } catch (error) {
+      console.error(error.message);
+      process.exitCode = error.exitCode || 1;
+    }
+    return;
+  }
+  if (command === "skill-loop") {
+    const skillLoopArgs = positionals.slice(1);
+    if (skillLoopArgs[0] === "reject" && typeof flags.reason === "string") {
+      skillLoopArgs.push("--reason", flags.reason);
+    }
+    process.exitCode = runSkillLoop(skillLoopArgs, flags, runtime);
+    return;
+  }
+  const lifecycle = await runLifecycleUpdateSafely(command, flags, runtime);
+  if (lifecycle.status === "failed" && (lifecycle.state === "unknown" || lifecycle.rollback?.status === "failed")) {
+    console.error("LitHermes automatic update left the Hermes home in an unknown state; run `lithermes doctor --offline --hermes-home PATH` before continuing.");
+    process.exitCode = 1;
+    return;
+  }
+  // An old `install` command must not immediately overwrite a newer payload
+  // just installed by the barrier. The user can rerun the now-current command
+  // if they explicitly need its local flags.
+  if (command === "install" && lifecycle.status === "updated") {
+    console.log(`LitHermes automatic update committed (${lifecycle.targetVersion}). Restart Hermes to load it.`);
+    return;
+  }
+  if (command === "install") {
+    const prompted = await maybePromptModelRoute(flags, runtime);
+    if (prompted === "aborted") {
+      console.log("Install aborted; nothing was written.");
+      return;
+    }
+    const spinner = shouldUseSpinner({ flags }) ? createSpinner({
+      target: resolveHome(flags),
+      version: require(path.join(__dirname, "..", "package.json")).version,
+    }) : null;
+    try {
+      if (spinner) spinner.start();
+      const result = installLitHermes({
+        ...flags,
+        onProgress: spinner ? (message) => spinner.update(message) : undefined,
+      });
+      if (spinner) spinner.succeed("Installing LitHermes complete");
+      console.log(spinner ? renderInstallReceipt(result.message) : result.message);
+    } catch (error) {
+      if (spinner) spinner.fail(error instanceof Error ? error.message : "Unexpected install error.");
+      throw error;
+    }
+    await maybePickHudAccent(flags, runtime, { promptForAccent: prompted === "chosen" });
+    await maybePickOutputStyle(flags);
+    scheduleUpdateSafely(command, flags, runtime);
+    return;
+  }
+  if (command === "uninstall") {
+    const result = uninstallLitHermes(flags);
+    console.log(result.message);
+    return;
+  }
+  // Private bridge used by the installed Python pre_llm_call lifecycle hook.
+  // The hook resolves an exact registry version and invokes this command from
+  // that exact package. The transaction wrapper then runs the guarded install
+  // child and performs the same backup/doctor/rollback protocol as the native
+  // interactive CLI barrier. It is deliberately absent from help output.
+  if (command === "__auto-update") {
+    const pkg = require(path.join(__dirname, "..", "package.json"));
+    let lifecycle;
+    try {
+      const update = runtime.runAutomaticUpdate || runAutomaticUpdate;
+      lifecycle = await update({
+        currentVersion: flags["installed-version"] || pkg.version,
+        latestVersion: pkg.version,
+        hermesHome: resolveHome(flags),
+        env: runtime.env || process.env,
+        now: runtime.now,
+        spawnSync: runtime.spawnSync,
+        doctor: runtime.doctor,
+        timeoutMs: runtime.timeoutMs,
+      });
+    } catch {
+      lifecycle = { status: "failed", reason: "automatic-update-error" };
+    }
+    if (lifecycle.status === "failed") {
+      process.exitCode = 1;
+      const suffix = lifecycle.state === "unknown" ? " Hermes home state is unknown; run `lithermes doctor --offline --hermes-home PATH`." : "";
+      console.error(`LitHermes automatic update failed: ${lifecycle.reason}.${suffix}`);
+    } else if (lifecycle.status === "updated") {
+      console.log(`LitHermes automatic update committed (${lifecycle.targetVersion}).`);
+    }
+    return;
+  }
+  if (command === "check") {
+    const result = checkLitHermes(flags);
+    console.log(result.message);
+    scheduleUpdateSafely(command, flags, runtime);
+    return;
+  }
+  if (command === "doctor") {
+    const result = doctorLitHermes(flags);
+    console.log(result.message);
+		if (result.ok === false) process.exitCode = 1;
+    if (result.ok !== false) scheduleUpdateSafely(command, flags, runtime);
+    return;
+  }
+  console.log([
+    "lithermes commands:",
+    "  install [--yes] [--dry-run] [--reconfigure-model] [--provider ID] [--model ID] [--effort LEVEL]",
+    "          [--child-provider ID] [--child-model ID] [--child-effort LEVEL]",
+    "          [--spinner] [--no-spinner] [--hud <accent>] [--no-hud] [--no-auto-update] [--hermes-home PATH]",
+    "  check [--offline] [--gateway-offline] [--hermes-home PATH]",
+    "  doctor [--offline] [--hermes-home PATH] [--hermes-repo PATH]",
+    "  uninstall [--yes] [--hermes-home PATH]",
+    "  hud [<accent>|off|--list] [--hermes-home PATH]   (Hermes HUD skin accents)",
+    "  skill-loop review|propose <file>|list|apply <id>|reject <id> [--reason TEXT]|rollback <ledger-id>|curator",
+    "  version",
+  ].join("\n"));
+}
+
+module.exports = { main, parseArgs };

package/src/lib/autoUpdate.js

@@ -0,0 +1,4 @@
+// Publicly discoverable automatic-update surface. The implementation remains
+// next to the advisory notifier so the cache-only worker and foreground
+// transaction share strict semver/registry helpers without a dependency loop.
+module.exports = require("./updateNotifier");