> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# archal autoloop

> Register a hosted Postgres or Supabase trace source, or run a local trace-directory loop that grades, reproduces, and opens fix PRs against your harness.

`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

```bash theme={null}
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.

```json theme={null}
{
  "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

```bash theme={null}
--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:

```bash theme={null}
archal autoloop \
  --repo . \
  --source supabase \
  --database-url-env TRACE_DATABASE_URL \
  --check
```

## Examples

Register a hosted Supabase source (name it in `.archal.json`):

```json theme={null}
{
  "autoloop": {
    "source": { "name": "prod-agent-traces" }
  }
}
```

```bash theme={null}
export TRACE_DATABASE_URL='postgres://readonly:...'

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

Register a hosted Postgres source with custom mapping:

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

```bash theme={null}
archal autoloop \
  --repo . \
  --source postgres \
  --database-url-env TRACE_DATABASE_URL
```

Use a secret reference instead of a local database URL:

```bash theme={null}
archal autoloop \
  --repo . \
  --source postgres \
  --database-url-secret-ref aws-secretsmanager://customer/prod-agent-traces
```

Watch a local directory and stop after reproduction:

```bash theme={null}
archal autoloop ./prod-traces --repo . --execution-policy reproduce
```

Stop a local file-backed autoloop:

```bash theme={null}
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:

```text theme={null}
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:

```text theme={null}
.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:

```bash theme={null}
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.

## See also

* [Autoloop production traces](/guides/autoloop-production-traces)
* [Run scenarios against your agent](/guides/run-with-agent)
* [Seeds](/guides/seeds)