oh-my-opencode 5.0.0-beta.3 → 5.0.0-beta.30

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

@@ -1,5 +1,8 @@
 import { UlwLoopError } from "./types.js";
 export const ULW_LOOP_HELP = `Usage:
+  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)
+  omo-agent-toolkit help | --help | -h                          (this message)
+  omo-agent-toolkit ulw-loop help
   omo-agent-toolkit ulw-loop create-goals --brief "..." [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--validation-batch-json <json-or-path>] [--force] [--json]
   omo-agent-toolkit ulw-loop status [--json]
   omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]
@@ -10,7 +13,14 @@ export const ULW_LOOP_HELP = `Usage:
   omo-agent-toolkit ulw-loop add-goal --title "..." --objective "..." [--json]
   omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title "..." --objective "..." --evidence "..." --codex-goal-json <...> [--json]
 
-All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.`;
+All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.
+Every subcommand accepts --help | -h to print its own usage line.`;
+export function subcommandHelp(subcommand) {
+    const lines = ULW_LOOP_HELP.split("\n").filter((line) => line.trimStart().startsWith(`omo-agent-toolkit ulw-loop ${subcommand}`));
+    if (lines.length === 0)
+        return ULW_LOOP_HELP;
+    return ["Usage:", ...lines].join("\n");
+}
 export function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }

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

@@ -33,8 +33,6 @@ var ULW_LOOP_SUCCESS_CRITERION_USER_MODELS = [
 ];
 // packages/omo-codex/plugin/components/ulw-loop/src/runtime.ts
 class UlwLoopError extends Error {
-  code;
-  details;
   constructor(message, code, opts) {
     super(message, opts?.cause === undefined ? undefined : { cause: opts.cause });
     this.name = "UlwLoopError";
@@ -48,7 +46,7 @@ function iso() {
   return new Date().toISOString();
 }
 // packages/omo-codex/plugin/components/ulw-loop/src/paths.ts
-var SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID"];
+var SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"];
 function normalizeUlwLoopSessionId(sessionId) {
   const trimmed = sessionId?.trim();
   if (!trimmed)
@@ -302,7 +300,7 @@ function parseCodexGoalSnapshot(value) {
     return { available: false, raw: value };
   }
   const goal = safeObject(goalValue);
-  const objective = safeString(goal["objective"] ?? goal["goal"] ?? goal["description"] ?? root["objective"]);
+  const objective = safeString(goal["objective"] ?? goal["goal"] ?? goal["description"] ?? goal["title"] ?? root["objective"] ?? root["title"]);
   const status = normalizeStatus(goal["status"] ?? root["status"]);
   return {
     available: Boolean(objective || status !== "unknown"),
@@ -1254,6 +1252,9 @@ async function checkpointUlwLoop(repoRoot, args, scope) {
 
 // packages/omo-codex/plugin/components/ulw-loop/src/cli-output.ts
 var ULW_LOOP_HELP = `Usage:
+  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)
+  omo-agent-toolkit help | --help | -h                          (this message)
+  omo-agent-toolkit ulw-loop help
   omo-agent-toolkit ulw-loop create-goals --brief "..." [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--validation-batch-json <json-or-path>] [--force] [--json]
   omo-agent-toolkit ulw-loop status [--json]
   omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]
@@ -1264,7 +1265,16 @@ var ULW_LOOP_HELP = `Usage:
   omo-agent-toolkit ulw-loop add-goal --title "..." --objective "..." [--json]
   omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title "..." --objective "..." --evidence "..." --codex-goal-json <...> [--json]
 
-All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.`;
+All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.
+Every subcommand accepts --help | -h to print its own usage line.`;
+function subcommandHelp(subcommand) {
+  const lines = ULW_LOOP_HELP.split(`
+`).filter((line) => line.trimStart().startsWith(`omo-agent-toolkit ulw-loop ${subcommand}`));
+  if (lines.length === 0)
+    return ULW_LOOP_HELP;
+  return ["Usage:", ...lines].join(`
+`);
+}
 function printJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}
 `);
@@ -2722,6 +2732,11 @@ async function ulwLoopCommand(argv) {
 `);
       return 1;
     }
+    if (command !== "help" && (hasFlag(rest, "--help") || hasFlag(rest, "-h"))) {
+      process.stdout.write(`${subcommandHelp(command)}
+`);
+      return 0;
+    }
     switch (command) {
       case "help":
         process.stdout.write(`${ULW_LOOP_HELP}
@@ -3400,18 +3415,12 @@ function parseStopPayload(value) {
 }
 
 // packages/omo-codex/plugin/components/ulw-loop/src/cli.ts
-var TOP_LEVEL_HELP = `Usage:
-  omo-agent-toolkit ulw-loop <subcommand> [args]
-  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)
-  omo-agent-toolkit help | --help | -h                          (this message)
-
-Run \`omo-agent-toolkit ulw-loop help\` for ulw-loop subcommands.
-`;
 async function main() {
   const argv = process.argv.slice(2);
   const command = argv[0];
   if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-    process.stdout.write(TOP_LEVEL_HELP);
+    process.stdout.write(`${ULW_LOOP_HELP}
+`);
     return 0;
   }
   if (command === "ulw-loop")
@@ -3443,7 +3452,8 @@ async function main() {
   if (isUlwLoopSubcommand(command))
     return ulwLoopCommand(argv);
   process.stderr.write(`[omo] unknown command: ${command}
-${TOP_LEVEL_HELP}`);
+${ULW_LOOP_HELP}
+`);
   return 1;
 }
 main().then((code) => {

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

@@ -31,7 +31,7 @@ export function parseCodexGoalSnapshot(value) {
         return { available: false, raw: value };
     }
     const goal = safeObject(goalValue);
-    const objective = safeString(goal["objective"] ?? goal["goal"] ?? goal["description"] ?? root["objective"]);
+    const objective = safeString(goal["objective"] ?? goal["goal"] ?? goal["description"] ?? goal["title"] ?? root["objective"] ?? root["title"]);
     const status = normalizeStatus(goal["status"] ?? root["status"]);
     return {
         available: Boolean(objective || status !== "unknown"),

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

@@ -1,6 +1,6 @@
 import { isAbsolute, join, relative, sep } from "node:path";
 import { ULW_LOOP_BRIEF, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
-const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID"];
+const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"];
 export function normalizeUlwLoopSessionId(sessionId) {
     const trimmed = sessionId?.trim();
     if (!trimmed)

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

@@ -5,7 +5,7 @@ import { normalizeUlwLoopSessionId, ulwLoopDir } from "./paths.js";
 // dies mid-turn (crash, kill, context blowup before any Stop) never reaches
 // this handler. Mid-turn stalls are out of scope by design.
 const RESUME_CAP = 2;
-// Mirrors start-work-continuation's context-pressure bail-out: injecting a
+// Mirrors ulw-execute-continuation's context-pressure bail-out: injecting a
 // resume directive into an already-overflowing context makes things worse.
 const CONTEXT_PRESSURE_MARKERS = [
     "context compacted",
@@ -132,7 +132,7 @@ function readCounter(counterPath) {
         throw error;
     }
 }
-// Local ~10-LOC approximation of start-work-continuation's boulder check (no
+// Local ~10-LOC approximation of ulw-execute-continuation's boulder check (no
 // cross-component import allowed): any continuable work for this session means
 // that hook owns the Stop event, so this one stays silent.
 function boulderContinuationWillFire(cwd, sessionId) {
@@ -167,7 +167,7 @@ function transcriptShowsContextPressure(transcriptPath) {
         throw error;
     }
 }
-// start-work-continuation owns an active Boulder plan until its final gate marks
+// ulw-execute-continuation owns an active Boulder plan until its final gate marks
 // the work complete, including the zero-remaining checklist state.
 function boulderPlanHasChecklist(cwd, entry) {
     const activePlan = entry["active_plan"];

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 5.0.0-beta.3) Checking Ulw-Loop Steering"
+						"statusMessage": "(OmO 5.0.0-beta.30) 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 5.0.0-beta.3) Enforcing Unlimited Ulw-Loop Budget"
+						"statusMessage": "(OmO 5.0.0-beta.30) Enforcing Unlimited Ulw-Loop Budget"
 					}
 				]
 			},
@@ -31,7 +31,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use-spawn",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.3) Guarding Ulw-Loop Spawns"
+						"statusMessage": "(OmO 5.0.0-beta.30) Guarding Ulw-Loop Spawns"
 					}
 				]
 			}
@@ -43,7 +43,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.3) Checking Ulw-Loop Resume"
+						"statusMessage": "(OmO 5.0.0-beta.30) Checking Ulw-Loop Resume"
 					}
 				]
 			}

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

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ulw-loop",
-	"version": "5.0.0-beta.3",
+	"version": "5.0.0-beta.30",
 	"description": "Codex plugin: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",
@@ -47,10 +47,10 @@
 		"check": "tsc --noEmit && biome check . && npm run build"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.4.16",
-		"@types/node": "^25.9.3",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.8"
+		"@biomejs/biome": "2.5.9",
+		"@types/node": "^26.2.0",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.11"
 	},
 	"engines": {
 		"node": ">=20.0.0"

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

@@ -15,12 +15,13 @@ This skill is intentionally compact. The full workflow lives in `references/full
 
 1. Open `references/full-workflow.md`.
 2. Read through **Bootstrap** (including its tier triage), **Execution Loop**, the **Manual-QA channels** table, and the **Stop Rules** before running any ULW command or recording evidence.
-3. If the task has code edits, tests, QA, or commit work, follow the full workflow's delegation and evidence rules. Tests alone never prove done.
+3. Open `references/define-goal.md` and register the run's goal by it. Goal creation is NEVER skipped: shape the objective and every success criterion by that reference before any implementation.
+4. If the task has code edits, tests, QA, or commit work, follow the full workflow's delegation and evidence rules. Tests alone never prove done.
 
 ## Non-Negotiables
 
 - Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
-- Register goals up front (`omo-agent-toolkit ulw-loop create-goals`, then `create_goal` from the printed handoff) and mirror every atomic step into the live `update_plan` checklist: one ultra-granular step per action, exactly one in_progress, transitions marked the instant they happen.
+- Register goals up front, shaped by `references/define-goal.md` (`omo-agent-toolkit ulw-loop create-goals`, then `create_goal` from the printed handoff), and mirror every atomic step into the live `update_plan` checklist: one ultra-granular step per action, exactly one in_progress, transitions marked the instant they happen.
 - After any compaction or context loss, re-read brief + goals + ledger FIRST plus `omo-agent-toolkit ulw-loop status --json`, then resume; never re-plan from scratch.
 - If `omo-agent-toolkit 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 (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).

package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/references/define-goal.md

@@ -0,0 +1,108 @@
+# Define Goal
+
+How to turn a brief into a registered goal the run can be held to. Read this BEFORE calling `create_goal`: the objective you register is the binding contract for the whole run, and the run's quality is capped by the quality of this objective.
+
+A goal is a prompt to the agent that executes it, including future-you after compaction. It earns its tokens the way any prompt does: it carries only what the run cannot re-derive later, the outcome, the proof, the bounds, and the stop state. Everything else is noise that steals attention from the parts that decide completion.
+
+## The quality bar
+
+Before registering, the objective must answer all five:
+
+1. What concrete thing will be TRUE when this is done? An outcome, never an activity.
+2. What evidence will prove it? Commands, validators, artifacts someone can open.
+3. What quantitative or binary threshold defines success?
+4. What scope boundaries matter? What is in, and what is explicitly out.
+5. What should make the agent stop and ask instead of grinding?
+
+An objective that cannot answer one of these is not ready. Repair it (below) before calling the tool.
+
+## Objective anatomy
+
+Write the objective outcome-first, in this order:
+
+1. **Outcome**: one sentence stating what will be true, naming the artifact, system, repo, or user-facing behavior involved.
+2. **Deliverables**: the named surfaces the work lands on (files, endpoints, packages, environments). Use literal paths and names: the executing agent interprets the objective literally and will not infer surfaces you did not name.
+3. **Success criteria**: sized by tier (below), each one a binary observable with its scenario and evidence named upfront.
+4. **Constraints and scope bounds**: Record the user's stated constraints verbatim, including what is explicitly out of scope wherever ambiguity would let the run expand. Where the user was silent on a bound the work forks on, SET it yourself: derive the clearest defensible bound from repo evidence and best practice (stack already in use, compatibility surfaces, scale the code must serve, audience or compliance the repo implies) and record it inside the objective as `assumed: <constraint> — <rationale>, <reversible?>`, binding until the user vetoes it. Unstated bounds do not exist — which is why you write them.
+5. **WHEN TO STOP**: one line, "I'll stop right away when <the exact observable state that ends this run>". This line is binding: the moment it holds, the run delivers and stops. Work past it is a defect, not diligence.
+
+State the motivation when it changes execution ("p95 matters because the checkout SLA is 300ms") and omit it when it does not. Positive statements beat prohibitions: "verify against staging" carries more signal than "do not touch production".
+
+## Success criteria construction
+
+Count by tier, mirroring the run's tier triage:
+
+- LIGHT (known pattern, no open design decisions): 1-2 criteria, happy path plus the riskiest edge.
+- HEAVY (new module or abstraction, auth or security, external integration, schema or migration, concurrency, cross-domain refactor, or the user demanded care): 3+ criteria covering happy path, edge (boundary, empty, malformed, concurrent), adjacent-surface regression named by file and function, and the adversarial risk the change actually creates.
+
+Every criterion carries, at definition time, not after the work:
+
+- a binary pass condition ("returns 200 and the body matches the schema", never "works correctly");
+- the exact scenario: the literal command, request, page action, or payload that will prove it;
+- the evidence artifact it will capture: transcript, status plus body, screenshot path, diff, parsed dump;
+- the failing-first proof (test id or scenario) that will be captured RED before implementation.
+
+A criterion that cannot fail is not a criterion. If no input could make the scenario fail, it measures nothing; rewrite it until failure is possible.
+
+## Make it quantitative
+
+Prefer numbers that represent real success over decorative precision. A threshold nobody would act on differently is noise.
+
+| Domain | Quantify as |
+| --- | --- |
+| Bug fix | reproduction first, fix second: the failing case captured RED, then the same validator green |
+| Tests | the exact command and required pass condition, plus run count for flake-sensitive suites |
+| Performance | metric, target threshold, measurement method, and run count ("p95 under 250ms across 3 consecutive local runs") |
+| Quality work | the observable acceptance bar: lint, typecheck, and test pass; reviewed examples; a user-approved artifact |
+| Research | the decision the research must enable, the sources or systems in scope, and the evidence standard per claim |
+| Operations | healthy state, monitoring window, failure threshold, and the rollback or escalation trigger |
+
+## Repair weak goals
+
+Reject pure activity objectives: "make progress", "keep investigating", "improve things", "work on X". They cannot fail, so they cannot finish.
+
+Rewrite vague goals into measurable ones when local context makes the rewrite safe. Ask ONE narrow question only when the missing detail is an OWNER-DECISION — irreversible, destructive, safety-critical, or a cross-cutting product choice (real budget or spend, public surface, external dependency, data shape, target audience) — that changes the intended outcome or its validation, shaped around the missing validator or bound:
+
+- "What metric defines success here: latency, cost, accuracy, or user-visible behavior?"
+- "Which environment do I verify against: local, staging, or production?"
+- "What is the minimum evidence you want before this goal is marked complete?"
+
+Every other missing constraint follows Objective anatomy #4: adopt the clearest defensible default, state it in the objective as `assumed:`, and let the user veto.
+
+When the user cannot provide a metric, propose the most honest binary validator available and proceed with it stated in the objective.
+
+Weak: "Make checkout faster."
+Repaired: "Reduce checkout API p95 below 250ms on the documented slow path with the smallest safe server-side change; prove it with `npm run test:checkout` green plus the local latency benchmark showing p95 under 250ms across 3 consecutive runs; out of scope: client-side changes and new caching layers."
+
+Weak: "Keep investigating the PR comments."
+Repaired: "Resolve every open change-requesting review comment on PR 123 touching only the affected auth files and their tests; prove it with the targeted auth test command green plus `gh pr view 123` showing zero unresolved change-request threads."
+
+## Registration protocol
+
+1. Call `get_goal` first, then act by state:
+
+| get_goal shows | Action |
+| --- | --- |
+| no active goal | Register with `create_goal`, passing exactly `objective`. Never include lifecycle fields such as `status`; never register a goal in prose, a notepad, or a plan instead of the tool. |
+| an active goal matching this intent | Continue it. Never register a duplicate. |
+| an active goal conflicting with this intent | Stop and surface the conflict; the user decides whether to finish it, complete it, or branch. |
+
+2. Goals are unlimited. Never invent a numeric budget, token limit, or deadline the user did not state — that ban covers run quotas; the `assumed:` work constraints from Objective anatomy #4 are different and required.
+3. In a ulw-loop run, the loop CLI owns per-goal state (`.omo/ulw-loop/goals.json`): `create_goal` registers the aggregate objective from the printed handoff, and this reference shapes both that objective and every goal's `successCriteria` at `create-goals` time.
+
+## Completion honesty
+
+- Report `update_goal` complete only after auditing every criterion against evidence captured in this run. A green suite is supporting evidence, never completion proof by itself.
+- Waiting is not blocked: while a monitor, background child, or scheduled continuation can wake the run, end the turn and let it fire. Blocked requires a true impasse: no live resumption channel, and the same block recurring across consecutive turns.
+- The moment the WHEN TO STOP line holds with evidence in hand, deliver and stop.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Instead |
+| --- | --- | --- |
+| Activity objective ("investigate X") | Cannot fail, so cannot finish; the run wanders | Name the outcome the activity must produce and its evidence |
+| Criteria added after implementation | The contract bent to fit the work; nothing was proven | Write criteria and scenarios at registration, before any edit |
+| Decorative precision ("99.97% uptime" nobody measures) | A threshold no validator checks is noise wearing a suit | Only thresholds a named validator will actually check |
+| Padded objective (role prose, restated context, filler) | Every extra token competes with the criteria for attention | Outcome, deliverables, criteria, bounds, stop line; nothing else |
+| Goal registered in prose or a notepad | Nothing binds the run; completion becomes a vibe | `create_goal` with the objective, every time the tool exists |
+| Duplicate goal for the same intent | Two contracts, neither authoritative | Continue the active goal or surface the conflict |

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

@@ -121,6 +121,7 @@ only when deliberately overwriting completed evidence.
 Write state through the CLI path. Do not hand-edit state files.
 
 ### 2. Refine success criteria + a Prometheus-grade QA and parallelism plan per goal
+Shape every goal's objective and `successCriteria` by `references/define-goal.md`: its quality bar, objective anatomy, and criterion construction govern this step. Where the brief is silent on a constraint the work forks on, derive the default per that reference, record it via `annotate_ledger` (`--evidence` naming the repo fact, `--rationale` the default plus reversibility), and surface the assumed list in the first user-visible report so a wrong default is a one-line veto, not a finished run.
 Gather context BEFORE planning with parallel `explorer` / `librarian` workers plus your own read-only tools.
 First survey available skills: read every loosely-relevant skill's description, deliberately choose which this work uses, and prefer applying genuinely-relevant skills over working raw.
 Then run tier triage per goal — rigor (LIGHT/HEAVY below) and shape (`delivery` default, or `research` when the deliverable is a cited answer, not an artifact) — and record both in an `annotate_ledger` steering entry. Default is LIGHT — a narrow change inside existing layers. Take HEAVY only on a fact you can point to: a new module / abstraction / domain model; auth, security, or session; an external integration; a DB schema or migration; concurrency, transaction boundaries, or cache invalidation; a cross-domain refactor; or the user signaled care or demanded review. When unsure, take HEAVY; upgrade the moment a HEAVY fact surfaces, never downgrade mid-run.

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

@@ -1,6 +1,6 @@
 import { checkpoint } from "./checkpoint-continuation.js";
 import { hasFlag, readValue } from "./cli-arg-parser.js";
-import { printJsonError, ULW_LOOP_HELP } from "./cli-output.js";
+import { printJsonError, subcommandHelp, ULW_LOOP_HELP } from "./cli-output.js";
 import {
 	addGoal,
 	captureEvidence,
@@ -53,6 +53,10 @@ export async function ulwLoopCommand(argv: readonly string[]): Promise<number> {
 			process.stdout.write(`${ULW_LOOP_HELP}\n`);
 			return 1;
 		}
+		if (command !== "help" && (hasFlag(rest, "--help") || hasFlag(rest, "-h"))) {
+			process.stdout.write(`${subcommandHelp(command)}\n`);
+			return 0;
+		}
 		switch (command) {
 			case "help":
 				process.stdout.write(`${ULW_LOOP_HELP}\n`);

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

@@ -2,6 +2,9 @@ import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan } from "./types.js"
 import { UlwLoopError } from "./types.js";
 
 export const ULW_LOOP_HELP = `Usage:
+  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)
+  omo-agent-toolkit help | --help | -h                          (this message)
+  omo-agent-toolkit ulw-loop help
   omo-agent-toolkit ulw-loop create-goals --brief "..." [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--validation-batch-json <json-or-path>] [--force] [--json]
   omo-agent-toolkit ulw-loop status [--json]
   omo-agent-toolkit ulw-loop complete-goals [--retry-failed] [--json]
@@ -12,7 +15,16 @@ export const ULW_LOOP_HELP = `Usage:
   omo-agent-toolkit ulw-loop add-goal --title "..." --objective "..." [--json]
   omo-agent-toolkit ulw-loop record-review-blockers --goal-id <id> --title "..." --objective "..." --evidence "..." --codex-goal-json <...> [--json]
 
-All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.`;
+All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.
+Every subcommand accepts --help | -h to print its own usage line.`;
+
+export function subcommandHelp(subcommand: string): string {
+	const lines = ULW_LOOP_HELP.split("\n").filter((line) =>
+		line.trimStart().startsWith(`omo-agent-toolkit ulw-loop ${subcommand}`),
+	);
+	if (lines.length === 0) return ULW_LOOP_HELP;
+	return ["Usage:", ...lines].join("\n");
+}
 
 type CriteriaCounts = { readonly pass: number; readonly total: number };
 

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

@@ -1,17 +1,15 @@
 #!/usr/bin/env node
 import { isUlwLoopSubcommand, ulwLoopCommand } from "./cli-commands.js";
+import { ULW_LOOP_HELP } from "./cli-output.js";
 import { runPreToolUseGoalBudgetGuardCli, runUlwLoopHookCli } from "./codex-hook.js";
 import { runSpawnGuardCli } from "./spawn-guard.js";
 import { runStopResumeHookCli } from "./stop-resume-hook.js";
 
-const TOP_LEVEL_HELP =
-	"Usage:\n  omo-agent-toolkit ulw-loop <subcommand> [args]\n  omo-agent-toolkit hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)\n  omo-agent-toolkit help | --help | -h                          (this message)\n\nRun `omo-agent-toolkit ulw-loop help` for ulw-loop subcommands.\n";
-
 async function main(): Promise<number> {
 	const argv = process.argv.slice(2);
 	const command = argv[0];
 	if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-		process.stdout.write(TOP_LEVEL_HELP);
+		process.stdout.write(`${ULW_LOOP_HELP}\n`);
 		return 0;
 	}
 	if (command === "ulw-loop") return ulwLoopCommand(argv.slice(1));
@@ -39,7 +37,7 @@ async function main(): Promise<number> {
 		return 1;
 	}
 	if (isUlwLoopSubcommand(command)) return ulwLoopCommand(argv);
-	process.stderr.write(`[omo] unknown command: ${command}\n${TOP_LEVEL_HELP}`);
+	process.stderr.write(`[omo] unknown command: ${command}\n${ULW_LOOP_HELP}\n`);
 	return 1;
 }
 

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

@@ -56,7 +56,9 @@ export function parseCodexGoalSnapshot(value: unknown): CodexGoalSnapshot {
 	}
 
 	const goal = safeObject(goalValue);
-	const objective = safeString(goal["objective"] ?? goal["goal"] ?? goal["description"] ?? root["objective"]);
+	const objective = safeString(
+		goal["objective"] ?? goal["goal"] ?? goal["description"] ?? goal["title"] ?? root["objective"] ?? root["title"],
+	);
 	const status = normalizeStatus(goal["status"] ?? root["status"]);
 
 	return {

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

@@ -95,7 +95,9 @@ export async function applyUserPromptUlwLoopSteering(
 }
 
 function hasSteeringDirectiveMarker(prompt: string): boolean {
-	return /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer|omo-agent-toolkit ulw-loop steer):/u.test(prompt);
+	return /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer|omo-agent-toolkit ulw-loop steer):/u.test(
+		prompt,
+	);
 }
 
 function payloadScope(payload: UserPromptSubmitPayload): UlwLoopScope {

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

@@ -5,7 +5,7 @@ export interface UlwLoopScope {
 	readonly sessionId?: string | null;
 }
 
-const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID"] as const;
+const SESSION_ENV_KEYS = ["OMO_ULW_LOOP_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"] as const;
 type EnvMap = Readonly<Record<string, string | undefined>>;
 
 export function normalizeUlwLoopSessionId(sessionId: string | null | undefined): string | null {

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

@@ -10,7 +10,7 @@ import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
 
 const RESUME_CAP = 2;
 
-// Mirrors start-work-continuation's context-pressure bail-out: injecting a
+// Mirrors ulw-execute-continuation's context-pressure bail-out: injecting a
 // resume directive into an already-overflowing context makes things worse.
 const CONTEXT_PRESSURE_MARKERS = [
 	"context compacted",
@@ -136,7 +136,7 @@ function readCounter(counterPath: string): { count: number; ledgerLineCount: num
 	}
 }
 
-// Local ~10-LOC approximation of start-work-continuation's boulder check (no
+// Local ~10-LOC approximation of ulw-execute-continuation's boulder check (no
 // cross-component import allowed): any continuable work for this session means
 // that hook owns the Stop event, so this one stays silent.
 function boulderContinuationWillFire(cwd: string, sessionId: string): boolean {
@@ -168,7 +168,7 @@ function transcriptShowsContextPressure(transcriptPath: string): boolean {
 	}
 }
 
-// start-work-continuation owns an active Boulder plan until its final gate marks
+// ulw-execute-continuation owns an active Boulder plan until its final gate marks
 // the work complete, including the zero-remaining checklist state.
 function boulderPlanHasChecklist(cwd: string, entry: Record<string, unknown>): boolean {
 	const activePlan = entry["active_plan"];

package/packages/omo-codex/plugin/components/ulw-loop/test/checkpoint-continuation.test.ts

@@ -31,7 +31,6 @@ describe("checkpointAndContinue", () => {
 		});
 
 		expect(result.next).toMatchObject({ resumed: false, goal: { id: "G002", status: "in_progress" } });
-		expect(result.next && "instruction" in result.next ? result.next.instruction.text : "").toContain("Goal: G002");
 		expect((await readUlwLoopPlan(repo)).activeGoalId).toBe("G002");
 	});
 

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-create-goals.test.ts

@@ -13,6 +13,7 @@ let err: string[];
 let originalCodexSessionId: string | undefined;
 let originalCodexThreadId: string | undefined;
 let originalOmoSessionId: string | undefined;
+let originalPiSessionId: string | undefined;
 
 beforeEach(async () => {
 	testDir = await mkdtemp(join(tmpdir(), "ug-cli-create-goals-"));
@@ -21,9 +22,11 @@ beforeEach(async () => {
 	originalCodexSessionId = process.env["CODEX_SESSION_ID"];
 	originalCodexThreadId = process.env["CODEX_THREAD_ID"];
 	originalOmoSessionId = process.env["OMO_ULW_LOOP_SESSION_ID"];
+	originalPiSessionId = process.env["PI_SESSION_ID"];
 	delete process.env["CODEX_SESSION_ID"];
 	delete process.env["CODEX_THREAD_ID"];
 	delete process.env["OMO_ULW_LOOP_SESSION_ID"];
+	delete process.env["PI_SESSION_ID"];
 	vi.spyOn(process, "cwd").mockReturnValue(testDir);
 	vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array): boolean => {
 		out.push(chunk.toString());
@@ -43,6 +46,8 @@ afterEach(async () => {
 	else process.env["CODEX_THREAD_ID"] = originalCodexThreadId;
 	if (originalOmoSessionId === undefined) delete process.env["OMO_ULW_LOOP_SESSION_ID"];
 	else process.env["OMO_ULW_LOOP_SESSION_ID"] = originalOmoSessionId;
+	if (originalPiSessionId === undefined) delete process.env["PI_SESSION_ID"];
+	else process.env["PI_SESSION_ID"] = originalPiSessionId;
 	await rm(testDir, { recursive: true, force: true });
 });
 
@@ -182,6 +187,26 @@ describe("ulwLoopCommand create-goals", () => {
 		expect(await readFile(join(testDir, ".omo/ulw-loop/manual-456/goals.json"), "utf8")).toContain("Manual scoped");
 	});
 
+	it("#given two Senpi sessions in one cwd #when each reads ulw-loop state #then only the owner sees its run", async () => {
+		process.env["PI_SESSION_ID"] = "session-A";
+		expect(await ulwLoopCommand(["create-goals", "--brief", "- Session A run", "--json"])).toBe(0);
+		resetOutput();
+
+		process.env["PI_SESSION_ID"] = "session-B";
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(1);
+		expect(stdoutJson()).toMatchObject({ ok: false, error: { code: "ULW_LOOP_PLAN_MISSING" } });
+		resetOutput();
+
+		process.env["PI_SESSION_ID"] = "session-A";
+		expect(await ulwLoopCommand(["status", "--json"])).toBe(0);
+		expect(stdoutJson()).toMatchObject({
+			plan: {
+				goalsPath: ".omo/ulw-loop/session-A/goals.json",
+				goals: [{ title: "Session A run" }],
+			},
+		});
+	});
+
 	it("#given a valueless --session-id #when creating goals #then it fails and writes no plan", async () => {
 		const code = await ulwLoopCommand(["create-goals", "--session-id", "--brief", "- Alpha"]);
 

package/packages/omo-codex/plugin/components/ulw-loop/test/cli-entrypoint.test.ts

@@ -91,12 +91,36 @@ describe("dist/cli.js entrypoint dispatch", () => {
 		expect(result.code).toBe(1);
 	});
 
-	it("#given the top-level entrypoint #when invoked with 'help' #then prints usage and exits 0", async () => {
+	it("#given the top-level entrypoint #when invoked with 'help' #then prints the merged hook and subcommand usage and exits 0", async () => {
 		const result = await runCli(["help"]);
 
 		expect(result.code).toBe(0);
 		expect(result.stdout).toContain("Usage:");
-		expect(result.stdout).toContain("omo-agent-toolkit ulw-loop <subcommand>");
+		expect(result.stdout).toContain("hook user-prompt-submit");
+		expect(result.stdout).toContain("create-goals");
+		expect(result.stdout).toContain("complete-goals");
+		expect(result.stdout).toContain("record-review-blockers");
+		expect(result.stdout).not.toContain("for ulw-loop subcommands");
+	});
+
+	it("#given the staged router strips nothing #when invoked with 'ulw-loop help' #then prints the same merged help text", async () => {
+		const bare = await runCli(["help"]);
+		const nested = await runCli(["ulw-loop", "help"]);
+
+		expect(nested.code).toBe(0);
+		expect(nested.stdout.trim()).toBe(bare.stdout.trim());
+		expect(nested.stdout).toContain("hook user-prompt-submit");
+		expect(nested.stdout).toContain("record-review-blockers");
+		expect(nested.stdout).not.toContain("for ulw-loop subcommands");
+	});
+
+	it("#given a subcommand with required args #when invoked with 'create-goals --help' #then prints its usage and exits 0", async () => {
+		const result = await runCli(["create-goals", "--help"]);
+
+		expect(result.code).toBe(0);
+		expect(result.stdout).toContain("Usage:");
+		expect(result.stdout).toContain("create-goals");
+		expect(`${result.stdout}${result.stderr}`).not.toContain("Missing brief text");
 	});
 
 	it("#given a command outside the ulw-loop vocabulary #when invoked with 'frobnicate' #then fails as unknown command", async () => {

package/packages/omo-codex/plugin/components/ulw-loop/test/codex-goal-instruction.test.ts

@@ -113,9 +113,9 @@ describe("buildCodexGoalInstruction aggregate mode", () => {
 
 describe("buildCodexGoalInstruction per_story mode", () => {
 	it("uses the goal's own objective for create_goal", () => {
-		const goal = makeGoal({ objective: "Build the auth service" });
+		const goal = makeGoal({ objective: "per-story-objective-sentinel" });
 		const { text } = buildCodexGoalInstruction({ plan: makePlan({ codexGoalMode: "per_story" }), goal });
-		expect(text).toContain("Build the auth service");
+		expect(text).toContain("per-story-objective-sentinel");
 	});
 });