litclaude-ai 0.3.39 → 0.3.41

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.41 - 2026-08-09 — foreground automatic updates
+
+- Add a default-on SessionStart update barrier that installs an exact stable
+  package candidate only after a cached check, runs doctor/version verification,
+  records a transaction receipt, and fails closed when rollback is unknown.
+- Keep the detached notifier cache-only, with sanitized npm environment,
+  bounded locking, recursion/opt-out guards, and the documented
+  `--no-auto-update` escape hatch.
+
 ## 0.3.39 - 2026-08-04 — executable plan validation
 
 - Require planner handoff to use a generated plan that passes
@@ -17,7 +26,15 @@
   tools, so the harness read-before-write guard never sees them — copying an
   example literally could clobber a file in the user's working directory.
 
-## Unreleased — `lit-comprehend` explainer artifacts
+## Unreleased — output styles enrollment and `lit-comprehend` explainer artifacts
+
+- Add output styles enrollment to the installer: a `chooseOutputStyle` prompt
+  (mirroring `chooseHudAccent`) lets users pick `off`, `asd-ste100`,
+  `asd-ste100-ko`, `eli5`, or `eli5-ko` on every install run, defaulted from
+  the prior choice. The installer writes `settings.outputStyle` clobber-safely —
+  skipping the write and printing a note when the field was changed outside
+  LitClaude — and tracks `outputStyleChoice`/`outputStyleWrittenName` under
+  the `litclaude` settings key for idempotent reinstall defaulting.
 
 - Add the `lit-comprehend` skill, the `/litclaude:lit-comprehend` command, and the
   `lit-comprehend` / `comprehend` / `lit comprehend` / `$lit-comprehend` /

package/README.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.39-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.41-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -174,18 +174,18 @@ cd /tmp
 npx --yes litclaude-ai@latest install
 ```
 
-`0.3.39` is the version prepared by this checkout. Registry lookup is authoritative
+`0.3.41` is the version prepared by this checkout. Registry lookup is authoritative
 for whether that exact version can be installed:
 
 ```bash
-npm view litclaude-ai@0.3.39 version
+npm view litclaude-ai@0.3.41 version
 ```
 
-If that lookup returns 0.3.39, the exact install is available:
+If that lookup returns 0.3.41, the exact install is available:
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.39 install
+npx --yes litclaude-ai@0.3.41 install
 ```
 
 Otherwise, wait for explicit human publication and repeat the lookup before using
@@ -205,18 +205,26 @@ offline, failed, or interrupted refreshes while preserving the last successful
 version and check time. A transition/recovery mutex and per-attempt ownership
 generation serialize stale takeover and completion, so an old worker cannot
 remove a newer reservation or overwrite its result. The refresh is a detached, three-second request to the
-official npm registry, so the management command does not wait. Noncanonical or
-future cache timestamps are not trusted. The notice is disabled for CI, JSON,
-dry-run, or non-TTY use and by either `NO_UPDATE_NOTIFIER` or
-`LITCLAUDE_NO_UPDATE_CHECK`. It never reads npm credentials or installs an
-update. Follow the version-pinned `npx --yes litclaude-ai@<version> install`
-command shown in the notice, then restart Claude Code.
+official npm registry, so the management command does not wait; this advisory
+refresh is cache-only.
+
+When a fresh cache entry identifies a newer strict stable version, an interactive
+Claude `SessionStart` or TTY `install`/`update`/`doctor` command now performs a
+foreground automatic update. It invokes the exact `litclaude-ai@<version>` package,
+passes `--no-auto-update` to the child, strips npm credential variables, takes a bounded
+backup, runs the exact-version doctor, and rolls back on timeout or verification
+failure. A receipt and journal are written under `~/.litclaude/update-notifier/automatic/`.
+The automatic lane is disabled by `--no-auto-update`, `LITCLAUDE_NO_AUTO_UPDATE`,
+`NO_UPDATE_NOTIFIER`, or `LITCLAUDE_NO_UPDATE_CHECK`; it is also a no-op for CI,
+JSON, dry-run, non-TTY management commands, imports, and tool surfaces. The
+SessionStart hook is the host-owned interactive lifecycle exception to the TTY
+check. The legacy cache refresh never installs a package by itself.
 
 The installer also sets Claude Code's `statusLine` command to the packaged
 LitClaude HUD. A typical no-color render starts like:
 
 ```text
-[🔥LITCLAUDE v0.3.39] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.41] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 The `↻` suffix is a compact rate-limit reset countdown. It is separated from

package/README_ko-KR.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.39-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.41-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -183,18 +183,18 @@ cd /tmp
 npx --yes litclaude-ai@latest install
 ```
 
-`0.3.39`은 이 checkout에서 준비 중인 version입니다. exact version의 설치 가능
+`0.3.41`은 이 checkout에서 준비 중인 version입니다. exact version의 설치 가능
 여부에는 registry 조회 결과를 authoritative한 기준으로 사용합니다.
 
 ```bash
-npm view litclaude-ai@0.3.39 version
+npm view litclaude-ai@0.3.41 version
 ```
 
-조회 결과가 0.3.39이면 exact install을 사용할 수 있습니다.
+조회 결과가 0.3.41이면 exact install을 사용할 수 있습니다.
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.39 install
+npx --yes litclaude-ai@0.3.41 install
 ```
 
 그렇지 않으면 명시적인 human publication을 기다립니다. 게시 후 조회를 다시 실행해
@@ -214,18 +214,26 @@ time을 남겨 24시간 동안 재시도를 제한하되 마지막 성공 versio
 보존합니다. transition/recovery mutex와 attempt별 ownership generation이 stale
 takeover와 completion을 직렬화하므로 이전 worker가 새 reservation을 지우거나 새
 결과를 덮어쓸 수 없습니다. refresh는 official npm registry를 최대 3초 동안 조회하는 detached
-process이므로 management command는 기다리지 않습니다. canonical하지 않거나
-미래인 cache timestamp는 신뢰하지 않습니다. CI, JSON, dry-run, non-TTY에서는
-동작하지 않으며 `NO_UPDATE_NOTIFIER` 또는 `LITCLAUDE_NO_UPDATE_CHECK`로 끌 수
-있습니다. npm credential을 읽거나 update를 자동 설치하지 않습니다. notice가 제시한
-`npx --yes litclaude-ai@<version> install`을 실행한 뒤 Claude Code를 다시
-시작하세요.
+process이므로 management command는 기다리지 않습니다. 이 advisory refresh는
+cache만 갱신합니다.
+
+fresh cache가 더 높은 strict stable version을 가리키면 interactive Claude
+`SessionStart` 또는 TTY `install`/`update`/`doctor`가 foreground automatic update를
+수행합니다. exact `litclaude-ai@<version>` package만 실행하고 child에
+`--no-auto-update`를 전달하며 npm credential 변수를 제거한 환경, bounded backup,
+exact-version doctor, 실패 시 rollback을 사용합니다. receipt와 journal은
+`~/.litclaude/update-notifier/automatic/`에 남습니다. `--no-auto-update`,
+`LITCLAUDE_NO_AUTO_UPDATE`, `NO_UPDATE_NOTIFIER`, `LITCLAUDE_NO_UPDATE_CHECK`로
+자동 설치를 끌 수 있고 CI, JSON, dry-run, non-TTY management command, import,
+tool surface에서는 동작하지 않습니다. SessionStart hook은 host가 소유한
+interactive lifecycle이므로 TTY 검사만 예외입니다. 기존 cache refresh가
+package를 자동 설치하지는 않습니다.
 
 installer는 Claude Code의 `statusLine` command도 packaged LitClaude HUD로
 설정합니다. 색상을 제거한 예시는 다음처럼 시작합니다.
 
 ```text
-[🔥LITCLAUDE v0.3.39] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.41] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 `↻` 표시는 rate-limit reset까지 남은 시간을 짧게 보여주는 countdown입니다.

package/RELEASE_CHECKLIST.md

@@ -1,6 +1,6 @@
 # LitClaude Release Checklist
 
-Status: `litclaude-ai@0.3.39` is the current release candidate — exact canonical
+Status: `litclaude-ai@0.3.41` is the current release candidate — exact canonical
 frontend corpus plus Claude-native `autoresearch`, `autoconference`, and `wikify`
 workflow-family integration. It byte-pins the frontend library, legal companions,
 family source closures, and adapters through independent commitments and package
@@ -45,9 +45,9 @@ side-effect-free, the launcher starts only a separate Claude Code
 print/background worker, and the release preserves the Korean polishing
 command, strict multi-agent review pipeline, fidelity guardrails, package
 hygiene checks, native route gates, and safe start-work handoff behavior.
-`package.json` is aligned to `0.3.39`,
-`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.39`, and the
-plugin-local MCP server reports `0.3.39`.
+`package.json` is aligned to `0.3.41`,
+`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.41`, and the
+plugin-local MCP server reports `0.3.41`.
 
 This release carries the v0.2.2 Dynamic workflow hardening surfaces:
 `/dynamic-workflow`, `workflow-check --json`, native `/goal` fallback guidance,
@@ -280,9 +280,9 @@ checkout and from an isolated install of the packed tarball:
 Before requesting publication approval, confirm these artifacts from the current
 checkout:
 
-- `package.json` version is `0.3.39`.
-- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.39`.
-- `plugins/litclaude/bin/litclaude-mcp.js` reports server version `0.3.39`.
+- `package.json` version is `0.3.41`.
+- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.41`.
+- `plugins/litclaude/bin/litclaude-mcp.js` reports server version `0.3.41`.
 - Prompt-hook tests cover bundled `SKILL.md` body injection for bare `hyperplan`, `litresearch`, `lit research`, `init-deep`, and explicit leading `$start-work`; diagnostic/copy mentions stay inert while leading natural-language `lit start work` stays BLOCKED.
 - `lit search` and `lit query` route to `/litclaude:litresearch` without activating on slash mentions, code spans, or non-lit prompts.
 - Litresearch web lanes require public API/feed preference, validator-first checks, route traces, prompt-injection quarantine, and honest auth/paywall/private-data stop reasons.

package/bin/litclaude-ai.js

@@ -30,6 +30,7 @@ import { runStartWorkContinuationCli } from "../plugins/litclaude/lib/start-work
 import { runStartWorkCli } from "../plugins/litclaude/lib/start-work-cli.mjs";
 import { runLitgoalCli } from "../plugins/litclaude/lib/litgoal/cli.mjs";
 import { runWorkflowCheckCli } from "../plugins/litclaude/lib/workflow-check.mjs";
+import { automaticUpdateRoot, runAutomaticUpdate } from "../plugins/litclaude/lib/automatic-update.mjs";
 import { runUpdateNotifier } from "./update-notifier.mjs";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -55,6 +56,11 @@ Commands:
 Public read options:
   --json        Emit a machine-readable JSON result.
 
+Update options:
+  --no-auto-update
+                Skip LitClaude's foreground automatic install for this command.
+                LITCLAUDE_NO_AUTO_UPDATE provides the same opt-out for a session.
+
 Install options:
   --permission-mode <safe|balanced|yolo>
                 Mutates global Claude settings permissions.allow/deny.
@@ -67,12 +73,24 @@ Install options:
 `;
 
 const parseArgs = (argv) => {
-  const args = [...argv];
+  const args = [];
+  let noAutoUpdate = false;
+  let invalidOption;
+  for (const arg of argv) {
+    if (arg === "--no-auto-update") {
+      noAutoUpdate = true;
+      continue;
+    }
+    if (arg.startsWith("--no-auto-update=")) {
+      invalidOption = arg;
+    }
+    args.push(arg);
+  }
   const wantsVersion = args[0] === "--version" || args[0] === "-v";
-  if (wantsVersion) return { dryRun: false, command: "version", rest: [] };
+  if (wantsVersion) return { dryRun: false, command: "version", rest: [], noAutoUpdate, invalidOption };
   const dryRun = args[0] === "--dry-run";
   if (dryRun) args.shift();
-  return { dryRun, command: args[0], rest: args.slice(1) };
+  return { dryRun, command: args[0], rest: args.slice(1), noAutoUpdate, invalidOption };
 };
 
 const litHome = () => resolve(process.env.LITCLAUDE_HOME ?? join(homedir(), ".litclaude"));
@@ -100,6 +118,19 @@ const knownExternalLspPlugins = {
 };
 const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 const hudAccentThemes = HUD_ACCENT_THEMES;
+const OUTPUT_STYLE_OPTIONS = [
+  { id: "off", label: "None / keep current" },
+  { id: "asd-ste100", label: "ASD-STE100 (English)" },
+  { id: "asd-ste100-ko", label: "ASD-STE100 (한국어)" },
+  { id: "eli5", label: "ELI5 (English)" },
+  { id: "eli5-ko", label: "ELI5 (한국어)" },
+];
+const OUTPUT_STYLE_NAMES = {
+  "asd-ste100": "LitClaude — ASD-STE100",
+  "asd-ste100-ko": "LitClaude — ASD-STE100 (한국어)",
+  "eli5": "LitClaude — ELI5",
+  "eli5-ko": "LitClaude — ELI5 (한국어)",
+};
 const permissionModes = new Set(["safe", "balanced", "yolo"]);
 const permissionOwnershipDescription =
   "preserves pre-existing entries; removes only LitClaude-inserted entries on mode change or uninstall";
@@ -351,6 +382,50 @@ const chooseHudAccent = async (existingAccent = "cyan") => {
   }
 };
 
+const normalizeOutputStyle = (value) => {
+  if (!value) return "off";
+  const v = String(value).trim().toLowerCase();
+  const match = OUTPUT_STYLE_OPTIONS.find((opt) => opt.id === v);
+  return match ? match.id : "off";
+};
+
+const shouldPromptOutputStyle = () => {
+  if (process.env.LITCLAUDE_OUTPUT_STYLE_PROMPT === "1") return true;
+  if (process.env.LITCLAUDE_OUTPUT_STYLE_PROMPT === "0") return false;
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY && !process.env.CI);
+};
+
+const chooseOutputStyle = async (existingChoice = "off") => {
+  const preserved = normalizeOutputStyle(existingChoice);
+  const envStyle = process.env.LITCLAUDE_OUTPUT_STYLE;
+  if (envStyle && process.env.LITCLAUDE_OUTPUT_STYLE_PROMPT !== "1") {
+    return normalizeOutputStyle(envStyle);
+  }
+  if (!shouldPromptOutputStyle()) return envStyle ? normalizeOutputStyle(envStyle) : preserved;
+
+  process.stdout.write("Choose LitClaude output style:\n");
+  for (const [index, option] of OUTPUT_STYLE_OPTIONS.entries()) {
+    process.stdout.write(`  ${index}) ${option.label}\n`);
+  }
+
+  const preservedLabel = OUTPUT_STYLE_OPTIONS.find((opt) => opt.id === preserved)?.label ?? preserved;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`Style 0-4 [${preservedLabel}]: `);
+    const trimmed = answer.trim();
+    const byIndex = OUTPUT_STYLE_OPTIONS[Number.parseInt(trimmed, 10)]?.id;
+    const selected = byIndex !== undefined ? byIndex : (trimmed ? normalizeOutputStyle(trimmed) : preserved);
+    const isExplicitOff = trimmed.toLowerCase() === "off" || trimmed.toLowerCase() === "none";
+    if (trimmed && byIndex === undefined && selected === "off" && !isExplicitOff) {
+      process.stdout.write("OUTPUT_STYLE_WARNING: unknown style; using 'off'\n");
+    }
+    process.stdout.write(`OUTPUT_STYLE_SELECTED: ${selected}\n`);
+    return selected;
+  } finally {
+    rl.close();
+  }
+};
+
 const hudCommandForPlugin = (pluginPath, accent = "cyan") =>
   `LITCLAUDE_HUD_ACCENT=${normalizeHudAccent(accent)} node "${join(pluginPath, "bin", "litclaude-hud.js")}"`;
 
@@ -458,6 +533,30 @@ const installHudStatusLine = (pluginPath, home = claudeHome(), accent = "cyan")
   writeClaudeSettings(settings, home);
 };
 
+const installOutputStyle = (choice, home = claudeHome()) => {
+  if (choice === "off") return;
+  const writtenName = OUTPUT_STYLE_NAMES[choice] ?? null;
+  if (!writtenName) return;
+
+  const settings = readClaudeSettings(home);
+  const existingLitClaude = settings[litClaudeSettingsKey] ?? {};
+  const previousWrittenName = existingLitClaude.outputStyleWrittenName ?? null;
+
+  const currentOutputStyle = settings.outputStyle;
+  if (currentOutputStyle === undefined || currentOutputStyle === previousWrittenName) {
+    settings.outputStyle = writtenName;
+  } else {
+    process.stdout.write(`Note: outputStyle was changed outside LitClaude (currently "${currentOutputStyle}"). Switch it via /config if you want LitClaude's style.\n`);
+  }
+
+  settings[litClaudeSettingsKey] = {
+    ...existingLitClaude,
+    outputStyleChoice: choice,
+    outputStyleWrittenName: writtenName,
+  };
+  writeClaudeSettings(settings, home);
+};
+
 const uninstallHudStatusLine = (home = claudeHome()) => {
   const settingsPath = claudeSettingsPath(home);
   if (!existsSync(settingsPath)) return;
@@ -840,6 +939,7 @@ const install = async ({ dryRun, rest }) => {
   const existingLitClaude = readClaudeSettings(home)[litClaudeSettingsKey] ?? {};
   const { permissionMode, permissionExplicit } = parseInstallOptions(rest, existingLitClaude.permissionMode);
   const existingHudAccent = normalizeHudAccent(existingLitClaude.hudAccent);
+  const existingOutputStyle = existingLitClaude.outputStyleChoice ?? "off";
   const requestedHudAccent = process.env.LITCLAUDE_HUD_ACCENT
     ? normalizeHudAccent(process.env.LITCLAUDE_HUD_ACCENT)
     : existingHudAccent;
@@ -868,6 +968,7 @@ const install = async ({ dryRun, rest }) => {
   }
 
   const hudAccent = await chooseHudAccent(existingHudAccent);
+  const outputStyleChoice = await chooseOutputStyle(existingOutputStyle);
   progress.prepare({ claudeTarget: home, litTarget: litClaudeHome });
   await progress.run(
     {
@@ -901,7 +1002,10 @@ const install = async ({ dryRun, rest }) => {
       purpose: "Enable the plugin and HUD, then update global Claude settings permissions.allow/deny",
       target: claudeSettingsPath(home),
     },
-    () => registerClaudePlugin(targetPlugin, localMarketplace, home, hudAccent, permissionMode),
+    () => {
+      registerClaudePlugin(targetPlugin, localMarketplace, home, hudAccent, permissionMode);
+      installOutputStyle(outputStyleChoice, home);
+    },
   );
 
   const litRoot = versionRoot(litClaudeHome);
@@ -958,6 +1062,7 @@ const doctor = ({ dryRun }) => {
     process.stdout.write(`Would check Claude plugin registry: ${pluginKey}\n`);
     process.stdout.write(`Would check Claude statusLine HUD: ${hudCommandForPlugin(pluginPath)}\n`);
     process.stdout.write("Would check global Claude settings permissions.allow/deny and LitClaude ownership-safe removal metadata\n");
+    process.stdout.write(`Would inspect automatic-update receipt/journal under: ${join(automaticUpdateRoot(litHome()), "receipt.json")}\n`);
     process.stdout.write(`Would run: node ${join(pluginPath, "bin", "litclaude-scientific-visualization-doctor.js")}\n`);
     process.stdout.write("Would verify exact canonical frontend corpus bytes, legal companions, no extras, and three canonical runtime closures\n");
     return;
@@ -1063,6 +1168,10 @@ const doctor = ({ dryRun }) => {
   }
 
   process.stdout.write(`Plugin path: ${pluginPath}\n`);
+  const automaticReceiptPath = join(automaticUpdateRoot(litHome()), "receipt.json");
+  if (existsSync(automaticReceiptPath)) {
+    process.stdout.write(`AUTOMATIC_UPDATE_RECEIPT: ${automaticReceiptPath}\n`);
+  }
   const settings = readClaudeSettings();
   const permissionFailures = permissionIntegrityFailures(settings);
   if (permissionFailures.length > 0) {
@@ -1152,6 +1261,48 @@ const uninstall = ({ dryRun }) => {
   process.stdout.write("UNINSTALL_PASS\n");
 };
 
+const emitAutomaticUpdateResult = (result) => {
+  if (!result || result.status === "gated" || result.status === "no-candidate" || result.status === "current" || result.status === "stale-cache" || result.status === "locked") return;
+  if (result.status === "installed") {
+    process.stdout.write(`AUTO_UPDATE_PASS: LitClaude ${result.targetVersion} installed\n`);
+    if (result.receiptPath) process.stdout.write(`AUTO_UPDATE_RECEIPT: ${result.receiptPath}\n`);
+    return;
+  }
+  const label = result.status === "rolled-back"
+    ? "ROLLBACK"
+    : result.status === "rollback-failed" ? "UNKNOWN_STATE" : "STOPPED";
+  process.stderr.write(`AUTO_UPDATE_${label}: automatic update did not replace the current install\n`);
+  if (result.receiptPath) process.stderr.write(`AUTO_UPDATE_RECEIPT: ${result.receiptPath}\n`);
+};
+
+const runEligibleAutomaticUpdate = (parsed) => {
+  if (!["install", "update", "doctor"].includes(parsed.command)) return { status: "gated" };
+  // Validate install/update flags before any automatic side effect. This keeps
+  // malformed or ambiguous requests fail-closed rather than forwarding them to npm.
+  if (parsed.command === "install" || parsed.command === "update") {
+    const existing = readClaudeSettings()[litClaudeSettingsKey] ?? {};
+    parseInstallOptions(parsed.rest, existing.permissionMode);
+  }
+  const result = runAutomaticUpdate({
+    surface: "management",
+    command: parsed.command,
+    rest: parsed.rest,
+    dryRun: parsed.dryRun,
+    currentVersion: version,
+    cachePath: updateNotifierCachePath(),
+    litHome: litHome(),
+    claudeHome: claudeHome(),
+    env: process.env,
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    noAutoUpdate: parsed.noAutoUpdate,
+    cwd: process.cwd(),
+  });
+  emitAutomaticUpdateResult(result);
+  return result;
+};
+
 const main = async () => {
   const parsed = parseArgs(process.argv.slice(2));
   const { command } = parsed;
@@ -1160,6 +1311,17 @@ const main = async () => {
     printUsage();
     process.exit(64);
   }
+  if (parsed.invalidOption) fail(`Unknown update option: ${parsed.invalidOption}`, 64);
+
+  const automaticUpdate = runEligibleAutomaticUpdate(parsed);
+  if (automaticUpdate.status === "rollback-failed") {
+    fail("AUTO_UPDATE_UNKNOWN_STATE: automatic update rollback failed; run `litclaude doctor` before using the install", 1);
+  }
+  if (automaticUpdate.status === "installed") {
+    // The automatic transaction already ran the exact-version install and its
+    // post-install doctor. Do not immediately re-run the old package's command.
+    return;
+  }
 
   switch (command) {
     case "install":

package/docs/hooks.md

@@ -99,7 +99,7 @@ incumbents are not silently removed.
 
 | Event | Runner | Purpose |
 | --- | --- | --- |
-| `SessionStart` | `plugins/litclaude/bin/litclaude-hook.js session-start` | Discovers repo-local rule files and injects the bodies of always-on rules, plus the rules-loaded context line. |
+| `SessionStart` | `plugins/litclaude/bin/litclaude-hook.js session-start` | Runs the bounded foreground automatic-update barrier when a fresh cache names a newer version, then discovers repo-local rule files and injects the bodies of always-on rules plus the rules-loaded context line. |
 | `UserPromptSubmit` | `plugins/litclaude/bin/litclaude-hook.js user-prompt-submit` | Detects prompt routes and injects workflow context; independently delivers static rules not already recorded for this session. |
 | `PreToolUse` | `plugins/litclaude/bin/litclaude-hook.js pre-tool-use` | Enforces semantic action/root grants before Write, Edit, MultiEdit, NotebookEdit, Bash, Agent, and bounded read tools execute. |
 | `PostToolUse` | `plugins/litclaude/bin/litclaude-hook.js post-tool-use` | Names the post-edit checks the edit actually earned, and injects any glob-scoped rule matching the edited paths. |
@@ -109,6 +109,21 @@ incumbents are not silently removed.
 | `SubagentStop` | `plugins/litclaude/bin/litclaude-hook.js subagent-stop` | Finalizes the lane without child continuation. |
 | `SessionEnd` | `plugins/litclaude/bin/litclaude-hook.js session-end` | Records root-session end without blocking Claude. |
 
+### Foreground automatic-update barrier
+
+The SessionStart hook waits for one bounded automatic-update transaction when a
+fresh product-owned cache entry names a newer strict stable package version. The
+transaction uses a separate install lock, credential-free npm environment, exact
+`npm exec --yes --package litclaude-ai@<version>` arguments, a backup/journal,
+post-install doctor, and rollback before the hook emits its rules context. The
+same lane is available to interactive TTY `install`, `update`, and `doctor`
+commands. `--no-auto-update`, `LITCLAUDE_NO_AUTO_UPDATE`,
+`NO_UPDATE_NOTIFIER`, and `LITCLAUDE_NO_UPDATE_CHECK` disable it. CI, JSON,
+dry-run, non-TTY management commands, import, and tool surfaces remain no-op;
+the host-owned SessionStart hook is the lifecycle exception to the TTY check.
+The detached registry cache refresh described in the update-notifier section is
+advisory and never performs an install.
+
 ## Bounded-authority start-work lifecycle
 
 The hook and CLI share `plugins/litclaude/lib/start-work-lifecycle.mjs`.

package/docs/native-goal-surface.md

@@ -37,5 +37,7 @@ path. The condition does not make the ledger self-validating; recorded evidence
 still needs the normal LitClaude review gates.
 
 This documentation does not add a fake command, MCP method, or hook dispatch.
-It also does not auto-install anything, mutate a transcript, inject keystrokes,
-or claim success based on prompt context alone.
+The native-goal binding itself does not auto-install a goal, mutate a transcript,
+inject keystrokes, or claim success based on prompt context alone. Package
+updates, when eligible, follow the separate bounded transaction documented in
+[`docs/hooks.md`](hooks.md#foreground-automatic-update-barrier).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litclaude-ai",
-  "version": "0.3.39",
+  "version": "0.3.41",
   "description": "Claude Code-native workflow distribution.",
   "type": "module",
   "bin": {

package/plugins/litclaude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "litclaude",
   "description": "Claude Code-native workflow plugin with a bounded-authority start-work lifecycle.",
-  "version": "0.3.39",
+  "version": "0.3.41",
   "author": {
     "name": "LitClaude contributors"
   },

package/plugins/litclaude/bin/litclaude-hook.js

@@ -20,6 +20,7 @@ import { litgoalGoalsPath } from "../lib/litgoal/paths.mjs";
 import { readLitgoalState } from "../lib/litgoal/state.mjs";
 import { completeAutoloopGoal, evaluateAutoloop, readAutoloopState, writeAutoloopState } from "../lib/litgoal/autoloop.mjs";
 import { buildNativeGoalBindingGuidance, normalizeGoalObjective } from "../lib/native-goal-binding.mjs";
+import { automaticUpdateCachePath, runAutomaticUpdate } from "../lib/automatic-update.mjs";
 import {
   handleStartWorkStop,
   handleStartWorkPreToolUse,
@@ -84,9 +85,9 @@ const hookEventNames = {
   "session-end": "SessionEnd",
 };
 
-const writeContext = (additionalContext, systemMessage) => {
+const writeContext = (additionalContext, systemMessage, shouldContinue = true) => {
   const payload = {
-    continue: true,
+    continue: shouldContinue,
     hookSpecificOutput: {
       hookEventName: hookEventNames[eventName],
       additionalContext,
@@ -785,6 +786,14 @@ const litworkContext = ({ command, skill, skillId, discipline, softConfirm, safe
 // working directory — the same discipline staticSkillBodyContext uses.
 const pluginRoot = fileURLToPath(new URL("../", import.meta.url));
 
+const pluginVersion = (() => {
+  try {
+    return JSON.parse(readFileSync(join(pluginRoot, ".claude-plugin", "plugin.json"), "utf8")).version;
+  } catch {
+    return null;
+  }
+})();
+
 // The rules engine is advisory context. Every lane below is wrapped so a rules failure
 // degrades to "no rules injected" instead of taking the hook — and the hook's own
 // contract — down with it.
@@ -813,6 +822,25 @@ const input = readInput();
 switch (eventName) {
   case "session-start": {
     const cwd = typeof input.cwd === "string" ? input.cwd : "unknown workspace";
+    const automaticUpdate = pluginVersion
+      ? runAutomaticUpdate({
+        surface: "session-start",
+        currentVersion: pluginVersion,
+        cachePath: automaticUpdateCachePath(),
+        litHome: process.env.LITCLAUDE_HOME,
+        claudeHome: process.env.CLAUDE_CONFIG_DIR ?? process.env.CLAUDE_HOME,
+        env: process.env,
+        input,
+        cwd: typeof input.cwd === "string" ? input.cwd : process.cwd(),
+      })
+      : { status: "gated" };
+    const automaticContext = automaticUpdate.status === "installed"
+      ? ` Automatic update completed in the foreground to ${automaticUpdate.targetVersion}; receipt: ${inertFilesystemData(automaticUpdate.receiptPath)}.`
+      : automaticUpdate.status === "rollback-failed"
+        ? " BLOCKED: automatic update rollback failed; install state may be inconsistent. Run `litclaude doctor` before relying on it."
+      : ["rolled-back", "failed"].includes(automaticUpdate.status)
+        ? " Automatic update was not applied; the existing install was retained and the receipt records the result."
+        : "";
     const pressureContext = transcriptHasContextPressure(input.transcript_path)
       ? " Context pressure detected: before edits, reread HANDOFF.md, the active plan, .litclaude/start-work/ledger.jsonl, .litclaude/boulder.json, and git status --short."
       : "";
@@ -820,7 +848,11 @@ switch (eventName) {
     // AGENTS.md, plans). The engine now actually delivers the rule bodies themselves.
     const rules = staticRulesContext({ cwd, sessionId: input.session_id });
     const rulesSuffix = rules ? `\n\n${rules}` : "";
-    writeContext(`LitClaude rules loaded for ${inertFilesystemData(cwd)}. Read CLAUDE.md, AGENTS.md, .claude/rules/**/*.md, .github/instructions/**/*.md, and named plan or handoff files before edits.${pressureContext}${rulesSuffix}`);
+    writeContext(
+      `LitClaude rules loaded for ${inertFilesystemData(cwd)}. Read CLAUDE.md, AGENTS.md, .claude/rules/**/*.md, .github/instructions/**/*.md, and named plan or handoff files before edits.${automaticContext}${pressureContext}${rulesSuffix}`,
+      undefined,
+      automaticUpdate.status !== "rollback-failed",
+    );
     break;
   }
   case "user-prompt-submit": {

package/plugins/litclaude/bin/litclaude-mcp.js

@@ -3,7 +3,7 @@
 import { readPublicSource } from "../lib/public-source-reader/reader.mjs";
 
 const protocolVersion = "2024-11-05";
-const serverVersion = "0.3.39";
+const serverVersion = "0.3.41";
 
 const publicSourceReadTool = {
   name: "public_source_read",

package/plugins/litclaude/hooks/hooks.json

@@ -6,8 +6,8 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/litclaude-hook.js\" session-start",
-            "timeout": 10,
-            "statusMessage": "loading LitClaude rules"
+            "timeout": 60,
+            "statusMessage": "checking LitClaude update and loading rules"
           }
         ]
       }