Autonomous loops without the dashboard

Use this guide when a coding agent or human operator needs to run Archal from a terminal and hand off clear evidence without opening dashboard pages. Archal has two autonomous loops:

Loop	Use it for	Primary command
Pre-prod	Run scenario checks before a change ships, classify failures, optionally let a coding agent patch, rerun, validate, and publish a draft PR	`archal preprod run`
Post-prod traces	Import traces after an agent has already run, grade them, reproduce real failures against clones, and open reviewable fixes	`archal attach`

Both loops use the same product boundary as archal run: your harness calls the real agent path, the agent keeps using normal service SDKs and URLs, and Archal handles clone routing, isolation, scoring, and evidence capture behind that boundary. The post-prod loop is not arbitrary production trace replay. Attach reproduces only when the imported trace plus repo-owned scenario and seed context contain enough evidence to rebuild the relevant clone state. If that evidence is missing, the safe outcome is a blocked artifact that names the missing data.

First preflight

Install and authenticate once:

npm install -D archal
npx archal login
npx archal usage

For CI or SSH, set a workspace API key instead:

export ARCHAL_TOKEN=archal_ws_<your-key>

Make sure the repo has:

a runnable headless harness in .archal.json, --harness, or a repo-local harness file
scenario markdown with setup, prompt, success criteria, and clone config
model/provider keys needed by the agent
a GitHub origin remote if the loop will open a PR

Smoke-test the harness before letting either loop spend attempts:

AGENT_TASK="Reply with OK and do not use tools." node ./.archal/harness.mjs

Pre-prod loop

Start by asking Archal what it can run:

npx archal preprod plan --repo . --write-scenarios --write-config --out .archal/preprod-plan.json

--write-scenarios writes parser-validated starter scenarios under archal/ by default. --write-config writes .archal.json only when it can do so without overwriting an existing config. Then resolve the loop without running scenarios:

npx archal preprod run --plan --artifacts .archal/preprod

Run scenarios and classification, but stop before fix or PR commands:

npx archal preprod run \
  --runs 3 \
  --pass-threshold 80 \
  --dry-run \
  --artifacts .archal/preprod

If the repo already had .archal.json and preprod plan could not write a new one, pass the generated scenario paths from .archal/preprod-plan.json (authoredScenarios[].path) explicitly. Let a coding agent patch and rerun only after reviewing the dry-run artifacts:

npx archal preprod run \
  --runs 3 \
  --pass-threshold 80 \
  --max-fix-attempts 2 \
  --allow-external-execution \
  --fix-command 'codex exec "Fix the Archal preprod failures in $ARCHAL_PREPROD_FAILURES_JSON"' \
  --validation-command 'pnpm test' \
  --open-pr \
  --pr-command 'gh pr create --draft --fill' \
  --artifacts .archal/preprod

Use --dry-run for a classification-only stop. Omit --allow-external-execution to prevent local fix or PR commands from running. Omit --open-pr to finish after scenarios and validation pass. Fix and PR commands run in a restricted environment. The fix command receives ARCHAL_PREPROD_FAILURES_JSON and ARCHAL_PREPROD_ATTEMPT; the PR command receives ARCHAL_PREPROD_VALIDATION_JSON. Commands that spend their own model tokens can write usage JSON to ARCHAL_PREPROD_USAGE_PATH with fields such as inputTokens, outputTokens, provider, model, isByok, and costUsd.

Pre-prod status

archal preprod run reports one of these statuses:

Status	Meaning
`passed`	scenarios passed, validation passed, and PR publishing was either not requested or completed
`planned`	`--plan` resolved scenarios and stopped
`dry_run`	`--dry-run` classified failures and stopped before fix commands
`blocked`	the loop stopped before a safe next phase, such as missing harness, disabled external execution, or denied cost reservation
`budget_exhausted`	fix attempts reached `--max-fix-attempts`
`validation_failed`	scenario reruns passed, but `--validation-command` failed
`pr_failed`	validation passed, but the PR command or PR verification failed

When --artifacts <dir> is set, inspect:

File	What to read
`preprod-result.json`	full redacted loop result, status, stop reason, attempts, scenario run ids, validation, and PR summary
`preprod-failures.json`	schema-limited failure classifications for a coding agent or handoff

Failure classifications are intentionally practical. Read them as harness setup, routing, clone fidelity, scenario/evaluator, agent behavior, or unknown failure categories. Treat harness setup blockers as setup work before asking a coding agent to patch product code.

Post-prod trace loop

Use Attach when traces already exist from pre-production or production agent runs. Run a readiness check first:

npx archal attach \
  --repo . \
  --source supabase \
  --database-url-env TRACE_DATABASE_URL \
  --source-name prod-agent-traces \
  --check

npx archal attach \
  --repo . \
  --source supabase \
  --database-url-env TRACE_DATABASE_URL \
  --source-name prod-agent-traces

For local exported traces, run a file-backed loop:

npx archal attach ./prod-traces --repo . --execution-policy reproduce

For non-database trace sources, normalize and optionally upload traces with archal trace-source:

npx archal trace-source import ./exports --preview --json
npx archal trace-source import ./exports --upload --repository owner/repo
npx archal trace-source status

Use trace-source sync or trace-source watch for pull-style sources such as Langfuse, Braintrust, S3/GCS mirrors, or Postgres views. Use trace-source serve for HTTP/OTel push sources. Stop that local file-backed loop with:

npx archal detach ./prod-traces --repo .

archal detach only stops local file-backed attachments. Hosted database sources are registered for hosted workers and are not stopped by detach.

Attach status and artifacts

For local file-backed Attach, inspect:

.archal/attach/
  attachments.json
  runs.jsonl
  raw/
  grades/
  seeds/
  runs/
  fixes/
  failed/
  logs/

Use archal attach-status --repo . to summarize trace jobs, and archal attach-reprocess --repo . <trace-id> to retry a terminal trace job after fixing the blocker. Key artifacts:

Artifact	What to inspect
`grades/<trace>/grade.json`	verdict, summary, and whether reproduction should continue
`seeds/<trace>/scenario.md`	generated reproduction scenario
`seeds/<trace>/seed.json`	generated seed request or materialized seed metadata
`runs/<trace>/manifest.json`	reproduction status, command, attempts, and evidence
`runs/<trace>/stdout.json`	machine-readable run output
`runs/<trace>/stderr.log`	reproduction stderr
`fixes/<trace>/status.json`	blocked fix status
`fixes/<trace>/pr-details.md`	reviewer summary for a generated fix
`fixes/<trace>/repo.patch`	patch captured when PR creation cannot complete

Safe resume and stop patterns

Pre-prod: rerun the same archal preprod run ... --artifacts <dir> command after fixing setup or code. The loop is bounded by --max-fix-attempts and does not run fix or PR commands unless --allow-external-execution is set.
Pre-prod PRs: keep PR creation behind --open-pr and a draft-producing --pr-command. Archal verifies the PR head, changed files, draft status, and checks before reporting success.
Attach local: use archal detach <trace-dir> --repo . to stop the watcher. Use attach-status to find terminal jobs and attach-reprocess to retry after the evidence or setup is corrected.
Attach hosted: use --check before registration, then keep credentials read-only and source mappings explicit. Hosted source state is operated by Archal workers, so local detach does not apply.

What to hand off

For every loop, include:

exact command and repo
scenario paths or source name
execution policy or pre-prod options
final status and stop reason
artifact directory and the two or three files that justify the decision
PR URL, if opened
remaining blocker, if any

Do not add model-visible instructions telling the tested agent it is in Archal or in a clone-backed run. That changes the behavior being evaluated.

​First preflight

​Pre-prod loop

​Pre-prod status

​Post-prod trace loop

​Attach status and artifacts

​Safe resume and stop patterns

​What to hand off

​See also