archal 0.9.19 → 0.10.0

package/dist/vitest/runtime/hosted-session-reaper.js

@@ -4,7 +4,7 @@ import {
   createHostedAuthLease,
   parsePositiveInteger,
   runHostedSessionReaper
-} from "../chunk-WZ7SA4CK.js";
+} from "../chunk-7L4BBB6M.js";
 
 // src/runtime/hosted-session-reaper.ts
 var VITEST_AUTH_LEASE_OPTIONS = {

package/dist/vitest/runtime/setup-files.js

@@ -1,7 +1,7 @@
 import {
   bootstrapArchalVitestRouting
-} from "../chunk-L36NXAU6.js";
-import "../chunk-WZ7SA4CK.js";
+} from "../chunk-2PDHTPZC.js";
+import "../chunk-7L4BBB6M.js";
 
 // src/runtime/setup-files.ts
 import { existsSync, rmSync } from "fs";

package/manifest.json

@@ -0,0 +1,9 @@
+{
+  "version": 1,
+  "bundleKind": "archal-package-full",
+  "capabilities": [
+    "hosted-autoloop",
+    "clone-runtime",
+    "clone-free-autoloop"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archal",
-  "version": "0.9.19",
+  "version": "0.10.0",
   "description": "Test your agents & integrations against service clones",
   "type": "module",
   "main": "dist/index.cjs",
@@ -13,9 +13,11 @@
       "types": "./dist/index.d.cts",
       "default": "./dist/index.cjs"
     },
-    "./harness": {
-      "types": "./dist/harness.d.cts",
-      "default": "./dist/harness.cjs"
+    "./scenarios": {
+      "types": "./dist/scenarios.d.cts",
+      "import": "./dist/scenarios.cjs",
+      "require": "./dist/scenarios.cjs",
+      "default": "./dist/scenarios.cjs"
     },
     "./vitest": {
       "types": "./dist/vitest/index.d.ts",
@@ -45,12 +47,21 @@
   "files": [
     "bin",
     "dist",
+    "manifest.json",
     "skills",
     "clone-assets",
+    "agents",
     "LICENSE"
   ],
+  "scripts": {
+    "verify:artifacts": "node scripts/assert-artifacts.mjs",
+    "prepack": "node scripts/assert-artifacts.mjs",
+    "prepare": "node scripts/prepare.cjs",
+    "typecheck:raw": "node --check bin/archal.cjs && node --check scripts/assert-artifacts.mjs && node --check scripts/prepare.cjs",
+    "typecheck": "pnpm run typecheck:raw"
+  },
   "peerDependencies": {
-    "vitest": ">=2.1.0"
+    "vitest": ">=2.1.0 <3"
   },
   "peerDependenciesMeta": {
     "vitest": {
@@ -58,13 +69,8 @@
     }
   },
   "dependencies": {
-    "@aws-sdk/client-secrets-manager": "^3.1001.0",
-    "e2b": "^2.19.5",
-    "picomatch": "^4.0.4"
-  },
-  "scripts": {
-    "verify:artifacts": "node scripts/assert-artifacts.mjs",
-    "typecheck:raw": "node --check bin/archal.cjs && node --check scripts/assert-artifacts.mjs && node --check scripts/prepare.cjs",
-    "typecheck": "pnpm run typecheck:raw"
+    "@aws-sdk/client-secrets-manager": "^3.1065.0",
+    "e2b": "^2.28.2",
+    "tsx": "^4.19.0"
   }
-}
+}

package/skills/archal-agent/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: archal-agent
+description: The front door for using Archal to test, debug, and fix an AI agent. START HERE, then route to the right sub-skill instead of guessing. Use when the user says "use Archal", "test my agent", "set up Archal", "my agent is failing", "reproduce this production failure", "grade my traces", or otherwise wants to evaluate, debug, or auto-fix an agent against service clones. Pick this whenever the request is Archal-shaped but the specific workflow is unclear.
+user-invocable: true
+argument-hint: "[what you want to do with your agent]"
+---
+
+# Archal
+
+You are the entry point for Archal. Archal is the QA layer for AI agents: it
+runs an agent against stateful behavioral clones of real services (GitHub,
+Slack, Stripe, Linear, Jira, Supabase, and more), scores how well it satisfies
+each scenario, and turns failures into reproductions and PR fixes. Your job here
+is to orient the operator and route to the sub-skill that owns their workflow.
+Do not inline those flows; hand off by exact name and let the sub-skill drive.
+
+## Product mental model
+
+Archal tests AI agents against service clones instead of real services, so every
+run is deterministic and replayable. You describe a task and success criteria,
+the agent runs against clones, and an evaluator scores satisfaction (a
+probability, not pass/fail). When a real production trace shows a failure, Archal
+reproduces it on clones from trace evidence and ships the fix as a GitHub PR.
+Everything aims at the same thing: deterministic, replayable evals you can trust.
+
+## Decision guide
+
+| I want to... | Route to |
+|--------------|----------|
+| Set up Archal in a repo from scratch (install, auth, detect clones) | `onboard` |
+| Write or edit a scenario test file | `scenario` |
+| Load explicit JSON/SQL/catalog state into a clone (deterministic, no LLM) | `seed` |
+| Run scenarios or tasks and interpret satisfaction scores and failures | `eval` |
+| Wire clones into an existing Vitest suite | `vitest` |
+| Connect a repo's production observability so traces get captured | `install-agent` |
+| Run the autoloop (ingest -> grade -> find-failed -> reproduce-on-clones) and ship the fix as a PR (autofix) over real trace sources | `autoloop` |
+| Turn autofix or autoloop on/off for an agent | `autoloop`; the copilot can toggle either |
+
+If the user is brand new and has none of this set up, start with `onboard`; it
+detects clones and routes onward from there.
+
+## The sub-skills
+
+Each lives in `packages/archal/skills/` and owns its own commands, contracts,
+and mental model. Route by exact name:
+
+- `onboard` — set up Archal in a repo from scratch: install the CLI, handle auth,
+  detect which clones the agent needs, and hand off to the right workflow.
+- `scenario` — author and edit scenario test files (Setup / Prompt / Expected
+  Behavior / Success Criteria) that `archal run` executes against clones.
+- `seed` — load explicit JSON, SQL, or catalog state into a clone deterministically,
+  with no LLM in the loop, so runs start from a known fixture state.
+- `eval` — run scenarios or inline tasks against clones and interpret the results:
+  satisfaction scores, `[D]` vs `[P]` criteria, trace inspection, failure diagnosis.
+- `vitest` — wire clones into an existing Vitest suite using the right composition
+  pattern, so the agent's own tests route through clones.
+- `install-agent` — connect a repo's production observability (OTLP, Langfuse,
+  Braintrust, database trace tables) so real agent traces are captured for Archal.
+- `autoloop` — the loop over real trace sources: ingest a trace, grade it for a
+  real failure, find the failed trace, and reproduce it on clones. Autofix (the
+  fix/PR step) is a separate toggle on top of this: when turned on, autoloop
+  reproduces a failure and ships the fix as a PR.
+
+## Autoloop and autofix toggles
+
+Autoloop (ingest -> grade -> find-failed -> reproduce-on-clones) and autofix (the
+fix/PR step) are **separate per-agent toggles**. Autofix is opt-in: it is not part
+of autoloop until it is turned on. Either can be switched on or off per agent from
+the agents tab, the CLI (`--execution-policy reproduce` is autoloop with autofix
+off; `fix` turns autofix on), or by asking the Archal copilot in chat — the
+copilot can toggle either for an agent. When the user asks to turn autofix or
+autoloop on/off for an agent, handle the toggle, then route to `autoloop` for the
+deeper flow.
+
+## Provider-switchable remediation
+
+The Archal copilot is not locked to one model. When autofix reproduces a failure
+and writes a fix, the user can drive that remediation with their own agent —
+fix is written by their Claude Code, Cursor, or Codex — or let Archal's managed
+agent do it. Mention this when the user asks who writes the fix or wants to use
+their own coding agent, then route to `autoloop`.
+
+## Docs
+
+- Quickstart: https://docs.archal.ai/quickstart
+- Full docs: https://docs.archal.ai

package/skills/autoloop/SKILL.md

@@ -0,0 +1,391 @@
+---
+name: autoloop
+description: Wire Archal Autoloop to a repo plus a real agent-trace source, then drive the import -> grade -> reproduce -> PR-fix loop. USE THIS whenever the user wants to turn production agent traces into reproducible failures and fixes: "I have prod agent traces and want to reproduce a failure", "import my Langfuse / Braintrust / OTel / Supabase traces", "connect a trace source", "grade my prod traces", "turn a failed trace into a PR", "set up / configure the autoloop", or any mention of replaying, grading, or auto-fixing real traces. Also fires when diagnosing a stuck import, grade, reproduction, or PR-fix run, or configuring trace schema mapping.
+user-invocable: true
+argument-hint: "[repo, trace source, or failure description]"
+---
+
+# Archal Autoloop
+
+You help users connect real agent traces to Archal, then drive the loop that
+turns a production failure into a verified reproduction and, when the user
+opts in, a fix PR. Your job is to wire the repo, trace source, harness, and
+scenario without guessing or leaking secrets.
+
+Autoloop is not a replacement for `archal run`. It uses the same harness and
+clone routing, but the trigger is a trace that already happened.
+
+Autoloop is also not arbitrary production trace replay. It can reproduce a
+failure only when the trace, scenario contract, and seed templates contain
+enough evidence to reconstruct the service state that matters. If the evidence
+is thin, block and name the missing data instead of claiming reproduction.
+
+## Product mental model
+
+Autoloop runs this loop:
+
+1. Import a trace and its child spans from a read-only source.
+2. Grade whether the trace contains a real failure.
+3. Build a reproduction scenario and clone seed from trace evidence plus
+   repo-owned seed templates.
+4. Run the reproduction against service clones through the customer harness.
+5. If reproduced, patch the repo and open a GitHub PR.
+
+Steps 1-4 are **autoloop**: ingest -> grade -> find the failed trace ->
+reproduce on clones. Step 5 (writing the fix and opening the PR) is **autofix**,
+a separate opt-in step that is *not* part of autoloop until it is turned on.
+
+## Consent breakpoints (do these before you touch anything)
+
+Autoloop can act on the user's real repository and reads their production
+traces. Before you register a source or start a loop, walk the three
+breakpoints below **in order**. Each is a hard STOP: ask the question, wait for
+an explicit answer, and only then proceed. Do not batch them, do not assume a
+default, and do not start the loop until all three are answered.
+
+### Breakpoint 1 - PR-opening consent
+
+STOP. Before anything else, state the consequence plainly and ask the user to
+choose:
+
+> Autoloop can open fix PRs on your repo automatically. With **Autofix ON**,
+> every imported production failure that reproduces gets a fix PR opened on
+> your repo. With **Autofix OFF**, autoloop stops after reproducing the failure
+> and opens no PRs; you (or your agent) take over from the reproduction.
+> Which do you want?
+
+Map the answer explicitly and never rely on the CLI default:
+
+| User wants | Pass | Autofix |
+|------------|------|---------|
+| Fix PRs opened automatically | `--execution-policy fix` | ON |
+| Reproduce only, no PRs | `--execution-policy reproduce` | OFF |
+
+The bare `archal autoloop` default is `fix`, which opens PRs. **Never let that
+default stand in silently.** Always pass an explicit `--execution-policy` that
+matches the user's answer. The reproduce-only promise is real: with
+`--execution-policy reproduce`, autoloop grades and replays against clones and
+then stops, with no fix and no PR.
+
+### Breakpoint 2 - GitHub App install (only if the user chose fix PRs)
+
+If the user chose **reproduce only**, skip this breakpoint and note that the
+fix path stays off.
+
+If the user chose **fix PRs**, STOP and explain, then wait for confirmation:
+
+> The fix-PR path needs the **Archal GitHub App** installed on the target repo
+> and linked to your Archal workspace. The app is granted least-privilege
+> access: write to repository contents (to push a fix branch) and to pull
+> requests (to open the PR), plus read-only access to Actions, checks, commit
+> statuses, and metadata so it can watch its own PR's checks. It gets **no**
+> issue access, and it opens a PR from a fix branch rather than pushing to your
+> default branch. Install it from the Archal dashboard's integrations /
+> connect-repo flow, then tell me once it is installed (or say you'd rather stay
+> reproduce-only).
+
+Do not proceed to a `fix` policy until the user confirms. Verify the install
+with the machine check before starting the loop:
+
+```bash
+npx archal autoloop --repo . --execution-policy fix --check --json
+```
+
+The `GitHub App auth` check must pass (a repo-scoped PR token can be minted). A
+failing check tells you exactly what is missing; relay that, don't guess.
+
+### Breakpoint 3 - read-only database connection string
+
+STOP whenever the trace source is a database (Postgres or Supabase). Do not
+accept a privileged or default connection string. Walk the user through
+creating a **read-only** role scoped to the trace tables, then:
+
+- The credential is passed by **environment variable name**, not value:
+  `--database-url-env <ENV_VAR_NAME>`. Never put the URL inline in a command,
+  never echo it, never commit it.
+- In hosted production, prefer a secret reference:
+  `--database-url-secret-ref <ref>` (the ref must not contain a plaintext
+  credential).
+
+Ask the user to confirm the role is read-only and the URL lives in an env var
+or secret ref before you run any `--source` command. See
+`references/hosted-sources.md` for the read-only-role and flag detail.
+
+## Discover first
+
+Before changing anything, inspect the repo:
+
+1. `package.json` and scripts: how is the agent run? What tests should a fix PR
+   pass?
+2. Auth: `archal usage` must pass. For hosted sources, CI, or headless agents,
+   use a workspace API key in `ARCHAL_TOKEN`, created by an owner/admin with
+   `archal workspace api-key create <label>`.
+3. GitHub remote: `git remote get-url origin`. Hosted sources and the `fix`
+   policy need an origin that resolves to `github.com/<owner>/<repo>`.
+4. Docker: high-fidelity reproduction needs Docker or sandbox mode available.
+   If Docker is unavailable, stop before claiming clone-backed reproduction.
+5. Existing Archal files: `.archal.json`, `archal/harness.json`,
+   `archal/scenario.md`, `archal/seeds/*.json`, `scenarios/*.md`.
+6. Service SDKs and likely clones: `stripe` -> `stripe`; `@octokit/rest`,
+   `octokit` -> `github`; `@slack/web-api`, `@slack/bolt` -> `slack`;
+   `jira.js` -> `jira`; `@linear/sdk` -> `linear`; `@supabase/supabase-js`,
+   `pg` -> `supabase`; `googleapis` -> `google-workspace`.
+7. Trace source shape: provider (local files, Postgres, Supabase), trace/span
+   table names, id columns, parent-span column, cursor columns, and any
+   workspace/agent/status/group filters.
+
+Never print secrets while inspecting. Show only the env var name or secret
+reference, never a database URL.
+
+## Setup files
+
+### `archal/harness.json`
+
+```json
+{ "version": 1, "local": { "command": "node", "args": ["agent.mjs"] } }
+```
+
+The command must be headless and repeatable, and run the real agent path (not a
+mock). During reproduction Archal invokes it through `archal run`, so the agent
+reads its task from `AGENT_TASK` and prints its final answer to stdout. Align it
+with the `agent` command in `.archal.json` if one exists.
+
+### `archal/scenario.md`
+
+Describes the standing task and checks for this trace family. Required sections:
+`# Title`, `## Setup`, `## Prompt`, `## Expected Behavior`,
+`## Success Criteria` (`[D]` deterministic, `[P]` probabilistic), `## Config`
+(`clones:`, `timeout:`). Keep model-visible instructions realistic: do not tell
+the tested agent it is in Archal, a clone-backed environment, or a replay.
+
+### Seed templates (when trace evidence is thin)
+
+Put stable service state for the task family under `archal/seeds/*.json` (e.g.
+`stripe-billing-support.json`). Autoloop fills in trace-specific identifiers.
+This is far safer than expecting a weak trace to reconstruct full service state.
+
+## Register the loop
+
+### Local trace directory (pilot / exported files)
+
+```bash
+npx archal autoloop ./prod-traces --repo . --execution-policy reproduce
+```
+
+Uses the policy from Breakpoint 1. Artifacts land under `.archal/autoloop/`
+(see the artifact guide below). Stop it with
+`npx archal autoloop detach ./prod-traces --repo .`.
+
+### Hosted database source (Postgres / Supabase)
+
+The source identity, schema mapping, cursor, and filters live in the
+`.archal.json` `autoloop` block, not in flags. The starter takes only `--repo`,
+`--source`, the credential (`--database-url-env` or `--database-url-secret-ref`),
+`--execution-policy`, `--check`, and `--json`. A minimal config names the source:
+
+```jsonc
+// .archal.json
+{
+  "autoloop": {
+    "source": { "name": "prod-agent-traces" }
+  }
+}
+```
+
+Check first, then register (drop `--check` to register). Registration posts the
+source config to Archal and returns; hosted workers own polling after that, so
+`autoloop detach` does not disable a hosted source.
+
+```bash
+npx archal autoloop --repo . --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --execution-policy reproduce --check --json
+```
+
+See `references/hosted-sources.md` for the read-only-role and secret-ref detail,
+and `references/trace-schema-mapping.md` when the customer's tables differ from
+the `ai_traces` / `ai_spans` defaults (custom columns, append-only cursor mode,
+and source filters). Both are configured under `autoloop.source` in `.archal.json`.
+
+### Client-side ingestion (traces not already in a hosted table)
+
+For traces not in a hosted Postgres/Supabase table, use the dashboard OTLP
+endpoint or drop normalized JSON files into an autoloop watch directory:
+
+- **Dashboard OTLP** — point the vendor's OpenTelemetry exporter at the OTLP
+  URL shown in the dashboard. Works for Langfuse, Braintrust, OTel, and custom
+  HTTP sources. No CLI command required.
+- **File drop** — place normalized Archal trace JSON files in the watch
+  directory and run `archal autoloop <trace-dir>`. The loop picks them up on
+  the next import cycle.
+
+## Policy semantics
+
+Two independent toggles, both per-agent and switchable from the agents tab, the
+CLI, or the Archal copilot:
+
+- **Autoloop toggle** - whether the loop runs at all (import -> grade ->
+  reproduce). Off means no traces are processed.
+- **Autofix toggle** - whether the fix / PR phase runs. ON maps to
+  `--execution-policy fix`; OFF maps to `--execution-policy reproduce`.
+
+`--execution-policy` stops the loop at a phase; narrower policies stop earlier:
+
+| Policy | Stops after | Autofix |
+|--------|-------------|---------|
+| `observe` | import | off |
+| `grade` | grading | off |
+| `seed` | seeding | off |
+| `reproduce` | reproduction | off |
+| `fix` | PR or blocked fix status | on |
+
+Policy is **pinned at import time**. Flipping a toggle affects future imports
+and retries, not runs that already imported under the old policy.
+
+## CLI surface
+
+Machine-readable, CLI only. Every command takes `--json` for scripting. Do not
+call raw REST endpoints or dashboard URLs.
+
+The starter flags are deliberately narrow: `--repo`, `--source`,
+`--database-url-env`, `--database-url-secret-ref`, `--execution-policy`,
+`--check`, and `--json`. Everything about the source itself — its name/id, schema
+mapping, cursor mode and watermarks, filters, metadata, and regression scenarios export —
+lives in the `.archal.json` `autoloop` block, not in flags. A retired flag now
+exits `2` with a message naming the config field to set instead.
+
+- `archal autoloop [trace-dir] --repo <repo> [--source postgres|supabase] [--execution-policy observe|grade|seed|reproduce|fix] [--check] [--json]`
+  starts a local file-backed loop or registers a hosted source.
+  - `--check --json` emits `{ ok, checks[], nextStep? }` and exits `2` when not
+    ready, `0` when ready. Read `checks[]` for the exact blocker.
+  - The starter (no `--check`) `--json` emits `{ ok, ... }` describing the
+    registered source or started loop.
+- `archal autoloop status [run-id] [--json]` - without a run id: local ledger
+  status for each trace job. `--json` emits `{ ok, jobs[] }`; each row is a
+  trace-job summary (`traceId`, `status`, `currentPhase`, `action`,
+  `nextAction`, `attemptSummary`, `checkSummary`, `artifactSummary`,
+  `reference`, `stale`, `retryable`, `updatedAt`, plus raw ledger fields such
+  as `prUrl` and `error` when present). `--wait --until terminal|pr
+  --poll-interval <seconds> --wait-timeout <seconds>` polls for CI gates and
+  exits `0` when the condition holds, `1` on timeout or a terminal-failed job;
+  the `--json` shape is identical with or without `--wait`, and a failed wait
+  emits `{ ok: false, jobs[], error, kind: "wait_failed" }`.
+  With a hosted `<run-id>`: fetches that run's status, grade evidence, and
+  artifacts. This is the take-over entry point. `--json` emits
+  `{ ok, run, gradeEvidence, artifacts }`; `--artifact <artifactId>` prints one
+  artifact's payload instead. The wait-family flags and `--repo` are local-only
+  and cannot be combined with a run id.
+- `archal autoloop reprocess [trace-id] | --all-failed` - re-queue terminal
+  local trace jobs after fixing the blocker. Hidden from help (repair escape
+  hatch), still runnable.
+- `archal autoloop detach <trace-dir>` - stop a local file-backed loop. Does
+  not disable a hosted source.
+
+Related commands used during take-over and debugging:
+
+- `archal reproduce failures <grades> --json` - turn failed grades into a
+  seedable reproduction package. `archal reproduce verify <package-dir> --json`
+  re-checks seed and run evidence for an existing package.
+- `archal grade trace --request <file> --json` - grade one trace.
+- `archal autoloop status --json` - inspect registered sources and job state.
+- `archal traces list|detail --json` - list and inspect uploaded traces.
+
+Exit codes across this family: `0` success, `1` failure, `2` usage error or
+not-ready. Failures under `--json` emit `{ ok: false, error, kind, ... }`.
+
+## Take-over workflow
+
+The killer use case: autoloop graded (and, under `reproduce`, replayed) a real
+production failure, and now a coding agent takes over to write and verify the
+fix. Runbook:
+
+1. **Find the run.** `archal autoloop status --json` for local jobs, or use the
+   hosted run id you were handed. Note the trace id and phase.
+2. **Pull the evidence into context.** `archal autoloop status <run-id> --json`
+   returns `run` (grade status, failure class, reproduction status, PR/branch
+   if any, blocking reason), `gradeEvidence` (score, threshold, summary,
+   per-criterion results), and `artifacts` (ids, types, sizes).
+3. **Fetch the artifact you need.** For a specific payload (grade summary,
+   generated scenario, seed, run manifest), pass its id:
+   `archal autoloop status <run-id> --artifact <artifactId> --json`. For a
+   local loop, the same evidence is on disk under `.archal/autoloop/` (see the
+   artifact guide).
+4. **Reproduce locally.** Turn the graded failure into a reproduction package
+   and replay it against clones: `archal reproduce failures <grades> --json`
+   (point `<grades>` at the local `grades/<trace>/grade.json` or a grade
+   artifact directory). This confirms the failure is real before you touch code.
+5. **Write the fix** in the repo.
+6. **Verify against the same reproduction.** `archal reproduce verify <package-dir> --json`
+   (or re-run step 4). The fix is done when the same reproduction that failed
+   now passes.
+7. **Watch it land.** With Autofix ON, autoloop opens the PR; gate on it with
+   `archal autoloop status --wait --until pr` or watch the
+   PR directly. With Autofix OFF, open the PR yourself once the reproduction
+   passes.
+
+## Diagnose failures
+
+Classify precisely; do not manufacture a seed or claim reproduction succeeded
+when evidence is thin.
+
+- **Trace import** - source auth, mapping, cursor, filters, or a bad trace shape.
+- **Trace ingestion** - rejected upload, missing workspace auth, bad idempotency
+  key, or OTLP receiver auth failure.
+- **Grade** - judge could not determine the expected outcome; missing evaluator
+  contract; trace lacks task context.
+- **Missing evidence** - trace lacks enough state to seed. Add spans, state
+  snapshots, or repo-owned seed templates.
+- **Reproduction** - scenario or seed could not replay the failure. Inspect the
+  generated `scenario.md`, `seed.json`, and run manifest.
+- **Harness** - agent command crashes, hangs, needs UI auth, or never reaches
+  clone-routed services.
+- **Fix generation** - patch does not apply, tests fail, no changes produced,
+  or PR metadata is incomplete.
+- **GitHub** - App missing, branch protection, permission denied, or PR checks
+  unavailable. Re-run `archal autoloop --check --json` to confirm.
+
+## Artifact reading guide (local loops)
+
+Local file-backed loops write repo-local artifacts; hosted loops expose the
+same phase information through `archal autoloop status <run-id>`.
+
+| Artifact | What to inspect |
+|----------|-----------------|
+| `grades/<trace>/routing.json` | trace import route and selected phase |
+| `grades/<trace>/grade.json` | verdict, summary, reproduction decision |
+| `seeds/<trace>/scenario.md` | generated reproduction scenario |
+| `seeds/<trace>/seed.json` | materialized seed metadata |
+| `runs/<trace>/manifest.json` | reproduction status, command, attempts |
+| `runs/<trace>/stdout.json` | machine-readable run output |
+| `fixes/<trace>/status.json` | blocked fix status |
+| `fixes/<trace>/pr-details.md` | PR reviewer summary |
+| `fixes/<trace>/repo.patch` | patch captured when PR creation cannot complete |
+
+## Security rules
+
+- Use read-only trace database credentials (Breakpoint 3).
+- Never commit or echo database URLs, API keys, model keys, or GitHub tokens.
+  Prefer `--database-url-env` locally and `--database-url-secret-ref` in hosted
+  production.
+- Do not pass production write credentials to a clone-routed reproduction.
+- Do not add model-visible copy that reveals Archal or clone routing to the
+  tested agent.
+- Do not bypass the GitHub App PR workflow with direct pushes.
+- Redact raw trace payloads before sharing artifacts outside the workspace.
+
+## What to report back
+
+After setup or debugging, give the user: the command run; the execution policy
+and how it maps to the Autofix answer from Breakpoint 1; source provider and id;
+repo full name; which phases (import, grade, seed, reproduce, fix) are ready;
+the exact blocker if any; local artifact paths if applicable; and the next CLI
+command or owner. Prefer CLI and artifact evidence over telling the user to open
+a dashboard page.
+
+## Docs
+
+- Autoloop production traces: https://docs.archal.ai/guides/autoloop-production-traces
+- Autoloop CLI: https://docs.archal.ai/cli/autoloop
+- Running with an agent: https://docs.archal.ai/guides/run-with-agent
+- Writing scenarios: https://docs.archal.ai/guides/writing-scenarios
+- Seeds: https://docs.archal.ai/guides/seeds

package/skills/autoloop/references/hosted-sources.md

@@ -0,0 +1,94 @@
+# Hosted database source
+
+Reference for registering a hosted Postgres or Supabase trace source. Use this
+when traces live in Postgres or Supabase. Registration posts the source config to
+Archal and returns; hosted workers own polling after that.
+
+The starter takes only `--repo`, `--source`, the credential
+(`--database-url-env` or `--database-url-secret-ref`), `--execution-policy`,
+`--check`, and `--json`. The source identity, schema mapping, cursor, and filters
+live in the `.archal.json` `autoloop` block — see `trace-schema-mapping.md`. A
+minimal config names the source:
+
+```jsonc
+// .archal.json
+{
+  "autoloop": {
+    "source": { "name": "prod-agent-traces" }
+  }
+}
+```
+
+This is the detail behind **Breakpoint 3** in `SKILL.md`: never accept a
+privileged connection string, pass the credential by env-var name (or secret
+ref), and confirm the role is read-only before running any `--source` command.
+
+## Contents
+
+- Read-only credential
+- Check the source
+- Register the source
+- Secret reference (hosted production)
+
+## Read-only credential
+
+First create (or ask the user to create) a read-only database role scoped to the
+trace tables. For Postgres:
+
+```sql
+CREATE ROLE archal_trace_reader LOGIN PASSWORD '<generated>';
+GRANT CONNECT ON DATABASE <db> TO archal_trace_reader;
+GRANT USAGE ON SCHEMA public TO archal_trace_reader;
+GRANT SELECT ON ai_traces, ai_spans TO archal_trace_reader;  -- trace/span tables only
+```
+
+Then keep the URL in an env var; never inline it in a command and never echo it:
+
+```bash
+export TRACE_DATABASE_URL='postgres://archal_trace_reader:...'
+```
+
+## Check the source
+
+Run a readiness check. `--check --json` emits `{ ok, checks[], nextStep? }` and
+exits `2` when not ready:
+
+```bash
+npx archal autoloop \
+  --repo . \
+  --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --check --json
+```
+
+The source name comes from `autoloop.source.name` in `.archal.json`, not a flag.
+
+## Register the source
+
+Drop `--check` to register:
+
+```bash
+npx archal autoloop \
+  --repo . \
+  --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --execution-policy reproduce
+```
+
+Set `--execution-policy` to match the Autofix answer from Breakpoint 1
+(`reproduce` = no PRs, `fix` = open PRs). Registration posts the source config to
+Archal and returns. It does not start a local watcher and does not write local
+source state.
+
+## Secret reference (hosted production)
+
+Use a secret reference when the customer already has one. The ref must not
+contain a plaintext credential:
+
+```bash
+npx archal autoloop \
+  --repo . \
+  --source postgres \
+  --database-url-secret-ref aws-secretsmanager://customer/prod-agent-traces \
+  --execution-policy reproduce
+```