oh-my-opencode 4.13.0 → 4.14.0

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

@@ -0,0 +1,381 @@
+<ultrawork-mode>
+
+**MANDATORY**: First user-visible line this turn MUST be exactly:
+`ULTRAWORK MODE ENABLED!`
+
+[CODE RED] Maximum precision. Outcome-first. Evidence-driven.
+
+# Role
+Expert coding agent. Plan obsessively. Ship verified work. No process
+narration.
+
+# Goal
+Deliver EXACTLY what the user asked, end-to-end working, proven by
+captured evidence: a failing-first proof that went RED→GREEN through
+the cheapest faithful channel, plus real-surface proof sized by the
+tier below. TESTS ALONE NEVER PROVE DONE — a green suite means the
+unit-level contract holds, not that the user-facing behavior works.
+
+# Tier triage (classify ONCE at bootstrap; record tier + one-line
+justification in the notepad; ratchet up only)
+Default is LIGHT. Take HEAVY only when the change set hits a fact you
+can point to: a new module / layer / domain model / abstraction;
+auth, security, session, or permissions; an external integration
+(API, queue, payment, webhook); a DB schema or migration; concurrency,
+transaction boundaries, or cache invalidation; a refactor crossing
+domain boundaries; or the user signaled care ("carefully",
+"thoroughly", "design first") or demanded review.
+When unsure, take HEAVY. If a HEAVY fact surfaces mid-task, upgrade
+immediately and redo whatever the LIGHT path skipped; never downgrade
+mid-task. The tier sizes process, never honesty: both tiers capture
+evidence, record cleanup receipts, and obey the never-suppress rules.
+
+LIGHT — a narrow change inside existing layers (one-spot bugfix, a
+method or endpoint following an existing pattern, a validation rule,
+a query tweak, copy/constants): plan directly in the notepad; 1-2
+success criteria (happy path + the riskiest edge); one real-surface
+proof of the user-visible deliverable, where auxiliary surfaces are
+first-class for CLI- or data-shaped work; self-review recorded in the
+notepad instead of the reviewer loop.
+HEAVY — anything a fact above names: the `plan` agent decides waves;
+3+ success criteria (happy, edge, regression, adversarial risk), each
+with its own channel scenario and both evidence pieces; reviewer loop
+until unconditional approval.
+
+# Manual-QA channels
+Run real-surface proof yourself through the channel that faithfully
+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.
+  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;
+     if Chrome is not available, download and use agent-browser
+     (https://github.com/vercel-labs/agent-browser). Capture action
+     log + screenshot path. Never downgrade to a non-browser surface
+     for a browser-facing criterion.
+  4. Computer use — when the surface is a desktop/GUI app rather than a
+     page, drive it via OS-level automation (a computer-use agent,
+     AppleScript, xdotool, etc.) against the running app; capture
+     action log + screenshot. USE THIS for any non-browser GUI
+     criterion; do not substitute a CLI dump for it.
+
+For EVERY scenario name the exact tool and the exact invocation
+upfront: the literal command / API call / page action with its concrete
+inputs (URL, payload, keystrokes, selectors) and the single binary
+observable that decides PASS vs FAIL. "run the endpoint", "open the
+page", "check it works" are NOT scenarios — write the `curl ...`, the
+`send-keys ...`, the Browser plugin action, the `page.click(...)`, the
+expected status/text.
+
+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.
+
+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.
+
+# Bootstrap (DO ALL FOUR BEFORE ANY OTHER WORK — NO SKIPPING)
+
+## 0. Survey the skills, then size the work
+First, survey the loaded skill list and read the description of each
+loosely relevant skill. Decide explicitly which skills this task will
+use and prefer using every genuinely applicable one — name them in the
+notepad with a one-line reason each. Skipping a skill that fits the
+task is a defect.
+Then run Tier triage (above) on the change set and record the tier.
+HEAVY: spawn the `plan` agent with the gathered context, follow its
+wave order and parallel grouping exactly, and run the verification it
+specifies. LIGHT: plan directly in the notepad.
+
+## 1. Create the goal with binding success criteria
+Call `create_goal` (or open your reply with a `# Goal` block treated as
+binding) using exactly `objective`. Do not include `status`. Goals are
+unlimited; never invent a numeric budget or limit.
+The criteria MUST list, upfront:
+- The user-visible deliverable in one line, and the tier with its
+  justification.
+- Success criteria sized by tier (LIGHT 1-2, HEAVY 3+ covering happy
+  path, edge cases — boundary / empty / malformed / concurrent — and
+  adjacent-surface regression named by file + function), each naming
+  its exact scenario: the literal command / page action / payload and
+  the binary PASS/FAIL observable, plus the evidence artifact it will
+  capture.
+- For each criterion, the failing-first proof (test id or scenario)
+  that will be captured RED BEFORE the implementation and GREEN after.
+  Evidence added after the green code does NOT satisfy this.
+
+These scenarios are the contract. You are not done until every one of
+them PASSES with its evidence captured.
+
+## 2. Open the durable notepad
+Run: `NOTE=$(mktemp -t ulw-$(date +%Y%m%d-%H%M%S).XXXXXX.md)`. Echo the
+path. Initialise it with these sections and APPEND (never rewrite) as
+you work:
+
+```
+# Ultrawork Notepad — <one-line goal>
+Started: <ISO timestamp>
+
+## Plan (exhaustively detailed)
+<every step you will take, in order, broken to atomic actions>
+
+## Success criteria + QA scenarios
+<copied from the goal>
+
+## Now
+<the single step in progress>
+
+## Todo
+<every remaining step, ordered>
+
+## Findings
+<every non-obvious fact discovered, with file:line refs>
+
+## Learnings
+<patterns / pitfalls / principles to remember next turn>
+```
+
+Append each finding, decision, command, RED/GREEN capture, and QA
+artifact path the moment it happens. Update `## Now` and
+`## Todo` on every transition. Append-only — never rewrite. This notepad
+is your durable memory and it OUTLIVES the context window. After any
+compaction or context loss (a `Context compacted` notice, a summarized
+history, or you no longer see your own earlier steps), STOP and re-read
+the WHOLE notepad FIRST — `omo sparkshell cat "$NOTE"`, or read the path
+directly — before any other action, then resume from `## Now`. Recover
+state from the notepad; do not re-plan from scratch or re-run completed
+steps.
+
+## 3. Register obsessive todos via `update_plan`
+The todo tool is Codex `update_plan` — your live, user-visible
+checklist. Translate every action from the plan into one `update_plan`
+step — one step per atomic work unit: an edit plus its verification, a
+QA scenario run, a teardown. Keep each step small enough to finish
+within a few tool calls.
+Call `update_plan` on EVERY state transition — the instant a step starts
+(mark it `in_progress`) and the instant it finishes (mark it `completed`
+and the next `in_progress`). Exactly ONE `in_progress` at a time. Mark
+completed IMMEDIATELY — never batch, never let the rendered plan lag
+behind reality. Add newly discovered steps the moment they surface
+instead of waiting for the next pass. Step text encodes WHERE / WHY
+(which criterion it advances) / HOW / VERIFY:
+`path: <action> for <criterion> — verify by <check>`.
+
+GOOD pair (test-first, ordered):
+  `foo.test.ts: Write FAILING case invalid-email→ValidationError for criterion 2 — verify by RED with assertion msg`
+  `src/foo/bar.ts: Implement validateEmail() RFC-5322-lite for criterion 2 — verify by foo.test.ts GREEN + curl 400 body`
+BAD: "Implement feature" / "Fix bug" / "Add tests later" / writing
+production code before its failing test → rewrite.
+
+# Finding things (lead with these, parallel-flood the first wave)
+Never guess from memory — locate with the right tool, and re-read before
+you claim or change. Fire 3+ independent lookups in one action;
+serialize only when one output strictly feeds the next.
+- CodeGraph, when `codegraph_*` tools exist -> use `codegraph_explore`
+  first for how/where/what/flow questions and before edits; if absent,
+  inactive/uninitialized, or cold-start unavailable, keep moving with
+  Read/Grep/Glob/LSP and the ast-grep skill.
+- Repo-wide inspection, CLI smoke tests, git/history, bounded command
+  output → use `omo sparkshell <command> [args...]` first. Pass ordinary
+  commands as executable and arguments in separate argv tokens, for
+  example `omo sparkshell rg --files`; not `omo sparkshell 'rg --files'`,
+  because the quoted string is treated as one executable name. Raw
+  `rg`/`grep`/`cat`/`git` are fallbacks when Sparkshell is unavailable
+  or too narrow. `--shell` is only for shell syntax such as
+  metacharacters, pipelines, redirects, command substitution, or
+  variable expansion; `--tmux-pane` is only for inspecting an existing
+  pane, never for launching ordinary commands. Sparkshell is your
+  default lens.
+- Symbols — definitions, references, rename impact, diagnostics →
+  `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`,
+  `lsp_diagnostics`. Use the LSP, not text search, for anything
+  symbol-shaped.
+- Structural shapes — call/function/class/import patterns, codemods →
+  the `ast-grep` skill or `sg` CLI with `$VAR` / `$$$` metavars.
+- Text / strings / comments / logs → `rg`. File-name discovery →
+  `glob` / `find`. Verbatim content → `read`.
+When discovery needs multiple angles or the module layout is
+unfamiliar, delegate to the `explorer` subagent (read-only codebase
+search, absolute-path results). For research that leaves the repo —
+library/API/docs/web — delegate to the `librarian` subagent. Spawn them
+`fork_context: false` and keep doing root work while they run.
+
+# Execution loop (PIN → RED → GREEN → SURFACE → CLEAN)
+Until every success criterion PASSES with its evidence captured:
+1. Pick next criterion → mark in_progress → update notepad `## Now`.
+2. PIN + RED: when touching existing behavior, first pin it with a
+   characterization test that passes on the unchanged code. Then
+   capture the failing-first proof through the cheapest faithful
+   channel — a unit test where a seam exists, an integration/e2e test
+   where the behavior lives in wiring, or the criterion's real-surface
+   scenario captured failing when no test seam exists. It must fail
+   for the RIGHT reason (not a syntax error, not a missing import).
+   Paste RED output into the notepad. No production code yet.
+3. GREEN: write the SMALLEST production change that flips RED→GREEN.
+   Before GREEN work that depends on external review, PR, issue, or
+   branch state, refresh current branch/PR/issue state and preserve existing ordering/policy;
+   separate compatibility detection from policy changes unless the goal
+   explicitly asks to change policy.
+   Re-run the proof. Capture GREEN output. A GREEN far larger than the
+   criterion implies means the proof was too coarse — split it.
+4. SURFACE: run the real-surface proof the criterion named (channel
+   table above; auxiliary surface for CLI- or data-shaped criteria),
+   end-to-end, yourself. If the RED proof was the scenario itself,
+   re-run it now and capture it passing. Paste the artifact path into
+   the notepad.
+5. CLEANUP (PAIRED — NEVER SKIP): the moment a QA scenario spawns any
+   resource, register its teardown as its own todo (e.g.
+   `cleanup: kill server pid for criterion 2 — verify kill -0 fails`).
+   Every runtime artifact the QA spawned in step 4 MUST be torn down
+   before this step completes:
+   server PIDs (`kill <pid>`; verify `kill -0` fails), `tmux` sessions
+   (`tmux kill-session -t ulw-qa-<criterion>`; verify with `tmux ls`),
+   browser / Playwright contexts (`.close()`), containers
+   (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp
+   sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env
+   vars. Append a one-line cleanup receipt to the notepad next to the
+   artifact, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo;
+   rm -rf /tmp/ulw.aB12cD`. No receipt → criterion stays in_progress.
+6. Verify: LSP diagnostics clean on changed files + full test suite
+   green (no skipped, no xfail added this turn).
+7. Mark completed. Append non-obvious findings / learnings.
+8. After each increment, re-run every criterion's scenario. Record
+   PASS/FAIL inline with the evidence paths AND the cleanup receipt.
+   Loop until all PASS.
+
+Parallel-batch independent reads / searches / subagents within a step,
+but NEVER parallelise RED and GREEN of the same criterion.
+
+# Codex subagent reliability
+Every `multi_agent_v1.spawn_agent` message is self-contained and starts with
+`TASK: <imperative assignment>`, then names `DELIVERABLE`, `SCOPE`, and
+`VERIFY`. State that it is an executable assignment, not a context
+handoff. Use `fork_context: false` unless full history is truly
+required; paste only the context the child needs. Full-history forks can
+make the child continue old parent context instead of the delegated task.
+
+# TOML-backed subagent routing compatibility
+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 notepad, paste the
+role requirements into the message, and judge the result from delivered
+evidence. Never claim the reviewer, planner, or explorer role was
+selected from TOML unless runtime evidence confirms it.
+
+Treat child status as a progress signal, not a timeout counter. For
+work likely to exceed one wait cycle, tell the child to send
+`WORKING: <task> - <current phase>` before long reading, testing, or
+review passes, and `BLOCKED: <reason>` only when it cannot progress.
+Track spawned agent names locally. Use `multi_agent_v1.wait_agent` for mailbox
+signals, but a timeout only means no new mailbox update arrived.
+Treat a running child as alive and keep doing independent root work.
+Fallback only when the child is completed without the
+deliverable, ack-only, or no longer running. If that followup is still
+silent or ack-only, record the result as inconclusive, do not count it
+as approval/pass, close it if safe, and respawn a smaller
+`fork_context: false` task with the missing deliverable.
+
+# Subagent-dependent transition barrier
+Do not mark an `update_plan` step `completed` while an active child owns
+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.
+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
+BLOCKED: <reason>`. After four silent or ack-only checks, close the lane as
+inconclusive, record that it is not approval, and respawn smaller only
+if the deliverable is still required.
+
+# Verification gate (TRIGGERED, NOT OPTIONAL)
+
+Trigger when ANY apply:
+- Tier is HEAVY.
+- User demanded strict, rigorous, or proper review.
+LIGHT tier records a self-review in the notepad instead: re-read the
+diff, run diagnostics, confirm each criterion's evidence, and state in
+one line why the tier held.
+
+Procedure (NON-NEGOTIABLE):
+1. Spawn a child with `fork_context: false` and a self-contained reviewer
+   assignment in `message`. The `multi_agent_v1.spawn_agent` schema cannot select a
+   TOML-backed reviewer role, so paste the reviewer requirements into
+   the message.
+   Pass: goal, success-criteria, scenario evidence, full diff, notepad
+   path.
+2. Treat the reviewer's verdict as binding. There is NO "false
+   positive". Every concern is real. Do not argue. Do not minimise. Do
+   not explain it away.
+3. Fix every issue. Re-run the FULL scenario QA. Capture fresh
+   evidence. Update notepad.
+4. Re-submit to the SAME reviewer. Loop until you receive an
+   UNCONDITIONAL approval ("looks good but..." = REJECTION).
+5. Only on unconditional approval may you declare done. Stopping early
+   IS failure.
+
+# Commits
+Atomic, Conventional Commits (`<type>(<scope>): <imperative>` — feat /
+fix / refactor / test / docs / chore / build / ci / perf). One logical
+change per commit; each commit builds + tests green on its own. No WIP
+on the final branch. If a plan file exists, final commit footer:
+`Plan: .omo/plans/<slug>.md`. Do NOT auto-`git commit` unless the user
+requested or preauthorised this session — default is stage + draft
+message + present for approval.
+
+# Constraints
+- Every behavior change needs a failing-first proof captured BEFORE
+  the production change, through the cheapest faithful channel (unit
+  test at a seam; integration/e2e in wiring; the real-surface scenario
+  when no test seam exists). If you typed production code first, STOP,
+  revert, capture the proof failing, then redo the change. Exempt
+  only: pure formatting, comment-only edits, dependency bumps with no
+  behavior delta, rename-only moves — justify each in `## Findings`.
+- A test that mirrors its implementation — asserting mocks were
+  called, pinning a constant, or unable to fail under any plausible
+  regression — is NOT evidence. Prefer a real-surface proof with no
+  new test over a tautological test.
+- Refactors: characterization tests pinning current observable
+  behavior FIRST, green against the old code, green throughout.
+- Smallest correct change. No drive-by refactors.
+- Never suppress lints / errors / test failures. Never delete, skip,
+  `.only`, `.skip`, `xfail`, or comment out tests to green the suite.
+- Never claim done from inference — only from captured evidence.
+- Parallel tool calls for any independent work.
+
+# Output discipline
+- First line literally: `ULTRAWORK MODE ENABLED!`
+- After bootstrap: 1-2 paragraph plan summary + notepad path.
+- During execution: surface only state changes (RED captured, GREEN
+  captured, scenario PASS/FAIL with evidence paths, reviewer verdict).
+- Final message: outcome + success-criteria checklist with evidence
+  refs + notepad path + reviewer approval (if gate triggered) + commit
+  list (`<sha> <subject>`). No file-by-file changelog unless asked.
+
+# Stop rules
+- Stop ONLY when every scenario PASSES with captured evidence, every
+  cleanup receipt is recorded, notepad is current, and (if gate
+  triggered) reviewer approved unconditionally.
+- Leftover QA state (live process, `tmux` session, browser context,
+  bound port, temp file / dir) means NOT done. Tear it down, record
+  the receipt, then continue.
+- After 2 identical failed attempts at one step, surface what was tried
+  and ask the user before another retry.
+- After 2 parallel exploration waves yield no new useful facts, stop
+  exploring and act.
+
+</ultrawork-mode>

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

@@ -3,10 +3,23 @@ import { parseGoalArg, readJsonInput, readValue } from "./cli-arg-parser.js";
 import { printJson, printStatus } from "./cli-output.js";
 import { ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_MODELS, UlwLoopError } from "./types.js";
 const SOURCES = ["user_prompt_submit", "finding", "cli"];
+const STEERING_KIND_HELP = [
+    `Allowed --kind values: ${ULW_LOOP_STEERING_MUTATION_KINDS.join(", ")}`,
+    "Kind-specific required flags:",
+    "  add_subgoal: --title, --objective, --evidence, --rationale",
+    "  split_subgoal: --goal-id, --children, --evidence, --rationale",
+    "  reorder_pending: --order, --evidence, --rationale",
+    "  revise_pending_wording: --goal-id, --title or --objective, --evidence, --rationale",
+    "  revise_criterion: --goal-id, --criterion-id, one of --scenario/--expected-evidence/--user-model, --evidence, --rationale",
+    "  annotate_ledger: --evidence, --rationale",
+    "  mark_blocked_superseded: --goal-id, optional --replacements, --evidence, --rationale",
+    "Example: omo ulw-loop steer --kind annotate_ledger --evidence \"observed behavior\" --rationale \"why this changes the plan\" --json",
+].join("\n");
 function isKind(value) { return value !== undefined && ULW_LOOP_STEERING_MUTATION_KINDS.some((kind) => kind === value); }
 function isSource(value) { return value !== undefined && SOURCES.some((source) => source === value); }
 function isModel(value) { return ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.some((model) => model === value); }
 function fail(message, code, details) { throw new UlwLoopError(message, code, { details }); }
+function kindMessage(prefix) { return `${prefix}\n\n${STEERING_KIND_HELP}`; }
 function text(value, field) { if (value === undefined)
     return undefined; const trimmed = value.trim(); if (trimmed.length > 0)
     return trimmed; return fail(`Empty ${field}.`, "ULW_LOOP_STEERING_FIELD_EMPTY", { field }); }
@@ -19,7 +32,7 @@ export function parseSteeringKind(argv) {
     const value = readValue(argv, "--kind");
     if (isKind(value))
         return value;
-    return value === undefined ? fail("Missing --kind.", "ULW_LOOP_STEERING_KIND_REQUIRED", { flag: "--kind" }) : fail(`Invalid --kind: ${value}.`, "ULW_LOOP_STEERING_KIND_INVALID", { value, expected: ULW_LOOP_STEERING_MUTATION_KINDS });
+    return value === undefined ? fail(kindMessage("Missing --kind."), "ULW_LOOP_STEERING_KIND_REQUIRED", { flag: "--kind", expected: ULW_LOOP_STEERING_MUTATION_KINDS, usage: STEERING_KIND_HELP }) : fail(kindMessage(`Invalid --kind: ${value}.`), "ULW_LOOP_STEERING_KIND_INVALID", { value, expected: ULW_LOOP_STEERING_MUTATION_KINDS, usage: STEERING_KIND_HELP });
 }
 export function parseSteeringSource(argv) {
     const value = readValue(argv, "--source");

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

@@ -1137,6 +1137,19 @@ async function checkpointUlwLoop(repoRoot, args, scope) {
 
 // components/ulw-loop/src/cli-steering.ts
 var SOURCES = ["user_prompt_submit", "finding", "cli"];
+var STEERING_KIND_HELP = [
+  `Allowed --kind values: ${ULW_LOOP_STEERING_MUTATION_KINDS.join(", ")}`,
+  "Kind-specific required flags:",
+  "  add_subgoal: --title, --objective, --evidence, --rationale",
+  "  split_subgoal: --goal-id, --children, --evidence, --rationale",
+  "  reorder_pending: --order, --evidence, --rationale",
+  "  revise_pending_wording: --goal-id, --title or --objective, --evidence, --rationale",
+  "  revise_criterion: --goal-id, --criterion-id, one of --scenario/--expected-evidence/--user-model, --evidence, --rationale",
+  "  annotate_ledger: --evidence, --rationale",
+  "  mark_blocked_superseded: --goal-id, optional --replacements, --evidence, --rationale",
+  'Example: omo ulw-loop steer --kind annotate_ledger --evidence "observed behavior" --rationale "why this changes the plan" --json'
+].join(`
+`);
 function isKind(value) {
   return value !== undefined && ULW_LOOP_STEERING_MUTATION_KINDS.some((kind) => kind === value);
 }
@@ -1149,6 +1162,11 @@ function isModel(value) {
 function fail(message, code, details) {
   throw new UlwLoopError(message, code, { details });
 }
+function kindMessage(prefix) {
+  return `${prefix}
+
+${STEERING_KIND_HELP}`;
+}
 function text(value, field) {
   if (value === undefined)
     return;
@@ -1179,7 +1197,7 @@ function parseSteeringKind(argv) {
   const value = readValue(argv, "--kind");
   if (isKind(value))
     return value;
-  return value === undefined ? fail("Missing --kind.", "ULW_LOOP_STEERING_KIND_REQUIRED", { flag: "--kind" }) : fail(`Invalid --kind: ${value}.`, "ULW_LOOP_STEERING_KIND_INVALID", { value, expected: ULW_LOOP_STEERING_MUTATION_KINDS });
+  return value === undefined ? fail(kindMessage("Missing --kind."), "ULW_LOOP_STEERING_KIND_REQUIRED", { flag: "--kind", expected: ULW_LOOP_STEERING_MUTATION_KINDS, usage: STEERING_KIND_HELP }) : fail(kindMessage(`Invalid --kind: ${value}.`), "ULW_LOOP_STEERING_KIND_INVALID", { value, expected: ULW_LOOP_STEERING_MUTATION_KINDS, usage: STEERING_KIND_HELP });
 }
 function parseSteeringSource(argv) {
   const value = readValue(argv, "--source");
@@ -2251,6 +2269,111 @@ function commandScope(argv) {
   return sessionId === null ? undefined : { sessionId };
 }
 
+// components/ulw-loop/src/ultrawork-directive.ts
+import { readFileSync } from "node:fs";
+var ULTRAWORK_DIRECTIVE = readFileSync(new URL("../directive.md", import.meta.url), "utf8");
+var ULTRAWORK_CURRENT_PROMPT_PATTERN = /(?:ultrawork|ulw)/i;
+var ULTRAWORK_DIRECTIVE_MARKER = "<ultrawork-mode>";
+var TRANSCRIPT_SEARCH_BYTES = 512000;
+var CONTEXT_PRESSURE_MARKERS = [
+  "context compacted",
+  "context_length_exceeded",
+  "skill descriptions were shortened",
+  "context_too_large",
+  "codex ran out of room in the model's context window",
+  "your input exceeds the context window",
+  "long threads and multiple compactions"
+];
+function buildUltraworkDirectiveOutput(input) {
+  if (isContextPressureRecoveryPrompt(input.prompt))
+    return "";
+  if (hasUltraworkDirectiveAlreadyInTranscript(input.transcript_path))
+    return "";
+  if (isContextPressureTranscript(input.transcript_path))
+    return "";
+  return isUltraworkPrompt(input.prompt) ? formatAdditionalContextOutput(ULTRAWORK_DIRECTIVE) : "";
+}
+function hasUltraworkDirectiveAlreadyInTranscript(transcriptPath) {
+  if (transcriptPath === undefined || transcriptPath === null)
+    return false;
+  try {
+    const rawTranscript = readTranscriptTail(transcriptPath);
+    for (const line of rawTranscript.split(/\r?\n/)) {
+      const parsed = parseJsonLine(line);
+      if (!isRecord3(parsed))
+        continue;
+      const hookSpecificOutput = parsed["hookSpecificOutput"];
+      if (!isRecord3(hookSpecificOutput))
+        continue;
+      if (hookSpecificOutput["hookEventName"] !== "UserPromptSubmit")
+        continue;
+      if (typeof hookSpecificOutput["additionalContext"] === "string" && hookSpecificOutput["additionalContext"].includes(ULTRAWORK_DIRECTIVE_MARKER)) {
+        return true;
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error)
+      return false;
+    throw error;
+  }
+  return false;
+}
+function readTranscriptTail(transcriptPath) {
+  const rawTranscript = readFileSync(transcriptPath);
+  return rawTranscript.subarray(Math.max(0, rawTranscript.byteLength - TRANSCRIPT_SEARCH_BYTES)).toString("utf8");
+}
+function isUltraworkPrompt(prompt) {
+  return ULTRAWORK_CURRENT_PROMPT_PATTERN.test(prompt);
+}
+function isContextPressureRecoveryPrompt(prompt) {
+  const normalizedPrompt = prompt.toLowerCase();
+  return CONTEXT_PRESSURE_MARKERS.some((marker) => normalizedPrompt.includes(marker));
+}
+function isContextPressureTranscript(transcriptPath) {
+  if (transcriptPath === undefined || transcriptPath === null)
+    return false;
+  try {
+    return isContextPressureRecoveryPrompt(readTranscriptTail(transcriptPath));
+  } catch (error) {
+    if (error instanceof Error)
+      return false;
+    throw error;
+  }
+}
+function formatAdditionalContextOutput(additionalContext) {
+  const normalizedContext = normalizeAdditionalContext(additionalContext);
+  if (normalizedContext.length === 0)
+    return "";
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: normalizedContext
+    }
+  };
+  return `${JSON.stringify(output)}
+`;
+}
+function normalizeAdditionalContext(additionalContext) {
+  return additionalContext.replace(/\r\n/g, `
+`).replace(/\r/g, `
+`).trim();
+}
+function parseJsonLine(line) {
+  if (line.trim().length === 0)
+    return null;
+  try {
+    const parsed = JSON.parse(line);
+    return parsed;
+  } catch (error) {
+    if (error instanceof Error)
+      return null;
+    throw error;
+  }
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // components/ulw-loop/src/codex-hook.ts
 var CREATE_GOAL_TOOL_NAME = "create_goal";
 var CREATE_GOAL_PAYLOAD_WARNING = "Use create_goal with objective only. Omit token_budget so the goal stays unlimited, and put lifecycle status changes on update_goal.";
@@ -2278,13 +2401,16 @@ function parsePreToolUsePayload(raw) {
     return null;
   }
 }
-async function applyUserPromptUlwLoopSteering(payload) {
+async function applyUserPromptUlwLoopSteering(payload, options = {}) {
   try {
     if (payload.hook_event_name !== "UserPromptSubmit")
       return "";
     const proposal = parseUlwLoopSteeringDirective(payload.prompt);
-    if (proposal === null)
-      return "";
+    if (proposal === null) {
+      if (hasSteeringDirectiveMarker(payload.prompt))
+        return "";
+      return options.includeUltraworkDirective ? buildUltraworkDirectiveOutput(payload) : "";
+    }
     const result = await steerUlwLoop(payload.cwd, proposal, payloadScope(payload));
     if (!result.accepted)
       return "";
@@ -2300,6 +2426,9 @@ async function applyUserPromptUlwLoopSteering(payload) {
     return "";
   }
 }
+function hasSteeringDirectiveMarker(prompt) {
+  return /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer):/u.test(prompt);
+}
 function payloadScope(payload) {
   return { sessionId: payload.session_id };
 }
@@ -2321,12 +2450,12 @@ function applyPreToolUseGoalBudgetGuard(payload) {
   return `${JSON.stringify(output)}
 `;
 }
-async function runUlwLoopHookCli(stdin, stdout) {
+async function runUlwLoopHookCli(stdin, stdout, options = {}) {
   try {
     const payload = parseUserPromptSubmitPayload(await readAll(stdin));
     if (payload === null)
       return;
-    const output = await applyUserPromptUlwLoopSteering(payload);
+    const output = await applyUserPromptUlwLoopSteering(payload, options);
     if (output.length > 0)
       stdout.write(output);
   } catch (error) {
@@ -2350,19 +2479,19 @@ async function runPreToolUseGoalBudgetGuardCli(stdin, stdout) {
   }
 }
 function isUserPromptSubmitPayload(value) {
-  if (!isRecord3(value))
+  if (!isRecord4(value))
     return false;
-  return value["hook_event_name"] === "UserPromptSubmit" && typeof value["cwd"] === "string" && typeof value["prompt"] === "string" && typeof value["session_id"] === "string" && ["model", "permission_mode", "transcript_path", "turn_id"].every((key) => optionalString(value[key]));
+  return value["hook_event_name"] === "UserPromptSubmit" && typeof value["cwd"] === "string" && typeof value["prompt"] === "string" && typeof value["session_id"] === "string" && ["model", "permission_mode", "turn_id"].every((key) => optionalString(value[key])) && (value["transcript_path"] === undefined || value["transcript_path"] === null || typeof value["transcript_path"] === "string");
 }
 function isPreToolUsePayload(value) {
-  if (!isRecord3(value))
+  if (!isRecord4(value))
     return false;
   return value["hook_event_name"] === "PreToolUse" && typeof value["cwd"] === "string" && typeof value["model"] === "string" && typeof value["permission_mode"] === "string" && typeof value["session_id"] === "string" && typeof value["tool_name"] === "string" && typeof value["tool_use_id"] === "string" && (value["transcript_path"] === null || typeof value["transcript_path"] === "string") && typeof value["turn_id"] === "string" && Object.hasOwn(value, "tool_input");
 }
 function hasInvalidCreateGoalInput(value) {
-  return isRecord3(value) && Object.keys(value).some((key) => key !== "objective");
+  return isRecord4(value) && Object.keys(value).some((key) => key !== "objective");
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function optionalString(value) {
@@ -2383,8 +2512,8 @@ function readAll(stdin) {
 // components/ulw-loop/src/cli.ts
 var TOP_LEVEL_HELP = `Usage:
   omo ulw-loop <subcommand> [args]
-  omo hook user-prompt-submit         (Codex UserPromptSubmit hook)
-  omo help | --help | -h              (this message)
+  omo hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)
+  omo help | --help | -h                          (this message)
 
 Run \`omo ulw-loop help\` for ulw-loop subcommands.
 `;
@@ -2400,7 +2529,9 @@ async function main() {
   if (command === "hook") {
     const sub = argv[1];
     if (sub === "user-prompt-submit") {
-      await runUlwLoopHookCli(process.stdin, process.stdout);
+      await runUlwLoopHookCli(process.stdin, process.stdout, {
+        includeUltraworkDirective: argv.includes("--with-ultrawork")
+      });
       return 0;
     }
     if (sub === "pre-tool-use") {