oh-my-opencode 4.15.1 → 4.16.1

package/packages/omo-codex/plugin/components/ulw-loop/dist/plan-io.d.ts

@@ -6,3 +6,9 @@ export declare function readUlwLoopPlan(repoRoot: string, scope?: UlwLoopScope):
 export declare function writePlan(repoRoot: string, plan: UlwLoopPlan, scope?: UlwLoopScope): Promise<void>;
 export declare function appendLedger(repoRoot: string, entry: UlwLoopLedgerEntry, scope?: UlwLoopScope): Promise<void>;
 export declare function readSteeringLedgerEntries(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopLedgerEntry[]>;
+/**
+ * First accepted steering entry matching an idempotency key/prompt signature.
+ * A cheap substring probe on the raw line skips JSON.parse for the vast
+ * majority of entries, so dedup stays flat even on legacy multi-MB ledgers.
+ */
+export declare function findAcceptedSteeringLedgerEntry(repoRoot: string, key: string, scope?: UlwLoopScope): Promise<UlwLoopLedgerEntry | undefined>;

package/packages/omo-codex/plugin/components/ulw-loop/dist/plan-io.js

@@ -1,4 +1,6 @@
+import { createReadStream } from "node:fs";
 import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
 import { aggregateCodexObjectiveForScope } from "./goal-status.js";
 import { repoRelative, ulwLoopDir, ulwLoopGoalsPath, ulwLoopLedgerPath, ulwLoopRelativeDir, } from "./paths.js";
 import { iso, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from "./types.js";
@@ -20,9 +22,17 @@ export async function withUlwLoopMutationLock(repoRoot, scopeOrFn, maybeFn) {
     if (fn === undefined)
         throw new UlwLoopError("Missing ulw-loop mutation body.", "ULW_LOOP_LOCK_BODY_MISSING");
     const lockKey = `${repoRoot}\0${ulwLoopRelativeDir(scope)}`;
-    const prior = locks.get(lockKey) ?? Promise.resolve();
+    const prior = locks.get(lockKey) ?? Promise.resolve(undefined);
     const run = prior.then(fn, fn);
-    locks.set(lockKey, run.catch(() => undefined));
+    // The stored gate resolves to undefined so the map never retains fn's result
+    // (plans/audits), and it removes itself once no newer waiter replaced it —
+    // otherwise a long-lived host leaks one entry per (repo, scope) forever.
+    const gate = run.then(() => undefined, () => undefined);
+    locks.set(lockKey, gate);
+    void gate.then(() => {
+        if (locks.get(lockKey) === gate)
+            locks.delete(lockKey);
+    });
     return run;
 }
 export async function readUlwLoopPlan(repoRoot, scope) {
@@ -69,21 +79,57 @@ export async function appendLedger(repoRoot, entry, scope) {
     await mkdir(ulwLoopDir(repoRoot, scope), { recursive: true });
     await appendFile(ulwLoopLedgerPath(repoRoot, scope), `${JSON.stringify(entry)}\n`, "utf8");
 }
-export async function readSteeringLedgerEntries(repoRoot, scope) {
-    let raw;
+/**
+ * Streams raw ledger lines without materializing the file. Real ledgers reach
+ * many MB (legacy entries embedded full-plan snapshots), so `readFile` here
+ * ballooned every steer/dedup path; line-at-a-time keeps memory O(longest line).
+ */
+async function* ledgerLines(repoRoot, scope) {
+    const stream = createReadStream(ulwLoopLedgerPath(repoRoot, scope), { encoding: "utf8" });
+    const lines = createInterface({ input: stream, crlfDelay: Number.POSITIVE_INFINITY });
     try {
-        raw = await readFile(ulwLoopLedgerPath(repoRoot, scope), "utf8");
+        for await (const line of lines) {
+            if (line.trim().length > 0)
+                yield line;
+        }
     }
     catch (error) {
-        if (hasCode(error, "ENOENT"))
-            return [];
-        throw error;
+        if (!hasCode(error, "ENOENT"))
+            throw error;
+    }
+    finally {
+        lines.close();
+        stream.destroy();
     }
+}
+export async function readSteeringLedgerEntries(repoRoot, scope) {
     const entries = [];
-    for (const line of raw.split(/\r?\n/).filter(Boolean)) {
+    for await (const line of ledgerLines(repoRoot, scope)) {
         const entry = JSON.parse(line);
         if (isSteeringKind(entry.kind))
             entries.push(entry);
     }
     return entries;
 }
+/**
+ * First accepted steering entry matching an idempotency key/prompt signature.
+ * A cheap substring probe on the raw line skips JSON.parse for the vast
+ * majority of entries, so dedup stays flat even on legacy multi-MB ledgers.
+ */
+export async function findAcceptedSteeringLedgerEntry(repoRoot, key, scope) {
+    const probe = JSON.stringify(key);
+    for await (const line of ledgerLines(repoRoot, scope)) {
+        if (!line.includes(probe))
+            continue;
+        const entry = JSON.parse(line);
+        if (!isSteeringKind(entry.kind))
+            continue;
+        if (entry.steering?.invariant.accepted !== true)
+            continue;
+        if (entry.idempotencyKey === key ||
+            entry.steering.idempotencyKey === key ||
+            entry.steering.promptSignature === key)
+            return entry;
+    }
+    return undefined;
+}

package/packages/omo-codex/plugin/components/ulw-loop/dist/steering-snapshot.d.ts

@@ -0,0 +1,15 @@
+import type { UlwLoopPlan } from "./domain-types.js";
+import type { UlwLoopSteeringPlanSnapshot } from "./steering-types.js";
+/**
+ * Compact before/after snapshots for steering ledger entries.
+ *
+ * Ledger entries used to embed the FULL plan (every goal, criterion, and
+ * evidence string) twice per audit and twice more at the entry top level.
+ * That made each accepted steer O(plan size) on disk, so the ledger grew
+ * quadratically over a run, and every dedup scan re-hydrated all of it into
+ * memory. A snapshot instead records plan-level counters plus only the goals
+ * the mutation actually touched, keeping each entry O(changed goals).
+ */
+export declare function buildSteeringPlanSnapshot(plan: UlwLoopPlan, changedGoalIds: ReadonlySet<string>): UlwLoopSteeringPlanSnapshot;
+/** Ids of goals that differ between two plans, including added or removed goals. */
+export declare function changedGoalIdsBetween(before: UlwLoopPlan, after: UlwLoopPlan): Set<string>;

package/packages/omo-codex/plugin/components/ulw-loop/dist/steering-snapshot.js

@@ -0,0 +1,33 @@
+/**
+ * Compact before/after snapshots for steering ledger entries.
+ *
+ * Ledger entries used to embed the FULL plan (every goal, criterion, and
+ * evidence string) twice per audit and twice more at the entry top level.
+ * That made each accepted steer O(plan size) on disk, so the ledger grew
+ * quadratically over a run, and every dedup scan re-hydrated all of it into
+ * memory. A snapshot instead records plan-level counters plus only the goals
+ * the mutation actually touched, keeping each entry O(changed goals).
+ */
+export function buildSteeringPlanSnapshot(plan, changedGoalIds) {
+    const snapshot = {
+        updatedAt: plan.updatedAt,
+        goalCount: plan.goals.length,
+        goalIds: plan.goals.map((goal) => goal.id),
+        goals: plan.goals.filter((goal) => changedGoalIds.has(goal.id)),
+    };
+    return plan.activeGoalId === undefined ? snapshot : { ...snapshot, activeGoalId: plan.activeGoalId };
+}
+/** Ids of goals that differ between two plans, including added or removed goals. */
+export function changedGoalIdsBetween(before, after) {
+    const beforeById = new Map(before.goals.map((goal) => [goal.id, goal]));
+    const changed = new Set();
+    for (const goal of after.goals) {
+        const prior = beforeById.get(goal.id);
+        if (prior === undefined || JSON.stringify(prior) !== JSON.stringify(goal))
+            changed.add(goal.id);
+        beforeById.delete(goal.id);
+    }
+    for (const id of beforeById.keys())
+        changed.add(id);
+    return changed;
+}

package/packages/omo-codex/plugin/components/ulw-loop/dist/steering-types.d.ts

@@ -1,5 +1,5 @@
 import type { UlwLoopSteeringMutationKind, UlwLoopSteeringSource } from "./constants.js";
-import type { UlwLoopPlan } from "./domain-types.js";
+import type { UlwLoopItem, UlwLoopPlan } from "./domain-types.js";
 export interface UlwLoopSteeringInvariantResult {
     accepted: boolean;
     structuralInvariantAccepted: boolean;
@@ -39,13 +39,20 @@ export interface UlwLoopSteeringProposal {
     idempotencyKey?: string;
     now?: Date;
 }
+export interface UlwLoopSteeringPlanSnapshot {
+    readonly updatedAt: string;
+    readonly activeGoalId?: string;
+    readonly goalCount: number;
+    readonly goalIds: readonly string[];
+    readonly goals: readonly UlwLoopItem[];
+}
 export interface UlwLoopSteeringAudit {
     kind: UlwLoopSteeringMutationKind;
     source: UlwLoopSteeringSource;
     targetGoalIds: string[];
     criterionId?: string;
-    before?: unknown;
-    after?: unknown;
+    before?: UlwLoopSteeringPlanSnapshot;
+    after?: UlwLoopSteeringPlanSnapshot;
     evidence: string;
     rationale: string;
     invariant: UlwLoopSteeringInvariantResult;

package/packages/omo-codex/plugin/components/ulw-loop/dist/steering.js

@@ -1,7 +1,8 @@
 // biome-ignore-all format: compact steering module must stay below the 240 pure-LOC budget
 import { isUlwLoopDone } from "./goal-status.js";
 import { seedDefaultSuccessCriteria } from "./plan-crud.js";
-import { appendLedger, readSteeringLedgerEntries, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { appendLedger, findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
+import { buildSteeringPlanSnapshot, changedGoalIdsBetween } from "./steering-snapshot.js";
 import { iso, ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_MODELS } from "./types.js";
 const SOURCES = ["user_prompt_submit", "finding", "cli"];
 const PROTECTED = new Set(["aggregateCompletion", "codexObjective", "codexObjectiveAliases", "originalConstraints", "qualityGate", "status", "completedAt", "completionStatus"]);
@@ -260,15 +261,22 @@ export async function steerUlwLoop(repoRoot, proposal, scope) {
     return withUlwLoopMutationLock(repoRoot, scope, async () => {
         const plan = await readUlwLoopPlan(repoRoot, scope);
         const key = proposal.idempotencyKey ?? proposal.promptSignature;
-        const prior = key === undefined ? undefined : (await readSteeringLedgerEntries(repoRoot, scope)).find((entry) => entry.steering?.invariant.accepted === true && (entry.idempotencyKey === key || entry.steering.idempotencyKey === key || entry.steering.promptSignature === key));
-        if (prior?.steering !== undefined)
-            return { plan, accepted: true, audit: { ...prior.steering, deduped: true }, rejectedReasons: [], deduped: true };
+        const prior = key === undefined ? undefined : await findAcceptedSteeringLedgerEntry(repoRoot, key, scope);
+        if (prior?.steering !== undefined) {
+            // Legacy entries embedded full-plan before/after snapshots; never
+            // re-surface those multi-MB payloads on the dedup path.
+            const { before: _before, after: _after, ...compactPrior } = prior.steering;
+            return { plan, accepted: true, audit: { ...compactPrior, deduped: true }, rejectedReasons: [], deduped: true };
+        }
         const audit = validateUlwLoopSteeringProposal(plan, proposal);
         const accepted = audit.invariant.accepted;
         const next = accepted ? applySteeringMutation(plan, proposal, audit) : plan;
-        const finalAudit = { ...audit, before: plan };
-        if (accepted)
-            finalAudit.after = next;
+        const finalAudit = { ...audit };
+        if (accepted) {
+            const changed = changedGoalIdsBetween(plan, next);
+            finalAudit.before = buildSteeringPlanSnapshot(plan, changed);
+            finalAudit.after = buildSteeringPlanSnapshot(next, changed);
+        }
         if (accepted)
             await writePlan(repoRoot, next, scope);
         await appendLedger(repoRoot, ledgerEntry(proposal, finalAudit, proposal.now?.toISOString() ?? iso()), scope);
@@ -284,9 +292,5 @@ function ledgerEntry(proposal, audit, at) {
         entry.criterionId = proposal.criterionId;
     if (proposal.idempotencyKey !== undefined)
         entry.idempotencyKey = proposal.idempotencyKey;
-    if (audit.before !== undefined)
-        entry.before = audit.before;
-    if (audit.after !== undefined)
-        entry.after = audit.after;
     return entry;
 }

package/packages/omo-codex/plugin/components/ulw-loop/dist/ultrawork-directive.d.ts

@@ -1,5 +1,6 @@
+import { type UltraworkAdditionalContextOptions } from "./ultrawork-skill-pointer.js";
 export interface UltraworkDirectiveInput {
     readonly prompt: string;
     readonly transcript_path?: string | null;
 }
-export declare function buildUltraworkDirectiveOutput(input: UltraworkDirectiveInput): string;
+export declare function buildUltraworkDirectiveOutput(input: UltraworkDirectiveInput, options?: UltraworkAdditionalContextOptions): string;

package/packages/omo-codex/plugin/components/ulw-loop/dist/ultrawork-directive.js

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-const ULTRAWORK_DIRECTIVE = readFileSync(new URL("../directive.md", import.meta.url), "utf8");
+import { buildUltraworkAdditionalContext } from "./ultrawork-skill-pointer.js";
 const ULTRAWORK_CURRENT_PROMPT_PATTERN = /(?:ultrawork|ulw)/i;
 const ULTRAWORK_DIRECTIVE_MARKER = "<ultrawork-mode>";
 const TRANSCRIPT_SEARCH_BYTES = 512_000;
@@ -12,14 +12,16 @@ const CONTEXT_PRESSURE_MARKERS = [
     "your input exceeds the context window",
     "long threads and multiple compactions",
 ];
-export function buildUltraworkDirectiveOutput(input) {
+export function buildUltraworkDirectiveOutput(input, options = {}) {
     if (isContextPressureRecoveryPrompt(input.prompt))
         return "";
     if (hasUltraworkDirectiveAlreadyInTranscript(input.transcript_path))
         return "";
     if (isContextPressureTranscript(input.transcript_path))
         return "";
-    return isUltraworkPrompt(input.prompt) ? formatAdditionalContextOutput(ULTRAWORK_DIRECTIVE) : "";
+    return isUltraworkPrompt(input.prompt)
+        ? formatAdditionalContextOutput(buildUltraworkAdditionalContext(options))
+        : "";
 }
 function hasUltraworkDirectiveAlreadyInTranscript(transcriptPath) {
     if (transcriptPath === undefined || transcriptPath === null)

package/packages/omo-codex/plugin/components/ulw-loop/dist/ultrawork-skill-pointer.d.ts

@@ -0,0 +1,7 @@
+export declare const ULTRAWORK_SKILL_POINTER_TEMPLATE = "<ultrawork-mode>\nULTRAWORK MODE IS ACTIVE FOR THIS TASK.\n\nMANDATORY BOOTSTRAP: do all three steps, in order, before anything else.\n\n1. First user-visible line this turn MUST be exactly:\n`ULTRAWORK MODE ENABLED!`\n\n2. Call `create_goal` NOW with `objective` set to the user's request.\nSend `objective` only: no `status`, no budget fields. If the\n`create_goal` tool is unavailable, open your reply with a binding\n`# Goal` block instead. Never skip this step.\n\n3. Read the FULL ultrawork directive NOW, before any other tool call,\nplan, or edit. It is the `ultrawork` skill, stored at:\n\n{{ULTRAWORK_SKILL_PATH}}\n\nRead the whole file. If a read result comes back truncated, keep\nreading the remaining line ranges until you have seen every line.\nEvery rule in that file is binding for this entire task: no\ncompromise, no summarizing from memory, no skipping. If the file does\nnot exist, tell the user the omo ultrawork skill is missing and\ncontinue with steps 1 and 2 plus evidence-bound execution.\n\nDo not start the requested work until all three steps are complete.\n</ultrawork-mode>\n";
+export interface UltraworkAdditionalContextOptions {
+    readonly skillFilePath?: string | null;
+}
+export declare function resolveUltraworkSkillFilePath(): string;
+export declare function buildUltraworkSkillPointer(skillFilePath: string): string;
+export declare function buildUltraworkAdditionalContext(options?: UltraworkAdditionalContextOptions): string;

package/packages/omo-codex/plugin/components/ulw-loop/dist/ultrawork-skill-pointer.js

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+export const ULTRAWORK_SKILL_POINTER_TEMPLATE = `<ultrawork-mode>
+ULTRAWORK MODE IS ACTIVE FOR THIS TASK.
+
+MANDATORY BOOTSTRAP: do all three steps, in order, before anything else.
+
+1. First user-visible line this turn MUST be exactly:
+\`ULTRAWORK MODE ENABLED!\`
+
+2. Call \`create_goal\` NOW with \`objective\` set to the user's request.
+Send \`objective\` only: no \`status\`, no budget fields. If the
+\`create_goal\` tool is unavailable, open your reply with a binding
+\`# Goal\` block instead. Never skip this step.
+
+3. Read the FULL ultrawork directive NOW, before any other tool call,
+plan, or edit. It is the \`ultrawork\` skill, stored at:
+
+{{ULTRAWORK_SKILL_PATH}}
+
+Read the whole file. If a read result comes back truncated, keep
+reading the remaining line ranges until you have seen every line.
+Every rule in that file is binding for this entire task: no
+compromise, no summarizing from memory, no skipping. If the file does
+not exist, tell the user the omo ultrawork skill is missing and
+continue with steps 1 and 2 plus evidence-bound execution.
+
+Do not start the requested work until all three steps are complete.
+</ultrawork-mode>
+`;
+const ULTRAWORK_SKILL_PATH_PLACEHOLDER = "{{ULTRAWORK_SKILL_PATH}}";
+const ULTRAWORK_SKILL_FILE_URL = new URL("../../../skills/ultrawork/SKILL.md", import.meta.url);
+const ULTRAWORK_DIRECTIVE = readFileSync(new URL("../directive.md", import.meta.url), "utf8");
+export function resolveUltraworkSkillFilePath() {
+    return fileURLToPath(ULTRAWORK_SKILL_FILE_URL);
+}
+export function buildUltraworkSkillPointer(skillFilePath) {
+    return ULTRAWORK_SKILL_POINTER_TEMPLATE.replace(ULTRAWORK_SKILL_PATH_PLACEHOLDER, skillFilePath);
+}
+export function buildUltraworkAdditionalContext(options = {}) {
+    const skillFilePath = options.skillFilePath === undefined ? resolveUltraworkSkillFilePath() : options.skillFilePath;
+    if (skillFilePath !== null && existsSync(skillFilePath)) {
+        return buildUltraworkSkillPointer(skillFilePath);
+    }
+    return ULTRAWORK_DIRECTIVE;
+}

package/packages/omo-codex/plugin/components/ulw-loop/hooks/hooks.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit --with-ultrawork",
 						"timeout": 10,
-						"statusMessage": "(OmO) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 4.16.1) Checking Ulw-Loop Steering"
 					}
 				]
 			}
@@ -20,7 +20,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
 						"timeout": 5,
-						"statusMessage": "(OmO) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 4.16.1) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			}

package/packages/omo-codex/plugin/components/ulw-loop/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ulw-loop",
-	"version": "4.15.1",
+	"version": "4.16.1",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/SKILL.md

@@ -22,7 +22,7 @@ This skill is intentionally compact. The full workflow lives in `references/full
 - Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
 - After any compaction or context loss, re-read brief + goals + ledger FIRST plus `omo ulw-loop status --json`, then resume; never re-plan from scratch.
 - If `omo ulw-loop create-goals` says the existing aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` instead of steering or forcing the completed default state. Use `--force` only to intentionally overwrite completed evidence.
-- Every success criterion needs observable evidence from a real surface: a channel (tmux, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
+- Every success criterion needs observable evidence from a real surface: a channel (terminal/TUI via the xterm.js web terminal, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
 - Record evidence through the CLI only after cleanup receipts are available.
 - Delegate code edits, test writes, fixes, and QA execution to right-sized Codex subagents when the workflow requires it.
 - Every `multi_agent_v1.spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`; put role and specialty instructions inside `message`; use `fork_context: false` unless full history is truly required.

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/references/full-workflow.md

@@ -19,16 +19,16 @@ Audit each pass, fail, block, steering change, and checkpoint in `.omo/ulw-loop/
 Run each criterion's real-surface proof yourself through the channel that faithfully exercises it; capture the artifact before recording PASS.
 
 1. **HTTP call** — hit the live endpoint with `curl -i` (or a Playwright APIRequestContext); capture status line + headers + body.
-2. **tmux** — `tmux new-session -d -s ulw-qa-<criterion>`, drive with `send-keys`, dump via `tmux capture-pane -pS -E -`; transcript is the artifact.
+2. **Terminal / TUI** - prove it through the xterm.js web terminal; tmux `send-keys` is fine for a boot smoke, but NEVER `tmux capture-pane` for color/layout/CJK evidence (it degrades truecolor).
 3. **Browser use** — in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile. Otherwise use Chrome to drive the REAL page; if unavailable, use agent-browser. Capture action log + screenshot path. Never downgrade a browser-facing criterion.
 4. **Computer use** — for desktop/GUI apps, drive the running app via OS automation (computer-use, AppleScript, xdotool, etc.); capture action log + screenshot.
 
-For TUI visual QA, pair the tmux transcript with a browser-rendered terminal
-screenshot. In this repo run `node script/qa/web-terminal-visual-qa.mjs
---from-file <capture.txt> --evidence-dir <dir>` and record `terminal.png`,
-`terminal.html`, `terminal.txt`, and `metadata.json` as the visual evidence
-bundle. This is mandatory when a PR or review needs to inspect the terminal
-screen, not just the text.
+For TUI visual QA, render the terminal through the real xterm.js web terminal and
+screenshot it - NEVER a `tmux capture-pane` dump (it degrades color and wide-glyph
+width). In this repo run `node script/qa/web-terminal-visual-qa.mjs --command
+"<cmd>" --input "{Enter}" --evidence-dir <dir>` (live pty + xterm.js in Chrome;
+`--from-file` replays a raw stream) and record `terminal.png`, `terminal.txt`, and
+`metadata.json`. Mandatory when a PR or review must inspect the terminal screen.
 
 Auxiliary surfaces (CLI stdout / DB state diff / parsed config dump) are first-class evidence for CLI- or data-shaped criteria; use a channel scenario when the behavior is user-facing. `--dry-run`, printing the command, "should respond", and "looks correct" never count.
 

package/packages/omo-codex/plugin/components/ulw-loop/src/cli-commands.ts

@@ -39,8 +39,8 @@ export async function ulwLoopCommand(argv: readonly string[]): Promise<number> {
 	const rest = argv.slice(1);
 	const repoRoot = process.cwd();
 	const json = hasFlag(rest, "--json");
-	const scope = commandScope(rest);
 	try {
+		const scope = commandScope(rest);
 		if (!isUlwLoopSubcommand(command)) {
 			if (json) {
 				printJsonError(
@@ -94,7 +94,22 @@ function unhandledSubcommand(command: never): never {
 	throw new UlwLoopError(`Unhandled ulw-loop subcommand: ${String(command)}.`, "ULW_LOOP_SUBCOMMAND_UNHANDLED");
 }
 
+const SESSION_ID_FLAG = "--session-id";
+
+function sessionIdFlagPresent(argv: readonly string[]): boolean {
+	return hasFlag(argv, SESSION_ID_FLAG) || argv.some((arg) => arg.startsWith(`${SESSION_ID_FLAG}=`));
+}
+
 function commandScope(argv: readonly string[]): UlwLoopScope | undefined {
-	const sessionId = readValue(argv, "--session-id") ?? resolveUlwLoopSessionIdFromEnv();
+	if (sessionIdFlagPresent(argv)) {
+		const sessionId = readValue(argv, SESSION_ID_FLAG)?.trim();
+		if (!sessionId) {
+			throw new UlwLoopError(`${SESSION_ID_FLAG} requires a non-empty value.`, "ULW_LOOP_SESSION_ID_REQUIRED", {
+				details: { flag: SESSION_ID_FLAG },
+			});
+		}
+		return { sessionId };
+	}
+	const sessionId = resolveUlwLoopSessionIdFromEnv();
 	return sessionId === null ? undefined : { sessionId };
 }

package/packages/omo-codex/plugin/components/ulw-loop/src/cli-steering.ts

@@ -73,7 +73,8 @@ function model(value: string | undefined): UlwLoopSuccessCriterionUserModel | un
 function neverKind(kind: never): never { return fail(`Unsupported steering kind: ${String(kind)}.`, "ULW_LOOP_STEERING_KIND_UNSUPPORTED", { kind }); }
 
 export async function parseSteeringProposal(argv: readonly string[]): Promise<CliSteeringProposal> {
-	const kind = parseSteeringKind(argv); const source = parseSteeringSource(argv); const base = { kind, source, evidence: required(argv, "--evidence"), rationale: required(argv, "--rationale") };
+	const kind = parseSteeringKind(argv); const source = parseSteeringSource(argv); const idempotencyKey = text(readValue(argv, "--idempotency-key"), "--idempotency-key");
+	const base = { kind, source, evidence: required(argv, "--evidence"), rationale: required(argv, "--rationale"), ...(idempotencyKey === undefined ? {} : { idempotencyKey }) };
 	switch (kind) {
 		case "add_subgoal": return normalizeSteeringProposal({ ...base, title: required(argv, "--title"), objective: required(argv, "--objective") });
 		case "split_subgoal": { const goalId = requiredGoal(argv); return normalizeSteeringProposal({ ...base, goalId, targetGoalId: goalId, childGoals: await children(argv, "--children", true) }); }

package/packages/omo-codex/plugin/components/ulw-loop/src/codex-hook.ts

@@ -15,6 +15,7 @@ export interface UserPromptSubmitPayload {
 
 export interface UserPromptSubmitHookOptions {
 	readonly includeUltraworkDirective?: boolean;
+	readonly ultraworkSkillFilePath?: string | null;
 }
 
 export interface PreToolUsePayload {
@@ -74,7 +75,10 @@ export async function applyUserPromptUlwLoopSteering(
 		const proposal = parseUlwLoopSteeringDirective(payload.prompt);
 		if (proposal === null) {
 			if (hasSteeringDirectiveMarker(payload.prompt)) return "";
-			return options.includeUltraworkDirective ? buildUltraworkDirectiveOutput(payload) : "";
+			if (!options.includeUltraworkDirective) return "";
+			return options.ultraworkSkillFilePath === undefined
+				? buildUltraworkDirectiveOutput(payload)
+				: buildUltraworkDirectiveOutput(payload, { skillFilePath: options.ultraworkSkillFilePath });
 		}
 		const result = await steerUlwLoop(payload.cwd, proposal, payloadScope(payload));
 		if (!result.accepted) return "";

package/packages/omo-codex/plugin/components/ulw-loop/src/plan-io.ts

@@ -1,4 +1,6 @@
+import { createReadStream } from "node:fs";
 import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
 
 import { aggregateCodexObjectiveForScope } from "./goal-status.js";
 import {
@@ -14,7 +16,7 @@ import { iso, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER, UlwLoopError } from
 
 const LEGACY_OBJECTIVE_PREFIX = `Complete all ulw-loop stories in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}: `;
 const LEGACY_OBJECTIVE = `Complete all ulw-loop stories listed in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}. Use ${ULW_LOOP_DIR}/${ULW_LOOP_LEDGER} as the durable audit trail.`;
-const locks = new Map<string, Promise<unknown>>();
+const locks = new Map<string, Promise<undefined>>();
 
 function hasCode(error: unknown, code: string): boolean {
 	return error instanceof Error && "code" in error && error.code === code;
@@ -43,12 +45,19 @@ export async function withUlwLoopMutationLock<T>(
 	const fn = typeof scopeOrFn === "function" ? scopeOrFn : maybeFn;
 	if (fn === undefined) throw new UlwLoopError("Missing ulw-loop mutation body.", "ULW_LOOP_LOCK_BODY_MISSING");
 	const lockKey = `${repoRoot}\0${ulwLoopRelativeDir(scope)}`;
-	const prior = locks.get(lockKey) ?? Promise.resolve();
+	const prior = locks.get(lockKey) ?? Promise.resolve(undefined);
 	const run = prior.then(fn, fn);
-	locks.set(
-		lockKey,
-		run.catch(() => undefined),
+	// The stored gate resolves to undefined so the map never retains fn's result
+	// (plans/audits), and it removes itself once no newer waiter replaced it —
+	// otherwise a long-lived host leaks one entry per (repo, scope) forever.
+	const gate: Promise<undefined> = run.then(
+		() => undefined,
+		() => undefined,
 	);
+	locks.set(lockKey, gate);
+	void gate.then(() => {
+		if (locks.get(lockKey) === gate) locks.delete(lockKey);
+	});
 	return run;
 }
 
@@ -107,18 +116,57 @@ export async function appendLedger(repoRoot: string, entry: UlwLoopLedgerEntry,
 	await appendFile(ulwLoopLedgerPath(repoRoot, scope), `${JSON.stringify(entry)}\n`, "utf8");
 }
 
-export async function readSteeringLedgerEntries(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopLedgerEntry[]> {
-	let raw: string;
+/**
+ * Streams raw ledger lines without materializing the file. Real ledgers reach
+ * many MB (legacy entries embedded full-plan snapshots), so `readFile` here
+ * ballooned every steer/dedup path; line-at-a-time keeps memory O(longest line).
+ */
+async function* ledgerLines(repoRoot: string, scope?: UlwLoopScope): AsyncGenerator<string> {
+	const stream = createReadStream(ulwLoopLedgerPath(repoRoot, scope), { encoding: "utf8" });
+	const lines = createInterface({ input: stream, crlfDelay: Number.POSITIVE_INFINITY });
 	try {
-		raw = await readFile(ulwLoopLedgerPath(repoRoot, scope), "utf8");
+		for await (const line of lines) {
+			if (line.trim().length > 0) yield line;
+		}
 	} catch (error) {
-		if (hasCode(error, "ENOENT")) return [];
-		throw error;
+		if (!hasCode(error, "ENOENT")) throw error;
+	} finally {
+		lines.close();
+		stream.destroy();
 	}
+}
+
+export async function readSteeringLedgerEntries(repoRoot: string, scope?: UlwLoopScope): Promise<UlwLoopLedgerEntry[]> {
 	const entries: UlwLoopLedgerEntry[] = [];
-	for (const line of raw.split(/\r?\n/).filter(Boolean)) {
+	for await (const line of ledgerLines(repoRoot, scope)) {
 		const entry: UlwLoopLedgerEntry = JSON.parse(line);
 		if (isSteeringKind(entry.kind)) entries.push(entry);
 	}
 	return entries;
 }
+
+/**
+ * First accepted steering entry matching an idempotency key/prompt signature.
+ * A cheap substring probe on the raw line skips JSON.parse for the vast
+ * majority of entries, so dedup stays flat even on legacy multi-MB ledgers.
+ */
+export async function findAcceptedSteeringLedgerEntry(
+	repoRoot: string,
+	key: string,
+	scope?: UlwLoopScope,
+): Promise<UlwLoopLedgerEntry | undefined> {
+	const probe = JSON.stringify(key);
+	for await (const line of ledgerLines(repoRoot, scope)) {
+		if (!line.includes(probe)) continue;
+		const entry: UlwLoopLedgerEntry = JSON.parse(line);
+		if (!isSteeringKind(entry.kind)) continue;
+		if (entry.steering?.invariant.accepted !== true) continue;
+		if (
+			entry.idempotencyKey === key ||
+			entry.steering.idempotencyKey === key ||
+			entry.steering.promptSignature === key
+		)
+			return entry;
+	}
+	return undefined;
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/steering-snapshot.ts

@@ -0,0 +1,38 @@
+import type { UlwLoopItem, UlwLoopPlan } from "./domain-types.js";
+import type { UlwLoopSteeringPlanSnapshot } from "./steering-types.js";
+
+/**
+ * Compact before/after snapshots for steering ledger entries.
+ *
+ * Ledger entries used to embed the FULL plan (every goal, criterion, and
+ * evidence string) twice per audit and twice more at the entry top level.
+ * That made each accepted steer O(plan size) on disk, so the ledger grew
+ * quadratically over a run, and every dedup scan re-hydrated all of it into
+ * memory. A snapshot instead records plan-level counters plus only the goals
+ * the mutation actually touched, keeping each entry O(changed goals).
+ */
+export function buildSteeringPlanSnapshot(
+	plan: UlwLoopPlan,
+	changedGoalIds: ReadonlySet<string>,
+): UlwLoopSteeringPlanSnapshot {
+	const snapshot: UlwLoopSteeringPlanSnapshot = {
+		updatedAt: plan.updatedAt,
+		goalCount: plan.goals.length,
+		goalIds: plan.goals.map((goal) => goal.id),
+		goals: plan.goals.filter((goal) => changedGoalIds.has(goal.id)),
+	};
+	return plan.activeGoalId === undefined ? snapshot : { ...snapshot, activeGoalId: plan.activeGoalId };
+}
+
+/** Ids of goals that differ between two plans, including added or removed goals. */
+export function changedGoalIdsBetween(before: UlwLoopPlan, after: UlwLoopPlan): Set<string> {
+	const beforeById = new Map<string, UlwLoopItem>(before.goals.map((goal) => [goal.id, goal]));
+	const changed = new Set<string>();
+	for (const goal of after.goals) {
+		const prior = beforeById.get(goal.id);
+		if (prior === undefined || JSON.stringify(prior) !== JSON.stringify(goal)) changed.add(goal.id);
+		beforeById.delete(goal.id);
+	}
+	for (const id of beforeById.keys()) changed.add(id);
+	return changed;
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/steering-types.ts

@@ -1,5 +1,5 @@
 import type { UlwLoopSteeringMutationKind, UlwLoopSteeringSource } from "./constants.js";
-import type { UlwLoopPlan } from "./domain-types.js";
+import type { UlwLoopItem, UlwLoopPlan } from "./domain-types.js";
 
 export interface UlwLoopSteeringInvariantResult {
 	accepted: boolean;
@@ -44,13 +44,21 @@ export interface UlwLoopSteeringProposal {
 	now?: Date;
 }
 
+export interface UlwLoopSteeringPlanSnapshot {
+	readonly updatedAt: string;
+	readonly activeGoalId?: string;
+	readonly goalCount: number;
+	readonly goalIds: readonly string[];
+	readonly goals: readonly UlwLoopItem[];
+}
+
 export interface UlwLoopSteeringAudit {
 	kind: UlwLoopSteeringMutationKind;
 	source: UlwLoopSteeringSource;
 	targetGoalIds: string[];
 	criterionId?: string;
-	before?: unknown;
-	after?: unknown;
+	before?: UlwLoopSteeringPlanSnapshot;
+	after?: UlwLoopSteeringPlanSnapshot;
 	evidence: string;
 	rationale: string;
 	invariant: UlwLoopSteeringInvariantResult;