@litfamily/litcodex 1.0.0

package/dist/install/codex.js

@@ -0,0 +1,164 @@
+// M12 / T17 — Codex discovery + read-only probes (S12 §codex.ts; addendum A2/A5).
+//
+// SELF-CONTAINED: this module owns the ONE place that ever spawns a child process, and that child
+// is always `codex` (the host runtime) — never an exec-wrapper, never a harness/forwarder package. Discovery
+// is pure (fs.existsSync + path joins, no spawn). The probes spawn `codex … list` read-only so
+// idempotency is M12's property (probe-before-spawn), independent of Codex's re-add exit codes.
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+import { LITCODEX_MARKETPLACE, LITCODEX_PLUGIN_REF } from "./marketplace.js";
+export function codexSpawnInvocation(command, args, env, platform = process.platform) {
+    const lowerCommand = command.toLowerCase();
+    if (platform === "win32" && lowerCommand.endsWith(".ps1")) {
+        // A .ps1-only npm shim cannot be spawned directly or via cmd.exe; route it through PowerShell
+        // with an argv array (shell:false) so paths with spaces need no manual quoting.
+        return {
+            command: "powershell",
+            args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", command, ...args],
+            shell: false,
+            windowsVerbatimArguments: false,
+        };
+    }
+    if (platform !== "win32" || (!lowerCommand.endsWith(".cmd") && !lowerCommand.endsWith(".bat"))) {
+        return { command, args: [...args], shell: false, windowsVerbatimArguments: false };
+    }
+    const comspec = env["ComSpec"]?.trim() || env["COMSPEC"]?.trim() || "cmd.exe";
+    return {
+        command: comspec,
+        args: ["/d", "/s", "/c", command, ...args],
+        shell: false,
+        windowsVerbatimArguments: false,
+    };
+}
+/** Resolve the absolute Codex home: trimmed `CODEX_HOME`, else `~/.codex`. */
+export function resolveCodexHome(env) {
+    const raw = env["CODEX_HOME"]?.trim();
+    if (raw !== undefined && raw.length > 0) {
+        return resolve(raw);
+    }
+    const home = env["HOME"]?.trim() || homedir();
+    return resolve(home, ".codex");
+}
+function platformBins(env, platform) {
+    if (platform !== "win32")
+        return ["codex"];
+    const names = ["codex.exe", "codex.cmd"];
+    for (const ext of (env["PATHEXT"] ?? ".COM;.EXE;.BAT;.CMD").split(";")) {
+        const normalized = ext.trim().toLowerCase();
+        if (normalized.length === 0)
+            continue;
+        const name = `codex${normalized}`;
+        if (!names.includes(name))
+            names.push(name);
+    }
+    // PATHEXT rarely lists .PS1, but npm can install a codex.ps1-only shim; check it LAST so the
+    // existing discovery order is unchanged whenever a real .exe/.cmd exists.
+    if (!names.includes("codex.ps1"))
+        names.push("codex.ps1");
+    return names;
+}
+/**
+ * Locate an absolute path to a `codex` file, or null. Pure: only `fs.existsSync` + path joins,
+ * NO spawn (a present-but-broken binary is "found"; execution failure is a later step error).
+ * Order (addendum A2.1): CODEX_BIN override → CODEX_HOME/bin → PATH scan.
+ */
+export function findCodexBinary(env, fs, platform = process.platform) {
+    const override = env["CODEX_BIN"]?.trim();
+    if (override !== undefined && override.length > 0) {
+        const abs = resolve(override);
+        // An explicit override that points nowhere is a hard "not found" — do NOT fall through.
+        return fs.existsSync(abs) ? abs : null;
+    }
+    for (const name of platformBins(env, platform)) {
+        const homeBin = join(resolveCodexHome(env), "bin", name);
+        if (fs.existsSync(homeBin))
+            return homeBin;
+    }
+    const pathVar = env["PATH"] ?? "";
+    const pathDelimiter = platform === "win32" ? ";" : delimiter;
+    for (const dir of pathVar.split(pathDelimiter)) {
+        if (dir.length === 0) {
+            continue;
+        }
+        for (const name of platformBins(env, platform)) {
+            const candidate = join(dir, name);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** True if `codex plugin marketplace list` stdout names the LitCodex marketplace. Read-only. */
+export function probeMarketplaceRegistered(codexBin, spawn) {
+    const res = spawn(codexBin, ["plugin", "marketplace", "list"], { stdio: "pipe", timeout: 5_000 });
+    if (res.error || res.status !== 0) {
+        // "cannot determine" → "not present" (the add step is the authoritative source of truth).
+        return false;
+    }
+    return (res.stdout ?? "").includes(LITCODEX_MARKETPLACE);
+}
+/** Return the registered LitCodex source from Codex's structured marketplace listing. */
+export function probeMarketplaceRegistration(codexBin, spawn) {
+    const res = spawn(codexBin, ["plugin", "marketplace", "list", "--json"], {
+        stdio: "pipe",
+        timeout: 5_000,
+    });
+    if (res.error || res.status !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(res.stdout ?? "");
+        const entries = Array.isArray(parsed)
+            ? parsed
+            : isRecord(parsed) && Array.isArray(parsed["marketplaces"])
+                ? parsed["marketplaces"]
+                : [];
+        for (const entry of entries) {
+            if (!isRecord(entry) || entry["name"] !== LITCODEX_MARKETPLACE)
+                continue;
+            const nestedSource = isRecord(entry["marketplaceSource"]) ? entry["marketplaceSource"] : undefined;
+            return {
+                name: LITCODEX_MARKETPLACE,
+                source: stringOrNull(nestedSource?.["source"] ?? entry["source"] ?? entry["root"]),
+                sourceType: stringOrNull(nestedSource?.["sourceType"] ?? entry["sourceType"] ?? entry["source_type"]),
+            };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * True iff `codex plugin list` shows `litcodex@litcodex` with an INSTALLED status. Read-only.
+ *
+ * VERIFY-LIVE (codex-cli 0.139.x): once the marketplace is added, the plugin ref appears in the list
+ * BEFORE it is installed, as `litcodex@litcodex  not installed  …`. Matching the ref string alone is
+ * a false positive that makes `install` skip the real `codex plugin add` (plugin never installs, hook
+ * never fires) and `doctor` report a phantom install. So parse the row's STATUS column: the ref must
+ * be on a line that says `installed` and NOT `not installed`.
+ */
+export function probePluginInstalled(codexBin, spawn) {
+    const res = spawn(codexBin, ["plugin", "list"], { stdio: "pipe", timeout: 5_000 });
+    if (res.error || res.status !== 0) {
+        return false;
+    }
+    const out = res.stdout ?? "";
+    for (const line of out.split(/\r?\n/)) {
+        if (!line.includes(LITCODEX_PLUGIN_REF)) {
+            continue;
+        }
+        if (/\bnot installed\b/i.test(line)) {
+            continue; // available-but-not-installed row → not a real install
+        }
+        if (/\binstalled\b/i.test(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringOrNull(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

package/dist/install/development-marketplace.d.ts

@@ -0,0 +1,6 @@
+export interface DevelopmentMarketplaceSource {
+    readonly root: string;
+    readonly cleanup: () => void;
+}
+/** Build the packed runtime shape when npm shadows npx with this development workspace package. */
+export declare function materializeDevelopmentMarketplace(packageRoot: string, tempParent?: string): DevelopmentMarketplaceSource | null;

package/dist/install/development-marketplace.js

@@ -0,0 +1,83 @@
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { isRuntimeSkillPath } from "./runtime-file-policy.js";
+const EXACT_RUNTIME_FILES = new Set([
+    ".agents/plugins/marketplace.json",
+    "plugins/litcodex/.codex-plugin/plugin.json",
+    "plugins/litcodex/assets/logo.png",
+    "plugins/litcodex/.mcp.json",
+    "plugins/litcodex/hooks/hooks.json",
+]);
+const REQUIRED_RUNTIME_FILES = [...EXACT_RUNTIME_FILES];
+const PLUGIN_PREFIX = "plugins/litcodex/";
+const VENDOR_SCIENTIFIC_TESTS = new Set(["tests/test_figure_export.py", "tests/test_style_presets.py"]);
+/** Build the packed runtime shape when npm shadows npx with this development workspace package. */
+export function materializeDevelopmentMarketplace(packageRoot, tempParent = tmpdir()) {
+    const repoRoot = resolve(packageRoot, "../..");
+    if (!REQUIRED_RUNTIME_FILES.every((path) => existsSync(join(repoRoot, path))))
+        return null;
+    const stage = mkdtempSync(join(tempParent, "litcodex-workspace-marketplace-"));
+    for (const path of REQUIRED_RUNTIME_FILES)
+        copyRuntimeFile(repoRoot, stage, path);
+    for (const sourcePath of walkFiles(join(repoRoot, "plugins", "litcodex"))) {
+        const relativePath = relative(repoRoot, sourcePath).replaceAll("\\", "/");
+        if (isRuntimeFile(relativePath))
+            copyRuntimeFile(repoRoot, stage, relativePath);
+    }
+    return {
+        root: stage,
+        cleanup: () => rmSync(stage, { recursive: true, force: true }),
+    };
+}
+function walkFiles(root) {
+    const files = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            files.push(...walkFiles(path));
+        else if (entry.isFile())
+            files.push(path);
+    }
+    return files;
+}
+function copyRuntimeFile(repoRoot, stage, relativePath) {
+    const target = join(stage, relativePath);
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(join(repoRoot, relativePath), target);
+}
+function isRuntimeFile(path) {
+    if (EXACT_RUNTIME_FILES.has(path))
+        return true;
+    if (!path.startsWith(PLUGIN_PREFIX))
+        return false;
+    const relativePath = path.slice(PLUGIN_PREFIX.length);
+    if (relativePath.startsWith("skills/"))
+        return isRuntimeSkillPath(relativePath.slice("skills/".length));
+    if (relativePath.startsWith("vendor/"))
+        return isRuntimeVendorPath(relativePath.slice("vendor/".length));
+    if (!relativePath.startsWith("components/"))
+        return false;
+    const componentPath = relativePath.slice("components/".length);
+    if (/^[^/]+\/dist\//.test(componentPath) || /^[^/]+\/package\.json$/.test(componentPath))
+        return true;
+    return (componentPath.startsWith("lit-loop/directives/") ||
+        componentPath.startsWith("lit-loop/agents/") ||
+        componentPath === "lit-loop/directive.md" ||
+        componentPath.startsWith("rules/bundled-rules/") ||
+        componentPath.startsWith("rules/node_modules/picomatch/") ||
+        componentPath === "start-work-continuation/directive.md");
+}
+function isRuntimeVendorPath(relativePath) {
+    if (relativePath === "NOTICE" || relativePath.startsWith("licenses/") || relativePath.startsWith("provenance/")) {
+        return true;
+    }
+    if (relativePath.startsWith("handoff/")) {
+        return isRuntimeSkillPath(relativePath.slice("handoff/".length));
+    }
+    if (relativePath.startsWith("scientific-visualization/")) {
+        const corpusPath = relativePath.slice("scientific-visualization/".length);
+        return VENDOR_SCIENTIFIC_TESTS.has(corpusPath) || isRuntimeSkillPath(corpusPath);
+    }
+    return false;
+}

package/dist/install/doctor-config.d.ts

@@ -0,0 +1,4 @@
+import type { ReadonlyFsLike } from "./codex.js";
+import type { EffectiveConfigReport } from "./types.js";
+/** Read-only effective root-route inspection shared by the doctor surface and its tests. */
+export declare function inspectEffectiveConfig(fs: ReadonlyFsLike, configPath: string): EffectiveConfigReport;

package/dist/install/doctor-config.js

@@ -0,0 +1,54 @@
+import { ASTRA_MODEL, EXPLICIT_GPT56_SOL_MODEL, GPT56_MODELS, unsafeEffectiveRoute, } from "../config-migration/gpt56-policy.js";
+import { hasReservedSpawnSchemaMismatch } from "../config-migration/multi-agent-v2-guard.js";
+import { readRootSettings } from "../config-migration/root-settings.js";
+/** Read-only effective root-route inspection shared by the doctor surface and its tests. */
+export function inspectEffectiveConfig(fs, configPath) {
+    if (!fs.existsSync(configPath)) {
+        return { state: "unavailable", detail: "config.toml is missing" };
+    }
+    try {
+        const config = fs.readFileSync(configPath, "utf8");
+        if (hasReservedSpawnSchemaMismatch(config)) {
+            return {
+                state: "unavailable",
+                detail: "multi-agent V2 exposes metadata that violates the reserved collaboration.spawn_agent schema",
+            };
+        }
+        const root = readRootSettings(config);
+        const unsafeRoute = unsafeEffectiveRoute(root);
+        if (unsafeRoute !== null)
+            return { state: "unavailable", detail: `unsafe effective model route: ${unsafeRoute}` };
+        const model = root.model ?? "host default";
+        const effort = root.model_reasoning_effort ?? "host default";
+        if (model === EXPLICIT_GPT56_SOL_MODEL) {
+            return {
+                state: "preserved",
+                detail: "gpt-5.6-sol · existing explicit Sol representation preserved; review `litcodex install --reconfigure` for a one-time alias update",
+            };
+        }
+        if (isManagedRoute(model, effort)) {
+            if (root.model_context_window === undefined && root.model_auto_compact_token_limit === undefined) {
+                return {
+                    state: "applied",
+                    detail: `${model} · ${effort}; context/auto-compaction unset; host defaults apply`,
+                };
+            }
+        }
+        return {
+            state: "preserved",
+            detail: `${model} · ${effort}; preserved (limits or ownership differ); use --reconfigure to review`,
+        };
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return { state: "unavailable", detail: "config.toml could not be read" };
+        }
+        throw error;
+    }
+}
+function isManagedRoute(model, effort) {
+    return ((model === ASTRA_MODEL &&
+        (effort === "low" || effort === "medium" || effort === "high" || effort === "xhigh" || effort === "max")) ||
+        ((model === GPT56_MODELS.sol || model === GPT56_MODELS.terra) && (effort === "high" || effort === "xhigh")) ||
+        (model === GPT56_MODELS.luna && (effort === "high" || effort === "xhigh" || effort === "max")));
+}

package/dist/install/doctor-render.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorReport } from "./types.js";
+export declare function renderDoctorText(report: DoctorReport): string;

package/dist/install/doctor-render.js

@@ -0,0 +1,72 @@
+const MAX_RESOURCE_FAMILIES = 2;
+const MAX_RESOURCE_EXAMPLES = 2;
+const MAX_RESOURCE_PATH_LENGTH = 120;
+export function renderDoctorText(report) {
+    const lines = [
+        "litcodex doctor",
+        `  codex binary found:     ${yn(report.codexBinaryFound)}`,
+        `  marketplace registered: ${yn(report.marketplaceRegistered)}`,
+        `  plugin installed:       ${yn(report.pluginInstalled)}`,
+        `  hook wired:             ${yn(report.hooksWired)}`,
+        `  config managed:         ${yn(report.configManaged)}`,
+        `  effective config:       ${report.effectiveConfig.state} (${report.effectiveConfig.detail})`,
+        `  desired agent config:   ${report.agentRouting.desiredConfig}`,
+        `  installed TOMLs:        ${report.agentRouting.installedTomls}`,
+        `  spawn override:         ${report.agentRouting.spawnOverride}`,
+        `  effective child:        ${report.agentRouting.effectiveChild}`,
+        `  agents installed:       ${yn(report.agentsInstalled)}`,
+        `  skill catalog complete: ${yn(report.skillCatalogComplete)}`,
+        ...(report.missingSkillResourcePaths.length > 0
+            ? [`  missing skill resources: ${missingResourceSummary(report.missingSkillResourcePaths)}`]
+            : []),
+        `  lit-handoff installed:   ${yn(report.handoffInstalled)}`,
+        `  science payload installed: ${yn(report.scientificVisualizationInstalled)}`,
+        ...(report.autoUpdate === undefined
+            ? []
+            : [
+                `  foreground auto-update:  ${report.autoUpdate.enabled ? "enabled" : "disabled"} (${report.autoUpdate.status ?? "no receipt"}; ${report.autoUpdate.detail})`,
+            ]),
+        `  concurrency 20:          ${capabilityText(report.capabilities.concurrency)}`,
+        `  probe-only explicit context/auto-compaction override: ${capabilityText(report.capabilities.autoCompaction)}`,
+    ];
+    if (report.issues.length > 0) {
+        lines.push("Issues:");
+        for (const issue of report.issues)
+            lines.push(`  - ${issue}`);
+    }
+    if (report.warnings.length > 0) {
+        lines.push("Warnings:");
+        for (const warning of report.warnings)
+            lines.push(`  - ${warning}`);
+    }
+    if (report.issues.length === 0)
+        lines.push("All checks passed.");
+    return lines.join("\n");
+}
+function missingResourceSummary(paths) {
+    const byFamily = new Map();
+    for (const path of paths) {
+        const integrity = path.match(/^<(.+)-payload-integrity>$/u);
+        const family = integrity?.[1] ?? path.split("/", 1)[0] ?? "unknown";
+        const familyPaths = byFamily.get(family) ?? [];
+        familyPaths.push(path.length > MAX_RESOURCE_PATH_LENGTH ? `${path.slice(0, MAX_RESOURCE_PATH_LENGTH - 1)}…` : path);
+        byFamily.set(family, familyPaths);
+    }
+    const families = [...byFamily.entries()].sort(([left], [right]) => left.localeCompare(right));
+    const examples = families.slice(0, MAX_RESOURCE_FAMILIES).map(([family, familyPaths]) => {
+        const shown = familyPaths.slice(0, MAX_RESOURCE_EXAMPLES);
+        const remainder = familyPaths.length - shown.length;
+        return `${family}: ${familyPaths.length} missing [${shown.join(", ")}${remainder > 0 ? `, +${remainder} more` : ""}]`;
+    });
+    const remainingFamilies = families.length - examples.length;
+    if (remainingFamilies > 0)
+        examples.push(`+${remainingFamilies} more families`);
+    const familyLabel = families.length === 1 ? "family" : "families";
+    return `${paths.length} across ${families.length} ${familyLabel} (${examples.join("; ")}; full paths: --json)`;
+}
+function yn(value) {
+    return value ? "yes" : "no";
+}
+function capabilityText(report) {
+    return `${report.status} (${report.reason}; source: ${report.observedSource})`;
+}

package/dist/install/doctor.d.ts

@@ -0,0 +1,12 @@
+import { type ReadonlyFsLike, type SpawnLike } from "./codex.js";
+import type { DoctorReport } from "./types.js";
+export { renderDoctorText } from "./doctor-render.js";
+export interface DoctorDeps {
+    readonly spawn: SpawnLike;
+    readonly fs: ReadonlyFsLike;
+    readonly env: NodeJS.ProcessEnv;
+    readonly repoRoot: string;
+    /** Hook verification (defaults to the M14 resolvers over repoRoot). */
+    readonly verifyHook?: (repoRoot: string) => void;
+}
+export declare function runDoctor(deps: DoctorDeps): DoctorReport;

package/dist/install/doctor.js

@@ -0,0 +1,223 @@
+// M12 / T17 — doctor health report (S12 §doctor; A2 §6.6 — installer-side install health).
+//
+// Read-only: spawns ONLY the `codex … list` probes (never a mutating command). Reports whether the
+// marketplace is registered, the plugin installed, the hook wired, the config managed, and whether
+// a `codex` binary was even found. `ok` is true only when every check passes.
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { EXPLICIT_GPT56_SOL_MODEL, GPT56_MODELS } from "../config-migration/gpt56-policy.js";
+import { inspectAgentRouting, routingReport } from "./agent-routing.js";
+import { detectAuthMode } from "./auth-mode.js";
+import { probeBundledSkills } from "./bundled-skills.js";
+import { findCodexBinary, probeMarketplaceRegistration, probePluginInstalled, resolveCodexHome, } from "./codex.js";
+import { inspectEffectiveConfig } from "./doctor-config.js";
+import { probeHostCapabilities } from "./host-capabilities.js";
+import { canonicalMarketplacePath, LITCODEX_MARKETPLACE, managedMarketplaceRoot } from "./marketplace.js";
+import { probeSkillCatalogPayload } from "./skill-catalog.js";
+export { renderDoctorText } from "./doctor-render.js";
+const PACKAGE_VERSION = createRequire(import.meta.url)("../../package.json").version;
+const MAX_DIAGNOSTIC_FAMILIES = 2;
+const MAX_DIAGNOSTIC_PATHS = 2;
+const MAX_DIAGNOSTIC_PATH_LENGTH = 120;
+function boundedCatalogSummary(missingSkillIds, missingResourcePaths) {
+    const byFamily = new Map();
+    const add = (family, path) => {
+        const paths = byFamily.get(family) ?? [];
+        paths.push(path.length > MAX_DIAGNOSTIC_PATH_LENGTH ? `${path.slice(0, MAX_DIAGNOSTIC_PATH_LENGTH - 1)}…` : path);
+        byFamily.set(family, paths);
+    };
+    for (const skillId of missingSkillIds)
+        add(skillId, `${skillId}/SKILL.md`);
+    for (const path of missingResourcePaths) {
+        const integrity = path.match(/^<(.+)-payload-integrity>$/u);
+        add(integrity?.[1] ?? path.split("/", 1)[0] ?? "unknown", path);
+    }
+    const families = [...byFamily.entries()].sort(([left], [right]) => left.localeCompare(right));
+    const summaries = families.slice(0, MAX_DIAGNOSTIC_FAMILIES).map(([family, paths]) => {
+        const shown = paths.slice(0, MAX_DIAGNOSTIC_PATHS);
+        const remainder = paths.length - shown.length;
+        return `${family}: ${paths.length} missing [${shown.join(", ")}${remainder > 0 ? `, +${remainder} more` : ""}]`;
+    });
+    const remainingFamilies = families.length - summaries.length;
+    if (remainingFamilies > 0)
+        summaries.push(`+${remainingFamilies} more families`);
+    return summaries.join("; ");
+}
+export function runDoctor(deps) {
+    const codexBin = findCodexBinary(deps.env, deps.fs);
+    const codexBinaryFound = codexBin !== null;
+    const issues = [];
+    const warnings = [];
+    const unavailableCapabilities = {
+        concurrency: {
+            status: "unavailable",
+            reason: "codex-binary-unavailable",
+            observedSource: "Codex binary discovery",
+        },
+        autoCompaction: {
+            status: "unavailable",
+            reason: "codex-binary-unavailable",
+            observedSource: "Codex binary discovery",
+        },
+        modelContexts: { "gpt-5.6": null, "gpt-5.6-terra": null, "gpt-5.6-luna": null },
+    };
+    if (!codexBinaryFound) {
+        issues.push("Codex CLI not found on PATH or in CODEX_HOME.");
+        return {
+            ok: false,
+            marketplaceRegistered: false,
+            pluginInstalled: false,
+            hooksWired: false,
+            configManaged: false,
+            effectiveConfig: { state: "unavailable", detail: "Codex CLI not found" },
+            agentRouting: routingReport([]),
+            codexBinaryFound: false,
+            agentsInstalled: false,
+            skillCatalogComplete: false,
+            missingSkillIds: [],
+            missingSkillResourcePaths: [],
+            handoffInstalled: false,
+            scientificVisualizationInstalled: false,
+            capabilities: unavailableCapabilities,
+            autoUpdate: readAutoUpdateReport(deps.env),
+            issues,
+            warnings,
+        };
+    }
+    const codexHome = resolveCodexHome(deps.env);
+    const managedRoot = managedMarketplaceRoot(codexHome);
+    const registration = probeMarketplaceRegistration(codexBin, deps.spawn);
+    const marketplaceRegistered = registration?.source !== null &&
+        registration?.source !== undefined &&
+        canonicalMarketplacePath(registration.source) === canonicalMarketplacePath(managedRoot);
+    const capabilities = probeHostCapabilities(codexBin, deps.spawn, { env: deps.env });
+    if (!marketplaceRegistered) {
+        issues.push("LitCodex managed local marketplace is not registered. Run `litcodex install`.");
+    }
+    const pluginInstalled = probePluginInstalled(codexBin, deps.spawn);
+    if (!pluginInstalled) {
+        issues.push("LitCodex plugin is not installed. Run `litcodex install`.");
+    }
+    let hooksWired = payloadHealthy(deps.fs, managedRoot);
+    try {
+        (deps.verifyHook ?? (() => undefined))(managedRoot);
+    }
+    catch {
+        hooksWired = false;
+    }
+    if (!hooksWired)
+        issues.push("Bundled UserPromptSubmit hook payload is missing or malformed.");
+    const effectiveConfig = inspectEffectiveConfig(deps.fs, join(codexHome, "config.toml"));
+    const configManaged = effectiveConfig.state !== "unavailable";
+    if (effectiveConfig.state === "unavailable") {
+        issues.push(`Codex config unavailable: ${effectiveConfig.detail}.`);
+    }
+    const authMode = detectAuthMode(deps.fs, codexHome);
+    const agentRouting = inspectAgentRouting(deps.fs, codexHome, authMode);
+    const agentsInstalled = agentRouting.healthy;
+    if (!agentsInstalled) {
+        issues.push("LitCodex litwork agent roles are not installed. Run `litcodex install`.");
+        for (const issue of agentRouting.issues)
+            issues.push(`Agent routing ${issue}.`);
+    }
+    const bundledSkills = probeBundledSkills(deps.fs, managedRoot);
+    const skillCatalog = probeSkillCatalogPayload(deps.fs, managedRoot);
+    if (!skillCatalog.complete) {
+        issues.push(`Bundled skill catalog is incomplete (${boundedCatalogSummary(skillCatalog.missingSkillIds, skillCatalog.missingResourcePaths)}). Run \`litcodex install\`.`);
+    }
+    if (!bundledSkills.handoffInstalled) {
+        issues.push("Bundled lit-handoff payload is incomplete. Run `litcodex install`.");
+    }
+    if (!bundledSkills.scientificVisualizationInstalled) {
+        issues.push("Bundled lit-scientific-visualization payload is incomplete. Run `litcodex install`.");
+    }
+    if (capabilities.concurrency.status === "unavailable") {
+        issues.push(`Concurrency 20 is ${capabilities.concurrency.status}: ${capabilities.concurrency.reason}.`);
+    }
+    else if (capabilities.concurrency.status === "advisory") {
+        warnings.push(`Concurrency 20 is advisory: ${capabilities.concurrency.reason}.`);
+    }
+    if (authMode === "chatgpt") {
+        const rootModel = effectiveConfig.state !== "unavailable" ? effectiveConfig.detail : "";
+        const rootUsesAlias = new RegExp(`^${GPT56_MODELS.sol.replaceAll(".", "\\.")}(?:\\s|$)`).test(rootModel);
+        if (rootUsesAlias) {
+            issues.push(`ChatGPT-subscription auth detected with model ${GPT56_MODELS.sol}: the API rejects this alias for ChatGPT accounts. Run \`litcodex install --reconfigure\` to route through ${EXPLICIT_GPT56_SOL_MODEL}.`);
+        }
+    }
+    else if (authMode === "unknown") {
+        warnings.push("Codex auth mode could not be determined (auth.json absent or unrecognized). ChatGPT-subscription accounts may fail with the public gpt-5.6 alias; run `litcodex install` after authenticating.");
+    }
+    const autoUpdate = readAutoUpdateReport(deps.env);
+    if (autoUpdate.status === "unknown-state") {
+        issues.push(`Foreground auto-update rollback failed; installation state is unknown. Inspect ${autoUpdate.receiptPath} and reinstall the exact stable package.`);
+    }
+    return {
+        ok: issues.length === 0,
+        marketplaceRegistered,
+        pluginInstalled,
+        hooksWired,
+        configManaged,
+        effectiveConfig,
+        agentRouting,
+        codexBinaryFound,
+        agentsInstalled,
+        skillCatalogComplete: skillCatalog.complete,
+        missingSkillIds: skillCatalog.missingSkillIds,
+        missingSkillResourcePaths: skillCatalog.missingResourcePaths,
+        ...bundledSkills,
+        capabilities,
+        autoUpdate,
+        issues,
+        warnings,
+    };
+}
+/** Read the updater receipt without touching the updater lock, journal, or npm. */
+function readAutoUpdateReport(env) {
+    const configuredRoot = env["LITCODEX_AUTO_UPDATE_STATE_ROOT"]?.trim();
+    const dataRoot = env["LITCODEX_DATA_ROOT"]?.trim() || join(homedir(), ".litcodex");
+    const stateRoot = configuredRoot || join(dataRoot, "auto-update");
+    const receiptPath = join(stateRoot, "receipt.json");
+    const enabled = !Object.hasOwn(env, "LITCODEX_NO_AUTO_UPDATE") &&
+        !Object.hasOwn(env, "NO_UPDATE_NOTIFIER") &&
+        !Object.hasOwn(env, "LITCODEX_NO_UPDATE_CHECK");
+    try {
+        const parsed = JSON.parse(readFileSync(receiptPath, "utf8"));
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            const status = parsed["status"];
+            if (typeof status === "string") {
+                return {
+                    enabled,
+                    status,
+                    receiptPath,
+                    detail: "receipt present",
+                };
+            }
+        }
+    }
+    catch {
+        // A missing or malformed receipt is a healthy read-only no-receipt state, not a doctor issue.
+    }
+    return { enabled, status: null, receiptPath, detail: "no receipt yet" };
+}
+function payloadHealthy(fs, root) {
+    const marketplacePath = join(root, ".agents", "plugins", "marketplace.json");
+    const pluginPath = join(root, "plugins", "litcodex", ".codex-plugin", "plugin.json");
+    const hooksPath = join(root, "plugins", "litcodex", "hooks", "hooks.json");
+    if (![marketplacePath, pluginPath, hooksPath].every((path) => fs.existsSync(path)))
+        return false;
+    try {
+        const marketplace = JSON.parse(fs.readFileSync(marketplacePath, "utf8"));
+        const plugin = JSON.parse(fs.readFileSync(pluginPath, "utf8"));
+        const hooks = JSON.parse(fs.readFileSync(hooksPath, "utf8"));
+        return (marketplace.name === LITCODEX_MARKETPLACE &&
+            plugin.name === "litcodex" &&
+            plugin.version === PACKAGE_VERSION &&
+            typeof hooks.hooks === "object" &&
+            hooks.hooks !== null);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/install/errors.d.ts

@@ -0,0 +1,20 @@
+export declare const INSTALL_ERROR_CODES: readonly ["LITCODEX_INSTALL_CODEX_NOT_FOUND", "LITCODEX_INSTALL_CODEX_VERSION_UNSUPPORTED", "LITCODEX_INSTALL_HOST_PROBE_FAILED", "LITCODEX_INSTALL_MARKETPLACE_ADD_FAILED", "LITCODEX_INSTALL_PLUGIN_ADD_FAILED", "LITCODEX_INSTALL_HOOKS_MISSING", "LITCODEX_INSTALL_AGENTS_MISSING", "LITCODEX_INSTALL_UNSAFE_MODEL_ROUTE", "LITCODEX_INSTALL_CONFIG_WRITE_FAILED", "LITCODEX_INSTALL_HOST_CONFIG_INCOMPATIBLE", "LITCODEX_INSTALL_UNKNOWN_COMMAND", "LITCODEX_INSTALL_BAD_FLAG"];
+export type InstallErrorCode = (typeof INSTALL_ERROR_CODES)[number];
+export declare class InstallError extends Error {
+    readonly name = "InstallError";
+    readonly code: InstallErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: InstallErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
+}
+export interface InstallErrorEnvelope {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly details: Readonly<Record<string, unknown>>;
+    };
+}
+/** Process exit code for an installer error (S12 §Exit-code table). */
+export declare function exitCodeForInstallError(code: InstallErrorCode): number;
+/** Machine-readable error envelope (written to stderr alongside a human prefix line). */
+export declare function toErrorJson(err: unknown): InstallErrorEnvelope;