oh-my-opencode 4.15.1 → 4.16.1

package/packages/omo-codex/plugin/components/ultrawork/src/skill-pointer.ts

@@ -0,0 +1,56 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { ULTRAWORK_DIRECTIVE } from "./directive.js";
+
+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);
+
+export interface UltraworkAdditionalContextOptions {
+	readonly skillFilePath?: string | null;
+}
+
+export function resolveUltraworkSkillFilePath(): string {
+	return fileURLToPath(ULTRAWORK_SKILL_FILE_URL);
+}
+
+export function buildUltraworkSkillPointer(skillFilePath: string): string {
+	return ULTRAWORK_SKILL_POINTER_TEMPLATE.replace(ULTRAWORK_SKILL_PATH_PLACEHOLDER, skillFilePath);
+}
+
+export function buildUltraworkAdditionalContext(options: UltraworkAdditionalContextOptions = {}): string {
+	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/ultrawork/test/codex-hook.test.ts

@@ -183,14 +183,14 @@ describe("codex ultrawork hook", () => {
 		};
 
 		// when
-		const output = runUserPromptSubmitHook(payload);
+		const output = runUserPromptSubmitHook(payload, { skillFilePath: null });
 		const parsed = parseHookOutput(output);
 
 		// then
 		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/# Manual-QA channels/);
 		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/TESTS ALONE NEVER PROVE DONE/);
 		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/1\. HTTP call/);
-		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/2\. tmux/);
+		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/2\. Terminal \/ TUI/);
 		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/3\. Browser use/);
 		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/4\. Computer use/);
 		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/CLEANUP \(PAIRED/);
@@ -209,7 +209,7 @@ describe("codex ultrawork hook", () => {
 		};
 
 		// when
-		const output = runUserPromptSubmitHook(payload);
+		const output = runUserPromptSubmitHook(payload, { skillFilePath: null });
 		const parsed = parseHookOutput(output);
 
 		// then
@@ -230,7 +230,7 @@ describe("codex ultrawork hook", () => {
 		};
 
 		// when
-		const output = runUserPromptSubmitHook(payload);
+		const output = runUserPromptSubmitHook(payload, { skillFilePath: null });
 		const parsed = parseHookOutput(output);
 
 		// then
@@ -244,6 +244,27 @@ describe("codex ultrawork hook", () => {
 		expect(directive).toMatch(/WORKING:/);
 	});
 
+	it("#given directive #when inspected #then blocks dependent work until spawned planners finish", () => {
+		// given
+		const payload = {
+			hook_event_name: "UserPromptSubmit",
+			prompt: "ulw",
+		};
+
+		// when
+		const output = runUserPromptSubmitHook(payload, { skillFilePath: null });
+		const parsed = parseHookOutput(output);
+
+		// then
+		const directive = parsed.hookSpecificOutput.additionalContext;
+		expect(directive).toMatch(/Subagent-dependent transition barrier/);
+		expect(directive).toMatch(/Spawn every independent child for the current wave first/);
+		expect(directive).toMatch(/After the wave\s+is launched[\s\S]{0,240}wait_agent[\s\S]{0,240}terminal status/);
+		expect(directive).not.toMatch(/Immediately after any `multi_agent_v1\.spawn_agent`/);
+		expect(directive).toMatch(/Do not start dependent implementation/);
+		expect(directive).toMatch(/Do not mark an `update_plan` step `completed`/);
+	});
+
 	it("#given directive #when inspected #then keeps impact-proportional sizing invariants", () => {
 		// given
 		const payload = {
@@ -252,7 +273,7 @@ describe("codex ultrawork hook", () => {
 		};
 
 		// when
-		const output = runUserPromptSubmitHook(payload);
+		const output = runUserPromptSubmitHook(payload, { skillFilePath: null });
 		const parsed = parseHookOutput(output);
 
 		// then

package/packages/omo-codex/plugin/components/ultrawork/test/directive-source.test.ts

@@ -13,4 +13,16 @@ describe("codex ultrawork directive source", () => {
 		// then
 		expect(codexPrompt).toBe(directive);
 	});
+
+	it("#given bundled ultrawork skill #when compared to the directive #then it wraps the same bytes with skill frontmatter", () => {
+		// given
+		const directive = readFileSync("directive.md", "utf8");
+
+		// when
+		const skill = readFileSync("skills/ultrawork/SKILL.md", "utf8");
+
+		// then
+		expect(skill.startsWith("---\nname: ultrawork\n")).toBe(true);
+		expect(skill.endsWith(directive)).toBe(true);
+	});
 });

package/packages/omo-codex/plugin/components/ultrawork/test/package-smoke.test.ts

@@ -31,6 +31,7 @@ describe("codex ultrawork package metadata", () => {
 		expect(scripts["test"]).toBe("vitest --run");
 		expect(packageFiles).toContain("dist");
 		expect(packageFiles).toContain("directive.md");
+		expect(packageFiles).toContain("skills");
 		expect(packageFiles).not.toContain("hooks/ultrawork-detector.py");
 		expect(cliSource.startsWith("#!/usr/bin/env node")).toBe(true);
 		expect(hookCommands).toContain(`node "${pluginRoot}/dist/cli.js" hook user-prompt-submit`);

package/packages/omo-codex/plugin/components/ultrawork/test/skill-pointer.test.ts

@@ -0,0 +1,82 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { runUserPromptSubmitHook } from "../src/codex-hook.js";
+import { ULTRAWORK_DIRECTIVE } from "../src/directive.js";
+import { buildUltraworkAdditionalContext, buildUltraworkSkillPointer } from "../src/skill-pointer.js";
+import { parseHookOutput } from "./codex-hook-test-helpers.js";
+
+const POINTER_MAX_BYTES = 4096;
+const tempDirectories: string[] = [];
+
+function makeTempDirectory(): string {
+	const directory = mkdtempSync(join(tmpdir(), "ultrawork-skill-"));
+	tempDirectories.push(directory);
+	return directory;
+}
+
+function writeSkillFile(): string {
+	const skillFilePath = join(makeTempDirectory(), "SKILL.md");
+	writeFileSync(skillFilePath, "---\nname: ultrawork\n---\n\n<ultrawork-mode>\ndirective body\n</ultrawork-mode>\n");
+	return skillFilePath;
+}
+
+afterEach(() => {
+	for (const directory of tempDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true });
+	}
+});
+
+describe("ultrawork skill pointer", () => {
+	it("#given an existing skill file #when context is built #then emits the compact pointer with the absolute path", () => {
+		// given
+		const skillFilePath = writeSkillFile();
+
+		// when
+		const context = buildUltraworkAdditionalContext({ skillFilePath });
+
+		// then
+		expect(context).toBe(buildUltraworkSkillPointer(skillFilePath));
+		expect(context.startsWith("<ultrawork-mode>")).toBe(true);
+		expect(context).toContain(skillFilePath);
+		expect(context).toContain("First user-visible line this turn MUST be exactly:");
+		expect(context).toContain("create_goal");
+		expect(context).not.toContain("Tier triage");
+		expect(Buffer.byteLength(context, "utf8")).toBeLessThan(POINTER_MAX_BYTES);
+	});
+
+	it("#given a missing skill file #when context is built #then falls back to the full directive", () => {
+		// given
+		const missingSkillFilePath = join(makeTempDirectory(), "SKILL.md");
+
+		// when
+		const context = buildUltraworkAdditionalContext({ skillFilePath: missingSkillFilePath });
+
+		// then
+		expect(context).toBe(ULTRAWORK_DIRECTIVE);
+	});
+
+	it("#given a null skill path #when context is built #then falls back to the full directive", () => {
+		expect(buildUltraworkAdditionalContext({ skillFilePath: null })).toBe(ULTRAWORK_DIRECTIVE);
+	});
+
+	it("#given the hook runs with a skill file #when prompt is ulw #then hook JSON carries the pointer", () => {
+		// given
+		const skillFilePath = writeSkillFile();
+
+		// when
+		const output = runUserPromptSubmitHook(
+			{ hook_event_name: "UserPromptSubmit", prompt: "ulw this change" },
+			{ skillFilePath },
+		);
+		const parsed = parseHookOutput(output);
+
+		// then
+		expect(parsed.hookSpecificOutput.hookEventName).toBe("UserPromptSubmit");
+		expect(parsed.hookSpecificOutput.additionalContext).toMatch(/^<ultrawork-mode>/);
+		expect(parsed.hookSpecificOutput.additionalContext).toContain(skillFilePath);
+	});
+});

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

@@ -2,6 +2,11 @@
 
 ## [0.1.0] - unreleased
 
+- **Memory:** steering ledger entries no longer embed the full plan four times (`before`/`after` at both the audit and entry level). Accepted steers now record a compact `UlwLoopSteeringPlanSnapshot` (plan counters + only the goals the mutation touched), shrinking a measured real-world entry from 189KB to 7.8KB (~24x) and ending quadratic `ledger.jsonl` growth over long runs.
+- **Memory:** steering dedup (`--idempotency-key` / `promptSignature`) streams the ledger line-by-line with a substring pre-filter instead of `JSON.parse`-ing every entry into memory; dedup returns strip legacy full-plan `before`/`after` payloads from re-surfaced audits. `readSteeringLedgerEntries` streams too.
+- **Memory:** `withUlwLoopMutationLock` no longer retains the mutation result (full plan/audit) per `(repo, scope)` in its module-level lock map; settled gates self-evict, so long-lived embedders stop accumulating entries.
+- **Fix:** `omo ulw-loop steer --idempotency-key` was parsed but never forwarded into the proposal, so CLI steers never deduped. It is now wired through.
+- Standalone ultrawork injection (`--with-ultrawork`) now emits the same compact bootstrap pointer as the ultrawork component (opener mandate, `create_goal` with `objective` only, read the bundled `ultrawork` skill at a runtime-resolved absolute path), falling back to the full bundled directive when the plugin skills tree is absent. Keeps the injected payload below Codex App's hook-output truncation budget (code-yeongyu/oh-my-openagent#5828).
 - Initial scaffold of codex-ulw-loop plugin.
 - Per-Criterion Cycle: `EXECUTE` is now **EXECUTE-AS-SCENARIO** — the agent must run the Manual-QA channel scenario the criterion named (HTTP call / tmux / browser use / computer use; see new `## Manual-QA channels` section). Inserted a new **CLEAN (PAIRED, NEVER SKIP)** step that tears down every QA-spawned process / `tmux` session / browser context / container / port / temp dir before recording evidence; the cleanup receipt is embedded in the `--evidence` string. Missing receipt → record BLOCKED, not PASS. Added Constraint #13 and a Stop Rule for leftover state.
 - New top-level **`## Manual-QA channels`** section explicitly enumerates the four channels (HTTP call, tmux, Browser use, Computer use) with concrete commands and required artifacts. Goal section now declares **TESTS ALONE NEVER PROVE DONE**: a green test suite is supporting evidence, never completion proof. Criterion-refinement step 2 requires each criterion to name its channel up front.

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

@@ -49,9 +49,10 @@ exercises the surface; capture the artifact.
   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 - drive a real pty and prove it through the
+     xterm.js web terminal (see the TUI visual QA note below). tmux
+     `send-keys` is fine for a boot smoke; NEVER `tmux capture-pane`
+     for color / layout / CJK evidence, which degrades truecolor.
   3. Browser use — in Codex, use `browser:control-in-app-browser`
      first when available and no authenticated/persistent user browser
      profile is required. Otherwise use Chrome to drive the REAL page;
@@ -79,13 +80,13 @@ channel scenario when the behavior is user-facing. `--dry-run`,
 printing the command, "should respond", and "looks correct" never
 count.
 
-For TUI visual QA, terminal transcripts alone are not enough when a
-visual surface is being evaluated. In this repo, prefer
-`node script/qa/web-terminal-visual-qa.mjs --title "<surface>" --from-file <capture.txt> --evidence-dir <dir>`
-or the helper's `--command` tmux-backed PTY connector when available.
-Outside this repo, capture equivalent browser/computer-use rendered
-terminal evidence: screenshot, plain transcript, rendered HTML or action
-log, and cleanup receipt.
+For TUI visual QA, render the terminal through the real xterm.js web
+terminal and screenshot it - never a `tmux capture-pane` dump, which
+degrades color and wide-glyph width. In this repo:
+`node script/qa/web-terminal-visual-qa.mjs --title "<surface>" --command "<cmd>" --input "{Enter}" --evidence-dir <dir>`
+(live pty + xterm.js in Chrome; `--from-file <capture>` replays a raw
+stream). Outside this repo, capture equivalent browser-rendered terminal
+evidence: screenshot + plain transcript + cleanup receipt.
 
 # Bootstrap (DO ALL FOUR BEFORE ANY OTHER WORK — NO SKIPPING)
 
@@ -287,6 +288,13 @@ evidence for that step. Do not start dependent implementation until the
 audit, research, or review result is integrated or explicitly recorded
 as inconclusive. Do not generate a plan before spawned research lanes
 that feed the plan have returned or been closed as inconclusive.
+Spawn every independent child for the current wave first. After the wave
+is launched, run `multi_agent_v1.wait_agent` for each spawned child until
+each reaches terminal status (`completed`, `failed`, `blocked`, or
+explicitly recorded inconclusive) before any dependent `update_plan`
+transition, `create_goal` continuation, implementation tool call, plan
+drafting, approval-gate work, PR handoff, or final response. A timeout is
+not terminal status.
 Do not write the final answer, PR handoff, or completion summary while
 active child agents remain open. Use short `multi_agent_v1.wait_agent` cycles.
 After two silent waits send `TASK STILL ACTIVE: return <deliverable> or

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

@@ -24,8 +24,8 @@ export async function ulwLoopCommand(argv) {
     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(new UlwLoopError(`Unknown ulw-loop subcommand: ${command}.`, "ULW_LOOP_SUBCOMMAND_UNKNOWN", {
@@ -79,7 +79,20 @@ export async function ulwLoopCommand(argv) {
 function unhandledSubcommand(command) {
     throw new UlwLoopError(`Unhandled ulw-loop subcommand: ${String(command)}.`, "ULW_LOOP_SUBCOMMAND_UNHANDLED");
 }
+const SESSION_ID_FLAG = "--session-id";
+function sessionIdFlagPresent(argv) {
+    return hasFlag(argv, SESSION_ID_FLAG) || argv.some((arg) => arg.startsWith(`${SESSION_ID_FLAG}=`));
+}
 function commandScope(argv) {
-    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/dist/cli-steering.js

@@ -83,7 +83,8 @@ function neverKind(kind) { return fail(`Unsupported steering kind: ${String(kind
 export async function parseSteeringProposal(argv) {
     const kind = parseSteeringKind(argv);
     const source = parseSteeringSource(argv);
-    const base = { kind, source, evidence: required(argv, "--evidence"), rationale: required(argv, "--rationale") };
+    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": {

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

@@ -521,7 +521,9 @@ function formatCodexGoalReconciliation(reconciliation) {
 }
 
 // components/ulw-loop/src/plan-io.ts
+import { createReadStream } from "node:fs";
 import { appendFile, mkdir, readFile as readFile4, rename, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
 var LEGACY_OBJECTIVE_PREFIX = `Complete all ulw-loop stories in ${ULW_LOOP_DIR}/${ULW_LOOP_GOALS}: `;
 var 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.`;
 var locks = new Map;
@@ -540,11 +542,18 @@ 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}\x00${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(() => {
+  const gate = run.then(() => {
     return;
-  }));
+  }, () => {
+    return;
+  });
+  locks.set(lockKey, gate);
+  gate.then(() => {
+    if (locks.get(lockKey) === gate)
+      locks.delete(lockKey);
+  });
   return run;
 }
 async function readUlwLoopPlan(repoRoot, scope) {
@@ -591,22 +600,36 @@ async function appendLedger(repoRoot, entry, scope) {
   await appendFile(ulwLoopLedgerPath(repoRoot, scope), `${JSON.stringify(entry)}
 `, "utf8");
 }
-async function readSteeringLedgerEntries(repoRoot, scope) {
-  let raw;
+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 readFile4(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();
   }
-  const entries = [];
-  for (const line of raw.split(/\r?\n/).filter(Boolean)) {
+}
+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))
-      entries.push(entry);
+    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 entries;
+  return;
 }
 
 // components/ulw-loop/src/evidence.ts
@@ -1254,7 +1277,8 @@ function neverKind(kind) {
 async function parseSteeringProposal(argv) {
   const kind = parseSteeringKind(argv);
   const source = parseSteeringSource(argv);
-  const base = { kind, source, evidence: required2(argv, "--evidence"), rationale: required2(argv, "--rationale") };
+  const idempotencyKey = text(readValue(argv, "--idempotency-key"), "--idempotency-key");
+  const base = { kind, source, evidence: required2(argv, "--evidence"), rationale: required2(argv, "--rationale"), ...idempotencyKey === undefined ? {} : { idempotencyKey } };
   switch (kind) {
     case "add_subgoal":
       return normalizeSteeringProposal({ ...base, title: required2(argv, "--title"), objective: required2(argv, "--objective") });
@@ -1725,6 +1749,30 @@ async function recordFinalReviewBlockers(repoRoot, args, scope) {
   });
 }
 
+// components/ulw-loop/src/steering-snapshot.ts
+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 };
+}
+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;
+}
+
 // components/ulw-loop/src/steering.ts
 var SOURCES2 = ["user_prompt_submit", "finding", "cli"];
 var PROTECTED = new Set(["aggregateCompletion", "codexObjective", "codexObjectiveAliases", "originalConstraints", "qualityGate", "status", "completedAt", "completionStatus"]);
@@ -1982,15 +2030,20 @@ 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) {
+      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);
@@ -2006,10 +2059,6 @@ 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;
 }
 
@@ -2205,8 +2254,8 @@ async function ulwLoopCommand(argv) {
   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(new UlwLoopError(`Unknown ulw-loop subcommand: ${command}.`, "ULW_LOOP_SUBCOMMAND_UNKNOWN", {
@@ -2264,14 +2313,76 @@ async function ulwLoopCommand(argv) {
 function unhandledSubcommand(command) {
   throw new UlwLoopError(`Unhandled ulw-loop subcommand: ${String(command)}.`, "ULW_LOOP_SUBCOMMAND_UNHANDLED");
 }
+var SESSION_ID_FLAG = "--session-id";
+function sessionIdFlagPresent(argv) {
+  return hasFlag(argv, SESSION_ID_FLAG) || argv.some((arg) => arg.startsWith(`${SESSION_ID_FLAG}=`));
+}
 function commandScope(argv) {
-  const sessionId = readValue(argv, "--session-id") ?? resolveUlwLoopSessionIdFromEnv();
+  if (sessionIdFlagPresent(argv)) {
+    const sessionId2 = readValue(argv, SESSION_ID_FLAG)?.trim();
+    if (!sessionId2) {
+      throw new UlwLoopError(`${SESSION_ID_FLAG} requires a non-empty value.`, "ULW_LOOP_SESSION_ID_REQUIRED", {
+        details: { flag: SESSION_ID_FLAG }
+      });
+    }
+    return { sessionId: sessionId2 };
+  }
+  const sessionId = resolveUlwLoopSessionIdFromEnv();
   return sessionId === null ? undefined : { sessionId };
 }
 
 // components/ulw-loop/src/ultrawork-directive.ts
-import { readFileSync } from "node:fs";
+import { readFileSync as readFileSync2 } from "node:fs";
+
+// components/ulw-loop/src/ultrawork-skill-pointer.ts
+import { existsSync as existsSync5, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+var 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>
+`;
+var ULTRAWORK_SKILL_PATH_PLACEHOLDER = "{{ULTRAWORK_SKILL_PATH}}";
+var ULTRAWORK_SKILL_FILE_URL = new URL("../../../skills/ultrawork/SKILL.md", import.meta.url);
 var ULTRAWORK_DIRECTIVE = readFileSync(new URL("../directive.md", import.meta.url), "utf8");
+function resolveUltraworkSkillFilePath() {
+  return fileURLToPath(ULTRAWORK_SKILL_FILE_URL);
+}
+function buildUltraworkSkillPointer(skillFilePath) {
+  return ULTRAWORK_SKILL_POINTER_TEMPLATE.replace(ULTRAWORK_SKILL_PATH_PLACEHOLDER, skillFilePath);
+}
+function buildUltraworkAdditionalContext(options = {}) {
+  const skillFilePath = options.skillFilePath === undefined ? resolveUltraworkSkillFilePath() : options.skillFilePath;
+  if (skillFilePath !== null && existsSync5(skillFilePath)) {
+    return buildUltraworkSkillPointer(skillFilePath);
+  }
+  return ULTRAWORK_DIRECTIVE;
+}
+
+// components/ulw-loop/src/ultrawork-directive.ts
 var ULTRAWORK_CURRENT_PROMPT_PATTERN = /(?:ultrawork|ulw)/i;
 var ULTRAWORK_DIRECTIVE_MARKER = "<ultrawork-mode>";
 var TRANSCRIPT_SEARCH_BYTES = 512000;
@@ -2284,14 +2395,14 @@ var CONTEXT_PRESSURE_MARKERS = [
   "your input exceeds the context window",
   "long threads and multiple compactions"
 ];
-function buildUltraworkDirectiveOutput(input) {
+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)
@@ -2319,7 +2430,7 @@ function hasUltraworkDirectiveAlreadyInTranscript(transcriptPath) {
   return false;
 }
 function readTranscriptTail(transcriptPath) {
-  const rawTranscript = readFileSync(transcriptPath);
+  const rawTranscript = readFileSync2(transcriptPath);
   return rawTranscript.subarray(Math.max(0, rawTranscript.byteLength - TRANSCRIPT_SEARCH_BYTES)).toString("utf8");
 }
 function isUltraworkPrompt(prompt) {
@@ -2409,7 +2520,9 @@ async function applyUserPromptUlwLoopSteering(payload, options = {}) {
     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)

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

@@ -10,6 +10,7 @@ export interface UserPromptSubmitPayload {
 }
 export interface UserPromptSubmitHookOptions {
     readonly includeUltraworkDirective?: boolean;
+    readonly ultraworkSkillFilePath?: string | null;
 }
 export interface PreToolUsePayload {
     readonly cwd: string;

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

@@ -36,7 +36,11 @@ export async function applyUserPromptUlwLoopSteering(payload, options = {}) {
         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)