@litfamily/litcodex 1.0.18 → 1.0.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README-Ko-KR.md +46 -147
  2. package/README.md +46 -150
  3. package/dist/auto-update.d.ts +2 -1
  4. package/dist/auto-update.js +2 -1
  5. package/dist/cli.d.ts +1 -1
  6. package/dist/cli.js +85 -5
  7. package/dist/config-migration/gpt56-policy.js +0 -3
  8. package/dist/config-migration/multi-agent-v2-guard.js +10 -21
  9. package/dist/config-migration/root-settings.js +30 -31
  10. package/dist/config-migration/toml-lines.d.ts +12 -0
  11. package/dist/config-migration/toml-lines.js +113 -0
  12. package/dist/config-migration/toml-shape.js +8 -15
  13. package/dist/install/doctor-render.js +19 -0
  14. package/dist/install/doctor-tui.d.ts +7 -0
  15. package/dist/install/doctor-tui.js +65 -0
  16. package/dist/install/doctor.js +2 -0
  17. package/dist/install/generated-skill-payload-hashes.d.ts +5 -5
  18. package/dist/install/generated-skill-payload-hashes.js +5 -5
  19. package/dist/install/index.d.ts +6 -1
  20. package/dist/install/index.js +16 -2
  21. package/dist/install/office-runtime.d.ts +1 -0
  22. package/dist/install/office-runtime.js +2 -2
  23. package/dist/install/types.d.ts +10 -0
  24. package/dist/install/uninstall.d.ts +2 -0
  25. package/dist/install/uninstall.js +12 -1
  26. package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
  27. package/marketplace/plugins/litcodex/components/auto-update/dist/auto-update.d.ts +16 -1
  28. package/marketplace/plugins/litcodex/components/auto-update/dist/auto-update.js +99 -13
  29. package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
  30. package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
  31. package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
  32. package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
  33. package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
  34. package/marketplace/plugins/litcodex/components/rules/dist/deliverable-hedge-guard.d.ts +6 -0
  35. package/marketplace/plugins/litcodex/components/rules/dist/deliverable-hedge-guard.js +10 -29
  36. package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
  37. package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
  38. package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
  39. package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
  40. package/marketplace/plugins/litcodex/hooks/hooks.json +1 -1
  41. package/marketplace/plugins/litcodex/skills/lit-pptx/runtime/package-lock.json +167 -119
  42. package/marketplace/plugins/litcodex/skills/lit-pptx/runtime/package.json +1 -1
  43. package/marketplace/plugins/litcodex/skills/lit-pptx/scripts/validate_pptx.py +3 -3
  44. package/marketplace/plugins/litcodex/skills/readme-studio/templates/hyperframes-cover/package-lock.json +169 -121
  45. package/marketplace/plugins/litcodex/skills/readme-studio/templates/remotion-cover/package-lock.json +3 -3
  46. package/model-catalog.json +17 -8
  47. package/node_modules/@litcodex/lit-loop/README.md +1 -1
  48. package/node_modules/@litcodex/lit-loop/package.json +1 -1
  49. package/package.json +12 -4
  50. package/readme-assets/badge-version.svg +1 -1
@@ -303,11 +303,11 @@ export const README_STUDIO_PAYLOAD_HASHES = {
303
303
  "templates/cover-source.json": "2f65ec7706431a308619f57c5741c5fa0b24bd60c0c2c649c364aafdb8170e26",
304
304
  "templates/hyperframes-cover/index.html": "cd89b5c6c0fbeeb895eb38a7eb9e232d622323a48adc9773b548032acf6d6c64",
305
305
  "templates/hyperframes-cover/index.motion.json": "18dab5464db575a5048e0f3a476c0eddbf284545147283ba04025a8495d16e43",
306
- "templates/hyperframes-cover/package-lock.json": "6cb809955794acbefa0f8f4ba0a00ba7d91e0b79c65345653ef5a5a8e21d59d8",
306
+ "templates/hyperframes-cover/package-lock.json": "d6d9b47ce49369bfc73d62e8efa01de2dca153e17fdde274456bb642a1afe2c8",
307
307
  "templates/hyperframes-cover/package.json": "9ec0e871126193a545f898f0ed994412a518e2bf06170cd07b3fc9e61cae2530",
308
308
  "templates/readme-cover-section.md": "324e61dd601c42af7117f0eed7ef6ca58c66444c0607919831a64685f4d49b7a",
309
309
  "templates/readme-facts.json": "3155f9b36f98db20d588f68358d0152aa24ad395c1cb62c39a72d2084abb6ddd",
310
- "templates/remotion-cover/package-lock.json": "09fb65f7b5a5088e4f568e6e444a0606f220116d3b3eae0d9ccbec17573219b1",
310
+ "templates/remotion-cover/package-lock.json": "586931a24fffb1117eb5b04f5a4917b5c099f0c040f6c04d278e2ba3c39f1f77",
311
311
  "templates/remotion-cover/package.json": "88448fd7021c32527fb36ee4d6a709f32f1289eae126d9532fca033c4b2debeb",
312
312
  "templates/remotion-cover/src/ReadmeCover.tsx": "bdaddbadcddd99102e2f915eb16eaa1d1def9d8aacd777772afc6d66d106443d",
313
313
  "templates/remotion-cover/src/Root.tsx": "0b3e22dd556216d67bbbca4745f5b041c9fc2a986ca3ba9945bf4b916a51e004",
@@ -805,8 +805,8 @@ export const PPTX_PAYLOAD_HASHES = {
805
805
  "references/tonalities/paper.md": "39973f22a4021c5dc1a4210ef123d7444b2dd279352418314caaabb8ae5d669e",
806
806
  "references/tonalities/signal.md": "3c52945f7c4d513b97ae382b6bd544f9cf1daf5780b6f462ac947284b1d38285",
807
807
  "references/tonalities/studio.md": "cca577f4458a6be2306995d996dd99e2d605b7f2a80cbc256c7eff776b65858f",
808
- "runtime/package-lock.json": "73cd3f54d979460757603c8a44c395e777cc0655d7f1c54dfb9512a9c77b8acd",
809
- "runtime/package.json": "700e183641eff75aa87b963d68d96b9c8e0bb21516a3b413c94b70bea10fbd55",
808
+ "runtime/package-lock.json": "67b19a8431f408ab6c75eeb6dd658850089e13f072bf475ae72a2ae79d4e1687",
809
+ "runtime/package.json": "a92c2edf9320ce49043317cb4c8437134a8473bd935f1b769fc595303fb1f879",
810
810
  "runtime/requirements.in": "893e4232e7e69e731053a8c3b3383eb22fb3f82affd6d96ad96d3a8ef8321656",
811
811
  "runtime/requirements.lock": "79028c622048b4a43f747a2bee14ce838b7092aa7eff39c0c725463394a2c85d",
812
812
  "scripts/check_ooxml.py": "52078a351f5f999e2871e9d4136c195f396dcfee45fea6cb6d2a84f07bd837a2",
@@ -832,7 +832,7 @@ export const PPTX_PAYLOAD_HASHES = {
832
832
  "scripts/office-run.mjs": "272f9bd74db9456fe5f5cce8f1dbf04fac60469f470a41c6571afafc5f444508",
833
833
  "scripts/package.json": "dbf8353f77358bc12169b7bb7301e1978d5b503e002ee927229a8993672818fc",
834
834
  "scripts/qa_deck.py": "dbde757b72dffe3f5b31def40dc5f7b92444a2b768ac3c91879fc959c30a2edc",
835
- "scripts/validate_pptx.py": "24032616fdfac18f42839667c601d12fd7ea425e8230b96ef3681ea290f2755a",
835
+ "scripts/validate_pptx.py": "2d3ddd0fd2564dab93f1bd74832c602d8df4f31e2856fd8a3b1e2c3e089d4ec4",
836
836
  "specs/markdown-slide-spec-v1.md": "eb9b04d070d9f2774746e65a34e5e6833fefd097ea7e01fc32327934ca8ee42b",
837
837
  "specs/markdown-slide-spec-v2.md": "3a7a91dfb21418711d5ad28f7a542603bc2f145051950478be0d2107f7fa5458",
838
838
  "specs/slide-ast-v1.schema.json": "d6d244bd30b6747645bd4a4f81cf0e2a3d12aa5aa4d0d11f2fb8b5f93dca1187",
@@ -23,5 +23,10 @@ export declare function runInstallCli(args: readonly string[], io?: RouteIo): Pr
23
23
  * side-effect-free.
24
24
  */
25
25
  export declare function runDoctorCli(args: readonly string[], io?: RouteIo): number;
26
- /** `litcodex uninstall [--json]` — remove the registered plugin via `codex plugin remove`. */
26
+ /** Shared text for a `--dry-run` of a state-changing route: the title, then numbered steps. */
27
+ export declare function renderDryRunPlan(title: string, steps: readonly string[]): string;
28
+ /**
29
+ * `litcodex uninstall [--json] [--dry-run]` — remove the registered plugin via `codex plugin remove`.
30
+ * With `--dry-run` it prints the removal plan, runs no `codex` and changes no file.
31
+ */
27
32
  export declare function runUninstallCli(args: readonly string[], io?: RouteIo): number;
@@ -25,7 +25,7 @@ import { resolveBundledMarketplaceSource } from "./package-root.js";
25
25
  import { buildInstallPlan } from "./plan.js";
26
26
  import { renderInstallPlan } from "./render-plan.js";
27
27
  import { createBlockingSpinnerMotion } from "./spinner-motion.js";
28
- import { runUninstall } from "./uninstall.js";
28
+ import { runUninstall, uninstallPlanSteps } from "./uninstall.js";
29
29
  export { renderDoctorText, runDoctor } from "./doctor.js";
30
30
  export { INSTALL_ERROR_CODES, InstallError, toErrorJson } from "./errors.js";
31
31
  export { executeInstallPlan } from "./execute.js";
@@ -382,11 +382,25 @@ export function runDoctorCli(args, io = defaultIo()) {
382
382
  }
383
383
  return report.ok ? 0 : 4;
384
384
  }
385
- /** `litcodex uninstall [--json]` — remove the registered plugin via `codex plugin remove`. */
385
+ /** Shared text for a `--dry-run` of a state-changing route: the title, then numbered steps. */
386
+ export function renderDryRunPlan(title, steps) {
387
+ return `${title} plan (dry run: nothing was changed)\n${steps.map((step, index) => `${index + 1}. ${step}`).join("\n")}\n`;
388
+ }
389
+ /**
390
+ * `litcodex uninstall [--json] [--dry-run]` — remove the registered plugin via `codex plugin remove`.
391
+ * With `--dry-run` it prints the removal plan, runs no `codex` and changes no file.
392
+ */
386
393
  export function runUninstallCli(args, io = defaultIo()) {
387
394
  const json = args.includes("--json");
388
395
  writeCommandBanner(io, args);
389
396
  const codexHome = resolveCodexHome(io.env);
397
+ if (args.includes("--dry-run")) {
398
+ const steps = uninstallPlanSteps(codexHome);
399
+ io.stdout.write(json
400
+ ? `${JSON.stringify({ ok: true, dryRun: true, codexHome, steps })}\n`
401
+ : renderDryRunPlan("litcodex uninstall", steps));
402
+ return 0;
403
+ }
390
404
  const env = io.env;
391
405
  const codexBin = env["CODEX_BIN"]?.trim() && existsSync(env["CODEX_BIN"].trim()) ? env["CODEX_BIN"].trim() : "codex";
392
406
  const result = runUninstall({
@@ -6,6 +6,7 @@ type Spawn = (command: string, args: readonly string[], options: {
6
6
  stdout?: string | null;
7
7
  error?: Error;
8
8
  };
9
+ export declare function officeRuntimeScript(codexHome: string): string;
9
10
  export declare function officeRuntimeStatus(codexHome: string, spawn?: Spawn, env?: NodeJS.ProcessEnv): {
10
11
  ready: boolean;
11
12
  pptx: boolean;
@@ -3,11 +3,11 @@ import { existsSync } from "node:fs";
3
3
  import { join } from "node:path";
4
4
  import { managedMarketplaceRoot } from "./marketplace.js";
5
5
  const RETRY = "npm exec --package @litfamily/litcodex -- litcodex office-runtime install";
6
- function runner(codexHome) {
6
+ export function officeRuntimeScript(codexHome) {
7
7
  return join(managedMarketplaceRoot(codexHome), "plugins/litcodex/skills/lit-pptx/scripts/office-run.mjs");
8
8
  }
9
9
  function invoke(codexHome, command, spawn, env) {
10
- const path = runner(codexHome);
10
+ const path = officeRuntimeScript(codexHome);
11
11
  if (!existsSync(path))
12
12
  return { status: null, stdout: "", error: new Error("Office skill payload is missing") };
13
13
  return spawn(process.execPath, [path, command], { encoding: "utf8", env });
@@ -93,6 +93,16 @@ export interface DoctorReport {
93
93
  readonly jevSkillHint?: JevSkillHintState;
94
94
  /** Opt-in automatic handoff: off by default; the percent comes from the user. */
95
95
  readonly autoHandoff?: AutoHandoffDoctorReport;
96
+ /** Built-in Codex status line / terminal title snippet; null when the config already sets both. */
97
+ readonly tuiSuggestion?: TuiSuggestion | null;
98
+ }
99
+ export type TuiSuggestionKey = "status_line" | "terminal_title";
100
+ export interface TuiSuggestion {
101
+ readonly missing: readonly TuiSuggestionKey[];
102
+ /** Where the snippet goes: a new `[tui]` table, under the existing one, or as root `tui.` keys. */
103
+ readonly placement: "new-table" | "existing-table" | "root-dotted";
104
+ readonly configPath: string;
105
+ readonly snippet: string;
96
106
  }
97
107
  export interface AutoHandoffDoctorReport {
98
108
  readonly state: "on" | "off";
@@ -26,3 +26,5 @@ export declare function runUninstall(deps: UninstallDeps): {
26
26
  readonly ok: boolean;
27
27
  readonly codexHome: string;
28
28
  };
29
+ /** The steps `runUninstall` would take, for `--dry-run`. Pure: reads and writes nothing. */
30
+ export declare function uninstallPlanSteps(codexHome: string): readonly string[];
@@ -6,6 +6,7 @@ import { unsafeEffectiveRoute } from "../config-migration/gpt56-policy.js";
6
6
  import { removeSubagentDefaults } from "../config-migration/multi-agent-v2-guard.js";
7
7
  import { ensureNativeDefaultAgentConfig } from "../config-migration/native-default-route.js";
8
8
  import { GPT56_PROFILE_FILE_NAMES, isManagedGpt56ProfileContent } from "../config-migration/profile-files.js";
9
+ import { isTomlTableHeader } from "../config-migration/toml-lines.js";
9
10
  import { NATIVE_DEFAULT_AGENT_FILE } from "./agent-routing.js";
10
11
  import { prepareAgentSources } from "./agents-install.js";
11
12
  import { isSafeManagedMarketplaceRoot, LITCODEX_MARKETPLACE, LITCODEX_PLUGIN_REF, managedMarketplaceRoot, } from "./marketplace.js";
@@ -31,6 +32,16 @@ export function runUninstall(deps) {
31
32
  removeManagedProfileFiles(deps);
32
33
  return { ok: pluginOk && marketplaceOk, codexHome: deps.codexHome };
33
34
  }
35
+ /** The steps `runUninstall` would take, for `--dry-run`. Pure: reads and writes nothing. */
36
+ export function uninstallPlanSteps(codexHome) {
37
+ return [
38
+ `Remove the plugin: codex plugin remove ${LITCODEX_PLUGIN_REF}`,
39
+ `Remove the marketplace: codex plugin marketplace remove ${LITCODEX_MARKETPLACE}, then delete ${managedMarketplaceRoot(codexHome)} only if the marketplace removal succeeds`,
40
+ `Remove LitCodex agent roles from ${join(codexHome, "agents")} and the native default route ${join(codexHome, NATIVE_DEFAULT_AGENT_FILE)}, when they still match what LitCodex installed`,
41
+ `Remove the managed [agents] defaults from ${join(codexHome, "config.toml")} and LitCodex-generated profile files from ${codexHome}`,
42
+ `If the marketplace root or config.toml is a symlink or otherwise unsafe, uninstall refuses to change anything`,
43
+ ];
44
+ }
34
45
  function isSafeUninstallPaths(deps) {
35
46
  if (!isSafeManagedMarketplaceRoot(deps.codexHome, deps.fs))
36
47
  return false;
@@ -252,7 +263,7 @@ function withoutGeneratedNativeBinding(config, target) {
252
263
  const trimmed = line.trim();
253
264
  if (trimmed === "")
254
265
  continue;
255
- if (trimmed.startsWith("[") && trimmed.endsWith("]"))
266
+ if (isTomlTableHeader(trimmed))
256
267
  break;
257
268
  return null;
258
269
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "litcodex",
3
- "version": "1.0.18",
3
+ "version": "1.0.20",
4
4
  "description": "LitCodex Codex plugin: the lit-loop activation, durable loop runtime, and local review-gated knowledge.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -1,5 +1,13 @@
1
1
  export declare const AUTO_UPDATE_PACKAGE: "@litfamily/litcodex";
2
2
  export declare const DEFAULT_AUTO_UPDATE_TIMEOUT_MS = 10000;
3
+ /**
4
+ * Limit for each install step: the global npm install, the target's Codex install, and both rollbacks.
5
+ * Measured on 2026-10-11 against the public registry from an empty npm cache: the global install with its
6
+ * postinstall pre-warm took 1.7-5.6 s and the target's Codex install took 7.9-14.1 s, so the old shared
7
+ * 10 s limit could cut the Codex step. Sixty seconds is about ten times the slowest npm install and four
8
+ * times the slowest Codex install, while one stuck step still cannot hold a session for long.
9
+ */
10
+ export declare const DEFAULT_AUTO_UPDATE_INSTALL_TIMEOUT_MS = 60000;
3
11
  export declare const DEFAULT_AUTO_UPDATE_INTERVAL_MS: number;
4
12
  export declare const DEFAULT_AUTO_UPDATE_RETRY_INTERVAL_MS: number;
5
13
  export declare const DEFAULT_AUTO_UPDATE_LOCK_STALE_MS: number;
@@ -27,6 +35,7 @@ export interface AutoUpdateVerification {
27
35
  readonly observedVersion?: string | undefined;
28
36
  readonly doctorStatus: AutoUpdateDoctorStatus;
29
37
  readonly doctorDetail?: string | undefined;
38
+ readonly codexInstallAttempted?: boolean | undefined;
30
39
  readonly detail: string;
31
40
  }
32
41
  export interface AutoUpdateSpawnOptions {
@@ -48,6 +57,7 @@ export interface AutoUpdateVerifyOptions {
48
57
  readonly cwd: string;
49
58
  readonly env: NodeJS.ProcessEnv;
50
59
  readonly timeout: number;
60
+ readonly installTimeout?: number;
51
61
  readonly spawn: AutoUpdateSpawn;
52
62
  }
53
63
  export type AutoUpdateVerify = (expectedVersion: string, options: AutoUpdateVerifyOptions) => AutoUpdateVerification;
@@ -77,6 +87,7 @@ export interface AutoUpdateRunOptions extends AutoUpdatePlanOptions {
77
87
  readonly stateRoot?: string;
78
88
  readonly cwd?: string;
79
89
  readonly timeoutMs?: number;
90
+ readonly installTimeoutMs?: number;
80
91
  readonly lockStaleMs?: number;
81
92
  readonly spawn?: AutoUpdateSpawn;
82
93
  readonly verifyInstalled?: AutoUpdateVerify;
@@ -110,8 +121,12 @@ export declare function resolveAutoUpdatePlan(options: AutoUpdatePlanOptions): A
110
121
  /**
111
122
  * Prove that npm's global executable resolves to the exact version that the install command targeted.
112
123
  * npm can return exit 0 for a no-op, warning, or partially successful lifecycle, so the install result
113
- * is never treated as committed until this independent version probe agrees.
124
+ * is never treated as committed until this independent version probe agrees. Only that exact package
125
+ * then installs itself into Codex (managed marketplace and plugin cache); its doctor runs last, because
126
+ * the doctor fails while Codex still holds the previous plugin version.
114
127
  */
115
128
  export declare function verifyInstalledVersion(expectedVersion: string, options: AutoUpdateVerifyOptions): AutoUpdateVerification;
116
129
  export declare function runForegroundAutoUpdate(options: AutoUpdateRunOptions): AutoUpdateResult;
130
+ /** The longest one transaction can run: three probes plus four install steps (two forward, two back). */
131
+ export declare function autoUpdateWorstCaseMs(timeout?: number, installTimeout?: number): number;
117
132
  export declare function readAutoUpdateReceipt(stateRoot?: string): AutoUpdateReceipt | null;
@@ -5,6 +5,14 @@ import { homedir, tmpdir } from "node:os";
5
5
  import { dirname, join } from "node:path";
6
6
  export const AUTO_UPDATE_PACKAGE = "@litfamily/litcodex";
7
7
  export const DEFAULT_AUTO_UPDATE_TIMEOUT_MS = 10_000;
8
+ /**
9
+ * Limit for each install step: the global npm install, the target's Codex install, and both rollbacks.
10
+ * Measured on 2026-10-11 against the public registry from an empty npm cache: the global install with its
11
+ * postinstall pre-warm took 1.7-5.6 s and the target's Codex install took 7.9-14.1 s, so the old shared
12
+ * 10 s limit could cut the Codex step. Sixty seconds is about ten times the slowest npm install and four
13
+ * times the slowest Codex install, while one stuck step still cannot hold a session for long.
14
+ */
15
+ export const DEFAULT_AUTO_UPDATE_INSTALL_TIMEOUT_MS = 60_000;
8
16
  export const DEFAULT_AUTO_UPDATE_INTERVAL_MS = 24 * 60 * 60 * 1000;
9
17
  export const DEFAULT_AUTO_UPDATE_RETRY_INTERVAL_MS = 30 * 60 * 1000;
10
18
  export const DEFAULT_AUTO_UPDATE_LOCK_STALE_MS = 10 * 60 * 1000;
@@ -36,6 +44,14 @@ const SAFE_ENV_KEYS = [
36
44
  "LANG",
37
45
  "LC_ALL",
38
46
  ];
47
+ // These name the Codex host being managed. The target package's install, version probe and doctor
48
+ // must act on the same host as the session that started the update, so only those children get them.
49
+ const CODEX_HOST_ENV_KEYS = [
50
+ "CODEX_HOME",
51
+ "CODEX_BIN",
52
+ "LITCODEX_DATA_ROOT",
53
+ "LITCODEX_AUTO_UPDATE_STATE_ROOT",
54
+ ];
39
55
  function parseStableVersion(version) {
40
56
  if (typeof version !== "string")
41
57
  return null;
@@ -118,6 +134,23 @@ function withSanitizedNpmEnvironment(env, operation) {
118
134
  rmSync(sandbox.root, { recursive: true, force: true });
119
135
  }
120
136
  }
137
+ function withCodexHost(safe, env) {
138
+ const host = { ...safe };
139
+ for (const key of CODEX_HOST_ENV_KEYS) {
140
+ const value = env[key];
141
+ if (value !== undefined)
142
+ host[key] = value;
143
+ }
144
+ return host;
145
+ }
146
+ function installIntoCodex(command, options, timeout) {
147
+ return options.spawn(command, ["exec", "--global", "--", "litcodex", "install", "--no-auto-update"], {
148
+ cwd: options.cwd,
149
+ env: options.env,
150
+ timeout,
151
+ stdio: "ignore",
152
+ });
153
+ }
121
154
  export function sanitizeNpmEnvironment(env = process.env) {
122
155
  // This public inspection helper intentionally returns the generated paths so callers/tests can
123
156
  // prove that user npm state was not reused. Runtime subprocesses use withSanitizedNpmEnvironment,
@@ -325,7 +358,9 @@ function latestFromRegistry(env, spawn, cwd, timeout) {
325
358
  /**
326
359
  * Prove that npm's global executable resolves to the exact version that the install command targeted.
327
360
  * npm can return exit 0 for a no-op, warning, or partially successful lifecycle, so the install result
328
- * is never treated as committed until this independent version probe agrees.
361
+ * is never treated as committed until this independent version probe agrees. Only that exact package
362
+ * then installs itself into Codex (managed marketplace and plugin cache); its doctor runs last, because
363
+ * the doctor fails while Codex still holds the previous plugin version.
329
364
  */
330
365
  export function verifyInstalledVersion(expectedVersion, options) {
331
366
  const versionArgs = ["exec", "--global", "--", "litcodex", "--version"];
@@ -365,6 +400,17 @@ export function verifyInstalledVersion(expectedVersion, options) {
365
400
  detail: `global litcodex resolved ${observedVersion}; expected ${expectedVersion}`,
366
401
  };
367
402
  }
403
+ const codexInstall = installIntoCodex(options.command, options, positiveTimeout(options.installTimeout, DEFAULT_AUTO_UPDATE_INSTALL_TIMEOUT_MS));
404
+ if (!spawnSucceeded(codexInstall)) {
405
+ return {
406
+ status: "unavailable",
407
+ expectedVersion,
408
+ observedVersion,
409
+ doctorStatus: "not-run",
410
+ codexInstallAttempted: true,
411
+ detail: `target litcodex install exited ${String(codexInstall.status)}`,
412
+ };
413
+ }
368
414
  const doctorArgs = ["exec", "--global", "--", "litcodex", "doctor", "--json", "--no-auto-update"];
369
415
  const doctorResult = options.spawn(options.command, doctorArgs, {
370
416
  cwd: options.cwd,
@@ -379,6 +425,7 @@ export function verifyInstalledVersion(expectedVersion, options) {
379
425
  observedVersion,
380
426
  doctorStatus: "failed",
381
427
  doctorDetail: `target litcodex doctor --json exited ${String(doctorResult.status)}`,
428
+ codexInstallAttempted: true,
382
429
  detail: `global litcodex resolved exact ${expectedVersion}, but target doctor did not pass`,
383
430
  };
384
431
  }
@@ -402,6 +449,7 @@ export function verifyInstalledVersion(expectedVersion, options) {
402
449
  observedVersion,
403
450
  doctorStatus: "failed",
404
451
  doctorDetail: "target litcodex doctor --json reported unhealthy or malformed output",
452
+ codexInstallAttempted: true,
405
453
  detail: `global litcodex resolved exact ${expectedVersion}, but target doctor did not pass`,
406
454
  };
407
455
  }
@@ -411,7 +459,8 @@ export function verifyInstalledVersion(expectedVersion, options) {
411
459
  observedVersion,
412
460
  doctorStatus: "passed",
413
461
  doctorDetail: "target litcodex doctor --json passed",
414
- detail: `global litcodex resolved exact ${expectedVersion}; target doctor passed`,
462
+ codexInstallAttempted: true,
463
+ detail: `global litcodex resolved exact ${expectedVersion}; installed into Codex; target doctor passed`,
415
464
  };
416
465
  }
417
466
  export function runForegroundAutoUpdate(options) {
@@ -425,29 +474,37 @@ export function runForegroundAutoUpdate(options) {
425
474
  const spawn = options.spawn ?? defaultSpawn;
426
475
  const cwd = options.cwd ?? process.cwd();
427
476
  const timeout = positiveTimeout(options.timeoutMs, positiveInteger(env["LITCODEX_AUTO_UPDATE_TIMEOUT_MS"], DEFAULT_AUTO_UPDATE_TIMEOUT_MS));
477
+ const installTimeout = positiveTimeout(options.installTimeoutMs, positiveInteger(env["LITCODEX_AUTO_UPDATE_INSTALL_TIMEOUT_MS"], DEFAULT_AUTO_UPDATE_INSTALL_TIMEOUT_MS));
428
478
  const state = readState(statePath);
429
- const latestVersion = options.latestVersion ?? env["LITCODEX_LATEST_VERSION"] ?? latestFromRegistry(env, spawn, cwd, timeout);
430
- const plan = resolveAutoUpdatePlan({
479
+ const planOptions = {
431
480
  ...options,
432
481
  env,
433
482
  now,
434
- latestVersion,
435
483
  lastCheckedAt: state.lastCheckedAt,
436
484
  lastAttemptedAt: state.lastAttemptedAt,
437
485
  lastStatus: state.lastStatus,
438
- });
486
+ };
487
+ // Every opt-out and throttle is decided before the registry is asked, so a throttled session never
488
+ // spends a network round trip. The registry is consulted only when nothing else stopped the run.
489
+ let plan = resolveAutoUpdatePlan(planOptions);
490
+ if (plan.reason === "unknown-latest" && (options.latestVersion ?? env["LITCODEX_LATEST_VERSION"]) === undefined) {
491
+ plan = resolveAutoUpdatePlan({ ...planOptions, latestVersion: latestFromRegistry(env, spawn, cwd, timeout) });
492
+ }
439
493
  if (!plan.shouldRun) {
440
494
  const result = noRunResult(plan, stateRoot, startedAt);
495
+ const earlierFailure = unresolvedFailure(readAutoUpdateReceipt(stateRoot), plan);
441
496
  if (options.writeReceipt !== false) {
442
497
  atomicJson(journalPath, { phase: "skipped", ...result });
443
- atomicJson(receiptPath, result);
498
+ if (!earlierFailure)
499
+ atomicJson(receiptPath, result);
500
+ }
501
+ if (plan.reason === "up-to-date") {
502
+ atomicJson(statePath, { ...state, lastCheckedAt: now, ...(earlierFailure ? {} : { lastStatus: "success" }) });
444
503
  }
445
- if (plan.reason === "up-to-date")
446
- atomicJson(statePath, { ...state, lastCheckedAt: now, lastStatus: "success" });
447
504
  return result;
448
505
  }
449
506
  const lockPath = join(stateRoot, "lock");
450
- const lockToken = acquireLock(lockPath, now, Math.max(positiveInteger(env["LITCODEX_AUTO_UPDATE_LOCK_STALE_MS"], DEFAULT_AUTO_UPDATE_LOCK_STALE_MS), timeout * 5 + 30_000));
507
+ const lockToken = acquireLock(lockPath, now, Math.max(positiveInteger(env["LITCODEX_AUTO_UPDATE_LOCK_STALE_MS"], DEFAULT_AUTO_UPDATE_LOCK_STALE_MS), autoUpdateWorstCaseMs(timeout, installTimeout) + 30_000));
451
508
  if (lockToken === null) {
452
509
  const result = noRunResult({ ...plan, shouldRun: false, reason: "locked" }, stateRoot, startedAt);
453
510
  if (options.writeReceipt !== false)
@@ -479,7 +536,7 @@ export function runForegroundAutoUpdate(options) {
479
536
  const result = withSanitizedNpmEnvironment(env, (safeEnv) => spawn(command, args, {
480
537
  cwd,
481
538
  env: safeEnv,
482
- timeout,
539
+ timeout: installTimeout,
483
540
  stdio: "ignore",
484
541
  }));
485
542
  let verification = {
@@ -494,8 +551,9 @@ export function runForegroundAutoUpdate(options) {
494
551
  verification = withSanitizedNpmEnvironment(env, (safeEnv) => (options.verifyInstalled ?? verifyInstalledVersion)(plan.latestVersion, {
495
552
  command,
496
553
  cwd,
497
- env: safeEnv,
554
+ env: withCodexHost(safeEnv, env),
498
555
  timeout,
556
+ installTimeout,
499
557
  spawn,
500
558
  }));
501
559
  }
@@ -560,13 +618,25 @@ export function runForegroundAutoUpdate(options) {
560
618
  const rollback = withSanitizedNpmEnvironment(env, (safeEnv) => spawn(command, ["install", "--global", "--no-fund", "--no-audit", `${AUTO_UPDATE_PACKAGE}@${plan.currentVersion}`], {
561
619
  cwd,
562
620
  env: safeEnv,
563
- timeout,
621
+ timeout: installTimeout,
564
622
  stdio: "ignore",
565
623
  }));
566
624
  rollbackStatus = rollback.status;
567
625
  rollbackSignal = rollback.signal;
568
626
  rollbackError = rollback.error;
569
627
  rollbackSucceeded = spawnSucceeded(rollback);
628
+ if (rollbackSucceeded && verification.codexInstallAttempted === true) {
629
+ // The target already wrote its plugin into Codex, so the restored package reinstalls its own.
630
+ const restore = withSanitizedNpmEnvironment(env, (safeEnv) => installIntoCodex(command, { cwd, env: withCodexHost(safeEnv, env), spawn }, installTimeout));
631
+ rollbackStatus = restore.status;
632
+ rollbackSignal = restore.signal;
633
+ rollbackError =
634
+ restore.error ??
635
+ (spawnSucceeded(restore)
636
+ ? undefined
637
+ : new Error(`restoring the ${plan.currentVersion} Codex plugin exited ${String(restore.status)}`));
638
+ rollbackSucceeded = spawnSucceeded(restore);
639
+ }
570
640
  }
571
641
  catch (error) {
572
642
  rollbackError = error instanceof Error ? error : new Error("rollback probe failed");
@@ -619,6 +689,22 @@ export function runForegroundAutoUpdate(options) {
619
689
  releaseLock(lockPath, lockToken);
620
690
  }
621
691
  }
692
+ /** The longest one transaction can run: three probes plus four install steps (two forward, two back). */
693
+ export function autoUpdateWorstCaseMs(timeout = DEFAULT_AUTO_UPDATE_TIMEOUT_MS, installTimeout = DEFAULT_AUTO_UPDATE_INSTALL_TIMEOUT_MS) {
694
+ return timeout * 3 + installTimeout * 4;
695
+ }
696
+ /**
697
+ * A failed or unknown-state receipt stays the visible receipt until an update attempt replaces it, or
698
+ * until an up-to-date check proves the failed target is installed, which makes that failure history.
699
+ */
700
+ function unresolvedFailure(previous, plan) {
701
+ if (previous?.status !== "failed" && previous?.status !== "unknown-state")
702
+ return false;
703
+ if (plan.reason !== "up-to-date" || previous.latestVersion === undefined || plan.currentVersion === undefined) {
704
+ return true;
705
+ }
706
+ return compareStableVersions(plan.currentVersion, previous.latestVersion) < 0;
707
+ }
622
708
  export function readAutoUpdateReceipt(stateRoot = resolveAutoUpdateStateRoot()) {
623
709
  const path = join(stateRoot, "receipt.json");
624
710
  if (!existsSync(path))
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/auto-update",
3
- "version": "1.0.18",
3
+ "version": "1.0.20",
4
4
  "description": "LitCodex foreground update barrier for the SessionStart and management lifecycles.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/comment-checker",
3
- "version": "1.0.18",
3
+ "version": "1.0.20",
4
4
  "description": "LitCodex Comment-Checker hook: flags low-value / AI-slop comments introduced by edits.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/git-bash",
3
- "version": "1.0.18",
3
+ "version": "1.0.20",
4
4
  "description": "LitCodex Git-Bash hook: reminds Windows sessions to prefer the git_bash MCP before the built-in shell.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/lit-loop",
3
- "version": "1.0.18",
3
+ "version": "1.0.20",
4
4
  "description": "LitCodex Lit-Loop runtime: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/lsp",
3
- "version": "1.0.18",
3
+ "version": "1.0.20",
4
4
  "description": "LitCodex LSP hook (inert placeholder): post-edit diagnostics + cache reset, no-op until an LSP daemon is provided.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -15,6 +15,12 @@ export interface HumanizerFinding {
15
15
  type GuardOptions = {
16
16
  readonly scan?: (text: string) => readonly HumanizerFinding[];
17
17
  };
18
+ /**
19
+ * Reader-facing prose formats. Block-tier rules are prose rules (a line-start `Source:` label, for
20
+ * example), so they apply only here; code and data files such as YAML keys or Python docstrings
21
+ * are never scanned.
22
+ */
23
+ export declare const HUMANIZER_PROSE_EXTENSIONS: ReadonlySet<string>;
18
24
  export declare function humanizerFailOpenOutput(event: "PreToolUse" | "PostToolUse"): string;
19
25
  /** Run the bundled detector. Its exit statuses 1 and 2 represent findings; 2 is also used for block hits. */
20
26
  export declare function inspectHumanizerText(text: string, detectorPath?: string): readonly HumanizerFinding[];
@@ -7,39 +7,20 @@ const MAX_PATHS = 64;
7
7
  const MAX_OUTPUT_BYTES = 512 * 1024;
8
8
  const DETECTOR_TIMEOUT_MS = 1500;
9
9
  const DEFAULT_DETECTOR = resolve(dirname(fileURLToPath(import.meta.url)), "../../../skills/lit-humanizer/scripts/detect.mjs");
10
- const TEXT_EXTENSIONS = new Set([
10
+ /**
11
+ * Reader-facing prose formats. Block-tier rules are prose rules (a line-start `Source:` label, for
12
+ * example), so they apply only here; code and data files such as YAML keys or Python docstrings
13
+ * are never scanned.
14
+ */
15
+ export const HUMANIZER_PROSE_EXTENSIONS = new Set([
11
16
  ".adoc",
12
- ".c",
13
- ".cc",
14
- ".cpp",
15
- ".css",
16
- ".csv",
17
- ".go",
18
- ".h",
19
17
  ".html",
20
- ".java",
21
- ".js",
22
- ".jsx",
23
- ".jsonc",
18
+ ".markdown",
24
19
  ".md",
25
20
  ".mdx",
26
- ".mjs",
27
- ".php",
28
- ".py",
29
- ".rb",
30
21
  ".rst",
31
- ".rs",
32
- ".sh",
33
- ".sql",
34
- ".svg",
35
22
  ".tex",
36
- ".toml",
37
- ".ts",
38
- ".tsx",
39
23
  ".txt",
40
- ".xml",
41
- ".yaml",
42
- ".yml",
43
24
  ]);
44
25
  const OFFICE_EXTENSIONS = new Set([".docx", ".pdf", ".pptx"]);
45
26
  const WRITER_TOOLS = new Set([
@@ -87,7 +68,7 @@ export function runHumanizerPreToolUse(input, options = {}) {
87
68
  return contextOutput("PreToolUse", FAIL_OPEN_NOTE);
88
69
  const text = writes
89
70
  .filter((part) => !isInternalPath(part.path) && !isOfficePath(part.path))
90
- .filter((part) => part.path === undefined || TEXT_EXTENSIONS.has(extname(part.path).toLowerCase()))
71
+ .filter((part) => part.path === undefined || HUMANIZER_PROSE_EXTENSIONS.has(extname(part.path).toLowerCase()))
91
72
  .map((part) => changedText(part, input.cwd))
92
73
  .join("\n\n");
93
74
  if (text.length === 0)
@@ -191,9 +172,9 @@ function collectPostToolPaths(input) {
191
172
  }
192
173
  return paths;
193
174
  }
194
- const WRITABLE_EXTENSIONS = new Set([...TEXT_EXTENSIONS, ...OFFICE_EXTENSIONS]);
175
+ const WRITABLE_EXTENSIONS = new Set([...HUMANIZER_PROSE_EXTENSIONS, ...OFFICE_EXTENSIONS]);
195
176
  function isTextPath(path) {
196
- return TEXT_EXTENSIONS.has(extname(path).toLowerCase());
177
+ return HUMANIZER_PROSE_EXTENSIONS.has(extname(path).toLowerCase());
197
178
  }
198
179
  function shellOutputPaths(command) {
199
180
  const intent = /(?:^|\s)(?:>>?|\d?>)\s*|--output(?:=|\s+)|\s-o\s+/iu.test(command);
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/rules",
3
- "version": "1.0.18",
3
+ "version": "1.0.20",
4
4
  "description": "LitCodex rules: injects project rule files (AGENTS.md etc.) into model context through lifecycle hooks.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/start-work-continuation",
3
- "version": "1.0.18",
3
+ "version": "1.0.20",
4
4
  "description": "LitCodex Start-Work continuation hook: resumes in-flight start-work state on root Stop.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/telemetry",
3
- "version": "1.0.18",
3
+ "version": "1.0.20",
4
4
  "description": "LitCodex telemetry: a deliberately inert, local-only SessionStart hook (NO network, NO data collection).",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/wikify-knowledge",
3
- "version": "1.0.18",
3
+ "version": "1.0.20",
4
4
  "description": "Local review-gated knowledge records for the LitCodex Wikify surface.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -58,7 +58,7 @@
58
58
  {
59
59
  "type": "command",
60
60
  "command": "node \"${PLUGIN_ROOT}/components/auto-update/dist/cli.js\" hook session-start",
61
- "timeout": 60,
61
+ "timeout": 300,
62
62
  "statusMessage": "\ud83d\udd25 LIT IGNITED \u00b7 auto-update \ud83d\udd25"
63
63
  }
64
64
  ]