Attach production traces

Use Attach when your agent already produces traces and you want Archal to keep checking those traces after they happen. Attach imports traces from a read-only source, grades them, tries to reproduce real failures against service clones, and opens a GitHub PR only when a reproducible fix exists. The important boundary is the same as archal run: your agent and harness keep using normal service SDKs and normal service URLs. Archal handles trace import, isolation, clone routing, scoring, artifacts, and the GitHub workflow behind that boundary.

When to use Attach

Use Attach for a repo that has all three:

a headless command for running the agent
traces from pre-production or production agent runs
a GitHub repo where fixes can be proposed as PRs

If you are still writing the first scenario for an agent, start with Run scenarios against your agent. If you want to keep a clone alive while debugging manually, use Clone sessions.

How the loop works

Attach has two entry points:

Hosted database source: archal attach --source postgres|supabase ... registers a read-only trace source with Archal. Hosted workers poll it and write run state to the dashboard.
Local trace directory: archal attach ./traces --repo . watches a local directory with one trace file per run and writes repo-local artifacts under .archal/attach/.

Hosted Attach supports two ingestion paths: hosted polling for Supabase/Postgres, and client-uploaded normalized traces for file, HTTP/OTel, Langfuse, Braintrust, S3/GCS, and custom sources.

Tier	Providers	Current path
Supported hosted	`supabase`, `postgres`	Register with `archal attach --source ...`
Client upload	`file`, `http`, `otel`, `langfuse`, `braintrust`, `s3`, `gcs`, `custom`	Normalize with `archal trace-source ...`, then pass `--upload --repository owner/repo`

Client upload still needs workspace auth. Use archal login for local setup, or set ARCHAL_TOKEN to a workspace API key in CI and include --repository so Archal knows which repo should receive issues or PRs. The phases are:

Phase	What Archal does	If it cannot continue
Import	Reads the trace and spans, then normalizes them into Archal trace evidence	Marks the source or trace as blocked with the connection or schema error
Grade	Decides whether the trace contains a real task failure worth reproducing	Stores the verdict and reason
Seed	Builds the scenario and clone seed needed to replay the trace-relevant state	Writes the missing evidence instead of guessing
Reproduce	Runs the generated scenario against clones with the repo harness	Marks not reproduced, flaky, or reproduced
Fix	Asks a coding agent to patch the harness or agent code, then validates it	Writes blocked status, issue details, or a PR

fix is the default policy. Use a narrower policy when you only want part of the loop.

Policy	Stops after
`observe`	import
`grade`	grading
`reproduce`	reproduction
`fix`	PR or blocked fix status

Prerequisites

Install and log in:

npm install -D archal
npx archal login
npx archal usage

In CI or a hosted customer repo, set ARCHAL_TOKEN to a workspace API key (archal_ws_...). Use a personal login for local setup.

Install the GitHub App on the target repo:

Install Archal on GitHub

Make sure the repo has a GitHub origin remote:

git remote get-url origin

Hosted sources and --execution-policy fix require a remote that resolves to github.com/<owner>/<repo>.

Add the agent execution contract under archal/:

archal/
  harness.json
  scenario.md
  seeds/
    github.json
    slack.json

harness.json tells Archal how to run the agent. scenario.md gives the standing task and evaluation contract for the trace family. Seed files are optional, but they make reproduction much more reliable when trace evidence is thin.

Export the model keys your agent and the attach worker need.

For a local file-backed loop, the worker checks local environment variables before it starts. Hosted database sources are registered locally, then operated by Archal workers.

Add the harness contract

The minimum archal/harness.json is:

{
  "version": 1,
  "local": {
    "command": "node",
    "args": ["agent.mjs"]
  }
}

The command should run the same headless agent code you would use in archal run: no UI, no browser OAuth, no manual prompts. It should accept the task from AGENT_TASK, call your normal agent runtime, and exit cleanly. Use env only for non-secret defaults that belong in the repo. Keep secrets in your shell, CI, hosted secret manager, or Archal workspace configuration.

{
  "version": 1,
  "local": {
    "command": "pnpm",
    "args": ["agent:run"],
    "env": {
      "NODE_ENV": "test"
    }
  }
}

Add the standing scenario

archal/scenario.md is not a one-off reproduction. It is the standing contract that tells Attach what the agent is supposed to do for this class of traces.

# Billing support follow-up

## Setup
The trace source contains customer-support agent runs involving Stripe
customers, invoices, subscription status, support messages, and refund
decisions. When Archal reproduces a failed trace, it should create the smallest
clone state needed for the customer, invoice, subscription, and support thread
present in the trace.

## Prompt
Use the customer request and available service state from the trace. Resolve the
support task without changing unrelated customers, invoices, or subscriptions.

## Expected Behavior
The agent should verify the customer and invoice, apply the refund or escalation
policy, make only the necessary service changes, and leave a clear support
reply.

## Success Criteria
- [D] No unrelated customer records are modified
- [D] No refund is created unless the invoice is eligible under policy
- [D] Any required escalation task is created exactly once
- [P] The support reply explains the decision without overpromising

## Config
clones: stripe, jira
timeout: 120

The prompt should describe the real task. Do not put instructions in the scenario that tell the tested agent it is using Archal, clones, or a special environment.

Add seed templates

Attach can seed from trace evidence, but the best integrations include repo-owned seed templates. Templates are especially useful when a trace contains IDs and tool calls but not the complete starting state.

archal/seeds/
  stripe-billing-support.json
  jira-support-escalations.json

Seed templates should match the services in archal/scenario.md. The attach worker prefers repo-owned seed templates when they exist, then fills in trace-specific IDs and fields during reproduction. See Seeds for clone seed formats and built-in examples.

Attach a Supabase or Postgres trace source

Use this path when traces live in a database table such as ai_traces with child spans in ai_spans. Create a read-only database user first. It should be able to select trace and span rows, but not mutate application data.

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

Run a readiness check:

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

This registers the source with the active Archal workspace. The database URL is sent to Archal during registration and is not written to .archal/attach/. If your secret already lives in an external secret manager, pass a reference instead of a local environment variable:

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

--database-url-secret-ref must be a secret reference, not a plaintext database URL.

Map custom trace tables

The defaults match the common shape:

Purpose	Default
Trace table	`ai_traces`
Span table	`ai_spans`
Trace id column	`id`
Span id column	`id`
Span trace id column	`trace_id`
Trace updated column	`updated_at`
Span updated column	`updated_at`
Cursor mode	`updated_at_id`

If your schema uses different table or column names, map them explicitly:

npx archal attach \
  --repo . \
  --source postgres \
  --database-url-env TRACE_DATABASE_URL \
  --trace-table public.agent_runs \
  --span-table public.agent_spans \
  --trace-id-column trace_id \
  --span-id-column span_id \
  --span-trace-id-column trace_id \
  --parent-span-id-column parent_span_id \
  --trace-updated-at-column updated_at \
  --span-updated-at-column updated_at

For append-only tables, use created_at_id:

npx archal attach \
  --repo . \
  --source supabase \
  --database-url-env TRACE_DATABASE_URL \
  --cursor-mode created_at_id \
  --trace-created-at-column created_at \
  --span-created-at-column created_at

You can also start from a known cursor:

npx archal attach \
  --repo . \
  --source supabase \
  --database-url-env TRACE_DATABASE_URL \
  --traces-watermark-at 2026-05-27T00:00:00.000Z \
  --traces-watermark-id trace_123

Filter imported traces

Use filters when the trace source contains many agents, tenants, or statuses.

npx archal attach \
  --repo . \
  --source supabase \
  --database-url-env TRACE_DATABASE_URL \
  --source-workspace-id workspace_123 \
  --source-agent-id support-agent \
  --source-status failed error \
  --source-trace-group billing-support \
  --source-limit 250 \
  --source-metadata owner=customer-success

Metadata is for labels and routing context. Do not put secrets in --source-metadata.

Attach a local trace directory

Use a local directory when you are testing the loop before a hosted source is ready, or when traces arrive as files.

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

Each file in ./prod-traces should contain one top-level trace and enough child span data for grading. The local loop writes artifacts under:

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

Stop a local file-backed attachment with:

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

archal detach is for local file-backed attachments. Hosted database sources are managed from the dashboard.

Dashboard pages

Attach results live in the workspace dashboard.

Page	Use it for
Imported traces	Source health, trace import status, grade verdicts, and blocked reasons
Reproduced failures	Seed evidence, reproduction status, clone parity, and run artifacts
Opened issues/PRs	GitHub issue links, PR links, branch names, check status, and residual risk

The pages are intentionally split so an operator can answer three different questions:

Did Archal receive the trace?
Did Archal reproduce a real failure against clones?
Did Archal open something reviewable in GitHub?

Artifact contract

Hosted sources surface these artifacts in the dashboard. Local file-backed attachments write the same kinds of artifacts under .archal/attach/.

Artifact	Purpose
`routing.json`	What trace was imported and how it moved through the loop
`grade.json`	Grade verdict, failure summary, evidence, and whether reproduction should continue
`scenario.md`	Generated reproduction scenario for the trace
`seed.json`	Generated seed request or materialized seed metadata
`manifest.json`	Phase status, commands, attempts, evidence, and output paths
`stdout.json`	Machine-readable output from the reproduction run
`stderr.log`	Reproduction command stderr
`status.json`	Fix status when a run blocks before a patch or PR
`pr-details.md`	Review summary for a generated fix
`repo.patch`	Patch captured from the fix worker when a PR cannot be opened

Artifacts should explain whether a failure was an agent issue, missing trace evidence, clone fidelity gap, harness issue, or GitHub/CI issue. When evidence is missing, Attach should say what is missing instead of manufacturing a reproduction.

Troubleshooting

No traces import

Check:

archal login or ARCHAL_TOKEN
GitHub origin remote
the read-only database URL
table and column mappings
--source-status, --source-agent-id, and other filters
whether updated_at or created_at values move past the stored cursor

Run archal attach --check ... with the same source flags to validate setup without registering or starting work.

Hosted source registration fails

Common causes:

no logged-in Archal account
missing ARCHAL_TOKEN in CI
--database-url-env points to an unset environment variable
--database-url-secret-ref contains a plaintext credential
repo remote is missing or is not GitHub

Reproduction is blocked as missing evidence

That usually means the trace does not contain enough state to build the starting clone state. Add one of:

richer trace fields such as input_data, output_data, state snapshots, or tool-call arguments
child spans for service reads and writes
repo-owned seed templates under archal/seeds/
a narrower archal/scenario.md that tells Archal what state matters

Blocked reproduction is a useful signal. It means Archal refused to claim a failure was reproducible without enough evidence.

A PR is not opened

Check:

the execution policy is fix
the GitHub App is installed on the repo
the repo has an origin remote on GitHub
reproduction status is reproduced or flaky
generated changes pass local validation
GitHub branch protection and CI status

Attach opens PRs for review. It does not auto-merge them.

Safety

Use read-only trace source credentials.
Do not commit database URLs, API keys, or model keys.
Prefer --database-url-env for local setup and secret references for hosted production setup.
Keep trace artifacts redacted before sharing them outside the workspace.
Do not add model-visible copy telling the tested agent it is in Archal or a clone-backed run.
Let the GitHub App open PRs; do not bypass the review path with direct pushes to protected branches.

Documentation Index

​When to use Attach

​How the loop works

​Prerequisites

​Add the harness contract

​Add the standing scenario

​Add seed templates

​Attach a Supabase or Postgres trace source

​Map custom trace tables

​Filter imported traces

​Attach a local trace directory

​Dashboard pages

​Artifact contract

​Troubleshooting

​No traces import

​Hosted source registration fails

​Reproduction is blocked as missing evidence

​A PR is not opened

​Safety

​Next steps