oh-my-opencode 4.9.2 → 4.11.0

package/.agents/skills/codex-qa/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: codex-qa
+description: "QA the omo Codex Light edition (lazycodex / packages/omo-codex) itself, in strict isolation so ONLY our plugin is exercised, never the user's real ~/.codex. The first-party method drives the real `codex app-server` against an isolated CODEX_HOME plus a LOCAL mock model (no real API call), and proves a plugin hook fired by asserting hook/started + hook/completed notifications. Also: isolated install verification, per-component hook probes, a tmux TUI smoke, and runtime log observation (RUST_LOG / logs SQLite / /debug-config). Ships tested helper scripts each with a --self-test. Use whenever someone changes anything under packages/omo-codex or wants to QA, smoke-test, verify, or debug the Codex plugin, its hooks/components, the installer/config.toml, the app-server flow, or the Codex TUI. Triggers: codex qa, qa codex, codex-qa, test codex plugin, verify codex hook, codex app-server, lazycodex qa, isolated CODEX_HOME, prove codex hook fired, codex tui test."
+---
+
+# Codex QA
+
+QA the omo Codex Light edition (`packages/omo-codex/`, shipped as lazycodex). We
+exercise OUR plugin in a REAL Codex while touching nothing of the user's setup:
+an isolated `CODEX_HOME` + a local mock model means no real API call and the real
+`~/.codex` is never read or written. Each helper script ships a `--self-test`
+that asserts its scenario against the live machine, so the scripts are both the
+QA tools and their own regression checks.
+
+Verified against `codex-cli 0.140.0` (node, jq, tmux, bun on macOS). Confirm with
+`codex --version`; check a flag with `codex <cmd> --help`.
+
+## Golden rules (read before running anything)
+
+- **QA ONLY our plugin.** Everything that spawns codex uses an isolated
+  `CODEX_HOME` (created by `cqa_mk_isolated_home`) and a LOCAL mock model
+  provider (`cqa_start_mock`). Never QA against the real `~/.codex`, never hit a
+  real model API. The bundled scripts enforce this; if you run codex by hand,
+  `export CODEX_HOME="$(mktemp -d)/codex"; mkdir -p "$CODEX_HOME"` FIRST (a set
+  `CODEX_HOME` must already exist or codex hard-errors).
+- **Prove the real home stayed clean.** Every script shasums
+  `~/.codex/config.toml` before and after and asserts it is unchanged. If you
+  script by hand, do the same.
+- **The interactive `codex` is a shell function** that injects `--profile quotio`.
+  Bash scripts bypass it and get the real binary; never rely on the interactive
+  alias. See [references/isolation.md](references/isolation.md).
+- **The first-party way to prove a hook fired is the app-server** notification
+  stream (`hook/started` / `hook/completed`), not log scraping. See
+  [references/app-server.md](references/app-server.md).
+- **The captured JSON / pane IS the evidence** — write it under
+  `.omo/evidence/<YYYYMMDD>-<slug>/` (no evidence file == the QA did not happen).
+
+## Setup
+
+```bash
+cd <this-skill-dir>                        # .agents/skills/codex-qa
+bash scripts/lib/common.sh --self-check    # confirm deps + isolation harness
+```
+
+**Docker is the default QA surface.** Run this QA inside a disposable container
+that has the latest codex and a copy of your config, with the host `~/.codex`
+untouched: `script/agent/qa-docker.sh` (see [references/docker-qa.md](references/docker-qa.md)).
+The local scripts below are the fallback for when Docker is unavailable or on
+Windows.
+
+## Router: pick your case
+
+| You need to… | Run | Deep dive |
+|---|---|---|
+| Prove a plugin hook fires in a LIVE Codex turn (first-party) | `scripts/app-server-drive.sh --plugin` | [app-server.md](references/app-server.md) |
+| Prove the app-server driver itself works (no plugin, fast) | `scripts/app-server-drive.sh --self-test` | [app-server.md](references/app-server.md) |
+| Install the LOCAL build into an isolated home + assert it landed | `scripts/install-verify.sh --self-test` | [install-verify.md](references/install-verify.md) |
+| Pin ONE component's hook logic deterministically (no codex) | `scripts/hook-unit-probe.sh --self-test` | [components-hooks.md](references/components-hooks.md) |
+| Smoke the real TUI under tmux (boots, renders, survives) | `scripts/tui-smoke.sh --self-test` | [logging-debug.md](references/logging-debug.md) |
+| Watch runtime logs while QAing | (see reference; RUST_LOG / logs DB / `/debug-config`) | [logging-debug.md](references/logging-debug.md) |
+
+## Scripts index (each is its own regression test)
+
+| Script | `--self-test` asserts |
+|---|---|
+| `scripts/lib/common.sh --self-check` | deps present; isolated `CODEX_HOME` is created inside a sandbox and auto-removed on exit; mock model serves the Responses SSE; real `~/.codex` unchanged |
+| `scripts/app-server-drive.sh` | `--self-test`: a bare turn completes and the mock assistant text comes back. `--plugin`: installs local omo, drives a turn, and asserts `hook/completed` for `sessionStart,userPromptSubmit` |
+| `scripts/install-verify.sh` | local omo installs into the isolated home; `config.toml` enables `omo@sisyphuslabs`; component bins + agent TOMLs linked in the sandbox; real `~/.codex` unchanged |
+| `scripts/hook-unit-probe.sh` | the `ultrawork` component injects `<ultrawork-mode>` on an `ulw` UserPromptSubmit (also a manual `--component/--event` mode) |
+| `scripts/tui-smoke.sh` | the real codex TUI boots in the isolated home, renders, and survives (no early exit); captures the pane |
+
+## Match QA to your change scope
+
+- **Component / hook logic** (`packages/omo-codex/plugin/components/*`):
+  `hook-unit-probe.sh` for the exact stdout, THEN `app-server-drive.sh --plugin`
+  to prove the live wiring. See [components-hooks.md](references/components-hooks.md).
+- **Installer / config.toml** (`packages/omo-codex/src/install/*`):
+  `install-verify.sh`.
+- **Anything that affects a live session** (hooks, agents, MCP wiring):
+  `app-server-drive.sh --plugin`, and `tui-smoke.sh --plugin` if the TUI path
+  matters.
+
+## Capturing evidence
+
+```bash
+ev=".omo/evidence/$(date +%Y%m%d)-codex-qa-<slug>"; mkdir -p "$ev"
+bash scripts/app-server-drive.sh --plugin > "$ev/app-server-drive.json" 2>&1
+bash scripts/install-verify.sh --self-test > "$ev/install-verify.txt" 2>&1
+```
+
+## On `/debugging`
+
+There is no `/debugging` command in Codex. To observe a run: the app-server
+notification stream (above), `RUST_LOG=debug` on the app-server's stderr, the
+logs SQLite under `$CODEX_HOME`, the TUI's `/debug-config`, and the
+`codex debug …` subcommands. See [logging-debug.md](references/logging-debug.md).

package/.agents/skills/codex-qa/references/app-server.md

@@ -0,0 +1,63 @@
+# Codex app-server — the first-party QA channel
+
+The app-server is how a host (IDE, our QA harness) drives Codex programmatically.
+We speak its protocol directly so we can read the **structured notification
+stream** — including `hook/started` / `hook/completed`, which is the
+authoritative proof that an omo plugin hook fired in a live turn.
+
+Verified against `codex-cli 0.139.0`. Source citations are `path:line` under
+`../codex/codex-rs/`.
+
+## Transport & framing
+
+- Start with `codex app-server` (no subcommand runs the server). Implemented by
+  the `codex-app-server` crate; entry `app-server/src/lib.rs:429`.
+- Default transport is **stdio**, framing is **newline-delimited JSON** (one
+  message per line) — `app-server-transport/src/transport/stdio.rs:46-88`.
+- It is NOT standard JSON-RPC 2.0: there is **no `"jsonrpc"` field**. Requests
+  are `{id, method, params}`; notifications are `{method, params}`
+  (`app-server-protocol/src/jsonrpc_lite.rs`). Field names are camelCase.
+
+Confirm the method set for the installed binary:
+
+```bash
+codex app-server generate-json-schema --out "$(mktemp -d)"   # ClientRequest.json / ServerNotification.json
+```
+
+## Drive one turn (the sequence the driver uses)
+
+```jsonc
+{"id":1,"method":"initialize","params":{"clientInfo":{"name":"codex-qa","version":"0.1.0"},"capabilities":{"experimentalApi":true,"requestAttestation":false}}}
+{"method":"initialized"}                                            // notification, REQUIRED, no id
+{"id":2,"method":"thread/start","params":{"cwd":"/abs/workdir"}}    // -> result.thread.id
+{"id":3,"method":"turn/start","params":{"threadId":"<id>","input":[{"type":"text","text":"say hello"}]}}  // -> result.turn.id
+```
+
+Read stdout line-by-line and collect:
+
+- `hook/started` / `hook/completed` — `params.run.eventName` (e.g. `sessionStart`,
+  `userPromptSubmit`, `stop`), `params.run.status` (`running` → `completed`),
+  `params.run.source` (`plugin`). **This is the plugin-fired proof.**
+- `item/completed` where `item.type == "agentMessage"` — `item.text` is the
+  assistant message.
+- `turn/completed` — stop when `turn.status == "completed"` (or `"failed"` with
+  `turn.error`) for your `turnId`.
+
+`scripts/lib/app-server-client.mjs` implements exactly this and exits non-zero
+unless the turn completes and every `EXPECT_HOOK` event reaches `completed`.
+
+## Why a mock model
+
+A turn needs a model. We point a custom `model_provider` at the local
+`scripts/lib/mock-model.mjs` (OpenAI Responses SSE), so the turn runs with NO
+real API call. A non-OpenAI provider needs no auth (`requires_openai_auth`
+defaults false). The driver injects the provider via `-c` overrides — see
+[isolation.md](./isolation.md).
+
+## Observed result on 0.139.0
+
+With omo installed in an isolated `CODEX_HOME`, one `ulw: say hello` turn emits
+`hook/*` for `sessionStart` (rules, telemetry, bootstrap, auto-update),
+`userPromptSubmit` (rules, ultrawork, ulw-loop), and `stop`
+(start-work-continuation), then the mock assistant message and `turn/completed`.
+`scripts/app-server-drive.sh --plugin` asserts this end to end.

package/.agents/skills/codex-qa/references/components-hooks.md

@@ -0,0 +1,38 @@
+# omo-codex components → events → observable proof
+
+The plugin's hook wiring lives in
+`packages/omo-codex/plugin/hooks/hooks.json`. Each hook runs
+`node "${PLUGIN_ROOT}/components/<c>/dist/cli.js" hook <event>`, reading the
+event JSON on stdin and writing zero-or-one line of JSON on stdout.
+
+Use this table to pick what to assert. Two proof tiers:
+
+- **Unit** (`hook-unit-probe.sh`): pipe a synthetic event into a component's
+  `dist/cli.js`, assert stdout/disk. Deterministic, no codex process.
+- **Live** (`app-server-drive.sh --plugin`): drive a real turn, assert the
+  `hook/completed` notification fires for the event. Proves Codex WIRES it.
+
+| Component | Codex events | Observable proof it fired |
+|---|---|---|
+| `rules` | SessionStart; UserPromptSubmit; PostToolUse `apply_patch`; PostCompact | `hookSpecificOutput.additionalContext` (rule body) on stdout; session cache at `$PLUGIN_DATA/sessions/<id>.json` |
+| `ultrawork` | UserPromptSubmit | stdout `additionalContext` contains `<ultrawork-mode>` **only** when prompt matches `/ultrawork|ulw/i`; empty otherwise |
+| `ulw-loop` | UserPromptSubmit; PreToolUse `create_goal` | steer JSON on a steer prompt; `permissionDecision:"deny"` when `create_goal` carries keys beyond `objective` |
+| `comment-checker` | PostToolUse (write/edit/apply_patch) | warning text on stdout when an edited file has banned comments; empty when clean |
+| `lsp` | PostToolUse (write/edit/apply_patch); PostCompact | LSP diagnostics as `additionalContext` for mutated files |
+| `start-work-continuation` | Stop; SubagentStop | `{"decision":"block","reason":...}` **only** when a continuation/boulder state exists for the session |
+| `git-bash` | PreToolUse `Bash`; PostCompact | **Windows-only**: reminder + marker `$PLUGIN_DATA/git-bash-reminder/<id>.seen`; no-op elsewhere |
+| `telemetry` | SessionStart | empty stdout; side effect is a PostHog event (or a diagnostic file on failure) |
+| `bootstrap` | SessionStart | `BOOTSTRAP_RESTART_NOTICE` additionalContext on first run (gated on `PLUGIN_ROOT`+`PLUGIN_DATA`) |
+
+Many components are **conditional** (only emit on a matching prompt / OS / state).
+For a stable always-fires assertion, prefer:
+
+- Live: `sessionStart` and `userPromptSubmit` `hook/completed` (several components
+  wire them, so the events always fire). `app-server-drive.sh --plugin` defaults
+  to `--expect sessionStart,userPromptSubmit`.
+- Unit: `ultrawork` on an `ulw` prompt deterministically injects `<ultrawork-mode>`.
+
+`hook/*` notification eventNames are camelCase (`sessionStart`,
+`userPromptSubmit`, `postToolUse`, `stop`, …); the hooks.json matchers use
+snake_case (`session_start`, `user_prompt_submit`, …). The component CLI takes
+the kebab form (`hook user-prompt-submit`).

package/.agents/skills/codex-qa/references/docker-qa.md

@@ -0,0 +1,62 @@
+# Docker QA (default path)
+
+Run Codex QA inside a DISPOSABLE container so the real `~/.codex` is never
+touched and you always test against the latest codex. The container is the
+sandbox: latest released codex (and opencode) are baked in, a COPY of your
+config is loaded, and the container is removed on exit (`docker run --rm`). This
+is the DEFAULT; fall back to running the scripts locally (see SKILL.md) only
+when Docker is unavailable or on Windows.
+
+## Use it
+
+`qa-docker.sh` brings up a disposable box (builds `omo-dev` then `omo-qa` on
+first use, reused after) and drops you into it. From the repo root:
+
+```bash
+# drive codex via the FIRST-PARTY app-server (no acp): a real turn in the box
+script/agent/qa-docker.sh codex
+
+# fallback: the interactive codex TUI in the box (uses your mounted config)
+script/agent/qa-docker.sh codex --tui
+
+# a shell inside the box: codex (and opencode) are on PATH
+script/agent/qa-docker.sh
+script/agent/qa-docker.sh shell
+
+# one-off command, or a codex-qa self-test inside the box:
+script/agent/qa-docker.sh exec codex --version
+script/agent/qa-docker.sh exec bash .claude/skills/codex-qa/scripts/tui-smoke.sh --self-test
+
+script/agent/qa-docker.sh --clean   # remove the QA images
+```
+
+`omo-qa` is `omo-dev` (`.devcontainer/Dockerfile`) plus the latest `@openai/codex`
+and `opencode-ai` npm packages and `sqlite3 jq curl rsync`.
+
+## Isolation still applies inside
+
+The codex-qa scripts already isolate via an mktemp `CODEX_HOME` and a local mock
+model (no real API call). In Docker that runs inside a throwaway container too,
+so there are two layers: the scripts never touch the mounted real `~/.codex`,
+and the container is discarded on exit. `qa-docker.sh` mounts `~/.codex`
+READ-ONLY at `/mnt/host/codex`; the entrypoint copies it into the container's
+writable home for any case that wants the real config. The host `~/.codex`
+(including `config.toml`) is never written.
+
+## Credentials
+
+codex-qa uses a mock model, so no real key is needed for the first-party hook
+proof. For runs that do need auth, provide it at run time only: a gitignored
+`.env` / `.env.local`, Codespaces secrets, or the devcontainer `remoteEnv`
+passthrough - never baked into the image.
+
+## Fallback: local / Windows
+
+`qa-docker.sh` exits 3 with guidance when Docker is unavailable or on Windows;
+run the scripts directly on the host there (they isolate via mktemp
+`CODEX_HOME`). Windows has no Docker QA path here by design.
+
+## Cleanup
+
+Each run auto-removes its container (`--rm`). The `omo-dev` / `omo-qa` images
+persist for fast re-runs; drop them with `script/agent/qa-docker.sh --clean`.

package/.agents/skills/codex-qa/references/install-verify.md

@@ -0,0 +1,57 @@
+# Installing the LOCAL omo build into an isolated CODEX_HOME
+
+QA must run THIS repo's local build, not the published package. The installer
+respects `CODEX_HOME` for everything, so a non-default home is fully self
+contained.
+
+## Command
+
+```bash
+export CODEX_HOME="$(mktemp -d)/codex"; mkdir -p "$CODEX_HOME"   # must exist first
+export OMO_DISABLE_POSTHOG=1 OMO_CODEX_DISABLE_POSTHOG=1
+export OMO_CODEX_PROJECT="$(mktemp -d)/project"                  # keep project-local cleanup off your tree
+node packages/omo-codex/scripts/install-local.mjs install
+```
+
+`cqa_install_local_omo` wraps this (logs to `$CQA_HOME_ROOT/install.log`).
+
+## What it writes (all under CODEX_HOME)
+
+Source: `packages/omo-codex/src/install/install-codex.ts`.
+
+1. Builds + copies the plugin to
+   `$CODEX_HOME/plugins/cache/sisyphuslabs/omo/<version>/` (then `npm ci --omit=dev`).
+2. Links component bins into `$CODEX_HOME/bin/omo-*` (8: comment-checker,
+   git-bash-hook, lsp, rules, start-work-continuation, telemetry, ultrawork,
+   ulw-loop).
+3. Links agent TOMLs into `$CODEX_HOME/agents/*.toml`.
+4. Writes a marketplace snapshot under `$CODEX_HOME/.tmp/marketplaces/sisyphuslabs/`.
+5. Edits `$CODEX_HOME/config.toml`: enables `[plugins."omo@sisyphuslabs"]`,
+   the `[marketplaces.sisyphuslabs]` local source, `[features]`
+   (plugins/plugin_hooks/multi_agent/child_agents_md), and one
+   `[hooks.state."omo@sisyphuslabs:hooks/hooks.json:<event>:i:j"] trusted_hash`
+   per hook (so Codex trusts them — no `--dangerously-bypass-hook-trust` needed
+   for the app-server turn).
+
+## Assertions (what install-verify.sh checks)
+
+```bash
+ls "$CODEX_HOME"/plugins/cache/sisyphuslabs/omo/*/                 # cache present
+grep -A2 '\[plugins."omo@sisyphuslabs"\]' "$CODEX_HOME/config.toml" | grep 'enabled = true'
+ls "$CODEX_HOME"/bin/omo-*                                          # component bins
+ls "$CODEX_HOME"/agents/*.toml                                      # agent links
+```
+
+Plus the cross-cutting invariant every script enforces: the real
+`~/.codex/config.toml` shasum is unchanged.
+
+## Notes
+
+- The only thing outside CODEX_HOME is the `omo` runtime wrapper, which targets
+  the repo's `dist/cli/index.js` (the CLI ships from the repo). `dist/cli/index.js`
+  must exist (run `bun run build` if missing) or that link is skipped.
+- Cleanup: for an isolated home just `rm -rf "$CODEX_HOME"` (the harness does
+  this on exit). For a normal home, `node packages/omo-codex/scripts/install-local.mjs uninstall`.
+- `bun run test:codex` is the hermetic unit gate (installer/config/component
+  build) and does NOT launch a real codex — this skill is what proves the live
+  session.

package/.agents/skills/codex-qa/references/isolation.md

@@ -0,0 +1,57 @@
+# Isolation — QA ONLY our plugin, never the user's real Codex
+
+The whole point of this skill: exercise the omo plugin in a real Codex without
+reading or writing the user's `~/.codex`, and without a real model API call. Two
+levers do all the work.
+
+## Lever 1 — an isolated `CODEX_HOME`
+
+`CODEX_HOME` is Codex's master state root: `config.toml`, `auth.json`, sessions,
+the state SQLite, plugins, and logs all hang off it (`utils/home-dir/src/lib.rs`).
+Point it at a fresh temp dir and Codex reads/writes nothing else.
+
+Gotcha: when `CODEX_HOME` is set it **must already exist** or Codex hard-errors.
+`cqa_mk_isolated_home` creates it first.
+
+`cqa_mk_isolated_home` also exports:
+
+- `OMO_CODEX_PROJECT` + `QA_CWD` → a sandbox project dir, so the installer's
+  project-local cleanup and the TUI's cwd never touch your real tree.
+- `CODEX_LOCAL_BIN_DIR=$CODEX_HOME/bin` → component bins land in the sandbox.
+  (Even without this, a non-default `CODEX_HOME` already routes bins to
+  `$CODEX_HOME/bin`; with the DEFAULT home they would leak to `~/.local/bin`.)
+- `OMO_DISABLE_POSTHOG=1` + `OMO_CODEX_DISABLE_POSTHOG=1` → no install/telemetry
+  network call.
+
+Proof it stayed clean: `cqa_guard_real_home` shasums `~/.codex/config.toml`
+before, `cqa_assert_real_home_unchanged` re-checks after. Every script runs it.
+
+## Lever 2 — a local mock model (no real API)
+
+Codex must reach a model to run a turn. Instead of OpenAI, we run
+`scripts/lib/mock-model.mjs` (OpenAI **Responses** SSE) on localhost and point a
+custom provider at it via `-c` overrides:
+
+```
+-c model="mock-model"
+-c model_provider="mock_provider"
+-c model_providers.mock_provider.name="codex-qa mock"   # REQUIRED: empty name fails config load
+-c model_providers.mock_provider.base_url="http://127.0.0.1:<PORT>/v1"
+-c model_providers.mock_provider.wire_api="responses"
+-c approval_policy="never"
+-c sandbox_mode="read-only"
+```
+
+A non-OpenAI provider needs no key/auth, so there is no real egress. `-c`
+overrides beat any value in `config.toml`, so even a misconfigured isolated home
+still lands on the mock.
+
+## The `codex` shell-function trap
+
+The interactive shell here wraps `codex` in a function that injects
+`--profile quotio` (sparkshell). That breaks non-runtime subcommands like
+`generate-json-schema` and would point a turn at the quotio provider. **Bash
+scripts do not inherit that function**, so `codex` inside a `#!/usr/bin/env bash`
+script is the real binary on PATH. `cqa_codex_bin` resolves it explicitly; never
+rely on the interactive alias. Combined with the isolated `CODEX_HOME`, the real
+quotio config is never read.

package/.agents/skills/codex-qa/references/logging-debug.md

@@ -0,0 +1,60 @@
+# Observing Codex at runtime (logs + debug surfaces)
+
+The intent "use `/debugging` to watch logs while QAing" maps to the surfaces
+below. Codex has **no `/debugging` command**; these are the real ways to observe
+a run.
+
+## 1. The notification stream (best signal for plugin QA)
+
+When you drive via the app-server, the stdout stream IS the live trace:
+`hook/started` / `hook/completed`, `item/*`, `mcpServer/*`, `error`, `warning`.
+This is structured and assertion-grade — prefer it over scraping text logs.
+`scripts/app-server-drive.sh` captures it; the JSON summary it prints is the
+evidence.
+
+## 2. app-server stderr (`RUST_LOG`)
+
+The app-server writes tracing logs to **stderr** (not a file), filtered by
+`RUST_LOG` (`app-server/src/lib.rs:638-651`). Turn it up and capture:
+
+```bash
+RUST_LOG=info   # or debug
+LOG_FORMAT=json # optional: machine-parseable lines
+```
+
+The driver inherits the env; raise `RUST_LOG` before invoking it to see the
+plugin/hook subprocess accounting on stderr (surfaced in the summary's
+`stderrTail`).
+
+## 3. The logs SQLite DB
+
+The app-server also writes structured logs to a SQLite DB under `$CODEX_HOME`
+(alongside `state_5.sqlite`). Query it post-run for a durable record:
+
+```bash
+ls "$CODEX_HOME"/*.sqlite
+```
+
+## 4. TUI `/debug-config`
+
+Inside the TUI, the slash command is **`/debug-config`** (NOT `/debugging`) —
+"show config layers and requirement sources" (`tui/src/slash_command.rs:107`).
+Useful to confirm which config layer enabled the plugin. Drive it under tmux:
+
+```bash
+tmux send-keys -t <sess> "/debug-config" Enter
+tmux capture-pane -t <sess> -p -S -
+```
+
+## 5. `codex debug` subcommands
+
+`codex debug models` (raw model catalog), `codex debug prompt-input` (the
+model-visible prompt list), and `codex debug app-server …` (a built-in
+app-server driver). Run them against the isolated `CODEX_HOME` for ad-hoc
+inspection.
+
+## Component-level logs
+
+`rules` emits phase/timing lines to stderr under `NODE_DEBUG=codex-rules`. Most
+components prove themselves through their stdout `additionalContext` or a disk
+artifact — see [components-hooks.md](./components-hooks.md).

package/.agents/skills/codex-qa/scripts/app-server-drive.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# app-server-drive.sh - FIRST-PARTY codex QA: drive a real `codex app-server`
+# turn against an ISOLATED CODEX_HOME + a LOCAL mock model, and read the
+# structured notification stream. This is how you prove the omo plugin behaves
+# in a live Codex session without scripting the TUI and without a real API call.
+#
+# Modes:
+#   --self-test   Bare isolated home (no plugin). Proves the driver works: a
+#                 turn runs and the assistant message comes back from the mock.
+#                 Fast; no install.
+#   --plugin      Install THIS repo's local omo build into the isolated home,
+#                 then drive a turn and PROVE the plugin hooks fire by asserting
+#                 hook/completed notifications for the expected events.
+#                 Heavier (runs install-local).
+#
+# Options (any mode):
+#   --prompt <text>    user message (default: "say hello"; --plugin defaults to
+#                      "ulw: say hello" so the ultrawork userPromptSubmit hook fires)
+#   --expect <ev,...>  hook eventNames that MUST complete (default in --plugin:
+#                      "sessionStart,userPromptSubmit")
+#   --keep             do not delete the isolated home (for inspection)
+#
+# The captured JSON summary IS the evidence; redirect it into .omo/evidence/.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/lib/common.sh"
+
+cqa_drive() {
+  local plugin="$1" prompt="$2" expect="$3"
+  cqa_require codex node jq || return 1
+  cqa_guard_real_home
+  cqa_mk_isolated_home
+  if [ "$plugin" = "1" ]; then
+    cqa_log "installing local omo build into $CODEX_HOME (this builds the plugin)..."
+    if ! cqa_install_local_omo; then
+      cqa_log "install failed; tail:"; tail -20 "$CQA_HOME_ROOT/install.log" >&2 2>/dev/null
+      return 1
+    fi
+    grep -q 'omo@sisyphuslabs' "$CODEX_HOME/config.toml" || { cqa_fail "omo not enabled in isolated config.toml"; return 1; }
+  fi
+  cqa_start_mock || return 1
+  local out
+  out="$(EXPECT_HOOK="$expect" PROMPT="$prompt" DEADLINE_MS="${DEADLINE_MS:-90000}" \
+    node "$SCRIPT_DIR/lib/app-server-client.mjs")"
+  local rc=$?
+  printf '%s\n' "$out"
+  cqa_assert_real_home_unchanged || rc=1
+  if [ "$rc" -eq 0 ]; then
+    cqa_pass "app-server turn completed; assistant text: $(printf '%s' "$out" | jq -r '.assistantText')"
+    [ -n "$expect" ] && cqa_pass "hooks fired: $(printf '%s' "$out" | jq -r '[.hooks[]|select(.method=="hook/completed")|.eventName]|unique|join(", ")')"
+  else
+    cqa_log "missing hooks: $(printf '%s' "$out" | jq -rc '.missingHooks? // []')"
+  fi
+  return "$rc"
+}
+
+MODE="--self-test"; PROMPT=""; EXPECT=""; KEEP=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --self-test|--plugin) MODE="$1"; shift ;;
+    --prompt) PROMPT="$2"; shift 2 ;;
+    --expect) EXPECT="$2"; shift 2 ;;
+    --keep) KEEP=1; shift ;;
+    -h|--help) sed -n '2,33p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) cqa_log "unknown option: $1"; shift ;;
+  esac
+done
+
+if [ "$KEEP" = "1" ]; then trap - EXIT; fi
+
+if [ "$MODE" = "--plugin" ]; then
+  cqa_drive 1 "${PROMPT:-ulw: say hello}" "${EXPECT:-sessionStart,userPromptSubmit}"
+else
+  cqa_drive 0 "${PROMPT:-say hello}" "$EXPECT"
+fi
+exit $?

package/.agents/skills/codex-qa/scripts/hook-unit-probe.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# hook-unit-probe.sh - deterministic, binary-free proof that a single omo
+# component's hook logic fires. Pipes a synthetic Codex hook event (the exact
+# stdin shape Codex sends) into the component's cached dist/cli.js and asserts
+# its stdout - no codex process, no model, no network. Fast and exact.
+#
+# Use this to pin a specific component's behavior; use app-server-drive.sh
+# --plugin to prove the app-server actually WIRES that hook in a live turn.
+#
+#   --self-test                 install local omo (if needed), then assert the
+#                               ultrawork component injects <ultrawork-mode> on
+#                               an "ulw" UserPromptSubmit. (default)
+#   --component <name> --event <kebab-event> [--prompt <text>]
+#                               run an arbitrary component/event by hand against
+#                               an already-installed isolated CODEX_HOME ($CODEX_HOME).
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/lib/common.sh"
+
+cqa_plugin_root() {
+  ls -d "$CODEX_HOME"/plugins/cache/sisyphuslabs/omo/*/ 2>/dev/null | head -1
+}
+
+cqa_run_component() {
+  local comp="$1" event="$2" prompt="$3" root cli
+  root="$(cqa_plugin_root)"; [ -n "$root" ] || { cqa_fail "no installed omo under $CODEX_HOME"; return 1; }
+  cli="$root/components/$comp/dist/cli.js"
+  [ -f "$cli" ] || { cqa_fail "component cli missing: $cli"; return 1; }
+  local payload
+  payload="$(jq -nc --arg p "$prompt" --arg cwd "${QA_CWD:-$PWD}" \
+    '{hook_event_name:"UserPromptSubmit",prompt:$p,cwd:$cwd,session_id:"cqa-unit",model:"mock-model"}')"
+  printf '%s' "$payload" | PLUGIN_ROOT="$root" PLUGIN_DATA="$CODEX_HOME/plugins/data/omo-$comp" node "$cli" hook "$event"
+}
+
+cqa_self_test() {
+  cqa_require codex node jq || return 1
+  cqa_guard_real_home
+  cqa_mk_isolated_home
+  cqa_log "installing local omo into $CODEX_HOME ..."
+  cqa_install_local_omo || { tail -20 "$CQA_HOME_ROOT/install.log" >&2; return 1; }
+  local out
+  out="$(cqa_run_component ultrawork user-prompt-submit "ulw: do the thing")"
+  cqa_assert_real_home_unchanged || return 1
+  if printf '%s' "$out" | jq -e '.hookSpecificOutput.additionalContext | test("ultrawork-mode")' >/dev/null 2>&1; then
+    cqa_pass "ultrawork UserPromptSubmit injected <ultrawork-mode> on an ulw prompt"
+    return 0
+  fi
+  cqa_log "FAIL: ultrawork did not inject ultrawork-mode; got: $out"; return 1
+}
+
+MODE="self"; COMP=""; EVENT=""; PROMPT="ulw: do the thing"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --self-test) MODE="self"; shift ;;
+    --component) MODE="manual"; COMP="$2"; shift 2 ;;
+    --event) EVENT="$2"; shift 2 ;;
+    --prompt) PROMPT="$2"; shift 2 ;;
+    -h|--help) sed -n '2,18p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) cqa_log "unknown option: $1"; shift ;;
+  esac
+done
+
+if [ "$MODE" = "manual" ]; then
+  [ -n "$COMP" ] && [ -n "$EVENT" ] || { cqa_log "manual mode needs --component and --event"; exit 2; }
+  cqa_run_component "$COMP" "$EVENT" "$PROMPT"
+  exit $?
+fi
+cqa_self_test
+exit $?

package/.agents/skills/codex-qa/scripts/install-verify.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# install-verify.sh - install THIS repo's local omo build into an ISOLATED
+# CODEX_HOME and prove it landed correctly while the real ~/.codex is untouched.
+#
+# Asserts: plugin cache dir exists, config.toml enables omo@sisyphuslabs, the
+# component bins + agent TOMLs linked inside the sandbox, and the real
+# ~/.codex/config.toml shasum is unchanged.
+#
+#   --self-test   run the full isolated install + assertions (default)
+#   --keep        keep the isolated home and print its path for inspection
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/lib/common.sh"
+
+cqa_install_verify() {
+  cqa_require codex node || return 1
+  cqa_guard_real_home
+  cqa_mk_isolated_home
+  cqa_log "installing local omo into $CODEX_HOME ..."
+  if ! cqa_install_local_omo; then
+    cqa_log "install failed; tail:"; tail -25 "$CQA_HOME_ROOT/install.log" >&2 2>/dev/null
+    return 1
+  fi
+  local fails=0
+  if ls "$CODEX_HOME"/plugins/cache/sisyphuslabs/omo/*/ >/dev/null 2>&1; then
+    cqa_pass "plugin cache present ($(ls "$CODEX_HOME"/plugins/cache/sisyphuslabs/omo/ | head -1))"
+  else cqa_log "FAIL: plugin cache missing"; fails=$((fails+1)); fi
+
+  if grep -q '\[plugins."omo@sisyphuslabs"\]' "$CODEX_HOME/config.toml" 2>/dev/null \
+     && grep -A2 '\[plugins."omo@sisyphuslabs"\]' "$CODEX_HOME/config.toml" | grep -q 'enabled = true'; then
+    cqa_pass "config.toml enables omo@sisyphuslabs"
+  else cqa_log "FAIL: omo not enabled in isolated config.toml"; fails=$((fails+1)); fi
+
+  if ls "$CODEX_HOME"/bin/omo-* >/dev/null 2>&1; then
+    cqa_pass "component bins linked in sandbox ($(ls "$CODEX_HOME"/bin/omo-* | wc -l | tr -d ' ') bins)"
+  else cqa_log "FAIL: no component bins under $CODEX_HOME/bin"; fails=$((fails+1)); fi
+
+  if [ -d "$CODEX_HOME/agents" ] && ls "$CODEX_HOME"/agents/*.toml >/dev/null 2>&1; then
+    cqa_pass "agent TOMLs linked in sandbox"
+  else cqa_log "FAIL: no agent TOMLs under $CODEX_HOME/agents"; fails=$((fails+1)); fi
+
+  cqa_assert_real_home_unchanged || fails=$((fails+1))
+
+  [ "$KEEP" = "1" ] && cqa_log "kept isolated home: $CODEX_HOME"
+  if [ "$fails" -eq 0 ]; then cqa_pass "install-verify"; return 0; fi
+  cqa_log "install-verify had $fails failure(s)"; return 1
+}
+
+KEEP=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --self-test) shift ;;
+    --keep) KEEP=1; shift ;;
+    -h|--help) sed -n '2,11p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) cqa_log "unknown option: $1"; shift ;;
+  esac
+done
+[ "$KEEP" = "1" ] && trap - EXIT
+cqa_install_verify
+exit $?