Updated: 2026-06-07 · Executes Chapter 6 Phase A. Designed to be run by Codex on obot's OpenClaw machine.
| Component | Role this phase | Concrete form |
|---|---|---|
| OpenClaw main obot | Telegram intake + scheduler + notifier. Not the executor. | Cron wakes a launcher / posts alerts; systemEvent wake path only (Chapter 3). |
| Supervised runner | Starts a worker, writes a run-record, heartbeats, enforces a deadline, recovers. | New scripts/run_codex_cycle.py, extending the existing scripts/work_session.py ledger. |
| Watchdog | Reads run-records, flags stalled/triggered-but-not-started, emits one alert. | scripts/check_runs.py (or a --watch mode on the runner), run by cron. |
| Dev executor | Isolated, audited code execution → PR. | Codex cloud @codex on an issue/PR, or a Codex Automation in a dedicated worktree. |
| PM executor | Portfolio audit → durable artifact → Dev target or decline. | Codex local (non-interactive) wrapped by the runner; output is a GitHub issue comment. |
| GitHub | Source of truth + audit. | Project / Requirement / Task issues; PR + Codex task log are the Dev evidence. |
| Run-records dir | Durable ledger of every run's state. | runs/<run_id>.json + transcript log, local + linked in issue comments. |
agentTurn directly (Chapter 3 root cause).scripts/work_session.py fields where they already exist (target, session ref, checkpoint, liveness, evidence, recovery).runs/<run_id>.json):
{
"run_id": "2026-06-08-pm-01",
"role": "pm | dev",
"target_issue": "obot-claw/obot-claw.github.io#NN",
"repo": "obot-claw/...",
"executor": "codex-local | codex-cloud",
"state": "triggered | started | completed | failed",
"started_at": "ISO-8601 or null",
"heartbeat_at": "ISO-8601, updated every N seconds",
"deadline_at": "ISO-8601 (started_at + timeout)",
"artifact": "PR url / issue-comment url / audit file path / null",
"failure_reason": "string or null",
"recovery": "what the watchdog/obot should do on stall"
}
State rule (Chapter 3): only started counts as active; only completed counts as useful work. A record stuck in triggered past a short grace window is a failure, not progress.
scripts/run_codex_cycle.py. Inputs: --role, --issue, --repo, --timeout, --prompt-template, --write-scope.triggered, launch the Codex CLI non-interactively as a managed subprocess, then flip to started once the process is confirmed running.heartbeat_at + append a transcript line) every N seconds while the subprocess lives.completed + artifact link. On timeout/crash/no-artifact: write failed + failure_reason.Exit: a manual PM dry-run writes a run-record and either an audit artifact or a clear failure reason. Keep it boring; this is a supervisor, not a platform.
This is the test Chapter 3 said we have never passed and Chapter 5 lists as an acceptance gate. Do it on the cheap substrate first.
scripts/check_runs.py on a short cron) must detect: (a) triggered that never reached started, and (b) started with a stale heartbeat_at past deadline_at.failed, writes a failure artifact, and emits one concise (<500 char, plain-text) Telegram alert via obot — without Jeremy asking.Pass = "Started vs triggered" and "Stall detection" from Chapter 5, satisfied with no Paperclip in the loop.
scripts/portfolio_audit.py).obot-claw.github.io (no secrets, deterministic check).@codex on the task issue, or run a Codex Automation in a dedicated worktree → one PR. No merge.This is the half Codex 2026 already solves natively (isolated worktrees, scheduled automations, issue→PR, PR-as-audit) — lean on it instead of hand-building.
| Criterion | Pass condition |
|---|---|
| One real cycle | A PM→Dev→PR cycle completed with liveness evidence at each step. |
| Stall detection | Failure-injection test flips to failed + alerts, unprompted (Phase 2). |
| No false status | Nothing was reported "active" without a started record + concrete evidence. |
| GitHub artifacts | Audit comment + PR exist and are linked from run-records. |
| Telegram hygiene | Summaries are <500 char plain text, sent only after a durable artifact. |
Follow the Autonomy operating contract: default block authority L2; L3 only where the parent Requirement approves implementation; merges stay review-gated. Stop and report (don't push) if requirements are ambiguous, checks fail without a clear fix, work needs non-obot-claw writes, private data could be exposed, credentials/tooling are blocked, or work exceeds the active Requirement scope.
scripts/run_codex_cycle.py — supervised runner with run-record + heartbeat.scripts/check_runs.py — watchdog with stall/triggered-but-not-started detection + Telegram alert.runs/ — durable run-record directory (gitignored if it may contain run detail, or sanitized if committed).agentTurn.agentTurn and calling it progress (Chapter 3).scripts/run_codex_cycle.py + the run-record schema above; (4) run the Phase 2 failure-injection test and capture the alert as evidence. Report back with the run-records and issue/PR links — that evidence is the go/no-go input for the Chapter 5 Paperclip pilot.AUTONOMOUS_QUEUE.md, TODO.md, AGENTS.md, HEARTBEAT.md, and skills work-session-supervision, codex-work-cycle, and portfolio-pm-audit.agentTurn is currently not trusted as an executor. Cron may wake/check; the runner must provide durable state and heartbeat evidence.triggered, started, completed, failed; heartbeat timestamp; transcript/log path; artifact link; failure reason; and recovery note.