litcodex-ai 0.3.7 → 0.3.9

package/dist/config-migration/toml-shape.js

@@ -28,8 +28,10 @@ export function validateTomlShape(config) {
         const trimmed = raw.trim();
         const isHeader = trimmed.startsWith("[");
         if (isHeader) {
-            // R2 — unbalanced [section] header.
-            if (!WELL_FORMED_HEADER.test(raw)) {
+            // R2 — unbalanced [section] header. Strip quoted key segments FIRST so brackets inside a
+            // quoted key (e.g. a Windows project path `[projects."C:\…\[INBOX] MEMOS"]`, which Codex
+            // writes verbatim and is valid TOML) are not mistaken for stray section brackets.
+            if (!WELL_FORMED_HEADER.test(stripQuotedSpans(raw))) {
                 return reject("unbalanced-section-header", lineNo);
             }
             // R3 — duplicate [features.multi_agent_v2] table.
@@ -105,3 +107,35 @@ function stripInlineComment(line) {
     const idx = line.indexOf("#");
     return idx === -1 ? line.trim() : line.slice(0, idx).trim();
 }
+/**
+ * Replace every quoted span (basic `"…"` or literal `'…'`) with a single inert placeholder, so a
+ * structural scan never sees `[`, `]`, `#`, or quote chars that live INSIDE a TOML string. Basic
+ * strings honor `\` escapes (so an escaped quote doesn't close early); literal strings do not.
+ * Used to bracket-balance a section header whose key may contain a quoted path (e.g. `[INBOX]`).
+ */
+function stripQuotedSpans(line) {
+    let out = "";
+    let i = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === '"' || ch === "'") {
+            out += "Q"; // the whole quoted span collapses to one bracket-free key token
+            i += 1;
+            while (i < line.length) {
+                if (ch === '"' && line[i] === "\\") {
+                    i += 2; // skip an escaped char in a basic string (e.g. \" or \\)
+                    continue;
+                }
+                if (line[i] === ch) {
+                    i += 1; // closing quote
+                    break;
+                }
+                i += 1;
+            }
+            continue;
+        }
+        out += ch;
+        i += 1;
+    }
+    return out;
+}

package/node_modules/@litcodex/lit-loop/directives/lit-plan.md

@@ -21,6 +21,17 @@ A plan is **decision-complete** when the implementer needs ZERO judgment calls:
 every decision made, every ambiguity resolved, every pattern referenced with a
 concrete path.
 
+# Native Codex Plan Mode cooperation
+
+Native Codex Plan Mode is a host UI state, not a LitCodex hook setting. LitCodex
+cannot switch Codex into native Plan Mode from `UserPromptSubmit`; if the user
+wants host-enforced native planning, tell them to press Shift+Tab and resend or
+continue. If native Codex Plan Mode is already active, keep the turn read-only,
+do not write `.litcodex/drafts` or `.litcodex/plans`, and return the final plan
+as a complete `<proposed_plan>...</proposed_plan>` block. If native mode is not
+active and the user only invoked lit-plan, proceed with the file-backed lit-plan
+workflow below.
+
 # The gate (non-negotiable behavior)
 - **Explore before asking.** Most "questions" are discoverable facts. Ground
   yourself in the repo with read-only tools and parallel research subagents
@@ -101,11 +112,13 @@ paths as `dirty_worktree` risk, keep them out of task scope, and require
 verifiers to reject plans that would overwrite user changes.
 
 # Phase 2 — Interview (ask only what exploration cannot resolve)
-Record everything to `.litcodex/drafts/<slug>.md` as you go: confirmed
+When not in native Codex Plan Mode, record everything to `.litcodex/drafts/<slug>.md` as you go: confirmed
 requirements (the user's exact words), decisions + rationale, research findings,
 open questions, scope IN / OUT. Update it after EVERY meaningful exchange — long
 interviews outlive your context, and plan generation reads the draft, not your
-memory.
+memory. In native Codex Plan Mode, keep equivalent notes in the response only;
+do not create files until the user leaves native mode or explicitly grants a
+write-capable planning pass.
 
 Interview focus, informed by Phase 1 findings: goal + definition of done, scope
 boundaries (IN and explicitly OUT), technical approach ("I found pattern X at
@@ -150,11 +163,13 @@ automatic interview-to-plan transition.
    assumptions, missing acceptance criteria. SCOPE: this planning session.
    VERIFY: each gap names a concrete fix.","fork_context":false})`. Fold the
    findings in silently.
-2. Write ONE plan to `.litcodex/plans/<slug>.md` using the template below. No
-   "Phase 1 plan / Phase 2 plan" splits; 50+ todos is fine. Build it
-   incrementally — skeleton first, then append todo batches — so output limits
-   never truncate it; re-read the file with the `shell` tool to confirm
-   completeness.
+2. If native Codex Plan Mode is active, return ONE complete
+   `<proposed_plan>...</proposed_plan>` using the template below and do not write
+   a file. Otherwise write ONE plan to `.litcodex/plans/<slug>.md`. No
+	"Phase 1 plan / Phase 2 plan" splits; 50+ todos is fine. Build it
+	incrementally — skeleton first, then append todo batches — so output limits
+	never truncate it; re-read the file with the `shell` tool to confirm
+	completeness.
 3. **Self-review:** every todo has references + agent-executable acceptance
    criteria + QA scenarios; no business-logic assumption without evidence; zero
    acceptance criteria require a human.
@@ -243,12 +258,12 @@ Every `multi_agent_v1.spawn_agent` message is self-contained and starts with
 context the child needs. Name any skills the child needs directly inside its
 `message`.
 
-Treat TOML-backed role routing as **routing-unverified**. The
-`multi_agent_v1.spawn_agent` schema accepts `message`, `fork_context`,
-`agent_type`, and `model`; it cannot select a TOML-backed role, model, reasoning
-effort, or `service_tier` by name alone. Say so briefly in the draft, paste the
-role requirements into the message, and judge the result from delivered
-evidence.
+Prefer exact installed LitCodex role names when the host accepts `agent_type`:
+`litcodex-explorer`, `litcodex-librarian`, `litcodex-plan`, `litcodex-metis`,
+`litcodex-momus`, and `litcodex-litwork-reviewer`. If the tool exposes no
+`agent_type` parameter or rejects the role, omit `agent_type` and paste the role
+requirements into `message`. Judge the result from delivered evidence, not from
+the route selected.
 
 Plan and reviewer agents may run for a long time; spawn them in the background,
 keep doing independent root work, and poll with short `multi_agent_v1.wait_agent`

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

@@ -2,19 +2,19 @@
 //
 // Builds the `create_goal` / `update_goal` instruction text and JSON payload that lit-loop's
 // handleRun and handleCheckpoint append to their output so the agent keeps Codex's `/goal`
-// surface in sync with the active lit-loop goal. Per-story model only (one Codex goal per
-// lit-loop goal). Pure — no I/O, no store, no clock.
-import { expectedCodexObjective, isFinalRunCompletionCandidate, isLitLoopDone } from "./goal-status.js";
+// surface in sync with the durable lit-loop plan. Pure — no I/O, no store, no clock.
+import { codexGoalMode, expectedCodexObjective, isFinalRunCompletionCandidate, isLitLoopDone } from "./goal-status.js";
 export function buildCodexGoalInstruction(args) {
     const { plan, goal } = args;
-    const json = { objective: expectedCodexObjective(goal) };
+    const json = { objective: expectedCodexObjective(plan, goal) };
     const isFinal = args.isFinal ?? isFinalRunCompletionCandidate(plan, goal);
     const text = buildText(plan, goal, json, isFinal);
     return { text, json };
 }
 function buildText(plan, goal, payload, isFinal) {
+    const mode = codexGoalMode(plan);
     return joinLines([
-        "lit-loop Codex goal handoff",
+        mode === "aggregate" ? "lit-loop aggregate Codex goal handoff" : "lit-loop Codex goal handoff",
         `Plan: ${plan.goalsPath}`,
         `Ledger: ${plan.ledgerPath}`,
         `Goal: ${goal.id} — ${goal.title}`,
@@ -26,17 +26,31 @@ function buildText(plan, goal, payload, isFinal) {
         "Codex goal integration constraints:",
         "- Use the create_goal payload exactly as rendered: objective only.",
         "- Goals are unlimited. Do not add numeric limits.",
-        "- First call get_goal. If no active goal exists, call create_goal with the payload below.",
-        "- If get_goal already reports this objective as active, continue without creating a new goal.",
-        "- If a different active Codex goal exists, finish or clear it (`/goal clear`) before starting this lit-loop goal.",
-        "- Work only this goal until all criteria pass.",
-        ...finalLines(goal, isFinal),
+        ...nativeGoalModeLines(mode),
+        ...finalLines(goal, isFinal, mode),
         ...checkpointLines(),
         "",
         "create_goal payload:",
         JSON.stringify(payload, null, 2),
     ]);
 }
+function nativeGoalModeLines(mode) {
+    if (mode === "aggregate") {
+        return [
+            "- This Codex goal represents the whole lit-loop plan, not just the active story.",
+            "- First call get_goal. If no active goal exists, call create_goal with the payload below.",
+            "- If get_goal already reports this aggregate objective as active, continue without creating a new goal.",
+            "- If a different active Codex goal exists, finish or clear it (`/goal clear`) before starting this lit-loop plan.",
+            "- Work only the active lit-loop goal until its criteria pass; the aggregate Codex goal remains active across later lit-loop goals.",
+        ];
+    }
+    return [
+        "- First call get_goal. If no active goal exists, call create_goal with the payload below.",
+        "- If get_goal already reports this objective as active, continue without creating a new goal.",
+        "- If a different active Codex goal exists, finish or clear it (`/goal clear`) before starting this lit-loop goal.",
+        "- Work only this goal until all criteria pass.",
+    ];
+}
 function activeGoalLines(goal) {
     return ["Active goal:", `- id: ${goal.id}`, `- title: ${goal.title}`, `- objective: ${goal.objective}`];
 }
@@ -51,9 +65,14 @@ function successCriteriaLines(goal) {
         }),
     ];
 }
-function finalLines(goal, isFinal) {
+function finalLines(goal, isFinal, mode) {
     if (!isFinal) {
-        return ["- This is not the final lit-loop goal; leave the Codex goal active for the next run."];
+        return mode === "aggregate"
+            ? [
+                "- This is not the final lit-loop goal; leave the aggregate Codex goal active for the next run.",
+                "- Do not call update_goal yet; complete only the current lit-loop goal in durable state.",
+            ]
+            : ["- This is not the final lit-loop goal; leave the Codex goal active for the next run."];
     }
     return [
         "- This is the final lit-loop goal. After all criteria pass and checkpoint is complete:",
@@ -70,18 +89,31 @@ function checkpointLines() {
 // ── checkpoint handoff ──────────────────────────────────────────────────────
 export function buildCodexGoalCheckpoint(args) {
     const { plan, goal, status } = args;
+    const mode = codexGoalMode(plan);
     if (status === "complete") {
-        const lines = [
-            "Codex goal checkpoint:",
-            `Goal ${goal.id} is complete. Call update_goal({status: "complete"}) to mark the Codex goal done.`,
-        ];
         if (isLitLoopDone(plan)) {
+            const lines = [
+                "Codex goal checkpoint:",
+                `Goal ${goal.id} is complete. Call update_goal({status: "complete"}) to mark the Codex goal done.`,
+            ];
             lines.push("All lit-loop goals are now complete. Run `/goal clear` to close the Codex goal surface.");
+            return joinLines(lines);
+        }
+        if (mode === "aggregate") {
+            return joinLines([
+                "Codex goal checkpoint:",
+                `Goal ${goal.id} is complete. The aggregate Codex goal remains active for the rest of the durable plan.`,
+                "Do not call update_goal yet; run `litcodex loop run` to hand off the next goal.",
+            ]);
         }
         else {
+            const lines = [
+                "Codex goal checkpoint:",
+                `Goal ${goal.id} is complete. Call update_goal({status: "complete"}) to mark the Codex goal done.`,
+            ];
             lines.push("Run `litcodex loop run` to hand off the next goal.");
+            return joinLines(lines);
         }
-        return joinLines(lines);
     }
     return joinLines([
         "Codex goal checkpoint:",

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

@@ -1,6 +1,8 @@
 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;
+export declare function codexGoalMode(plan: LoopPlan): "aggregate" | "per_story";
+export declare function aggregateCodexObjective(plan: LoopPlan): string;
+/** The Codex goal objective for a lit-loop plan/goal. Defaults to one aggregate goal per plan. */
+export declare function expectedCodexObjective(plan: LoopPlan, 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`. */

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

@@ -2,9 +2,16 @@
 //
 // 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;
+export function codexGoalMode(plan) {
+    return plan.codexGoalMode ?? "aggregate";
+}
+export function aggregateCodexObjective(plan) {
+    return (plan.codexObjective ??
+        `Complete the durable lit-loop plan in ${plan.goalsPath}, including any later accepted/appended goals; use ${plan.ledgerPath} as the audit trail.`);
+}
+/** The Codex goal objective for a lit-loop plan/goal. Defaults to one aggregate goal per plan. */
+export function expectedCodexObjective(plan, goal) {
+    return codexGoalMode(plan) === "per_story" ? goal.objective : aggregateCodexObjective(plan);
 }
 /** True when the goal has at least one criterion and every criterion is `pass`. */
 export function hasAllCriteriaPass(goal) {

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

@@ -9,7 +9,7 @@
 // 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 { hookRegisteredInstalled, 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";
@@ -59,7 +59,10 @@ export async function loopCommand(argv, io, clock) {
     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 });
+        // Use the INSTALL-AWARE hook probe: a real `litcodex loop doctor` runs from an arbitrary cwd
+        // (no dev-tree manifest), so the pure repoRoot-only probe falsely warns "hook not registered".
+        // hookRegisteredInstalled also checks where the installed plugin actually lives (Codex cache).
+        const report = await runLoopDoctor({ repoRoot, scope }, { hookRegistered: (r) => hookRegisteredInstalled(r) });
         stdout.write(json ? renderDoctorJson(report) : renderDoctorText(report));
         return 0;
     }

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

@@ -12,6 +12,19 @@ export declare const TERMINAL_LEDGER_KINDS: {
  * catch (→ warn). Never executes any command from the manifest.
  */
 export declare function hookRegistered(repoRoot: string): Promise<boolean>;
+/**
+ * Install-aware hook probe (production default the global CLI injects). The dev-tree manifest
+ * `<repoRoot>/plugins/litcodex/hooks/hooks.json` ONLY exists when run from the repo; a real install
+ * (`litcodex loop doctor` from any cwd) has no such file, so the pure `hookRegistered` falsely warns
+ * "not registered". This trusts the repoRoot manifest when present (dev/test), and otherwise looks
+ * where the INSTALLED plugin actually lives: the Codex plugin cache
+ * `<CODEX_HOME>/plugins/cache/.../hooks/hooks.json` (the global CLI runs the bundled lit-loop, so the
+ * plugin's aggregate manifest only exists in that cache). Pure-read, never executes a command;
+ * `opts.codexHome` is injectable so tests stay hermetic.
+ */
+export declare function hookRegisteredInstalled(repoRoot: string, opts?: {
+    codexHome?: 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;
 /**

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

@@ -11,7 +11,8 @@
 //
 // 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 { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { sanitizeId } from "./loop-doctor-render.js";
 import { summarizePlan } from "./loop-model.js";
@@ -52,6 +53,58 @@ export async function hookRegistered(repoRoot) {
     const parsed = JSON.parse(raw);
     return scanForCommand(parsed);
 }
+/** Read + scan a manifest at an absolute path; ENOENT/parse-error ⇒ false (never throws). */
+async function scanManifestAt(manifestAbs) {
+    try {
+        if (!(await statExists(manifestAbs)))
+            return false;
+        return scanForCommand(JSON.parse(await readFile(manifestAbs, "utf8")));
+    }
+    catch {
+        return false;
+    }
+}
+/** Walk `<cacheRoot>/<marketplace>/<plugin>/<version>/hooks/hooks.json` (bounded; a few installs). */
+async function scanCodexPluginCache(cacheRoot) {
+    const listDirs = async (dir) => {
+        try {
+            return await readdir(dir);
+        }
+        catch {
+            return [];
+        }
+    };
+    for (const mp of await listDirs(cacheRoot)) {
+        for (const plugin of await listDirs(join(cacheRoot, mp))) {
+            for (const ver of await listDirs(join(cacheRoot, mp, plugin))) {
+                if (await scanManifestAt(join(cacheRoot, mp, plugin, ver, "hooks", "hooks.json")))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Install-aware hook probe (production default the global CLI injects). The dev-tree manifest
+ * `<repoRoot>/plugins/litcodex/hooks/hooks.json` ONLY exists when run from the repo; a real install
+ * (`litcodex loop doctor` from any cwd) has no such file, so the pure `hookRegistered` falsely warns
+ * "not registered". This trusts the repoRoot manifest when present (dev/test), and otherwise looks
+ * where the INSTALLED plugin actually lives: the Codex plugin cache
+ * `<CODEX_HOME>/plugins/cache/.../hooks/hooks.json` (the global CLI runs the bundled lit-loop, so the
+ * plugin's aggregate manifest only exists in that cache). Pure-read, never executes a command;
+ * `opts.codexHome` is injectable so tests stay hermetic.
+ */
+export async function hookRegisteredInstalled(repoRoot, opts) {
+    // 1. Dev tree — authoritative when present (preserves dev/test behavior and keeps the real-fs cache
+    //    walk below from ever running inside the repo's own hermetic unit tests).
+    const devManifest = join(repoRoot, ...HOOK_MANIFEST_RELPATH.split("/"));
+    if (await statExists(devManifest)) {
+        return scanManifestAt(devManifest);
+    }
+    // 2. Codex plugin cache — the real install context for a global-CLI `litcodex loop doctor`.
+    const codexHome = opts?.codexHome ?? (process.env["CODEX_HOME"]?.trim() || join(homedir(), ".codex"));
+    return scanCodexPluginCache(join(codexHome, "plugins", "cache"));
+}
 /** Recursively scan every string value under a `command` key for ALL three fragments. */
 function scanForCommand(node) {
     if (Array.isArray(node)) {

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

@@ -1,5 +1,5 @@
 /** 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";
+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_PLAN_EXISTS_COMPLETE" | "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";

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

@@ -36,6 +36,7 @@ export function exitCodeForLoop(err) {
         case "LIT_LOOP_GOAL_NOT_FOUND":
         case "LIT_LOOP_CRITERION_NOT_FOUND":
         case "LIT_LOOP_CRITERIA_NOT_ALL_PASS":
+        case "LIT_LOOP_PLAN_EXISTS_COMPLETE":
             return 3; // not found / unresolved
         default:
             return exitCodeFor(err); // store codes (3/4/5) + unexpected → 1

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

@@ -6,6 +6,7 @@
 // `./state-store.js` (A3 C9) — this module never touches node:fs. Errors are the CLI's
 // `LitLoopError` (mapped on `.code` by loop-cli's exitCodeForLoop) or re-thrown store errors.
 import { buildCodexGoalCheckpoint, buildCodexGoalInstruction } from "./codex-goal-instruction.js";
+import { aggregateCodexObjective, codexGoalMode, isLitLoopDone } from "./goal-status.js";
 import { LitLoopError } from "./loop-errors.js";
 import { buildRunInstruction, deriveGoalCandidates, normalizeGoalId, pickNextRunnableGoal, requireAllCriteriaPass, seedDefaultSuccessCriteria, summarizePlan, titleFromObjective, } from "./loop-model.js";
 import { LOOP_CREATE_STDOUT } from "./loop-stdout.js";
@@ -71,6 +72,9 @@ export async function handleCreate(argv, ctx) {
     return withMutationLock(ctx.repoRoot, ctx.scope, async () => {
         const existing = await readPlanOrNull(ctx);
         if (existing !== null && !force) {
+            if (isLitLoopDone(existing)) {
+                throw new LitLoopError(`Existing lit-loop plan is already complete at ${existing.goalsPath}. Start fresh with litcodex loop create --session <new-id> or use --force to overwrite intentionally.`, "LIT_LOOP_PLAN_EXISTS_COMPLETE", { goalsPath: existing.goalsPath });
+            }
             return planResult(existing); // idempotent no-op
         }
         const now = ctx.now();
@@ -92,8 +96,10 @@ export async function handleCreate(argv, ctx) {
             updatedAt: now,
             ...paths,
             sessionId: ctx.scope?.sessionId ?? null,
+            codexGoalMode: "aggregate",
             goals,
         };
+        plan.codexObjective = aggregateCodexObjective(plan);
         await writeBrief(ctx.repoRoot, brief, ctx.scope);
         await writePlan(ctx.repoRoot, plan, ctx.scope);
         await appendLedger(ctx.repoRoot, { at: now, kind: "plan_created", message: `${goals.length} goal(s) derived from brief.` }, ctx.scope);
@@ -211,13 +217,28 @@ export async function handleCheckpoint(argv, ctx) {
         await writePlan(ctx.repoRoot, plan, ctx.scope);
         await appendLedger(ctx.repoRoot, ledgerEntry, ctx.scope);
         const codexCheckpoint = buildCodexGoalCheckpoint({ plan, goal, status });
+        const codexGoalStatus = checkpointCodexGoalStatus(plan, status);
         return {
             exitCode: 0,
             text: `lit-loop checkpoint: ${goalId} -> ${status}\n\n${codexCheckpoint}\n`,
-            json: { ok: true, goal, ledgerEntry, codexGoal: { status }, plan, summary: summarizePlan(plan) },
+            json: {
+                ok: true,
+                goal,
+                ledgerEntry,
+                codexGoal: { status: codexGoalStatus },
+                plan,
+                summary: summarizePlan(plan),
+            },
         };
     });
 }
+function checkpointCodexGoalStatus(plan, status) {
+    if (status !== "complete")
+        return "active";
+    if (isLitLoopDone(plan))
+        return "complete";
+    return codexGoalMode(plan) === "per_story" ? "complete" : "active";
+}
 // -- record-evidence -----------------------------------------------------------
 const EVIDENCE_STATUSES = new Set(["pass", "fail", "blocked"]);
 export async function handleRecordEvidence(argv, ctx) {

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

@@ -31,9 +31,11 @@ export declare function evidencePath(repoRoot: string, name: string, scope?: Lit
 export declare function repoRelative(absolutePath: string, repoRoot: string): string;
 /**
  * Resolve a LitLoopScope from argv/env. Precedence (first non-blank wins): `--session <id>` /
- * `--session=<id>` → env `LITCODEX_LOOP_SESSION` → env `LIT_LOOP_SESSION`. The chosen raw id is
- * normalized; returns `{ sessionId }` when a non-null id results, else `undefined`. Pure aside
- * from reading the provided `env` object (NEVER `process.env`); zero I/O.
+ * `--session=<id>` / `--session-id <id>` / `--session-id=<id>` → env `LITCODEX_SESSION_ID` →
+ * `CODEX_SESSION_ID` → `CODEX_THREAD_ID` → compatibility env `LITCODEX_LOOP_SESSION` →
+ * `LIT_LOOP_SESSION`. The chosen raw id is normalized; returns `{ sessionId }` when a non-null id
+ * results, else `undefined`. Pure aside from reading the provided `env` object (NEVER
+ * `process.env`); zero I/O.
  */
 export declare function resolveLoopScope(source: {
     argv?: readonly string[];

package/node_modules/@litcodex/lit-loop/dist/state-paths.js

@@ -87,25 +87,35 @@ export function repoRelative(absolutePath, repoRoot) {
 function readSessionFlag(argv) {
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
-        if (arg === "--session") {
+        if (arg === "--session" || arg === "--session-id") {
             return argv[i + 1];
         }
         if (arg?.startsWith("--session=")) {
             return arg.slice("--session=".length);
         }
+        if (arg?.startsWith("--session-id=")) {
+            return arg.slice("--session-id=".length);
+        }
     }
     return undefined;
 }
 /**
  * Resolve a LitLoopScope from argv/env. Precedence (first non-blank wins): `--session <id>` /
- * `--session=<id>` → env `LITCODEX_LOOP_SESSION` → env `LIT_LOOP_SESSION`. The chosen raw id is
- * normalized; returns `{ sessionId }` when a non-null id results, else `undefined`. Pure aside
- * from reading the provided `env` object (NEVER `process.env`); zero I/O.
+ * `--session=<id>` / `--session-id <id>` / `--session-id=<id>` → env `LITCODEX_SESSION_ID` →
+ * `CODEX_SESSION_ID` → `CODEX_THREAD_ID` → compatibility env `LITCODEX_LOOP_SESSION` →
+ * `LIT_LOOP_SESSION`. The chosen raw id is normalized; returns `{ sessionId }` when a non-null id
+ * results, else `undefined`. Pure aside from reading the provided `env` object (NEVER
+ * `process.env`); zero I/O.
  */
 export function resolveLoopScope(source) {
     const argv = source.argv ?? [];
     const env = source.env ?? {};
-    const raw = readSessionFlag(argv) ?? env["LITCODEX_LOOP_SESSION"] ?? env["LIT_LOOP_SESSION"];
+    const raw = readSessionFlag(argv) ??
+        env["LITCODEX_SESSION_ID"] ??
+        env["CODEX_SESSION_ID"] ??
+        env["CODEX_THREAD_ID"] ??
+        env["LITCODEX_LOOP_SESSION"] ??
+        env["LIT_LOOP_SESSION"];
     const sessionId = normalizeSessionId(raw);
     return sessionId === null ? undefined : { sessionId };
 }

package/node_modules/@litcodex/lit-loop/dist/state-store.js

@@ -130,6 +130,14 @@ function planInvalidReason(plan) {
     if (!(sessionId === null || typeof sessionId === "string")) {
         return "sessionId must be a string or null";
     }
+    const codexGoalMode = field(plan, "codexGoalMode");
+    if (codexGoalMode !== undefined && codexGoalMode !== "aggregate" && codexGoalMode !== "per_story") {
+        return "codexGoalMode must be aggregate or per_story when present";
+    }
+    const codexObjective = field(plan, "codexObjective");
+    if (codexObjective !== undefined && typeof codexObjective !== "string") {
+        return "codexObjective must be a string when present";
+    }
     const goals = field(plan, "goals");
     if (!Array.isArray(goals)) {
         return "goals must be an array";

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

@@ -6,6 +6,7 @@ export type LitLoopCriterionStatus = "pending" | "pass" | "fail" | "blocked";
  * branch + validation mismatch. Re-introducing it is a coordinated M08+M09 change.
  */
 export type LitLoopUserModel = "happy" | "edge" | "regression";
+export type LitLoopCodexGoalMode = "aggregate" | "per_story";
 /** Frozen tuple of the three user-model values (enumerable, single source). */
 export declare const LIT_LOOP_USER_MODELS: readonly LitLoopUserModel[];
 /** The 13-member ledger event-kind union: M08's 11 ∪ M09's 10 (A3 C7). */
@@ -49,6 +50,8 @@ export interface LitLoopPlan {
     ledgerPath: string;
     evidenceDir: string;
     sessionId: string | null;
+    codexGoalMode?: LitLoopCodexGoalMode;
+    codexObjective?: string;
     activeGoalId?: string;
     goals: LitLoopGoal[];
 }

package/node_modules/@litcodex/lit-loop/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@litcodex/lit-loop",
-	"version": "0.3.7",
+	"version": "0.3.9",
 	"description": "LitCodex Lit-Loop runtime: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"bin": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "litcodex-ai",
-	"version": "0.3.7",
+	"version": "0.3.9",
 	"description": "Codex loop harness installer. Run `npx litcodex-ai install` to set up the LitCodex Codex platform: the bare `lit` hook and the durable lit-loop runtime.",
 	"keywords": ["codex", "litcodex", "lit-loop", "ai-agents", "orchestration"],
 	"author": "LitCodex Authors",
@@ -15,7 +15,7 @@
 	},
 	"files": ["bin", "dist", "model-catalog.json", "README.md", "LICENSE"],
 	"dependencies": {
-		"@litcodex/lit-loop": "0.3.7"
+		"@litcodex/lit-loop": "0.3.9"
 	},
 	"bundledDependencies": ["@litcodex/lit-loop"],
 	"scripts": {