omp-headless-orchestration
Skill3 starsChanged 53 days agoMITView on GitHub
Run long OMP (`omp -p`) jobs headlessly so they survive the session that dispatched them — detached tmux, NDJSON event log, polled completion, session-id recovery. Use when delegating a repo task that will run more than a couple of minutes, when the orchestrating chat/session may restart, or when recovering a run that was killed mid-turn. Do not use for a two-minute command (run it inline) or for work that needs live steering (that is a TUI session).
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-harness-settings-paritySkill
- agent-operating-contract-evolutionSkill
- ai-coding-agent-delegationSkill
- arch-improvement-planSkill
- contract-bound-deliverablesSkill
- cross-agent-repair-routingSkill
- define-goalSkill
- delegated-work-acceptanceSkill
- design-an-interfaceSkill
- design-mdSkill
- discord-rich-messageSkill
- dotnet-repo-workflowSkill
- evidence-backed-analytical-writingSkill
- evidence-boundary-disciplineSkill
- find-nearbySkill
- gddSkill
- generated-runtime-repairsSkill
- ghc-searchSkill
- git-auto-sync-pipelinesSkill
- github-code-reviewSkill
- github-repo-managementSkill
- grounded-citationsSkill
- harness-engineeringSkill
- hermes-context-file-loadingSkill
- hermes-modelsSkill
- hermes-updatesSkill
- hoa-introspect-distillSkill
- hoa-introspectSkill
- hoa-skill-reviewSkill
- hoa-skill-workSkill
- html-artifactSkill
- jupyter-live-kernelSkill
- kanban-workflowsSkill
- m365-copilot-cdpSkill
- measurement-campaign-evidenceSkill
- microsoft-officeSkill
- notes-to-prdSkill
- ocr-and-documentsSkill
- official-document-verificationSkill
- ops-claim-verificationSkill
- package-release-verificationSkill
- plan-to-issuesSkill
- project-phase-closeoutSkill
- report-claim-auditSkill
- research-stream-consolidationSkill
- review-revision-candidatesSkill
- rss-feedsSkill
- skill-library-curationSkill
- skill-porting-and-publishingSkill
- spec-convergenceSkill
- structural-validity-gatesSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- teams-cdpSkill
- tmux-agent-controlSkill
- whisperSkill
- writing-plansSkill
- writingSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 70
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 …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
OMP headless orchestration
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
-pand 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):
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 (scripts/adapters/omp-run.py, cross-platform,
with 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=jsongives 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)
--restore("continue the interrupted turn") requires a TTY: it fails withopen terminal failed: not a terminalunder-p. Headless recovery isomp -r <session-id> -p "<hand-written continuation prompt>".-pemits nothing until exit. Without--mode=jsona long run is a black box and a kill costs everything: always tee the event stream.- 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
-9and looks like an OOM. Serialize heavy steps and say so in the prompt. - 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. -c/ "continue last session" is ambiguous when lanes run in parallel — always pass an explicit session id (-r <id>).- 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.idwithin 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. - 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.
- 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.
- Judge liveness from
state.json/tmux has-session, never fromps | 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 instate.json. - A tmux-hosted run has no completion notification. Nothing pings you when it ends: poll
omp-run.sh status <slug>at turn boundaries, and treatstateleavingrunning(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 timestatus/list/result/answerreads it; a state file stuck atrunningis not evidence that the work is alive — readfinalizedor thestale_recoveredflag. exit=0means 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. Readanswer.mdfor 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.- Never
omp-run.sh taila 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. Pollstatus <slug>for liveness and readanswer.md(orresult <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. state.jsonis 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. Readstate,exit,duration_s,cwdandrun_dirdefensively; treat everything else as optional.--max-timetakes one unit only.omp --max-time 1h30mexits 2 before any work withInvalid --max-time value, leaving a 0-byteanswer.mdand an empty event log — which reads like an instant crash, not a rejected flag. Use90m,2hor plain seconds. The wrapper does not validate this, so readstderr.logbefore blaming the prompt or the repo.- 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&/nohupwith 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 skillgdd→references/run-failure-modes.md§8.
Recovery after a session restart
scripts/omp-run.sh list # GONE = crashed/killed, shows the resume idThen 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

