Lower-level unified runner for multi-provider dispatch with shared governance. Routes to cc-glm, opencode, claude-code, or gemini providers with unified preflight, gates, and failure taxonomy. Use directly for provider debugging, custom orchestration, headless jobs, or when a task-specific shim such as dx-loop, dx-review, or dx-research delegates to it.
dx-runner is the lower-level governed execution substrate for agent dispatch. For chained Beads work, multi-step outcomes, implement/review baton flow, or PR-aware follow-up, use dx-loop first.
It provides:
dx-review GLM lane), opencode (primary throughput and dx-review fallback GLM transport), claude-code (native Claude Code review lane), gemini (optional burst)Native Claude Code dispatch is implemented as the claude-code provider. The cc-glm provider remains the Z.ai/GLM wrapper lane and is not Anthropic Claude Code support.
OpenCode behavior in this skill is grounded in official docs and live CLI help:
opencode run --help on the target host (for exact supported flags)Task-specific shims should be the default agent entrypoint:
| Outcome Needed | Preferred Surface | Notes |
|---|---|---|
| Chained Beads work / implement-review baton / PR-aware follow-up | dx-loop | Default agent-facing orchestrator over dx-runner |
| Independent code/design/security review | dx-review | Review quorum wrapper over dx-runner |
| Source-backed web/deep research + decision memo | dx-research | Research artifact wrapper over dx-runner |
| Provider debugging, custom orchestration, manual profile control | dx-runner | Substrate/manual escape hatch |
# Canonical control-plane cwd
export BEADS_DIR="$HOME/.beads-runtime/.beads"
# Start a job with cc-glm provider and explicit repo worktree
dx-runner start --beads bd-xxx --provider cc-glm --worktree /tmp/agents/bd-xxx/agent-skills --prompt-file /tmp/task.prompt
# Start the native Claude Code review lane with Opus
dx-runner start --beads bd-xxx.claude --profile claude-code-review --worktree /tmp/agents/bd-xxx/agent-skills --prompt-file /tmp/review.prompt
# Run the minimal two-reviewer quorum wrapper: Claude Code Opus + cc-glm GLM-5
# OpenCode GLM-5.1 is launched only if the cc-glm review lane fails at start/preflight.
dx-review run --beads bd-xxx --worktree /tmp/agents/bd-xxx/agent-skills --prompt-file /tmp/review.prompt --wait
# Run source-backed research wrapper and read merged summary first.
dx-research run --beads bd-xxx --worktree /tmp/agents/bd-xxx/agent-skills --topic "compare option A vs B" --depth deep --wait
dx-research summarize --beads bd-xxx
# Check job status
dx-runner status
# Check specific job health
dx-runner check --beads bd-xxx
# Generate report
dx-runner report --beads bd-xxx --format json
# Coordinate Beads state via wrapper
bdx show bd-xxx --json
Launch a job with specified provider:
dx-runner start --beads <id> --provider <name> --prompt-file <path> [options]
Options:
--worktree <path> Worktree path (must be under /tmp/agents or allowed prefix)
--repo <name> Repository name
--profile <name> Load profile from configs/dx-runner-profiles/<name>.yaml (bd-8wdg.1)
--pty Use PTY for output capture
--required-baseline <sha> Enforce baseline gate before dispatch
--allow-model-override Allow OPENCODE_MODEL env override (bd-8wdg.2)
Operator contract:
BEADS_DIR=~/.beads-runtime/.beads from a non-app directory.--worktree /tmp/agents/<beads>/<repo> explicitly for mutating jobs.DX_RUNNER_DEFAULT_WORKTREE only as fallback for legacy wrappers or previously recorded runs.bdx for Beads coordination around runs. Raw bd is for local diagnostics/bootstrap/path-sensitive operations.Show status of jobs:
dx-runner status [--beads <id>] [--json]
Prune stale/ghost PID records (including invalid/dead PIDs):
dx-runner prune [--beads <id>] [--json]
Check single job health (exit codes indicate state):
dx-runner check --beads <id> [--json] [--stall-minutes <n>]
Exit Codes:
0 = healthy or completed
2 = stalled
3 = error/blocked
Stop a running job:
dx-runner stop --beads <id>
Restart a job (preserves metadata, rotates logs):
dx-runner restart --beads <id>
Run watchdog loop for monitoring:
dx-runner watchdog [--interval <sec>] [--max-retries <n>]
Generate job report:
dx-runner report --beads <id> [--format json|markdown]
Run preflight checks:
dx-runner preflight [--provider <name>]
dx-runner preflight --profile claude-code-review
Test provider/model availability:
dx-runner probe --provider <name> [--model <id>]
dx-runner probe --provider claude-code --model opus
List available profiles:
dx-runner profiles
Evaluate scope constraints:
dx-runner scope-gate --allowed-paths-file <path> [--mutation-budget <n>]
Evaluate evidence requirements:
dx-runner evidence-gate --signoff-file <path>
# Baseline gate: verify runtime commit meets minimum
dx-runner baseline-gate --worktree <path> --required-baseline <sha>
# Integrity gate: verify reported commit exists
dx-runner integrity-gate --worktree <path> --reported-commit <sha>
# Feature-key gate: verify commits have required trailer
dx-runner feature-key-gate --worktree <path> --feature-key <bd-id>
dx-runner enforces workspace-first isolation by rejecting canonical repo paths:
Allowed mutating paths:
/tmp/agents/*/tmp/dx-runner/*/tmp/dxbench/*$HOME/agent-skills (only for non-mutating read operations)Forbidden paths (exit code 22, reason canonical_worktree_forbidden):
$HOME/agent-skills$HOME/prime-radiant-ai$HOME/affordabot$HOME/llm-commonExample rejection:
reason_code=canonical_worktree_forbidden
rejected_path=$HOME/agent-skills
policy=workspace_first_v86
remedy=dx-worktree create bd-xxx agent-skills
ERROR: Mutating execution forbidden in canonical repo
Canonical repos are clean mirrors. Use: dx-worktree create bd-xxx agent-skills
Normal operations still work in canonical repos:
git fetch, git pull --ff-onlyrailway status, railway run, railway shell~/agent-skillsZ.ai/GLM wrapper lane using cc-glm-headless.sh and proven patterns from cc-glm-job.sh. This is not native Claude Code provider support.
dx-runner start --beads bd-xxx --provider cc-glm --prompt-file /tmp/task.prompt
Auth resolution order:
CC_GLM_AUTH_TOKEN - Direct tokenCC_GLM_TOKEN_FILE - Path to token fileZAI_API_KEY - Plain or op:// referenceCC_GLM_OP_URI - Explicit op:// referenceop://dev/Agent-Secrets-Production/ZAI_API_KEYOpenCode headless. Includes reliability fixes for:
dx-runner start --beads bd-xxx --provider opencode --prompt-file /tmp/task.prompt
Model policy:
zhipuai/glm-5.1cc-glm or geminidx-review, OpenCode is fallback transport after cc-glm-review start/preflight failureNative Anthropic Claude Code CLI in headless prompt mode. Use this for review quorum work that explicitly needs Claude Code Opus separate from the cc-glm Z.ai/GLM wrapper lane.
dx-runner start --beads bd-xxx.claude --profile claude-code-review --worktree /tmp/agents/bd-xxx/repo --prompt-file /tmp/review.prompt
Model policy:
opusclaude --print, model availability, and non-interactive auth before launchGoogle Gemini CLI with detached launcher hardening:
rc grace window before no-rc classificationgemini login is the only canonical route (API-key env vars are not accepted by preflight)dx-runner start --beads bd-xxx --provider gemini --prompt-file /tmp/task.prompt
Operator expectations for Gemini finalization:
state=exited_ok, reason_code=process_exit_with_rc|outcome_exit_0state=exited_err, non-zero exit_code in outcome/reportreason_code=monitor_no_rc_file or late_finalize_no_rc, treat as runner lifecycle defect and escalateProfiles provide pre-configured settings for common workflows:
# Use production profile (strict governance)
dx-runner start --beads bd-xxx --profile opencode-prod --prompt-file /tmp/task.prompt
# Use explicit review profile
dx-runner start --beads bd-xxx.glm --profile cc-glm-review --prompt-file /tmp/review.prompt --worktree /tmp/agents/bd-xxx/repo
# Use native Claude Code Opus review profile
dx-runner start --beads bd-xxx.claude --profile claude-code-review --prompt-file /tmp/review.prompt --worktree /tmp/agents/bd-xxx/repo
# List available profiles
dx-runner profiles
| Profile | Provider | Description |
|---|---|---|
opencode-prod | opencode | Production: strict governance, canonical model only |
cc-glm-review | cc-glm | Review: primary GLM lane, glm-5 |
opencode-review | opencode | Review fallback: strict governance, zhipuai/glm-5.1 |
claude-code-review | claude-code | Review: strict governance, opus |
cc-glm-fallback | cc-glm | Reliability backstop for critical waves |
gemini-burst | gemini | Burst capacity with relaxed constraints |
dev | opencode | Development: permissive, allows model override |
# configs/dx-runner-profiles/opencode-prod.yaml