archal autoloop

archal autoloop connects a harness repo to trace evidence. Hosted database sources are registered with Archal and processed by hosted workers. Local trace directories run a local loop and write artifacts under .archal/autoloop/.

Usage

archal autoloop [trace-dir] --repo <dir> [options]

trace-dir is required for local file-backed autoloops. Omit it when using --source postgres or --source supabase.

Required options

Option	Description
`--repo <dir>`	Harness repository to autoloop

For hosted database sources, also set:

Option	Description
`--source <provider>`	`postgres` or `supabase`
`--database-url-env <name>`	Environment variable containing the database URL
`--database-url-secret-ref <ref>`	External secret reference for the database URL

Use exactly one of --database-url-env or --database-url-secret-ref.

Source configuration (`.archal.json`)

Per-source facts live in the autoloop block of .archal.json in the harness repo, not in flags. Every field is optional; unset fields fall back to the defaults shown.

{
  "autoloop": {
    "source": {
      "name": "prod-agent-traces",
      "id": "<hosted source uuid, optional>",
      "mapping": {
        "traces": {
          "table": "ai_traces",
          "idColumn": "id",
          "updatedAtColumn": "updated_at",
          "createdAtColumn": "created_at"
        },
        "spans": {
          "table": "ai_spans",
          "idColumn": "id",
          "traceIdColumn": "trace_id",
          "parentSpanIdColumn": "parent_span_id",
          "updatedAtColumn": "updated_at",
          "createdAtColumn": "created_at"
        }
      },
      "cursor": { "mode": "updated_at_id" },
      "filters": {
        "workspaceIds": [],
        "statuses": [],
        "traceGroups": [],
        "agentIds": [],
        "limit": null
      },
      "metadata": {}
    },
    "benchmarkExport": false
  }
}

source.name is the stable display name; source.id is the hosted source UUID (set both to re-register an existing source under its display name).
cursor.mode is updated_at_id or created_at_id; use created_at_id for append-only tables, and map mapping.traces.updatedAtColumn and mapping.spans.updatedAtColumn to the creation timestamp column too (the updated columns are always required).
cursor.watermarks is a repair escape hatch: set it only to rewind or skip the import cursor. Streams you leave unset keep their server-stored position across re-registrations. Setting a stream’s at or id to a timestamp or id moves its cursor; setting at or id to null resets that stream and re-imports from the beginning. Do not leave null placeholders in the config: { "at": null } is a deliberate reset on every registration, not an unset default.
filters restrict which rows import (workspaceIds, statuses, traceGroups, agentIds, and a per-poll limit).
metadata stores non-secret labels with the source.

The config file is discovered by walking up from --repo, so the source configuration always tracks the repo being fixed. Passing one of the retired source flags exits 2 with a message naming the config field to set instead.

Execution policy

--execution-policy observe|grade|seed|reproduce|fix

Default: fix

Policy	Runs through
`observe`	import only; no sandbox is launched
`grade`	import and grade
`seed`	import, grade, and seed
`reproduce`	import, grade, seed, and reproduce
`fix`	full loop, including GitHub issue or PR creation

Validation

Use --check to validate prerequisites without registering a hosted source or starting a local loop:

archal autoloop \
  --repo . \
  --source supabase \
  --database-url-env TRACE_DATABASE_URL \
  --check

Examples

{
  "autoloop": {
    "source": { "name": "prod-agent-traces" }
  }
}

export TRACE_DATABASE_URL='postgres://readonly:...'

archal autoloop \
  --repo . \
  --source supabase \
  --database-url-env TRACE_DATABASE_URL

{
  "autoloop": {
    "source": {
      "mapping": {
        "traces": { "table": "public.ai_traces", "idColumn": "id" },
        "spans": {
          "table": "public.ai_spans",
          "idColumn": "id",
          "traceIdColumn": "trace_id",
          "parentSpanIdColumn": "parent_span_id"
        }
      }
    }
  }
}

archal autoloop \
  --repo . \
  --source postgres \
  --database-url-env TRACE_DATABASE_URL

Use a secret reference instead of a local database URL:

archal autoloop \
  --repo . \
  --source postgres \
  --database-url-secret-ref aws-secretsmanager://customer/prod-agent-traces

Watch a local directory and stop after reproduction:

archal autoloop ./prod-traces --repo . --execution-policy reproduce

Stop a local file-backed autoloop:

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

archal autoloop detach applies to local file-backed autoloops. Hosted database sources are managed by hosted Autoloop workers; local detach does not disable them.

Output

Hosted database source registration prints:

Registered hosted trace source: prod-agent-traces
Source id: 11111111-1111-4111-8111-111111111111
Repository: acme/agent
Provider: supabase
Archal will poll this read-only source from the hosted autoloop worker.

Local file-backed autoloops print the trace directory, repo, resolved GitHub repository, execution policy, artifact directories, loop process id, and log path.

Local artifacts

Local file-backed autoloops write:

.archal/autoloop/
  autoloops.json
  runs.jsonl
  raw/
  grades/
  seeds/
  runs/
  fixes/
  failed/
  logs/

Hosted database sources expose phase information in workspace Autoloop state and through archal autoloop status <run-id>, which prints a hosted run’s status, grade evidence, and artifacts. Without a run id, archal autoloop status reads the repo-local ledger for file-backed autoloops only. For terminal-first handoffs, pair local artifacts with:

archal autoloop status --repo .
archal autoloop reprocess --repo . <trace-id>

Use autoloop status to summarize terminal trace jobs. Use autoloop reprocess after fixing the missing evidence, credential, mapping, harness, or GitHub blocker that caused a trace job to stop. With --json, the local view emits { "ok": true, "jobs": [...] } where each job row carries the trace id, status, phase, next action, and artifact summary. The shape is identical with or without --wait; a failed wait (timeout or a terminal-failed job) emits "ok": false with error and "kind": "wait_failed" and exits 1.

Exit behavior

archal autoloop exits non-zero when prerequisites fail, source options are invalid, database credentials are missing or malformed, the repo cannot be resolved to GitHub where required, or hosted registration fails.

CLI

SDK

API reference

Clones

archal autoloop

Usage

Required options

Source configuration (`.archal.json`)

Execution policy

Validation

Examples

Output

Local artifacts

Exit behavior

See also

​Usage

​Required options

​Source configuration (.archal.json)

​Execution policy

​Validation

​Examples

​Output

​Local artifacts

​Exit behavior

​See also

Usage

Required options

Source configuration (`.archal.json`)

Execution policy

Validation

Examples

Output

Local artifacts

Exit behavior

See also