A control plane for Codex when scientific work outlives the conversation.
Large context expands the workspace. Govern Complex Research Runs gives Codex a durable compass, ledger, event loop, and finish line for scientific work that runs for hours, days, and many recovery cycles.
It sits above scripts, schedulers, data providers, and analysis code as an outcome-and-evidence contract. Scientific authority stays explicit and versioned. Project memory stays compact. Supervision follows changed evidence. Recovery preserves valid work. Completion states exactly what the run proved.
Scientific authority · Global project memory · Durable execution · Event-driven supervision · Evidence-led recovery · Verified completion
Install · Why it exists · Long context · Token benchmark · Core contract · Try it · Repository map
Paste this into Codex:
$skill-installer Install the Codex skill at the repository root of https://github.com/FAITH-CKJ/govern-complex-research-runs and name it govern-complex-research-runs.
Then start a fresh turn with:
$govern-complex-research-runs Govern this long scientific workflow through a verified, scope-qualified terminal state.
Run /skills to confirm discovery. Codex detects newly installed skills
automatically; restarting refreshes discovery. OpenAI documents standalone
skills, $skill-installer, repository sources, and local discovery paths in the
official Codex Skills guide.
One year. Two Codex Pro 20× accounts. Thousands of long-run decisions. One governance system.
This skill is the compressed result of a full year of high-intensity research work across two Codex Pro accounts, each with a 20× usage allowance.
I am a deeply committed Codex user: both accounts stayed busy across real scientific work, recovery, supervision, and iteration. I sometimes joke that I may be even more attached to Codex than Tibo.
The work spanned production-scale scientific pipelines: multi-stage computation, large public-data acquisition, cloud exports, expensive intermediate artifacts, process trees that outlived foreground calls, stale runtime state, context compaction, repeated recovery decisions, and close supervision across long stretches of execution.
Every hard lesson became a reusable control primitive. Repeated patch spirals became blocker signatures and tripwires. Lost global perspective became one authoritative project-memory digest. Wasteful status loops became changed-event delivery with cursors. Full restarts became identity-aware dependency cones. Ambiguous “done” became a scope-qualified terminal transaction.
The result is a field-tested governance layer that helps Codex design, audit, execute, monitor, recover, and close complex research runs with scientific rigor and operational momentum.
At the time of this release, OpenAI documents frontier models with a 1.05-million-token context window and a higher-cost tier for requests above 272K input tokens. See the current OpenAI model documentation.
That capacity is extraordinary: more code, protocols, logs, artifacts, tool results, and prior decisions can stay in reach. A year of long-run practice also exposed the next systems problem—keeping the right facts authoritative, the critical path visible, recovery bounded, and model attention invested in events that move the research forward.
A bigger window holds more history. This skill keeps the whole research program oriented.
| Long-context pressure observed in real runs | Governance primitive |
|---|---|
| The active stage narrows attention to a local problem | One compact project-memory digest preserves the objective, identities, validated frontier, critical path, blocker, and next action |
| The same failure attracts another patch and another review | Stable blocker signatures, review latches, bounded recovery budgets, and CONTROL_PATH_BUDGET_EXCEEDED redirect effort |
| Compaction or interruption weakens continuity | Durable state records the first unfinished valid DAG node, process/lease truth, event cursor, and legal terminal |
| Large logs and task tables repeatedly re-enter context | One local watcher emits compact changed events; Codex advances one cursor and reads the affected slice |
| Token use grows faster than validated scientific output | Each model intervention earns its cost through a validated artifact, changed blocker evidence, a shorter critical path, a recovery transition, or stronger terminal proof |
| Process exit, stage completion, and project completion blur together | terminal_scope_id gives every completion claim an exact scientific and operational scope |
The skill turns repeated supervision from raw-state replay into an evidence stream: admit the run once, persist the control plane, and move attention only when the evidence moves.
96 model turns · 12 paired traces · 4 governance scenarios · 576/576 correctness gates passed. The governed path used 18.4% less input, 35.6% less uncached input, and 31.1% less list-price-equivalent cost.
| Measured across all 12 paired traces | Full-snapshot supervision | Governed by this skill | Result |
|---|---|---|---|
| Full snapshot loads | 48 | 12 | 75.0% fewer |
| User-supplied state payload | 2,433,934 characters | 645,798 characters | 73.5% smaller |
| Model input | 3,621,226 tokens | 2,954,007 tokens | 18.4% fewer |
| Uncached input | 1,448,042 tokens | 931,863 tokens | 35.6% fewer |
| Cached-input share | 60.0% | 68.5% | +8.4 points |
| Model output | 9,154 tokens | 9,023 tokens | 1.4% fewer |
| List-price-equivalent cost | $6.84 | $4.72 | 31.1% lower |
| Six-gate answer quality | 288/288 | 288/288 | 100% both |
The first review pays for the governance contract. Every one of the 12 traces recovered that investment by review 2; from there, the advantage compounded.
flowchart LR
A["Review 1<br/>load the contract<br/>13.2% investment"] --> B["Review 2<br/>follow the first delta<br/>10.7% lighter"]
B --> C["Review 3<br/>evidence stream established<br/>23.4% lighter"]
C --> D["Review 4<br/>governance compounds<br/>31.5% lighter"]
Those are median per-review differences across all scenarios and repetitions. In the nine continuous-session traces, input at review 4 had grown 163.2% from admission under full-snapshot supervision, versus 52.9% with the skill.
Each cell reports the median saving across all three paired repetitions, followed by the full observed range.
| Scenario | What the model had to preserve | Four-review input saved | Uncached input saved | Equivalent cost saved | Final-review input saved |
|---|---|---|---|---|---|
| Steady progress | Validated frontier, identities, leases, and next DAG slice | 18.3% (17.8–19.0) | 29.5% (28.7–41.9) | 26.3% (25.0–35.1) | 31.4% (29.9–32.7) |
| Failure and recovery | Blocker signature, retry budget, preserved 001–096 frontier, and the 097–100 recovery cone | 17.9% (17.9–19.4) | 28.7% (20.0–69.9) | 25.5% (20.1–56.6) | 29.9% (29.9–34.2) |
| Terminal audit | 240/240 compute completion, pending attestations, orphaned lease, then scoped terminal commit | 18.3% (18.3–18.5) | 39.1% (31.7–39.8) | 33.2% (27.9–33.4) | 31.4% (30.1–31.6) |
| Context handoff | A fresh session rehydrated from durable memory instead of the raw task table and logs | 18.7% (18.2–19.1) | 38.1% (18.4–39.6) | 34.2% (17.8–35.8) | 40.4% (37.6–40.5) |
At the forced fresh-session handoff itself, compact rehydration used a median 30.4% less input. One review later, the median advantage reached 40.4%. Durable memory makes continuity cheaper precisely when ordinary conversational memory disappears.
Treat the four-review protocol as a 10-minute supervision window—one review every 2.5 minutes. The measured window replaces three repeated full-state loads with three changed-event packets.
| Supervision horizon | Full-snapshot path | Governed path | Full snapshots avoided |
|---|---|---|---|
| 10-minute protocol, 4 reviews | 4 full snapshots | 1 admission + 3 deltas | 3 of 4 |
| 10-hour linear projection, 240 reviews | 240 full snapshots | 1 admission + 239 deltas | 239 of 240 (99.6%) |
Projection scope: one review every 2.5 minutes with unchanged authority and identities. It scales protocol counts; the token and cost results above remain the directly measured quantities.
Every response was checked by a deterministic six-gate rubric: exact six-line shape, scientific missing-versus-zero boundary, validated frontier, correct critical-path action, blocker/lease risk, and legal terminal scope. Both paths passed all six gates on all 48 responses. The governed path delivered the same decision completeness with 1.4% fewer output tokens.
Benchmark method
- Run on 2026-08-25 with Codex CLI 0.149.1,
gpt-5.6-sol, low reasoning, read-only execution, zero tool calls, and a 100-word response ceiling; all 96 responses stayed within that ceiling. - The matrix contains steady progress, failure/recovery, terminal audit, and context-handoff scenarios, each repeated three times under both conditions.
- Both conditions received the same first snapshot: a 240-tile scientific DAG, 240 task rows, 160 recent log rows, fixed identities, lease truth, blocker state, and one exact terminal scope.
- Full-snapshot supervision received the complete current snapshot every review. The governed condition admitted it once, then consumed changed events through one digest and cursor. The handoff scenario opened a fresh session at review 3: one side reloaded the raw snapshot; the other rehydrated a compact digest.
- Paired conditions launched concurrently, with start order alternated. All 12 final paired traces are pooled; scenario cells report medians and ranges.
- Counts come directly from the documented Codex CLI
turn.completed.usageJSONL event: input, cached input, cache-write input, output, and reasoning output. The largest request was 118,983 input tokens. - Cost uses the published GPT-5.6 Sol rates—$4.00/M input, $0.40/M cached input, and $20.00/M output—from the OpenAI model page. The usage stream reported zero cache-write tokens; every request remained below the 272K long-context price threshold. This is a public-rate equivalent; Codex Pro continues to follow subscription-plan usage.
- The benchmark targets repeated long-run supervision. One-shot work optimizes for immediate execution and usually skips the admission layer.
| Capability | What becomes durable |
|---|---|
| Scientific authority | Estimands, populations, variables, formulas, scales, thresholds, exclusions, missing-value semantics, and evidence boundaries |
| Project memory | One compact authoritative digest for resume, supervision, handoff, and context compaction |
| Execution ownership | One coordinator owns the DAG, task identities, leases, retries, checkpoints, side effects, promotion, and terminal publication |
| Responsive supervision | Frequent model-free local sampling, immediate changed-event delivery, bounded Codex safety audits, and concise user updates |
| Recovery discipline | Cause, affected scope, disposition, blocker signature, retry budget, and the smallest valid dependency cone |
| Artifact truth | Content identity, schema, lineage, task key, atomic promotion, and reusable attestations |
| Completion proof | Reconciled workers, leases, remote jobs, manifests, artifacts, limitations, downstream work, and a precise terminal scope |
The skill separates five identities so operational improvements preserve valid science and presentation fixes stay inside the presentation cone:
| Identity | Owns |
|---|---|
authority_id |
scientific definitions and authoritative inputs |
computation_id |
value-relevant code, schemas, and configuration |
runtime_id |
environment, scheduler, workers, and monitoring |
validator_id |
attestation logic that judges outputs |
presentation_id |
adapters, tables, figures, and report mappings |
A scheduler repair advances runtime_id. An attestation repair advances
validator_id. A figure-field correction advances presentation_id. The
validated upstream frontier stays reusable whenever identity, content, schema,
task key, and lineage still agree.
The skill separates four clocks that long-run work often compresses into one polling interval:
| Clock | Role |
|---|---|
| Local watchdog | Samples process, heartbeat, logs, disk, quota, and progress frequently with zero model calls |
| Changed-event delivery | Wakes Codex immediately for anomalies, retries, transitions, throughput shifts, and approaching terminals |
| Codex safety-audit bound | Revalidates event delivery, ownership, liveness, progress, and active risk at a risk-proportional cadence |
| User-visible silence bound | Keeps communication frequent enough for the user while updates remain compact and state-changing |
Stable periods reuse the same watcher, digest, and cursor. Risk transitions restore the fastest profile. A normal review reads one authoritative digest; deeper inspection opens only the affected task rows and new log slice.
This creates the combination long scientific work actually needs: high local observability, fast anomaly response, active Codex supervision, and disciplined token use.
The contract fixes the invariants that give a result meaning: scientific authority, data semantics, side-effect ownership, filesystem safety, artifact identity, and terminal evidence. Inside those boundaries, Codex keeps full solver autonomy to choose tools, replace low-yield approaches, reorder or parallelize independent work, tune runtime parameters, add instrumentation, and adopt validated artifacts.
Control depth scales with the active failure surface. A single observable process can use its own checkpoint, process wait, and terminal evidence. A multi-stage resumable run with retries, concurrent publishers, or remote side effects earns a durable coordinator, leases, event stream, and attestation DAG. The lightest control surface that closes the real risk wins.
flowchart LR
A[Freeze scientific authority] --> B[Prove end-to-end readiness]
B --> C[Run through one durable control plane]
C --> D[Supervise from structured events]
D --> E{Evidence changed?}
E -->|Healthy progress| C
E -->|Failure or blocker| F[Recover the smallest valid cone]
F --> C
C --> G[Attest artifacts]
G --> H[Publish a scope-qualified terminal]
Design, Audit, Execute, Recover, and Monitor form a flexible control vocabulary. Codex selects the modes that match the active failure surface, reuses gates already proven, and keeps independent work moving.
Data acquisition receives the same rigor as analysis. The skill freezes the claim-to-data contract, derives the minimum sufficient eligible subset, preflights every source through the real parser or export path, registers remote effects, reconciles uncertain submissions by durable identity, and promotes content after transport, container, parser, semantic, coverage, unit, CRS, quality, and checksum evidence agree.
Source audit, pilot transfer, frozen population, completed acquisition, analysis, and project completion each receive their own terminal scope.
- multi-hour and multi-stage scientific computations;
- large public-data downloads, cloud exports, and remote extraction jobs;
- context-heavy research programs with many files, decisions, and tool traces;
- repeatedly restarted workflows and stale
RUNNINGstates; - protocol–code drift and unfinished stage interfaces;
- checkpoint, cache, adoption, and invalidation decisions;
- branch-limited failures inside wider research programs;
- resource bottlenecks and weak validated throughput;
- token-heavy monitoring and repeated no-change status checks;
- formal runs that require auditable, scope-qualified completion.
Short deterministic jobs can stay direct: execute, validate, and close.
Design and admit a workflow:
$govern-complex-research-runs Design and audit this multi-stage scientific workflow, prove end-to-end readiness, freeze the value-relevant identities, and launch it under an attended control plane.
Recover a stalled workflow:
$govern-complex-research-runs Establish physical truth for this stalled run, classify cause, scope, and disposition, preserve valid artifacts, and resume the smallest affected dependency cone.
Supervise an active workflow:
$govern-complex-research-runs Monitor this active run from its authoritative digest and event stream until a verified scope-qualified terminal state.
User-wide installation with PowerShell:
$skillPath = Join-Path $HOME ".agents\skills\govern-complex-research-runs"
New-Item -ItemType Directory -Force (Split-Path $skillPath) | Out-Null
git clone https://github.com/FAITH-CKJ/govern-complex-research-runs.git $skillPathUser-wide installation with Bash:
mkdir -p "$HOME/.agents/skills"
git clone https://github.com/FAITH-CKJ/govern-complex-research-runs.git "$HOME/.agents/skills/govern-complex-research-runs"For repository-scoped discovery, place the skill at:
<repository>/.agents/skills/govern-complex-research-runs
Run git pull --ff-only inside a manual installation to update it. Use an
empty destination for a fresh built-in installer run.
SKILL.md— the outcome-and-evidence governance contract;references/architecture-and-readiness.md— authority separation, fixtures, readiness, identity, and admission;references/runtime-and-token-policy.md— four supervision clocks, event delivery, worker envelopes, and interaction budgets;references/recovery-and-review.md— failure classification, blocker latches, invalidation cones, amendments, and new-run decisions;references/research-data-acquisition.md— source preflight, resumable transfer, remote reconciliation, validation, and promotion;references/windows-long-runs.md— Windows process identity, ownership, paths, atomic publication, and concurrency admission;references/bundle-schema.md— canonical machine-readable control contracts;references/failure-patterns.md— a composite diagnostic scenario;scripts/audit_workflow_bundle.py— deterministic structural audit and self-test;agents/openai.yaml— Codex display and invocation metadata.
The skill is instruction-driven. The optional bundle auditor uses Python 3.10+ and PyYAML:
python -m pip install PyYAML
python scripts/audit_workflow_bundle.py --self-test
python scripts/audit_workflow_bundle.py --root path/to/workflow
The auditor verifies required control files, DAG structure and acyclicity, terminal scope, recovery classes, supervision invariants, blocker unlatch events, interaction budgets, and workflow-root-relative report paths. Project-specific scientific validators attest formulas, thresholds, and conclusions.
Released under the MIT License—use it, adapt it, and build on it.