litcodex-ai 0.3.0

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

@@ -0,0 +1,126 @@
+// src/codex-hook.ts — M06 pure hook engine (A2 §2.4, A3 C3/C12).
+//
+// Takes an already-parsed `unknown` (the JSON.parse'd stdin value) and returns a structured
+// HookDecision. NO process / stdin / stdout / exit lives here — that is hook-cli.ts. The engine is
+// total over `unknown` and NEVER throws on a structurally-valid event.
+//
+// Activation policy is delegated to the SINGLE guard entry point
+// `shouldSuppressLitLoopInjection(prompt, transcriptPath)` from ./guards.js (A3 C3): the engine
+// branches only on its `{suppress, reason}` result and imports NOTHING from the trigger module
+// (guard 0 `not-a-trigger` already covers lexical trigger detection). The engine never reads the
+// transcript itself and never slices the prompt by any offset (A3 A6).
+//
+// Casing (A3 C12): the input type-guard accepts BOTH the snake_case wire key `hook_event_name`
+// (primary) AND the camelCase `hookEventName` (fallback). The emitted envelope is ALWAYS camelCase
+// (`hookSpecificOutput.hookEventName`).
+//
+// On activation the payload is the trusted bundled directive, loaded behind a FAIL-SILENT boundary:
+// a directive-load error resolves to "" (→ noop), so a missing dist/directive.md degrades the hook
+// to a silent no-op + exit 0 rather than throwing into the Codex host.
+import { loadDirectiveFrom } from "./directive.js";
+import { shouldSuppressInjection } from "./guards.js";
+import { modeForToken } from "./modes.js";
+import { matchLitTrigger } from "./trigger.js";
+const HOOK_EVENT_NAME = "UserPromptSubmit";
+/** Narrow to a plain (non-null, non-array) record. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Read either casing of the event-name key (snake wins on conflict, A3 C12). */
+function readEventName(record) {
+    if (Object.hasOwn(record, "hook_event_name")) {
+        return record["hook_event_name"];
+    }
+    return record["hookEventName"];
+}
+/** Read either casing of the transcript-path key (snake wins on conflict). */
+function readTranscriptPath(record) {
+    if (Object.hasOwn(record, "transcript_path")) {
+        return record["transcript_path"];
+    }
+    if (Object.hasOwn(record, "transcriptPath")) {
+        return record["transcriptPath"];
+    }
+    return undefined;
+}
+function isTranscriptPathValue(value) {
+    return value === undefined || value === null || typeof value === "string";
+}
+/**
+ * Type-guard. True iff `value` is a record whose accepted event-name key (snake `hook_event_name`
+ * primary, camel `hookEventName` fallback) === "UserPromptSubmit", `prompt` is a string, and the
+ * transcript-path key (either casing) is undefined | null | string (A3 C12). This is a runtime
+ * accept-set, not a structural type assert, so a camelCase-keyed record also returns true.
+ */
+export function isLitUserPromptSubmitInput(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (readEventName(value) !== HOOK_EVENT_NAME) {
+        return false;
+    }
+    if (typeof value["prompt"] !== "string") {
+        return false;
+    }
+    return isTranscriptPathValue(readTranscriptPath(value));
+}
+/**
+ * Wraps directive text in the Codex output envelope. Returns "" if the normalized context is empty
+ * (caller treats "" as noop). Output is a single-line JSON + trailing "\n":
+ * {"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":<ctx>}}\n
+ */
+export function formatAdditionalContextOutput(additionalContext) {
+    const normalized = additionalContext.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+    if (normalized.length === 0) {
+        return "";
+    }
+    const output = {
+        hookSpecificOutput: {
+            hookEventName: HOOK_EVENT_NAME,
+            additionalContext: normalized,
+        },
+    };
+    return `${JSON.stringify(output)}\n`;
+}
+/**
+ * Load the matched mode's directive behind a fail-silent boundary: any loader error (e.g. a missing
+ * directives/<mode>.md or a marker-wrapper mismatch) resolves to "" so the hook degrades to a silent
+ * no-op instead of throwing into the Codex host.
+ */
+function loadDirectiveForModeFailSilent(mode) {
+    try {
+        return loadDirectiveFrom(mode.directivePath, mode.openMarker, mode.closeMarker);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Pure decision function (multi-mode router). Takes an already-parsed value (NOT a raw string).
+ * Total over `unknown`; NEVER throws. Flow: validate shape → match the lit-family trigger token
+ * (guard 0) → resolve the mode → run guards 1-3 against the MATCHED mode's marker (RC1) → load that
+ * mode's directive fail-silent. Returns { kind:"noop" } for a wrong-shape value, no trigger, a guard
+ * veto, or a fail-silent empty directive; { kind:"inject", stdout } only on a real activation.
+ */
+export function runUserPromptSubmitHook(input) {
+    if (!isLitUserPromptSubmitInput(input)) {
+        return { kind: "noop" };
+    }
+    // `input` is a narrowed record here; re-read the transcript key (either casing) as a raw value.
+    const transcriptPath = readTranscriptPath(input);
+    // Guard 0 / routing: which bounded lit-family token matched → which mode + directive.
+    const match = matchLitTrigger(input.prompt);
+    if (match === null) {
+        return { kind: "noop" };
+    }
+    const mode = modeForToken(match.token);
+    const decision = shouldSuppressInjection(input.prompt, transcriptPath, mode.openMarker);
+    if (decision.suppress) {
+        return { kind: "noop" };
+    }
+    const stdout = formatAdditionalContextOutput(loadDirectiveForModeFailSilent(mode));
+    if (stdout === "") {
+        return { kind: "noop" };
+    }
+    return { kind: "inject", stdout };
+}

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

@@ -0,0 +1,35 @@
+export { LIT_LOOP_DIRECTIVE_MARKER } from "./markers.js";
+/** Machine-readable codes for the three load-failure classes (ordered: unreadable → empty → marker). */
+export type LitLoopDirectiveErrorCode = "LIT_LOOP_DIRECTIVE_UNREADABLE" | "LIT_LOOP_DIRECTIVE_EMPTY" | "LIT_LOOP_DIRECTIVE_MARKER_MISSING";
+/** Typed error carrying a machine-readable code and the absolute path the loader attempted. */
+export declare class LitLoopDirectiveError extends Error {
+    readonly code: LitLoopDirectiveErrorCode;
+    readonly resolvedPath: string;
+    constructor(code: LitLoopDirectiveErrorCode, message: string, resolvedPath: string);
+}
+/**
+ * Generic (RC2): read + normalize + validate ANY mode's directive at an explicit path against an
+ * explicit `openMarker`/`closeMarker` pair. The multi-mode router (codex-hook → modes) uses this to
+ * load litwork / lit-plan / litgoal directives; `loadLitLoopDirectiveFrom` is the lit-loop wrapper.
+ * Normalization: CRLF→LF, lone CR→LF, then trim(). Fail-loud with a typed error (codes are generic).
+ */
+export declare function loadDirectiveFrom(resolvedPath: string, openMarker: string, closeMarker: string): string;
+/**
+ * Read + normalize + validate the lit-loop directive at an explicit path. Test-only seam (S10
+ * §Test plan) so corrupt / CRLF / missing-file cases can be exercised without swapping the bundled
+ * file. Delegates to the generic `loadDirectiveFrom` with the lit-loop marker pair.
+ */
+export declare function loadLitLoopDirectiveFrom(resolvedPath: string): string;
+/**
+ * Load the bundled directive.md from its resolved dist path. Re-readable on demand (tests /
+ * dev hot-reload); production consumers use the eagerly-computed `LIT_LOOP_DIRECTIVE` constant.
+ *
+ * @throws LitLoopDirectiveError code UNREADABLE / EMPTY / MARKER_MISSING.
+ */
+export declare function loadLitLoopDirective(): string;
+/**
+ * The normalized directive text, read once at module-load time. Guaranteed to start with
+ * `<lit-loop-mode>`, end with `</lit-loop-mode>`, and contain no `\r`; non-empty; frozen for
+ * the process lifetime.
+ */
+export declare const LIT_LOOP_DIRECTIVE: string;

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

@@ -0,0 +1,80 @@
+// src/directive.ts — M10 lit-loop directive loader.
+//
+// Reads the bundled directive.md at module-load time, normalizes line endings + trims, and
+// exports the normalized text plus the wrapper marker. This module owns content + loading only:
+// it never parses prompts, emits hook JSON, applies guards, or persists loop state, and it
+// imports NOTHING from trigger / guards / state-store / codex-hook (one-way: hook → directive).
+//
+// A3 C1: the marker is the single-source `markers.ts` value — re-exported here, never re-declared.
+// A3 G6 (SUPERSEDES C8): the single authored `directive.md` lives at the COMPONENT ROOT (tracked,
+//        in package.json files[]). The loader resolves `../directive.md` relative to its own module
+//        so it lands on that one file from BOTH layouts: src/directive.ts → <component>/directive.md
+//        (dev / vitest src-tree) AND dist/directive.js → <pkg>/directive.md (published tarball,
+//        since files[] ships directive.md at the tarball root beside dist/). No build-copy, no
+//        src/dist mirror — so a clean checkout passes `npm test` BEFORE any `npm run build`.
+//        Resolution uses `fileURLToPath(new URL(...))` — the percent-decoding, Windows-safe form
+//        that survives space/#/Hangul in the repo path.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { LIT_LOOP_DIRECTIVE_CLOSE, LIT_LOOP_DIRECTIVE_MARKER } from "./markers.js";
+// Re-export the single-source marker (A3 C1) so consumers import it from directive.ts unchanged.
+export { LIT_LOOP_DIRECTIVE_MARKER } from "./markers.js";
+/** Typed error carrying a machine-readable code and the absolute path the loader attempted. */
+export class LitLoopDirectiveError extends Error {
+    constructor(code, message, resolvedPath) {
+        super(message);
+        this.name = "LitLoopDirectiveError";
+        this.code = code;
+        this.resolvedPath = resolvedPath;
+    }
+}
+// A3 G6: directive.md is the authored component-root file, one level above this module's dir
+// (above src/ in the dev tree; above dist/ in the published tarball — files[] ships it at root).
+const DIRECTIVE_PATH = fileURLToPath(new URL("../directive.md", import.meta.url));
+/**
+ * Generic (RC2): read + normalize + validate ANY mode's directive at an explicit path against an
+ * explicit `openMarker`/`closeMarker` pair. The multi-mode router (codex-hook → modes) uses this to
+ * load litwork / lit-plan / litgoal directives; `loadLitLoopDirectiveFrom` is the lit-loop wrapper.
+ * Normalization: CRLF→LF, lone CR→LF, then trim(). Fail-loud with a typed error (codes are generic).
+ */
+export function loadDirectiveFrom(resolvedPath, openMarker, closeMarker) {
+    let raw;
+    try {
+        raw = readFileSync(resolvedPath, "utf8");
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new LitLoopDirectiveError("LIT_LOOP_DIRECTIVE_UNREADABLE", `directive: unreadable at ${resolvedPath}: ${detail}`, resolvedPath);
+    }
+    const normalized = raw.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+    if (normalized.length === 0) {
+        throw new LitLoopDirectiveError("LIT_LOOP_DIRECTIVE_EMPTY", `directive: empty after normalization at ${resolvedPath}`, resolvedPath);
+    }
+    if (!normalized.startsWith(openMarker) || !normalized.endsWith(closeMarker)) {
+        throw new LitLoopDirectiveError("LIT_LOOP_DIRECTIVE_MARKER_MISSING", `directive: missing ${openMarker} … ${closeMarker} wrapper at ${resolvedPath}`, resolvedPath);
+    }
+    return normalized;
+}
+/**
+ * Read + normalize + validate the lit-loop directive at an explicit path. Test-only seam (S10
+ * §Test plan) so corrupt / CRLF / missing-file cases can be exercised without swapping the bundled
+ * file. Delegates to the generic `loadDirectiveFrom` with the lit-loop marker pair.
+ */
+export function loadLitLoopDirectiveFrom(resolvedPath) {
+    return loadDirectiveFrom(resolvedPath, LIT_LOOP_DIRECTIVE_MARKER, LIT_LOOP_DIRECTIVE_CLOSE);
+}
+/**
+ * Load the bundled directive.md from its resolved dist path. Re-readable on demand (tests /
+ * dev hot-reload); production consumers use the eagerly-computed `LIT_LOOP_DIRECTIVE` constant.
+ *
+ * @throws LitLoopDirectiveError code UNREADABLE / EMPTY / MARKER_MISSING.
+ */
+export function loadLitLoopDirective() {
+    return loadLitLoopDirectiveFrom(DIRECTIVE_PATH);
+}
+/**
+ * The normalized directive text, read once at module-load time. Guaranteed to start with
+ * `<lit-loop-mode>`, end with `</lit-loop-mode>`, and contain no `\r`; non-empty; frozen for
+ * the process lifetime.
+ */
+export const LIT_LOOP_DIRECTIVE = loadLitLoopDirective();

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

@@ -0,0 +1,12 @@
+import type { LoopGoal, LoopPlan } from "./loop-types.js";
+/** The Codex goal objective for a given lit-loop goal (per-story: one Codex goal per goal). */
+export declare function expectedCodexObjective(goal: LoopGoal): string;
+/** True when the goal has at least one criterion and every criterion is `pass`. */
+export declare function hasAllCriteriaPass(goal: LoopGoal): boolean;
+/** True when every goal in the plan is `complete`. */
+export declare function isLitLoopDone(plan: LoopPlan): boolean;
+/**
+ * True when the given goal is NOT complete AND every OTHER goal IS complete — meaning completing
+ * this goal would finish the entire plan.
+ */
+export declare function isFinalRunCompletionCandidate(plan: LoopPlan, goal: LoopGoal): boolean;

package/node_modules/@litcodex/lit-loop/dist/goal-status.js

@@ -0,0 +1,25 @@
+// src/goal-status.ts — pure goal-status helpers for Codex native-goal integration.
+//
+// Predicates and objective resolver for the lit-loop ↔ Codex `/goal` handoff. All functions are
+// PURE — no I/O, no store, no clock. Imports only loop-types (which re-exports state-types).
+/** The Codex goal objective for a given lit-loop goal (per-story: one Codex goal per goal). */
+export function expectedCodexObjective(goal) {
+    return goal.objective;
+}
+/** True when the goal has at least one criterion and every criterion is `pass`. */
+export function hasAllCriteriaPass(goal) {
+    return goal.successCriteria.length > 0 && goal.successCriteria.every((c) => c.status === "pass");
+}
+/** True when every goal in the plan is `complete`. */
+export function isLitLoopDone(plan) {
+    return plan.goals.every((g) => g.status === "complete");
+}
+/**
+ * True when the given goal is NOT complete AND every OTHER goal IS complete — meaning completing
+ * this goal would finish the entire plan.
+ */
+export function isFinalRunCompletionCandidate(plan, goal) {
+    if (goal.status === "complete")
+        return false;
+    return plan.goals.every((g) => g.id === goal.id || g.status === "complete");
+}

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

@@ -0,0 +1,73 @@
+export { LIT_LOOP_DIRECTIVE_MARKER } from "./markers.js";
+/**
+ * Context-pressure / compaction / recovery markers. Lowercase substrings; matching is
+ * case-insensitive (input is lowercased before .includes). VERBATIM and ORDER-STABLE — the single
+ * source of truth (A3 §E): any module needing context-pressure detection MUST import this array,
+ * never copy it. Marker 5 retains the literal token `codex` (the host runtime, NOT a legacy brand —
+ * A3 C16) and the literal U+0027 apostrophe in `model's`.
+ */
+export declare const CONTEXT_PRESSURE_MARKERS: readonly ["context compacted", "context_length_exceeded", "skill descriptions were shortened", "context_too_large", "codex ran out of room in the model's context window", "your input exceeds the context window", "long threads and multiple compactions"];
+/** Tail window (bytes) read for the guard-2 directive-dedupe scan. Exactly 512000. */
+export declare const TRANSCRIPT_SEARCH_BYTES: 512000;
+/**
+ * Per-end byte budget for the guard-3 (context-pressure-transcript) read. Guard 3 reads at most the
+ * first and last GUARD3_WINDOW_BYTES of the transcript (whole file when smaller than 2×). Exactly
+ * 1 MiB per end so worst-case guard-3 work is ≤ 2 MiB of fixed-string scanning (A3 addendum §A).
+ * Distinct from TRANSCRIPT_SEARCH_BYTES (the guard-2 tail); the two MUST NOT be aliased.
+ */
+export declare const GUARD3_WINDOW_BYTES: 1048576;
+/**
+ * The hook OUTPUT envelope event-name value, written to the transcript by M06 and matched by guard
+ * 2 (A3 addendum §D). camelCase, load-bearing; declared exactly once here so M06's emitter and this
+ * guard cannot drift. M06 imports this from ./guards.js (one-way: codex-hook -> guards).
+ */
+export declare const HOOK_OUTPUT_EVENT_NAME: "UserPromptSubmit";
+/** Normalized transcript-path input shape accepted by the file-reading guards. */
+export type GuardTranscriptInput = string | null | undefined;
+/** Structured suppression decision returned to the M06 hook runner. */
+export interface LitLoopGuardDecision {
+    /** true => the hook MUST emit "" (no directive); false => injection may proceed. */
+    readonly suppress: boolean;
+    /** Machine-readable reason. "none" only when suppress === false. */
+    readonly reason: "none" | "context-pressure-prompt" | "already-injected" | "context-pressure-transcript" | "not-a-trigger";
+}
+/**
+ * Pure lexical test: does `text` contain ANY context-pressure marker? Lowercases `text`, then
+ * CONTEXT_PRESSURE_MARKERS.some(m => lower.includes(m)). No I/O, no state, idempotent.
+ * @throws TypeError if `text` is not a string.
+ */
+export declare function hasContextPressureMarker(text: string): boolean;
+/** Alias used by the prompt-level guard (guard 1). Identical semantics to hasContextPressureMarker. */
+export declare function isContextPressurePrompt(prompt: string): boolean;
+/**
+ * Generic per-mode idempotency check (RC1). Reads the TAIL (last TRANSCRIPT_SEARCH_BYTES bytes) of
+ * the transcript, parses each JSONL line, and returns true iff some line is a prior HOOK OUTPUT
+ * envelope: parsed.hookSpecificOutput.hookEventName === HOOK_OUTPUT_EVENT_NAME AND
+ * typeof additionalContext === "string" AND additionalContext.includes(`marker`). A marker quoted
+ * inside a user/assistant content STRING (or a forged envelope embedded as text) is NOT a top-level
+ * envelope line and is skipped. FAIL-OPEN: any thrown Error => false. The multi-mode hook passes the
+ * MATCHED mode's open marker so re-injection is suppressed per mode (mode switching is allowed).
+ */
+export declare function transcriptHasDirectiveMarker(transcriptPath: GuardTranscriptInput, marker: string): boolean;
+/** Lit-loop idempotency guard (guard 2) — the generic check bound to the lit-loop marker. */
+export declare function transcriptHasLitLoopDirective(transcriptPath: GuardTranscriptInput): boolean;
+/**
+ * Context-pressure transcript guard (guard 3). Reads a bounded head+tail window of the transcript
+ * (A3 addendum §A): the whole file when ≤ 2×GUARD3_WINDOW_BYTES, else the first + last
+ * GUARD3_WINDOW_BYTES joined by a "\n" separator (so a marker cannot be manufactured across the
+ * cut), then runs hasContextPressureMarker over it. Markers buried in nested JSON are caught by
+ * design. FAIL-OPEN: any thrown Error => false. null/undefined path => false.
+ */
+export declare function transcriptHasContextPressureMarker(transcriptPath: GuardTranscriptInput): boolean;
+/**
+ * THE single decision the M06 hook runner calls. Evaluates the four guards in fixed order and
+ * returns the first veto, else {suppress:false, reason:"none"}. Suppression dominates activation:
+ * guard 0 (not-a-trigger) runs first so the file-I/O guards only fire when a trigger is present;
+ * guard 1 (context-pressure-prompt) runs before the transcript guards so a recovery prompt that
+ * also contains `lit` is suppressed without any file read. Never throws for any string prompt +
+ * GuardTranscriptInput path (the only throw is the non-string prompt defensive guard).
+ * @throws TypeError only if `prompt` is not a string (M06 type-guards this upstream).
+ */
+export declare function shouldSuppressInjection(prompt: string, transcriptPath: GuardTranscriptInput, openMarker: string): LitLoopGuardDecision;
+/** Lit-loop entry point (backward-compatible) — the generic decision bound to the lit-loop marker. */
+export declare function shouldSuppressLitLoopInjection(prompt: string, transcriptPath: GuardTranscriptInput): LitLoopGuardDecision;

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

@@ -0,0 +1,215 @@
+// src/guards.ts — M07 activation-policy guard layer.
+//
+// Sits between the M05 bounded trigger matcher (./trigger.js) and the M06 hook runner. M05 asks
+// "does this prompt lexically contain a `lit` trigger?"; M07 asks "given the surrounding session
+// state, should we actually inject the <lit-loop-mode> directive NOW?". It owns four suppression
+// guards, evaluated in a fixed order (suppression dominates activation):
+//   0. not a lit trigger                 -> suppress, "not-a-trigger"
+//   1. prompt is a context-pressure msg  -> suppress, "context-pressure-prompt"
+//   2. transcript already hook-injected  -> suppress, "already-injected"
+//   3. transcript shows context pressure -> suppress, "context-pressure-transcript"
+//   else                                 -> allow,    "none"
+//
+// Detection is PURELY lexical/structural (fixed marker tables + a fixed JSON-envelope shape), so
+// prompt prose cannot alter any guard outcome. Every file-reading guard is FAIL-OPEN: any thrown
+// Error returns false (no suppression from that guard), never throwing — a missing, unreadable,
+// oversized, or malformed transcript can never crash the Codex turn. This module reads transcript
+// files but writes nothing and holds no mutable state.
+//
+// Dependency direction (A3 C9 flat layout; one-way: codex-hook -> guards -> trigger): imports ONLY
+// ./trigger.js and ./markers.js; NEVER ./directive.js, ./state-store.js, or ./codex-hook.js
+// (no-cycle invariant). The marker is the single-source markers.ts value, re-exported here
+// (A3 C1) — never re-declared.
+import { readFileSync } from "node:fs";
+import { LIT_LOOP_DIRECTIVE_MARKER } from "./markers.js";
+import { isLitTriggerPrompt } from "./trigger.js";
+// Re-export the single-source directive marker (A3 C1) so the guards public surface is unchanged
+// while markers.ts stays the only declaration site (guards never imports directive — no cycle).
+export { LIT_LOOP_DIRECTIVE_MARKER } from "./markers.js";
+/**
+ * Context-pressure / compaction / recovery markers. Lowercase substrings; matching is
+ * case-insensitive (input is lowercased before .includes). VERBATIM and ORDER-STABLE — the single
+ * source of truth (A3 §E): any module needing context-pressure detection MUST import this array,
+ * never copy it. Marker 5 retains the literal token `codex` (the host runtime, NOT a legacy brand —
+ * A3 C16) and the literal U+0027 apostrophe in `model's`.
+ */
+export const CONTEXT_PRESSURE_MARKERS = Object.freeze([
+    "context compacted",
+    "context_length_exceeded",
+    "skill descriptions were shortened",
+    "context_too_large",
+    "codex ran out of room in the model's context window",
+    "your input exceeds the context window",
+    "long threads and multiple compactions",
+]);
+/** Tail window (bytes) read for the guard-2 directive-dedupe scan. Exactly 512000. */
+export const TRANSCRIPT_SEARCH_BYTES = 512000;
+/**
+ * Per-end byte budget for the guard-3 (context-pressure-transcript) read. Guard 3 reads at most the
+ * first and last GUARD3_WINDOW_BYTES of the transcript (whole file when smaller than 2×). Exactly
+ * 1 MiB per end so worst-case guard-3 work is ≤ 2 MiB of fixed-string scanning (A3 addendum §A).
+ * Distinct from TRANSCRIPT_SEARCH_BYTES (the guard-2 tail); the two MUST NOT be aliased.
+ */
+export const GUARD3_WINDOW_BYTES = 1048576;
+/**
+ * The hook OUTPUT envelope event-name value, written to the transcript by M06 and matched by guard
+ * 2 (A3 addendum §D). camelCase, load-bearing; declared exactly once here so M06's emitter and this
+ * guard cannot drift. M06 imports this from ./guards.js (one-way: codex-hook -> guards).
+ */
+export const HOOK_OUTPUT_EVENT_NAME = "UserPromptSubmit";
+const PROMPT_NOT_A_STRING = "lit guard: prompt must be a string";
+const TEXT_NOT_A_STRING = "lit guard: text must be a string";
+// --- Internal helpers (not exported; semantics load-bearing) ----------------------------------
+/** Narrow to a plain (non-null, non-array) record. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse one JSONL line. Empty/whitespace line -> null; JSON.parse Error -> null (skipped);
+ * a non-Error throw (rare) is rethrown so the caller's fail-open boundary handles only Errors.
+ */
+function parseJsonLine(line) {
+    if (line.trim().length === 0) {
+        return null;
+    }
+    try {
+        return JSON.parse(line);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return null;
+        }
+        throw error;
+    }
+}
+// --- Pure marker matcher (guard 1 primitive) ---------------------------------------------------
+/**
+ * Pure lexical test: does `text` contain ANY context-pressure marker? Lowercases `text`, then
+ * CONTEXT_PRESSURE_MARKERS.some(m => lower.includes(m)). No I/O, no state, idempotent.
+ * @throws TypeError if `text` is not a string.
+ */
+export function hasContextPressureMarker(text) {
+    if (typeof text !== "string") {
+        throw new TypeError(TEXT_NOT_A_STRING);
+    }
+    const lower = text.toLowerCase();
+    return CONTEXT_PRESSURE_MARKERS.some((marker) => lower.includes(marker));
+}
+/** Alias used by the prompt-level guard (guard 1). Identical semantics to hasContextPressureMarker. */
+export function isContextPressurePrompt(prompt) {
+    return hasContextPressureMarker(prompt);
+}
+// --- Guard 2: idempotency (already-injected) ---------------------------------------------------
+/**
+ * Generic per-mode idempotency check (RC1). Reads the TAIL (last TRANSCRIPT_SEARCH_BYTES bytes) of
+ * the transcript, parses each JSONL line, and returns true iff some line is a prior HOOK OUTPUT
+ * envelope: parsed.hookSpecificOutput.hookEventName === HOOK_OUTPUT_EVENT_NAME AND
+ * typeof additionalContext === "string" AND additionalContext.includes(`marker`). A marker quoted
+ * inside a user/assistant content STRING (or a forged envelope embedded as text) is NOT a top-level
+ * envelope line and is skipped. FAIL-OPEN: any thrown Error => false. The multi-mode hook passes the
+ * MATCHED mode's open marker so re-injection is suppressed per mode (mode switching is allowed).
+ */
+export function transcriptHasDirectiveMarker(transcriptPath, marker) {
+    if (transcriptPath === null || transcriptPath === undefined) {
+        return false;
+    }
+    try {
+        const buf = readFileSync(transcriptPath);
+        const tail = buf.subarray(Math.max(0, buf.byteLength - TRANSCRIPT_SEARCH_BYTES)).toString("utf8");
+        for (const line of tail.split(/\r?\n/)) {
+            const parsed = parseJsonLine(line);
+            if (parsed === null || !isRecord(parsed)) {
+                continue;
+            }
+            const hso = parsed["hookSpecificOutput"];
+            if (!isRecord(hso)) {
+                continue;
+            }
+            if (hso["hookEventName"] !== HOOK_OUTPUT_EVENT_NAME) {
+                continue;
+            }
+            const additionalContext = hso["additionalContext"];
+            if (typeof additionalContext === "string" && additionalContext.includes(marker)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return false; // fail-open
+        }
+        throw error;
+    }
+}
+/** Lit-loop idempotency guard (guard 2) — the generic check bound to the lit-loop marker. */
+export function transcriptHasLitLoopDirective(transcriptPath) {
+    return transcriptHasDirectiveMarker(transcriptPath, LIT_LOOP_DIRECTIVE_MARKER);
+}
+// --- Guard 3: context-pressure transcript ------------------------------------------------------
+/**
+ * Context-pressure transcript guard (guard 3). Reads a bounded head+tail window of the transcript
+ * (A3 addendum §A): the whole file when ≤ 2×GUARD3_WINDOW_BYTES, else the first + last
+ * GUARD3_WINDOW_BYTES joined by a "\n" separator (so a marker cannot be manufactured across the
+ * cut), then runs hasContextPressureMarker over it. Markers buried in nested JSON are caught by
+ * design. FAIL-OPEN: any thrown Error => false. null/undefined path => false.
+ */
+export function transcriptHasContextPressureMarker(transcriptPath) {
+    if (transcriptPath === null || transcriptPath === undefined) {
+        return false;
+    }
+    try {
+        const buf = readFileSync(transcriptPath);
+        const n = buf.byteLength;
+        let text;
+        if (n <= 2 * GUARD3_WINDOW_BYTES) {
+            text = buf.toString("utf8");
+        }
+        else {
+            const head = buf.subarray(0, GUARD3_WINDOW_BYTES).toString("utf8");
+            const tail = buf.subarray(n - GUARD3_WINDOW_BYTES).toString("utf8");
+            text = `${head}\n${tail}`;
+        }
+        return hasContextPressureMarker(text);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return false; // fail-open
+        }
+        throw error;
+    }
+}
+// --- Single entry point (A3 C3) -----------------------------------------------------------------
+/**
+ * THE single decision the M06 hook runner calls. Evaluates the four guards in fixed order and
+ * returns the first veto, else {suppress:false, reason:"none"}. Suppression dominates activation:
+ * guard 0 (not-a-trigger) runs first so the file-I/O guards only fire when a trigger is present;
+ * guard 1 (context-pressure-prompt) runs before the transcript guards so a recovery prompt that
+ * also contains `lit` is suppressed without any file read. Never throws for any string prompt +
+ * GuardTranscriptInput path (the only throw is the non-string prompt defensive guard).
+ * @throws TypeError only if `prompt` is not a string (M06 type-guards this upstream).
+ */
+export function shouldSuppressInjection(prompt, transcriptPath, openMarker) {
+    if (typeof prompt !== "string") {
+        throw new TypeError(PROMPT_NOT_A_STRING);
+    }
+    if (!isLitTriggerPrompt(prompt)) {
+        return { suppress: true, reason: "not-a-trigger" };
+    }
+    if (isContextPressurePrompt(prompt)) {
+        return { suppress: true, reason: "context-pressure-prompt" };
+    }
+    // RC1: guard 2 checks the MATCHED mode's marker only — re-injecting the SAME mode is suppressed,
+    // switching modes (e.g. `lit` after `litwork`) is allowed.
+    if (transcriptHasDirectiveMarker(transcriptPath, openMarker)) {
+        return { suppress: true, reason: "already-injected" };
+    }
+    if (transcriptHasContextPressureMarker(transcriptPath)) {
+        return { suppress: true, reason: "context-pressure-transcript" };
+    }
+    return { suppress: false, reason: "none" };
+}
+/** Lit-loop entry point (backward-compatible) — the generic decision bound to the lit-loop marker. */
+export function shouldSuppressLitLoopInjection(prompt, transcriptPath) {
+    return shouldSuppressInjection(prompt, transcriptPath, LIT_LOOP_DIRECTIVE_MARKER);
+}

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

@@ -0,0 +1,17 @@
+/** Hard cap on stdin to bound memory / ReDoS exposure inside the 5 s Codex hook budget. 8 MB. */
+export declare const MAX_STDIN_BYTES = 8000000;
+/** Machine-readable error envelope emitted to stderr on a NON-zero exit. */
+export interface LitHookError {
+    readonly ok: false;
+    readonly error: {
+        readonly code: LitHookErrorCode;
+        readonly message: string;
+    };
+}
+export type LitHookErrorCode = "LIT_HOOK_STDIN_INVALID_JSON" | "LIT_HOOK_STDIN_TOO_LARGE";
+/**
+ * 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 declare function runUserPromptSubmitHookCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream): Promise<number>;