gdd-route-omp · git:20261118.d4726de · 2026-11-18 · sha256 61141689f07a98ec

gdd-route-omp git:20261118.d4726deA

Immutable. This exact content never changes and is served at /api/v1/blob/61141689f07a98ec.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_pc3qmvaqpu6bohpk/61141689f07a98ec9933e6a9b02235d5090a9c15218a93d2ecee9a8ea08f0f0d.json

Then /plugin install gdd-route-omp@markdownregistry-pc3qmvaqpu6bohpk in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: gdd-route-omp
description: >-
  Use when delegating a repo task to OMP (`omp -p`) that will run more than a couple of minutes —
  standalone or as `gdd`'s OMP route — when the orchestrating chat/session may restart, or when
  recovering a run that was killed mid-turn. Runs it headlessly so it survives the session that
  dispatched it: detached tmux, NDJSON event log, polled completion, session-id recovery. Do not use
  for a two-minute command (run it inline) or for work that needs live steering (that is a TUI session).
metadata:
  revision: "1"
  areas: "software-development,work-management"
  targets: "pi"
  summary: "detached tmux launcher for long `omp -p` runs; polled completion, session-id recovery"
  summary_zh: "脱离会话的 tmux 启动器跑 `omp -p` 长任务;轮询完成、按 session id 恢复"
  kind: "entry"
---

# gdd-route-omp

Delegate bounded work to OMP (`omp -p`) without losing runs when the dispatching session, gateway or
terminal goes down.

## When to Use

- Delegating a repo task to OMP that will run longer than a couple of minutes.
- You are working from chat (Discord/Slack) and cannot watch a terminal, but the run must not die when
  the session ends.
- Recovering an OMP run that was killed mid-turn (needs its session id).
- Deciding between headless `-p` and an attachable tmux TUI.

## Rule: never launch OMP as a bare background job of the session

A background child of the orchestrating session receives SIGTERM when that session ends, and `omp -p`
prints only at exit — a run killed at minute 37 leaves a 0-byte output file. Always launch through the
launcher shipped with this skill (a detached process: own session on POSIX, one hidden console on
Windows; `--backend tmux` when you want a session you can attach to):

```bash
scripts/omp-run.sh start --name <slug> --prompt <file> --cwd <repo> \
  [--resume <session-id>] [--model M] [--thinking L] [--max-time 3h] [--extra "--no-tools"]
scripts/omp-run.sh list | status <slug> | tail <slug> 20 | result <slug> | answer <slug> | kill <slug>
```

A detached run hangs off init (POSIX) or off the process tree Windows keeps alive on its own, not off
your session, so it survives session and gateway restarts. Verify with the ancestor chain of the omp
pid, not by assumption.

The implementation is maintained once, with skill `gdd` (`../gdd/scripts/adapters/omp-run.py`,
cross-platform, with `../gdd/scripts/adapters/omp-run.sh` beside it as the POSIX reference), because that skill's `gdd.py` defaults to
it; the copy here (`scripts/omp-run.sh`) is a forwarder, so manual and dispatched runs share one code
path.

## Why headless (not TUI)

- Headless output is a machine-checkable artifact; you can work from chat and attach to a TUI only for
  rare manual intervention.
- A TUI in tmux loses information when the pane scrolls or the client detaches; the NDJSON event log
  does not.
- `--mode=json` gives live progress (`session`, `turn_start`, `message_start`,
  `tool_execution_start`, `message_update`, `message_end`, `turn_end`) — observability does not
  require a TUI.

## Pitfalls (each one observed in production)

1. `--restore` ("continue the interrupted turn") requires a TTY: it fails with
   `open terminal failed: not a terminal` under `-p`. Headless recovery is
   `omp -r <session-id> -p "<hand-written continuation prompt>"`.
2. `-p` emits nothing until exit. Without `--mode=json` a long run is a black box and a kill costs
   everything: always tee the event stream.
3. Never run a measurement/benchmark project concurrently with the full test suite on a host sized for
   one heavy job: the run dies as exit `-9` and looks like an OOM. Serialize heavy steps and say so in
   the prompt.
4. Approval must be resolved before launch: headless with the default approval mode blocks silently
   forever and no human sees the prompt. Use an explicit non-interactive approval mode (the wrapper
   passes `--approval-mode yolo`) **only** in repos with machine gates.
5. `-c` / "continue last session" is ambiguous when lanes run in parallel — always pass an explicit
   session id (`-r <id>`).
6. Budget by stage: a single implementation run costs 45–55 min, a review 15–30, a fix 10–25. Anything
   above ~30 min is a kill risk; resuming needs the session id, so the wrapper captures it into
   `session.id` within seconds of start. **A review/simplify stage that fans out sub-reviewers costs
   the sum, not one pass** (~5 parallel reviewers, 20–100k tokens each, 35–40 min, tens of MB of
   events) — budget that, and do not read its timeout as a hang.
7. Model and thinking effort are coupled per provider: the fast reasoning model needs its high effort
   setting, a fallback model usually needs a lower one. A wrong pairing degrades quality silently.
   Record the pairing your CLI needs and pass it explicitly — never inherit a default.
8. Headless only works when the result is falsifiable. Treat the agent's report as a claim; re-run the
   repo gates yourself (build, test, format, docs snippets, api baseline, examples) and read exit codes
   before committing.
9. **Judge liveness from `state.json` / `tmux has-session`, never from `ps | grep <shim path>`.**
   Package-manager shims (`mise`, `asdf`, `volta`) point at a different binary than the one running, so
   grepping the shim path reports a healthy run as dead — use the pid in `state.json`.
10. **A tmux-hosted run has no completion notification.** Nothing pings you when it ends: poll
    `omp-run.sh status <slug>` at turn boundaries, and treat `state` leaving `running` (not the tmux
    session vanishing) as the done signal. A run whose pane died with its process is finalized as
    failed (`recovered_stale: true`, exit `-1`) the next time `status`/`list`/`result`/`answer` reads
    it; a state file stuck at `running` is not evidence that the work is alive — read `finalized` or
    the `stale_recovered` flag.
11. **`exit=0` means the process ended, not that the task finished.** A run can end its turn while a
    long command is still in flight and report "waiting for the test gate" as its last text. Read
    `answer.md` for trailing wait language before treating the phase as done; the fix is a continuation
    run (`-r <session-id>` plus a prompt that names the remaining steps), not a fresh restart.
12. **Never `omp-run.sh tail` a JSON-mode run to "see what it is doing".** Each event carries the full
    prompt of every sub-agent the run spawned, so one tail call returns hundreds of KB and floods the
    context for no signal. Poll `status <slug>` for liveness and read `answer.md` (or `result <slug>`)
    for the outcome; if you truly need the event stream, filter it by event type and count
    (`grep -c tool_execution_start`), never print it.
13. **`state.json` is not schema-stable across the run lifecycle.** Keys present while running (event
    byte counts, pid) are dropped when the run finalizes, so a reader that indexes them crashes on a
    finished run. Read `state`, `exit`, `duration_s`, `cwd` and `run_dir` defensively; treat everything
    else as optional.
14. **`--max-time` takes one unit only.** `omp --max-time 1h30m` exits 2 before any work with
    `Invalid --max-time value`, leaving a 0-byte `answer.md` and an empty event log — which reads like
    an instant crash, not a rejected flag. Use `90m`, `2h` or plain seconds. The wrapper does not
    validate this, so read `stderr.log` before blaming the prompt or the repo.

15. **A run that says it "launched" its verification is not evidence.** Whether teardown takes
    backgrounded children with it is the launcher's cleanup contract, not a universal law: a launcher
    that terminates its cleanup group at finalize (`systemd-run`, `KillMode=control-group`) kills a gate
    left under `&` / `nohup` with no exit code anywhere, while one that merely returns may leave it
    running. Require the exit code before treating the verification as done — a gate awaited to
    completion is fine, a gate left behind is not. The stage-side rule lives in skill `gdd` →
    `references/run-failure-modes.md` §8.

16. **A model-endpoint restart window is a transport fault, not a model defect — and a report-only
    stage can hide it behind `exit 0`.** The endpoint that fronts the models restarts on a schedule
    the operator's runtime configuration declares — read that schedule from the configuration, never
    assume it. A lane dispatched inside the window fails with `ECONNREFUSED`: classify that as
    suspected transport, not as a model failure. Confirm the window, retry **once** against the same
    route, and on a second failure switch to another model in the pool or fall back to the primary
    route — a third attempt on the same assumption is wasted budget. The window is doubly easy to miss
    because a report-only stage (simplify / review) can still exit 0 with an empty or truncated
    `answer.md`; that is a suspected failure to re-verify, not a completed stage — read the artifact,
    not just the exit code (pitfalls 8 and 11 are the same rule at the run level).

## Recovery after a session restart

```bash
scripts/omp-run.sh list          # GONE = crashed/killed, shows the resume id
```

Then `omp-run.sh start --name <slug>-r2 --prompt <continuation> --resume <id>`.

Artifacts per run: `<run>/prompt.md`, `run.sh` (replayable), `events.ndjson`, `stderr.log`,
`state.json`, `exit.code`, `session.id`, `answer.md`. Ledger: `$OMP_LEDGER`
(default `<run_root>/ledger.tsv`).

## When a TUI is still right

Ambiguous scope, work needing mid-run steering, or the operator explicitly asking to watch:
`tmux new -d -s omp-<slug> 'omp --resume <id>'` and let them attach. Never run a TUI and a headless
process on the same session id.

## Related

Delivery-specific transport rules (one run per stage, no cross-increment resume, one run per worktree):
skill `gdd` → `references/transport.md`. That skill's `scripts/gdd.py` calls this
launcher through the same contract.