codex-batch-runner

codex-batch-runner는 코딩 에이전트를 위한 policy-governed unattended execution control plane입니다. 현재 구현은 Codex CLI를 주 native backend로 사용하는 로컬 파일 큐 runner이며, 실행 권한·readiness·의존성·리뷰·복구를 분리해 비대화형 작업의 lifecycle을 통제합니다. 스케줄러가 자주 실행되더라도 처리할 작업이 있을 때만 codex exec --json 또는 codex exec resume ... --json을 호출하므로 불필요한 Codex 호출과 토큰 소모도 줄입니다.

현재 상태

현재는 로컬 beta 운영을 목표로 core flow를 구현하고 있습니다. 파일 기반 queue, lock, cooldown, Codex JSONL parsing, 자동 검토, bounded auto-fix, shell task backend, worktree 격리 실행, worktree apply/rebase/cleanup/branch-prune 흐름을 포함합니다.

실제 Codex CLI JSONL schema는 버전별 차이가 있을 수 있으므로 runner는 원본 JSONL 로그를 보존하고, 최종 응답과 session/thread id는 best-effort로 파싱합니다.

제품 경계

CBR은 durable하고 비대화형인 실행 lifecycle을 소유합니다. interactive/supervised agent IDE는 작업 공간 탐색, terminal steering, worktree 상호작용, diff 검토에 적합한 별도 surface입니다. 예를 들어 Orca는 그러한 interactive/supervised surface의 비규범적 예시일 뿐이며, CBR과의 통합·backend 지원·권한 이전을 뜻하지 않습니다.

CBR은 conversational UX, messaging gateway, personal memory, skill 또는 MCP discovery, 일반 목적의 cron·monitoring, browser research, interactive agent steering을 소유하지 않습니다. 이러한 사용자-facing 수집·정제·전달 계층은 CBR 밖의 교체 가능한 surface로 유지하고, 필요한 경우 bounded execution contract를 통해 CBR에 작업을 위임합니다.

외부 gateway나 agent runtime은 CBR의 adapter 또는 issuer가 될 수 있지만 CBR의 admission, authority, readiness, review, acceptance, apply, audit, recovery 경계를 우회하거나 대체하지 않습니다. CBR은 범용 개인 에이전트 플랫폼으로 확장하지 않고 unattended coding mutation의 정책·transaction control plane으로 유지합니다.

문서 지도

• 요구사항 계층 (ROOT-REQ-*, REQ-*)
• Model routing requirement contract: requirement v2와 exact-target routing의 D0 public contract.
• Core spec index: 현재 구현 truth와 topic 문서 index.
• Task schema and dependency contract: task JSON fields, task/review status, dependency readiness.
• Execution contract: model requirements, capacity/priority, shell backend, runner policy, watchdog, lock, atomic write, Codex command/prompt wrapper, rate-limit, queue mutation.
• Gateway-neutral execution plan: exact-target/delegation-bound sanitized execution-plan projection with no launch or runtime mutation.
• Provider resource report and D2-A simulator: read-only provider evidence, exact-target decision/alternative preview, canonical gate keys, and D2-B safety boundary.
• Review contract: review-bundle, review-next, reviewer Codex gates, bounded auto-fix loop.
• Worktree hibernation compatibility: deterministic branch-only review and attachment reconciliation report.
• Legacy worktree reconciliation plan and exact repair: snapshot-bound report-only classification plus queue-locked, single-task enum repair.
• Worktree contract: worktree prepare/apply/rebase/conflict-fix/cleanup/branch-prune/recovery.
• Scoped execution mutation provenance: report-only pre/post/terminal worktree evidence and explicit global non-claims.
• Trusted pre-execution delegation: immutable queue admission and runner-owned exact-target receipt barrier before worker invocation.
• Scoped readonly certification projection: receipt-bound 20/95%/zero-adverse advisory aggregation within the CBR worktree scope.
• Capacity target-ordering activation simulation: deterministic report-only counterfactual ordering over the immutable baseline eligible set.
• Execution-target selector decision envelope: task/attempt-scoped canonical override-or-absence binding over the unchanged ordering-v1 baseline.
• Bounded capacity target-ordering canary mechanism: default-disabled exact-scope claim-time ordering with deterministic assignment, append-only evidence, and fail-closed rollback.
• Capacity gate-lifecycle activation simulation: deterministic report-only replay of typed gate creation, deduplication, supersession, wake revalidation, release, rollback, and synthetic hard-exclusion mechanics.
• Capacity reservation and feedback simulation: exact-bound, report-only reservation, append-only feedback, half-open, and retry-budget previews.
• Orchestration selection shadow evidence: deterministic D1-bound recommendation/selection comparison with immutable private recording and no dispatch or warning authority.
• Orchestration selection funnel: read-only durable selection-to-CBR lifecycle projection with explicit unknown/non-applicable semantics.
• Source-goal reconciliation: strict source-owned goal manifest and deterministic read-only CBR evidence projection without source or completion authority.
• Events and index contract: event log, local SQLite read index, prune/retention.
• Retention inventory and additive compact records: sanitized lifecycle projection plus an explicit, non-destructive compact/tombstone/restore-index apply path.
• CLI reference: command reference and human/JSON output semantics, including list renderer and routing-report details.
• Operator installation guide: config discovery, macOS launchd setup, doctor, cooldown wake, cross-project usage.
• Beta operations guide: practical beta operating model and review workflow.

Private project planning notes should use an ignored .private/ directory, for example .private/ROADMAP.md and .private/TASKS.md; templates are in examples/private.

설치

Python 3.11 이상이 필요합니다. runtime dependency는 없습니다.

개발 checkout에서 바로 실행할 수 있습니다.

PYTHONPATH=src python3 -m codex_batch_runner --help

운영자가 직접 상태를 조회하거나 transcript를 검토하고 accept/reject를 기록하는 환경에서는 cbr console script 설치가 편리합니다.

python3 -m pip install -e .
cbr --help

테스트 실행:

PYTHONPATH=src python3 -m unittest discover -v

5-minute quickstart

작업 등록:

PYTHONPATH=src python3 -m codex_batch_runner enqueue \
  --cwd /path/to/repo \
  --title "Improve README quickstart" \
  --prompt "README를 개선하고 테스트를 실행해"

다음 실행 가능한 작업 하나 처리:

PYTHONPATH=src python3 -m codex_batch_runner run-next

Scheduler용 single-worker loop:

PYTHONPATH=src python3 -m codex_batch_runner run-loop --json

상태 확인:

PYTHONPATH=src python3 -m codex_batch_runner list
PYTHONPATH=src python3 -m codex_batch_runner summary task-id
PYTHONPATH=src python3 -m codex_batch_runner review-bundle task-id

검토 결과 기록:

PYTHONPATH=src python3 -m codex_batch_runner accept task-id --reason "verified locally"
PYTHONPATH=src python3 -m codex_batch_runner reject task-id --reason "tests are missing"
PYTHONPATH=src python3 -m codex_batch_runner resolve task-id --resolution manual --reason "handled outside cbr"

작업이 완료됐지만 후속 실행이 필요하면 Codex final JSON의 status는 needs_resume이 될 수 있습니다. Rate-limit은 runner가 stderr/JSONL evidence에서 별도로 감지하고 task/global cooldown을 설정합니다.

Core workflow

1. enqueue가 task JSON을 local queue에 저장합니다.
2. Scheduler가 run-loop를 주기적으로 호출합니다.
3. Runner가 lock, pause, cooldown, dependency, capacity gate를 확인합니다.
4. 실행 가능한 task 또는 auto-review action을 한 번 처리한 뒤 즉시 다음 iteration에서 config와 queue state를 다시 확인합니다.
5. 결과와 sanitized event를 저장합니다.
6. 운영자 또는 opt-in review automation이 summary, review-bundle, review-next를 기준으로 accept/reject/needs_followup을 기록합니다.
7. Worktree-backed accepted result는 worktree apply 또는 post-accept apply path로 integration target에 반영된 뒤 dependency-ready가 됩니다.

기본 운영에서는 다른 Codex thread나 사람이 작업을 queue에 등록하고, launchd/systemd 같은 외부 scheduler가 single worker로 run-loop --json을 호출합니다. run-next는 수동 점검과 기존 one-shot automation을 위한 단일 outcome command로 유지됩니다. 자동화 경로에서는 PATH에 의존하지 않고 config와 절대 경로를 사용하는 것이 안전합니다.

Common commands

# Register from a prompt file
PYTHONPATH=src python3 -m codex_batch_runner enqueue --cwd /path/to/repo --prompt-file task.md

# Register with metadata and routing hints
PYTHONPATH=src python3 -m codex_batch_runner enqueue \
  --cwd /path/to/repo \
  --project codex-batch-runner \
  --category implementation \
  --label queue \
  --routing-size small \
  --routing-risk low \
  --verification-scope unit \
  --prompt-file task.md

# Inspect queue and logs
PYTHONPATH=src python3 -m codex_batch_runner list --project codex-batch-runner
PYTHONPATH=src python3 -m codex_batch_runner follow task-id --lines 40 --poll-interval 1
PYTHONPATH=src python3 -m codex_batch_runner transcript task-id
PYTHONPATH=src python3 -m codex_batch_runner events --task-id task-id --limit 10
PYTHONPATH=src python3 -m codex_batch_runner dashboard

# Review automation reports
PYTHONPATH=src python3 -m codex_batch_runner review-next --dry-run
PYTHONPATH=src python3 -m codex_batch_runner review-next --dry-run --project codex-batch-runner --json
PYTHONPATH=src python3 -m codex_batch_runner recommend-routing \
  --task-bucket 'size=small risk=low verify=unit' \
  --execution-surface cbr_batch \
  --semantic-complexity medium --failure-cost medium \
  --objective-verification unit --expected-context context-v1 \
  --interaction-need none --usage-pressure normal --json

# Worktree integration
PYTHONPATH=src python3 -m codex_batch_runner worktree apply task-id --dry-run
PYTHONPATH=src python3 -m codex_batch_runner worktree cleanup task-id --dry-run
PYTHONPATH=src python3 -m codex_batch_runner worktree branch-prune task-id --dry-run

Detailed command semantics are in docs/cli-reference.md. Worktree apply/rebase/cleanup/branch-prune safety rules are in docs/worktrees.md.

cbr dashboard serves a local read-only operator overview on 127.0.0.1:8765 by default. The page and /api/dashboard use the sanitized dashboard read model and show queue, review/apply, failure, running, cooldown, index warning, and recent event summaries without raw prompts, full logs, session/thread ids, credentials, or private local paths.

Configuration

Config discovery order:

1. --config path/to/config.json
2. CBR_CONFIG environment variable
3. $XDG_CONFIG_HOME/codex-batch-runner/config.json, or $HOME/.config/codex-batch-runner/config.json

The first selected path is authoritative. A missing, unreadable, invalid, or non-object config fails closed without falling through to a lower tier. Discovery never creates a config or runtime directory and never searches the current working directory. Example configs are available in examples/config.example.json and examples/config.automation.example.json.

cbr launchd plan is a read-only managed LaunchAgent planning surface. cbr launchd install and cbr launchd uninstall add a guarded lifecycle: dry-run is the default, apply requires --apply plus an exact --confirm-label, and only an explicit current-user HOME/Library/LaunchAgents/LABEL.plist destination in gui/UID is eligible. The install operation creates an absent plist, no-ops on the same owned digest, and atomically backs up and updates owned drift. Foreign, malformed, symlink, non-regular, and oversized destinations fail closed without adoption. Update and uninstall retain or restore recoverable same-directory backups when transitions fail.

Optional root makes relative runtime paths independent of the process current working directory. worktree_mode=task enables task-specific git worktrees. A project can opt into reusable worktree directories with a tracked root .cbr.toml; projects without it keep disposable task worktrees, and invalid/untracked policy files fail closed. See worktree isolation and apply. model_requirement_vector, model_selection_rules, and default_execution_config keep task intent separate from local Codex model/profile choices. worker_targets and worker_selection_rules can route matching default Codex tasks to a configured shell or external JSON worker before claim.

usage_admission_enabled optionally adds a provider-neutral, read-only JSON snapshot check before a native Codex implementation task is claimed. It is disabled by default, never installs or authenticates a snapshot provider, and fails open to the existing runner path when the configured argv command is unavailable or invalid. See docs/execution.md and docs/operator-installation.md.

For launchd/systemd installation, config discovery, and doctor, use docs/operator-installation.md. For execution policy and full config contracts, use docs/execution.md.

Safety model

run-next handles one unit of work per invocation and emits one JSON object with --json. run-loop repeats the same one-shot path for launchd/operator use, reloading config and queue state before each iteration, and emits JSONL with --json. It suppresses redundant external post-run wake hooks between progress iterations because the same process claims follow-up work directly. It stops when the next iteration is empty, paused, cooling down, locked, review-blocked, or otherwise non-actionable.

Task/state writes use atomic replace. Core state-changing commands append sanitized audit events. Event payloads are intentionally small and redact prompt text, raw transcripts, session/thread ids, secrets, credentials, and token-like fields.

review-next is report-only by default. Mechanical accept, reviewer Codex, bounded auto-fix enqueue, worktree apply, cleanup, branch pruning, direct worktree cleanup, pruning retained files, and Codex CLI maintenance all require explicit command/config opt-in. worktree branch-prune --apply only deletes eligible cleaned applied local cbr/* branches with git branch -d; it does not delete remote branches, task JSON, runtime logs, event logs, worktree directories, or force-delete branches.

운영 메모

macOS에서는 launchd 운영을 권장합니다. Linux user service에서는 systemd timer/service를 사용할 수 있고, cron은 portable fallback으로만 취급합니다. Installation examples are maintained in docs/operator-installation.md.

Public docs must not include private/operator state, .private/ contents, runtime logs, actual Codex prompts, session ids, thread ids, personal paths, credentials, or .local files.