litcodex-ai 0.3.0

package/node_modules/@litcodex/lit-loop/dist/hook-cli.js

@@ -0,0 +1,94 @@
+// src/hook-cli.ts — M06 process adapter (A2 §2.4, A3 addendum A3/A4).
+//
+// The ONLY module that touches process streams + exit codes for the hook route. Reads stdin to a
+// UTF-8 string defensively, then BOM-strip → empty-check → JSON.parse (in that exact order, A3 A4),
+// hands the parsed value to the pure engine, and writes the decision. Exit map: any structurally
+// valid event → 0 (no-op writes zero bytes); unparseable or oversized stdin → 2 with a
+// machine-readable LitHookError JSON line on stderr. NEVER calls process.exit (the dispatcher does)
+// and NEVER throws.
+import { runUserPromptSubmitHook } from "./codex-hook.js";
+/** Hard cap on stdin to bound memory / ReDoS exposure inside the 5 s Codex hook budget. 8 MB. */
+export const MAX_STDIN_BYTES = 8_000_000;
+const INVALID_JSON_MESSAGE = "lit hook: stdin was not valid JSON";
+const TOO_LARGE_MESSAGE = `lit hook: stdin exceeded ${MAX_STDIN_BYTES} bytes`;
+function errorLine(code, message) {
+    const payload = { ok: false, error: { code, message } };
+    return `${JSON.stringify(payload)}\n`;
+}
+/**
+ * Read stdin to completion, enforcing MAX_STDIN_BYTES per chunk on the raw byte total BEFORE any
+ * decode (A3 A3). Resolves the decoded UTF-8 string, or `null` if the cap was exceeded (in which
+ * case the stream is destroyed and no decode/parse is attempted on the over-limit buffer).
+ */
+function readStdin(stdin) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let total = 0;
+        let settled = false;
+        const finish = (value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve(value);
+        };
+        stdin.on("data", (chunk) => {
+            const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+            total += buf.length;
+            if (total > MAX_STDIN_BYTES) {
+                // Stop reading and abandon the over-limit buffer without decoding/parsing it.
+                stdin.pause();
+                const destroy = stdin.destroy;
+                if (typeof destroy === "function") {
+                    destroy.call(stdin);
+                }
+                finish(null);
+                return;
+            }
+            chunks.push(buf);
+        });
+        stdin.on("end", () => {
+            finish(Buffer.concat(chunks).toString("utf8"));
+        });
+        stdin.on("error", () => {
+            // Treat a stream error like end-of-input over what we collected; the parse step decides.
+            finish(Buffer.concat(chunks).toString("utf8"));
+        });
+        stdin.on("close", () => {
+            finish(Buffer.concat(chunks).toString("utf8"));
+        });
+    });
+}
+/**
+ * Stream-driven entry point. Resolves exactly one exit code (0 or 2); NEVER calls process.exit and
+ * NEVER throws. Writes the camelCase activation line to stdout (empty on no-op), or a LitHookError
+ * line to stderr on malformed / oversized stdin.
+ */
+export async function runUserPromptSubmitHookCli(stdin, stdout, stderr) {
+    const decoded = await readStdin(stdin);
+    if (decoded === null) {
+        stderr.write(errorLine("LIT_HOOK_STDIN_TOO_LARGE", TOO_LARGE_MESSAGE));
+        return 2;
+    }
+    // A3 A4 ordering: strip ONE leading BOM, then empty-check, then parse.
+    let raw = decoded;
+    if (raw.charCodeAt(0) === 0xfeff) {
+        raw = raw.slice(1);
+    }
+    if (raw.trim().length === 0) {
+        return 0;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        stderr.write(errorLine("LIT_HOOK_STDIN_INVALID_JSON", INVALID_JSON_MESSAGE));
+        return 2;
+    }
+    const decision = runUserPromptSubmitHook(parsed);
+    if (decision.kind === "inject") {
+        stdout.write(decision.stdout);
+    }
+    return 0;
+}

package/node_modules/@litcodex/lit-loop/dist/loop-cli.d.ts

@@ -0,0 +1,19 @@
+export { exitCodeForLoop, LitLoopError, type LoopErrorCode } from "./loop-errors.js";
+export type { LoopClock } from "./loop-handlers.js";
+export { LOOP_CREATE_STDOUT } from "./loop-stdout.js";
+/** The 7 MVP subcommands, help-order, including `help` (A3 D2). M09 is the single source. */
+export declare const LOOP_SUBCOMMANDS: readonly ["help", "create", "status", "run", "checkpoint", "record-evidence", "doctor"];
+export type LoopSubcommand = (typeof LOOP_SUBCOMMANDS)[number];
+export declare function isLoopSubcommand(value: string): value is LoopSubcommand;
+export interface LoopIo {
+    readonly stdout: NodeJS.WritableStream;
+    readonly stderr: NodeJS.WritableStream;
+    readonly stdin: NodeJS.ReadableStream;
+    /** Test seam: override the repo root (default process.cwd()) without process.chdir. */
+    readonly cwd: string;
+}
+/**
+ * Entry point. `argv` is already sliced past `loop`. NEVER throws and NEVER calls process.exit —
+ * resolves exactly one exit code. The M03 router owns process.exit.
+ */
+export declare function loopCommand(argv: readonly string[], io?: Partial<LoopIo>, clock?: () => string): Promise<number>;

package/node_modules/@litcodex/lit-loop/dist/loop-cli.js

@@ -0,0 +1,106 @@
+// src/loop-cli.ts — M09/T14 loop command surface dispatcher (A3 C5/C6/C7/C9/C14, S09 §5).
+//
+// The thin `litcodex loop <sub>` dispatcher. PURE of process.exit and uncaught throws: loopCommand
+// always RESOLVES one exit code (the M03 router owns process.exit). Arg parsing + the five handlers
+// live in loop-handlers.ts; the error model + LOOP_CREATE_STDOUT are re-exported from
+// loop-errors.ts / loop-stdout.ts so this module's public surface is unchanged. All fs I/O is
+// delegated to the M08 store via flat `./state-store.js` (NEVER `../state/...`, A3 C9); M09 never
+// touches node:fs. Error model branches on `err.code` via exitCodeForLoop (A3 C7 — NOT instanceof):
+// store PLAN_MISSING→3, PLAN_CORRUPT→4, WRITE_FAILED→5; unknown subcommand/usage→1; bad args→2;
+// not-found→3. The `doctor` route delegates to the canonical M11 6-check doctor (A3 C5) and ALWAYS
+// resolves exit 0 (a diagnostic, never a gate).
+import { renderDoctorJson, renderDoctorText, runLoopDoctor } from "./loop-doctor.js";
+import { exitCodeForLoop, LitLoopError } from "./loop-errors.js";
+import { handleCheckpoint, handleCreate, handleRecordEvidence, handleRun, handleStatus, hasFlag, } from "./loop-handlers.js";
+import { resolveLoopScope } from "./state-store.js";
+// Re-export the error model + stdout contract so callers (M03 router, M20, tests) keep importing
+// them from `./loop-cli.js` as the M09 public surface.
+export { exitCodeForLoop, LitLoopError } from "./loop-errors.js";
+export { LOOP_CREATE_STDOUT } from "./loop-stdout.js";
+// ── Public contract ──────────────────────────────────────────────────────────
+/** The 7 MVP subcommands, help-order, including `help` (A3 D2). M09 is the single source. */
+export const LOOP_SUBCOMMANDS = ["help", "create", "status", "run", "checkpoint", "record-evidence", "doctor"];
+export function isLoopSubcommand(value) {
+    return LOOP_SUBCOMMANDS.includes(value);
+}
+const HELP_TEXT = `litcodex loop <subcommand>
+
+Subcommands:
+  help              Show this help.
+  create            Derive goals from a brief and seed success criteria.
+  status            Print the plan summary (use --json for a machine envelope).
+  run               Schedule the next runnable goal and print a handoff.
+  checkpoint        Set a goal terminal status (gated on all-criteria-pass for complete).
+  record-evidence   Capture per-criterion evidence.
+  doctor            Diagnose loop state (read-only health report; use --json for an envelope).
+`;
+/**
+ * Entry point. `argv` is already sliced past `loop`. NEVER throws and NEVER calls process.exit —
+ * resolves exactly one exit code. The M03 router owns process.exit.
+ */
+export async function loopCommand(argv, io, clock) {
+    const stdout = io?.stdout ?? process.stdout;
+    const stderr = io?.stderr ?? process.stderr;
+    const now = clock ?? (() => new Date().toISOString());
+    const repoRoot = io?.cwd ?? process.cwd();
+    let head = argv[0] ?? "help";
+    if (head === "--help" || head === "-h") {
+        head = "help";
+    }
+    const rest = argv.slice(1);
+    const json = hasFlag(argv, "--json");
+    if (head === "help") {
+        stdout.write(HELP_TEXT);
+        return 0;
+    }
+    if (!isLoopSubcommand(head)) {
+        return renderError(new LitLoopError(`unknown subcommand: ${head}`, "LIT_LOOP_SUBCOMMAND_UNKNOWN", { subcommand: head }), json, stdout, stderr);
+    }
+    const scope = resolveLoopScope({ argv: rest, env: process.env });
+    if (head === "doctor") {
+        // A3 C5: delegate to the canonical M11 6-check doctor; ALWAYS exit 0 (diagnostic, not gate).
+        const report = await runLoopDoctor({ repoRoot, scope });
+        stdout.write(json ? renderDoctorJson(report) : renderDoctorText(report));
+        return 0;
+    }
+    try {
+        const result = await dispatch(head, rest, { repoRoot, scope, now });
+        stdout.write(json ? `${JSON.stringify(result.json)}\n` : result.text);
+        return result.exitCode;
+    }
+    catch (err) {
+        return renderError(err, json, stdout, stderr);
+    }
+}
+async function dispatch(sub, argv, ctx) {
+    switch (sub) {
+        case "create":
+            return handleCreate(argv, ctx);
+        case "status":
+            return handleStatus(ctx);
+        case "run":
+            return handleRun(argv, ctx);
+        case "checkpoint":
+            return handleCheckpoint(argv, ctx);
+        case "record-evidence":
+            return handleRecordEvidence(argv, ctx);
+        default:
+            throw new LitLoopError(`unknown subcommand: ${sub}`, "LIT_LOOP_SUBCOMMAND_UNKNOWN", { subcommand: sub });
+    }
+}
+function renderError(err, json, stdout, stderr) {
+    const code = typeof err === "object" && err !== null && "code" in err
+        ? String(err.code)
+        : "LIT_LOOP_INTERNAL";
+    const message = err instanceof Error ? err.message : String(err);
+    const details = err instanceof LitLoopError && err.details !== undefined ? err.details : undefined;
+    if (json) {
+        const error = { code, message };
+        if (details !== undefined) {
+            error["details"] = details;
+        }
+        stdout.write(`${JSON.stringify({ ok: false, error })}\n`);
+    }
+    stderr.write(`[lit-loop] ${message}\n`);
+    return exitCodeForLoop(err);
+}

package/node_modules/@litcodex/lit-loop/dist/loop-doctor-render.d.ts

@@ -0,0 +1,7 @@
+import type { LoopDoctorReport } from "./loop-doctor-types.js";
+/** Render the --json envelope: one line + trailing `\n`. */
+export declare function renderDoctorJson(report: LoopDoctorReport): string;
+/** Render the human (text-mode) report. */
+export declare function renderDoctorText(report: LoopDoctorReport): string;
+/** Strip control chars (incl. newlines) and cap to 80 chars so an id can never forge a render line. */
+export declare function sanitizeId(value: string): string;

package/node_modules/@litcodex/lit-loop/dist/loop-doctor-render.js

@@ -0,0 +1,39 @@
+// src/loop-doctor-render.ts — M11/T16 pure doctor renderers (split from loop-doctor.ts for the
+// 250-LOC ceiling). Deterministic, no env reads, no untrusted-text interpolation: only ids,
+// statuses, integer counts, repo-relative paths, and ISO timestamps appear. `sanitizeId` strips
+// control chars and caps length so a crafted goalId can never forge a render line.
+const SYMBOL = { ok: "ok", warn: "!!", fail: "XX" };
+/** Render the --json envelope: one line + trailing `\n`. */
+export function renderDoctorJson(report) {
+    return `${JSON.stringify({ ok: report.healthy, report })}\n`;
+}
+/** Render the human (text-mode) report. */
+export function renderDoctorText(report) {
+    const failCount = report.checks.filter((c) => c.status === "fail").length;
+    const verdict = report.healthy ? "lit-loop doctor: HEALTHY" : `lit-loop doctor: UNHEALTHY (${failCount} issue(s))`;
+    const lines = [verdict, `state dir: ${report.stateDir}`];
+    for (const c of report.checks) {
+        lines.push(`  [${SYMBOL[c.status]}] ${c.name}: ${c.detail}`);
+    }
+    if (report.latestCheckpoint) {
+        const cp = report.latestCheckpoint;
+        lines.push(`latest checkpoint: ${sanitizeId(cp.goalId)} -> ${cp.status} @ ${sanitizeId(cp.at)}`);
+    }
+    if (report.counts) {
+        const s = report.counts;
+        lines.push(`goals: ${s.total} (${s.pending} pending, ${s.in_progress} in progress, ${s.complete} complete, ${s.failed} failed, ${s.blocked} blocked)`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Strip control chars (incl. newlines) and cap to 80 chars so an id can never forge a render line. */
+export function sanitizeId(value) {
+    let out = "";
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        // Drop C0 controls (incl. \n \r \t), DEL, and C1 controls; keep printable text.
+        if (code >= 0x20 && code !== 0x7f && !(code >= 0x80 && code <= 0x9f)) {
+            out += ch;
+        }
+    }
+    return out.slice(0, 80);
+}

package/node_modules/@litcodex/lit-loop/dist/loop-doctor-types.d.ts

@@ -0,0 +1,52 @@
+import type { LoopGoalStatus, PlanSummary } from "./loop-types.js";
+import type { LitLoopScope } from "./state-paths.js";
+/** The six diagnostic surfaces, in stable render order. */
+export type LoopDoctorCheckName = "state-dir" | "plan-schema" | "ledger" | "evidence-dir" | "hook" | "checkpoint";
+/** ok = healthy; warn = absent-but-recoverable (NOT a failure); fail = corrupt/unusable. */
+export type LoopDoctorCheckStatus = "ok" | "warn" | "fail";
+export interface LoopDoctorCheck {
+    readonly name: LoopDoctorCheckName;
+    readonly status: LoopDoctorCheckStatus;
+    /** One sanitized line. NO absolute paths beyond repo-relative artifacts; NO raw prompt/evidence text. */
+    readonly detail: string;
+    /** Optional machine-readable extras (e.g. backup path, ledger counts). JSON-serializable scalars only. */
+    readonly data?: Readonly<Record<string, string | number | boolean | null>>;
+}
+/** A pointer to the most-recent terminal goal event seen in the ledger tail. */
+export interface LoopCheckpointRef {
+    readonly goalId: string;
+    readonly status: LoopGoalStatus;
+    readonly at: string;
+}
+export interface LoopDoctorReport {
+    /** false iff ANY check.status === "fail". A `warn` alone keeps healthy = true. */
+    readonly healthy: boolean;
+    /** Repo-relative resolved state dir, e.g. ".litcodex/lit-loop" or ".litcodex/lit-loop/<sid>". */
+    readonly stateDir: string;
+    /** Always present, always length 6, always in LoopDoctorCheckName order. */
+    readonly checks: ReadonlyArray<LoopDoctorCheck>;
+    /** Most recent terminal checkpoint, or null when none / ledger unreadable. */
+    readonly latestCheckpoint: LoopCheckpointRef | null;
+    /** Goal/criterion counts when the plan is readable; null when missing/corrupt. */
+    readonly counts: PlanSummary | null;
+}
+export interface RunLoopDoctorOptions {
+    /** Absolute project root. MUST be absolute (the doctor never infers it from import.meta.url). */
+    readonly repoRoot: string;
+    /** Session scope to inspect; undefined ⇒ unscoped root dir. */
+    readonly scope?: LitLoopScope | undefined;
+}
+/**
+ * Injectable seams for deterministic, side-effect-free testing. ALL default to the real M08
+ * store + the real aggregate-hooks-manifest probe. Tests override individually for fault injection.
+ */
+export interface RunLoopDoctorDeps {
+    readonly readPlan: (repoRoot: string, scope?: LitLoopScope) => Promise<unknown>;
+    readonly readLedger: (repoRoot: string, scope?: LitLoopScope) => Promise<{
+        entries: ReadonlyArray<Record<string, unknown>>;
+        skipped: number;
+    }>;
+    readonly statExists: (absPath: string) => Promise<boolean>;
+    /** Resolves true iff a UserPromptSubmit command is wired in the aggregate plugins/litcodex/hooks/hooks.json. */
+    readonly hookRegistered: (repoRoot: string) => Promise<boolean>;
+}

package/node_modules/@litcodex/lit-loop/dist/loop-doctor-types.js

@@ -0,0 +1,7 @@
+// src/loop-doctor-types.ts — M11/T16 doctor-owned shapes (A3 C5/C9, S11 §Public-contract).
+//
+// Types only; ZERO I/O. The canonical LoopDoctorReport (6 checks incl. `checkpoint`, a per-check
+// `data` field, `healthy` flips ONLY on a `fail`) lives here, NOT in M09 (A3 C5 — M11 is the
+// single doctor owner). Imports `PlanSummary`/`LoopGoalStatus` from M09's `loop-types.js` barrel
+// and `LitLoopScope` from M08's `state-paths.js` — flat siblings, NEVER `../state/...` (A3 C9).
+export {};

package/node_modules/@litcodex/lit-loop/dist/loop-doctor.d.ts

@@ -0,0 +1,21 @@
+import type { LoopCheckpointRef, LoopDoctorReport, RunLoopDoctorDeps, RunLoopDoctorOptions } from "./loop-doctor-types.js";
+export { renderDoctorJson, renderDoctorText } from "./loop-doctor-render.js";
+/** The ONLY ledger kinds the checkpoint scan treats as terminal. Each is in BOTH producer enums. */
+export declare const TERMINAL_LEDGER_KINDS: {
+    readonly goal_completed: "complete";
+    readonly goal_failed: "failed";
+    readonly goal_blocked: "blocked";
+};
+/**
+ * Resolves true iff the AGGREGATE hooks.json registers UserPromptSubmit with the canonical command
+ * (all three HOOK_COMMAND_FRAGMENTS). ENOENT ⇒ false; any read/parse error rethrows to checkHook's
+ * catch (→ warn). Never executes any command from the manifest.
+ */
+export declare function hookRegistered(repoRoot: string): Promise<boolean>;
+/** Scan the ledger tail backward for the last terminal entry; null when none usable. */
+export declare function latestCheckpointFromLedger(entries: ReadonlyArray<Record<string, unknown>>): LoopCheckpointRef | null;
+/**
+ * Produce a LoopDoctorReport. NEVER throws, NEVER mutates state, NEVER calls process.exit. Every
+ * sub-check is independently fail-soft. Deterministic given the same on-disk state + injected deps.
+ */
+export declare function runLoopDoctor(options: RunLoopDoctorOptions, deps?: Partial<RunLoopDoctorDeps>): Promise<LoopDoctorReport>;

package/node_modules/@litcodex/lit-loop/dist/loop-doctor.js

@@ -0,0 +1,283 @@
+// src/loop-doctor.ts — M11/T16 canonical read-only loop doctor (A3 C5/C6/C9, S11 + addendum).
+//
+// The single doctor owner (A3 C5): six checks — state-dir / plan-schema / ledger / evidence-dir /
+// hook / checkpoint — a per-check `data` field, and `healthy` flips to false ONLY on a `fail`
+// (warnings keep healthy true). `runLoopDoctor` NEVER throws, NEVER mutates state, NEVER calls
+// process.exit, and ALWAYS resolves a report (M09 maps it to exit 0 unconditionally). Every
+// sub-check is independently try-wrapped; `checkStateDir`/`checkEvidenceDir` CATCH the `statExists`
+// non-ENOENT THROW (LIT_LOOP_WRITE_FAILED) and downgrade to warn (A3 C6 — statExists re-throws
+// EACCES/ELOOP/EIO; the doctor must not propagate it). The hook probe scans the AGGREGATE manifest
+// plugins/litcodex/hooks/hooks.json (M14/M19 ship it) and degrades to warn when absent.
+//
+// Imports flat siblings `./state-store.js`/`./state-paths.js`/`./loop-model.js`/`./loop-types.js`
+// (A3 C9 — NEVER `../state/...`). No `node:fs` import: existence-probing is M08 `statExists` only.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { sanitizeId } from "./loop-doctor-render.js";
+import { summarizePlan } from "./loop-model.js";
+import { litLoopDir, litLoopEvidenceDir, repoRelative } from "./state-paths.js";
+import { readLedger, readPlan, statExists } from "./state-store.js";
+// Re-export the pure renderers so the M11 public surface stays single-import from `./loop-doctor.js`
+// (A2 §2.5; loop-cli's doctor route imports both from here). The bodies live in loop-doctor-render.ts.
+export { renderDoctorJson, renderDoctorText } from "./loop-doctor-render.js";
+// ── Hook-probe contract (A3 §G11.2; byte-identical to M14 hookCommandFragments) ──────────────
+/** The aggregate manifest the host actually loads, POSIX-joined onto the absolute repoRoot. */
+const HOOK_MANIFEST_RELPATH = "plugins/litcodex/hooks/hooks.json";
+/** All three MUST appear in a `command` string for a registration to count (no bare-cli.js shortcut). */
+const HOOK_COMMAND_FRAGMENTS = [
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: inert literal the host expands; the doctor scans for it verbatim and MUST NOT interpolate it.
+    "${PLUGIN_ROOT}",
+    "components/lit-loop/dist/cli.js",
+    "hook user-prompt-submit",
+];
+// ── Terminal-kind contract (A3 §G11.3; the M08∩M09 intersection, closed constant) ────────────
+/** The ONLY ledger kinds the checkpoint scan treats as terminal. Each is in BOTH producer enums. */
+export const TERMINAL_LEDGER_KINDS = {
+    goal_completed: "complete",
+    goal_failed: "failed",
+    goal_blocked: "blocked",
+};
+// ── Default hooks-manifest probe (pure-Node: no spawn, no network, never runs the command) ───
+/**
+ * Resolves true iff the AGGREGATE hooks.json registers UserPromptSubmit with the canonical command
+ * (all three HOOK_COMMAND_FRAGMENTS). ENOENT ⇒ false; any read/parse error rethrows to checkHook's
+ * catch (→ warn). Never executes any command from the manifest.
+ */
+export async function hookRegistered(repoRoot) {
+    const manifestAbs = join(repoRoot, ...HOOK_MANIFEST_RELPATH.split("/"));
+    if (!(await statExists(manifestAbs))) {
+        return false;
+    }
+    const raw = await readFile(manifestAbs, "utf8");
+    const parsed = JSON.parse(raw);
+    return scanForCommand(parsed);
+}
+/** Recursively scan every string value under a `command` key for ALL three fragments. */
+function scanForCommand(node) {
+    if (Array.isArray(node)) {
+        return node.some(scanForCommand);
+    }
+    if (node !== null && typeof node === "object") {
+        for (const [key, value] of Object.entries(node)) {
+            if (key === "command" && typeof value === "string" && HOOK_COMMAND_FRAGMENTS.every((f) => value.includes(f))) {
+                return true;
+            }
+            if (scanForCommand(value)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+// ── Per-check helpers (each pure given its injected dep; the orchestrator try-wraps them) ─────
+async function checkStateDir(stateDirAbs, statExistsFn) {
+    try {
+        const exists = await statExistsFn(stateDirAbs);
+        return exists
+            ? { name: "state-dir", status: "ok", detail: "state directory present" }
+            : { name: "state-dir", status: "warn", detail: "not created — run `litcodex loop create`" };
+    }
+    catch {
+        // A3 C6: statExists re-throws non-ENOENT (EACCES/ELOOP) as LIT_LOOP_WRITE_FAILED. Downgrade
+        // to warn — an unreadable/absent state dir is benign for a diagnostic; NEVER `fail`.
+        return {
+            name: "state-dir",
+            status: "warn",
+            detail: "state directory unreadable (permission or I/O)",
+            data: { code: "LIT_LOOP_WRITE_FAILED" },
+        };
+    }
+}
+async function checkPlanSchema(repoRoot, scope, readPlanFn) {
+    try {
+        const plan = (await readPlanFn(repoRoot, scope));
+        const counts = summarizePlan(plan);
+        return {
+            check: {
+                name: "plan-schema",
+                status: "ok",
+                detail: `goals.json valid (version 1, ${plan.goals.length} goal(s))`,
+            },
+            counts,
+        };
+    }
+    catch (err) {
+        const code = errCode(err);
+        if (code === "LIT_LOOP_PLAN_MISSING") {
+            return {
+                check: { name: "plan-schema", status: "warn", detail: "no plan yet — run `litcodex loop create`" },
+                counts: null,
+            };
+        }
+        if (code === "LIT_LOOP_PLAN_CORRUPT") {
+            const backup = errBackup(err);
+            return {
+                check: {
+                    name: "plan-schema",
+                    status: "fail",
+                    detail: "goals.json was corrupt; quarantined to backup",
+                    data: { backup },
+                },
+                counts: null,
+            };
+        }
+        // Any other error (EACCES/EIO on read) — no raw message echoed.
+        return {
+            check: { name: "plan-schema", status: "fail", detail: "could not read goals.json (permission or I/O error)" },
+            counts: null,
+        };
+    }
+}
+async function checkLedger(repoRoot, scope, readLedgerFn) {
+    try {
+        const { entries, skipped } = await readLedgerFn(repoRoot, scope);
+        if (entries.length === 0 && skipped === 0) {
+            return { check: { name: "ledger", status: "warn", detail: "no ledger yet" }, entries: [] };
+        }
+        return {
+            check: {
+                name: "ledger",
+                status: skipped > 0 ? "warn" : "ok",
+                detail: `ledger present (${entries.length} entries, ${skipped} skipped)`,
+                data: { entries: entries.length, skipped },
+            },
+            entries,
+        };
+    }
+    catch {
+        // Defensive — readLedger is fail-open, but the ledger check NEVER fails and NEVER throws.
+        return {
+            check: { name: "ledger", status: "warn", detail: "ledger unreadable (treated as absent)" },
+            entries: [],
+        };
+    }
+}
+async function checkEvidenceDir(repoRoot, scope, statExistsFn) {
+    try {
+        const exists = await statExistsFn(litLoopEvidenceDir(repoRoot, scope));
+        return exists
+            ? { name: "evidence-dir", status: "ok", detail: "evidence/ present" }
+            : { name: "evidence-dir", status: "warn", detail: "evidence/ missing — created lazily on first capture" };
+    }
+    catch {
+        // A3 C6: same downgrade as state-dir; evidence-dir NEVER produces `fail`.
+        return {
+            name: "evidence-dir",
+            status: "warn",
+            detail: "evidence/ unreadable (permission or I/O)",
+            data: { code: "LIT_LOOP_WRITE_FAILED" },
+        };
+    }
+}
+async function checkHook(repoRoot, hookRegisteredFn) {
+    try {
+        const wired = await hookRegisteredFn(repoRoot);
+        return wired
+            ? { name: "hook", status: "ok", detail: "UserPromptSubmit hook registered" }
+            : { name: "hook", status: "warn", detail: "UserPromptSubmit hook not registered — run `litcodex install`" };
+    }
+    catch {
+        // Manifest unreadable / parse error / probe threw ⇒ warn. The hook check NEVER produces `fail`.
+        return { name: "hook", status: "warn", detail: "could not confirm hook registration" };
+    }
+}
+// ── Checkpoint derivation (pure) ──────────────────────────────────────────────────────────────
+/** Scan the ledger tail backward for the last terminal entry; null when none usable. */
+export function latestCheckpointFromLedger(entries) {
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+        const entry = entries[i];
+        if (entry === undefined) {
+            continue;
+        }
+        const kind = entry["kind"];
+        if (typeof kind !== "string" || !(kind in TERMINAL_LEDGER_KINDS)) {
+            continue;
+        }
+        const goalId = entry["goalId"];
+        const at = entry["at"];
+        if (typeof goalId === "string" && goalId !== "" && typeof at === "string" && at !== "") {
+            return { goalId, status: TERMINAL_LEDGER_KINDS[kind], at };
+        }
+    }
+    return null;
+}
+// ── Orchestrator ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Produce a LoopDoctorReport. NEVER throws, NEVER mutates state, NEVER calls process.exit. Every
+ * sub-check is independently fail-soft. Deterministic given the same on-disk state + injected deps.
+ */
+export async function runLoopDoctor(options, deps) {
+    const { repoRoot, scope } = options;
+    const d = {
+        readPlan: deps?.readPlan ?? ((r, s) => readPlan(r, s)),
+        readLedger: deps?.readLedger ??
+            (async (r, s) => {
+                const { entries, skipped } = await readLedger(r, s);
+                return { entries: entries, skipped };
+            }),
+        statExists: deps?.statExists ?? statExists,
+        hookRegistered: deps?.hookRegistered ?? hookRegistered,
+    };
+    // Murphy backstop (A3/S11 §9): a non-absolute root is misuse — never throw; report all-warn,
+    // with plan-schema `fail` so `healthy` is false (M09 always passes an absolute cwd).
+    if (typeof repoRoot !== "string" || !repoRoot.startsWith("/")) {
+        const detail = "invalid repoRoot (not absolute)";
+        const names = [
+            "state-dir",
+            "plan-schema",
+            "ledger",
+            "evidence-dir",
+            "hook",
+            "checkpoint",
+        ];
+        const checks = names.map((name) => ({
+            name,
+            status: name === "plan-schema" ? "fail" : "warn",
+            detail,
+        }));
+        return { healthy: false, stateDir: "", checks, latestCheckpoint: null, counts: null };
+    }
+    const stateDirAbs = litLoopDir(repoRoot, scope);
+    const stateDir = repoRelative(stateDirAbs, repoRoot);
+    const stateDirCheck = await checkStateDir(stateDirAbs, d.statExists);
+    const planResult = await checkPlanSchema(repoRoot, scope, d.readPlan);
+    const ledgerResult = await checkLedger(repoRoot, scope, d.readLedger);
+    const evidenceCheck = await checkEvidenceDir(repoRoot, scope, d.statExists);
+    const hookCheck = await checkHook(repoRoot, d.hookRegistered);
+    const latestCheckpoint = latestCheckpointFromLedger(ledgerResult.entries);
+    const checkpointCheck = latestCheckpoint
+        ? {
+            name: "checkpoint",
+            status: "ok",
+            detail: `latest checkpoint ${sanitizeId(latestCheckpoint.goalId)} -> ${latestCheckpoint.status}`,
+        }
+        : { name: "checkpoint", status: "warn", detail: "no checkpoint recorded yet" };
+    const checks = [
+        stateDirCheck,
+        planResult.check,
+        ledgerResult.check,
+        evidenceCheck,
+        hookCheck,
+        checkpointCheck,
+    ];
+    const healthy = checks.every((c) => c.status !== "fail");
+    return { healthy, stateDir, checks, latestCheckpoint, counts: planResult.counts };
+}
+// ── Error helpers ─────────────────────────────────────────────────────────────────────────────
+function errCode(err) {
+    if (typeof err === "object" && err !== null && "code" in err) {
+        const code = err.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    return undefined;
+}
+function errBackup(err) {
+    if (typeof err === "object" && err !== null && "details" in err) {
+        const details = err.details;
+        if (typeof details === "object" && details !== null && "backup" in details) {
+            const backup = details.backup;
+            return typeof backup === "string" ? backup : "";
+        }
+    }
+    return "";
+}

package/node_modules/@litcodex/lit-loop/dist/loop-errors.d.ts

@@ -0,0 +1,15 @@
+/** Stable SCREAMING_SNAKE error codes; consumers map them to an exit code via `.code`. */
+export type LoopErrorCode = "LIT_LOOP_SUBCOMMAND_UNKNOWN" | "LIT_LOOP_ARGUMENT_MISSING" | "LIT_LOOP_ARGUMENT_INVALID" | "LIT_LOOP_BRIEF_REQUIRED" | "LIT_LOOP_BRIEF_FILE_UNREADABLE" | "LIT_LOOP_EVIDENCE_STATUS_INVALID" | "LIT_LOOP_GOAL_NOT_FOUND" | "LIT_LOOP_CRITERION_NOT_FOUND" | "LIT_LOOP_CRITERIA_NOT_ALL_PASS";
+/** Machine-readable CLI error. `code` is the stable token; the exit code is derived from it. */
+export declare class LitLoopError extends Error {
+    readonly name = "LitLoopError";
+    readonly code: LoopErrorCode;
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(message: string, code: LoopErrorCode, details?: Readonly<Record<string, unknown>>);
+}
+/**
+ * Exit code for any thrown error, branching ONLY on `err.code` (A3 C7 — never `instanceof`
+ * PlanMissingError/PlanCorruptError). Store codes (PLAN_MISSING→3, PLAN_CORRUPT→4, WRITE_FAILED→5)
+ * defer to the store-owned {@link exitCodeFor}; the CLI's own codes map here.
+ */
+export declare function exitCodeForLoop(err: unknown): number;