Run checks

dystopic ci review --platform-suite runs one suite's regression check locally, exactly the way CI runs it: it resolves a base and a head commit, materializes each as a detached git worktree, submits the two sides as commit-keyed CI runs, and polls the assembled review to a gate verdict. Each side submits no agent config and no scenarios — the platform resolves the execution recipe from the connected repo's umbrella agent and sources the bound suite's frozen scenarios server-side, byte-identical to an in-app check. The command is decoupled: it submits and exits with a verdict; the platform drives run completion and posts the branded Dystopic check asynchronously.

The walkthrough in /docs/flow/run-checks is the happy path — run it, read the verdict, iterate before you push. This page is the lookup surface: every flag, the exit-code contract your CI keys off, the full preflight error catalog, and the sharp edges (floor-only degradation, cache reuse, the --fresh cost, platform-resolved gating) that bite when you go off the golden path.

The command

dystopic ci review \
  --platform-suite \
  --suite default \
  --base "$(git merge-base origin/main HEAD)" \
  --head HEAD \
  --repo owner/name \
  --pr-number 123

It is also reachable as odyssey ci review — same parser, same behavior. The odyssey front end is the one wired into the GitHub Action.

--base is required unless you pass --head-only. It should be the PR's merge-base, not the base-branch tip — the merge-base is stable across base-branch churn, which is what makes cached runs reuse. The GitHub Action derives it for you; run it by hand with git merge-base origin/main HEAD as above.

Flags

Under the hood

One invocation runs this sequence for each reviewed suite:

Submission and caching (--sample / --repeats / --fresh)

Under --platform-suite the run body sent to /api/ci/runs for each side carries no recipe and no scenarios:

{
  "repo": "owner/name",
  "commit_sha": "<sha>",
  "repeats": 1,
  "suite": "default"
}

• agent is omitted. CiRunSubmission.agent is Optional; an absent agent tells the server to resolve the execution recipe from the connected repo's umbrella agent, stamping source_git to this side's commit.
• scenarios are submitted empty. No local scenarios are read, so the list is []. The API accepts an empty list only when suite resolves to a bound platform suite (the server sources that suite's frozen scenarios); a submission that does not resolve fails closed with a 422.
• --sample N would truncate a locally-submitted scenario set, but is ignored under --platform-suite — the platform sources the full frozen set server-side.
• --repeats N rides the repeats field on both sides identically so the comparison stays fair (see Repeats precedence).
• --fresh adds an epoch field — the current UTC-hour bucket. Same identity key + a new epoch = a distinct run, so identical configs re-run for real instead of attaching to a cached run. This costs real runs; it exists for drift canaries and "run it again for real," not routine iteration.

The /api/ci/runs response tells you what happened per run:

{
  "config_hash": "<hash of the resolved config>",
  "runs": [ { "id": 12345, "created": true } ]
}

created: true means a fresh run was minted; created: false means an existing commit-keyed run was reused (a cache hit).

Repeats precedence

The repeats value submitted on both sides is resolved in this order:

1. Explicit --repeats N always wins.
2. Otherwise the bound suite's configured repeats.
3. When the suite configures none, the default 1.

Exit-code contract

CI keys off exactly three codes. This is the contract:

A poll timeout and an HTTP 429 quota deferral are both exit 0 — a bounded local wait or a busy platform must never turn a gated PR red. In both cases the review_id (or quota_deferred: true) is surfaced so the run stays traceable and the check lands async.

Preflight error catalog

All preflight runs client-side, before any run row is created. Each named error is part of the contract and exits 2 with no submission:

The server-side fail-closed 422 (unconnected repo, umbrella agent with no run command, or unresolved suite) is separate from these client preflights — it fires during submission and surfaces as exit 1.

run_command_missing_file in detail

Agent source lands at /home/user/agent/<relative>, but the run command executes from /home/user/workspace. A relative path or a wrong absolute path fails in the sandbox with "file not found." Preflight lints this by splitting the run command into tokens, checking each token ending in a script suffix (.py, .sh, .bash, .js, .mjs, .ts, .rb) against the packaged file set or the local worktree, and suggesting the correct absolute path:

run_command_missing_file: run_command references 'agent.py' but agent source lands at
/home/user/agent/ and the command runs from /home/user/workspace — use the absolute
path /home/user/agent/agent.py

The lint is skipped for zip and static-git sources (their tree is not local) and for pure-CLI run commands with no agent source at all.

Decision table

Every (base, head) state maps to a defined outcome — never a stack trace. On a connected repo both commits are platform-resolved (the recipe lives on the umbrella agent), so the shape turns only on whether a base is present to diff against:

Floor-only degradation (head-only)

When there is no base to compare against — a first PR, an absent base branch, or --head-only for a push context — the command runs the head side alone and enforces only the absolute floor.

In --head-only mode:

• --pr-number is rejected (mutually exclusive); a --branch (or $GITHUB_REF_NAME) is required for the review context.
• Only the head side is submitted. base_config_hash: null on the review body signals floor mode to the server.
• The only gate tier that applies is block_on_min_pass_rate — the head's absolute pass-rate floor. There is no diff, no reviewer, no severity / constraint / scorer tiering.
• With a floor configured and the head below it → blocked (exit 1). With the floor met or unset → neutral/pass (exit 0).

The same degradation is reached implicitly on the full PR path when there is no base side: the decision table returns head_only and the review is flagged accordingly.

Reading the output

Without --json, the command prints a human report to stdout: a header with the gate status, the target line (owner/name#123 · base abc1234 → head def5678), the gate description, a per-scenario table with ▼ regressed / ▲ improved markers and trace links, findings blocks, any banners, and a final verdict line. Trace and review deep links point at the web dashboard at https://platform.pipelines.tech. With --json, the machine dump goes to stdout and that same human report goes to stderr, so stdout stays byte-clean JSON.

Scenarios tagged xfail on the platform suite run and report but never gate — an expected-failure row cannot turn the PR red.

The full review schema (findings, blocking_reasons, diff subfields, structural-change and floor-only degradations) is documented on /docs/reference/review-findings. To fetch an already-created review directly, GET /api/ci/reviews/{id}.

Related