---
title: "From discovery to a verified fix"
description: "Observe dependencies, run browser and service workflows, preserve incident regressions and verify committed patches."
canonical: "https://agenttwin.si/docs/stack-loop/"
---

# From discovery to a verified fix

Observe dependencies, run browser and service workflows, preserve incident regressions and verify committed patches.


AgentTwin can observe exercised Node HTTP calls, run explicit workflows in a test world, and check committed patches against trusted regression definitions. This page describes the source checkout; use its built CLI until a package containing these commands is published.

## Find dependencies used at runtime

Run a reviewed Node application with instrumentation. By default, observed HTTP calls are recorded and blocked before transmission:

```bash
agenttwin observe -- node app.mjs
agenttwin services list --json
agenttwin services confirm --host api.stripe.com --decision include
agenttwin discover --json
```

A confirmation adds a dependency to inventory; it does not allow requests or install an adapter. To exercise a permitted destination, explicitly pass `--allow-host HOST`. Observation starts with only `PATH` and `NODE_ENV=test`; use repeatable `--env-key NAME` for environment variables you deliberately want to forward. Request URLs, headers, payloads and application output are omitted from observations.

This instruments Node fetch/http/https. Native clients, direct sockets, subprocess traffic and unexercised branches remain outside coverage. It is not an operating-system network sandbox. Discovery also identifies route callbacks and queue handlers as candidates; invocation and business expectations still require review.

## Account for every service

After discovery, run `agenttwin services coverage --json`. Every application dependency appears with its required operations, available provider subset or real engine, limitations, and the next action for missing coverage. Development tooling is excluded. An available adapter does not make the customer workflow verified, and custom collections do not establish vendor compatibility. Build and validate missing operations before claiming complete workflow coverage.

## Use verified provider operations

Run `agenttwin contracts --json` for the operation matrix. Stripe's bounded adapter supports customer create/retrieve/list and payment-intent create/retrieve/confirm, with test payment methods, pagination, idempotency and modeled errors. Slack supports its advertised message/channel/history subset. Custom collections support explicitly defined HTTP operations.

Official Stripe SDK conformance tests exercise the supported subset. No real charge is made. Subscriptions, refunds, webhooks, broader object fields and unmodeled parameters are not covered. Unsupported behavior returns 501 and makes the test incomplete.

## Exercise the application and background work

A world can include a local browser recipe for a bundled Node server. Install Chromium using `npx playwright install chromium` from the CLI package directory. Add these fields to a complete reviewed world:

```json
{
  "browser": {
    "baseUrl": "http://127.0.0.1:4321",
    "steps": [
      { "action": "goto", "path": "/" },
      { "action": "click", "selector": "#create-order" },
      { "action": "expectText", "selector": "#result", "text": "Created" }
    ]
  },
  "background": {
    "service": "orders",
    "path": "/orders",
    "count": 1,
    "timeoutMs": 3000
  }
}
```

Run with `agenttwin run --file agenttwin.world.json --runtime local`. The Node server starts, browser actions execute, and the background check waits for matching collection state. Receipts include browser step outcomes and a screenshot when capture succeeds. Browser requests outside the application and configured twins are blocked and recorded as incomplete coverage. Server code still has the local process's host access; this is not a VM sandbox.

Browser/background recipes currently require local execution. Hosted submissions reject them before queuing a job. Protected Docker approval also returns incomplete for those recipes until its browser runner is implemented. Background checks do not replicate Bull, SQS or arbitrary queue semantics.

## Trace failures and validate a repair

Service events from local instrumented execution carry application-reported call sites. `agenttwin receipt --id RUN_ID --json` links those events and stack frames to tested source files, checks source freshness, and produces repair hypotheses. These locations guide investigation; they do not prove a root cause.

Patch application code and rerun the same fixtures, fault and outcomes. A suggestion is unvalidated until execution proves it against unchanged checks. The dashboard's Recorded steps view shows reported call sites; Technical details shows available browser evidence.

## Turn an incident into a permanent regression

Start with a scoped exported incident containing a linked scenario. The repository includes a runnable example in `examples/incident-regression`.

```bash
agenttwin incident import --file incident.json --out reviewed-preview.json
# Review the redacted records and define the intended outcomes in the world.
agenttwin regression save --file agenttwin.world.json \
  --id retry_safety --incident reviewed-preview.json
```

Redaction preserves matching identities across services. It is heuristic, so review unusual fields and free text before sharing. Import does not connect to production or infer business correctness. Regression definitions are immutable; change their identifier when deliberately changing the contract.

## Add coding agents and pull requests

`agenttwin mcp` exposes world lifecycle, incident import, regression saving and protected checks to coding agents. For CI, commit the reviewed regression to a trusted baseline and run:

```bash
agenttwin regression run \
  --regression .agenttwin/regressions/retry_safety.json \
  --revision FULL_CANDIDATE_SHA --baseline FULL_TRUSTED_BASELINE_SHA \
  --runtime docker --json
```

Checks come from the baseline commit; application files come from the exact candidate commit. The candidate runs in a restricted Docker container without the grading files or Docker socket. Use a reviewed, digest-pinned image through `AGENTTWIN_RUNNER_IMAGE`. Docker checks currently support HTTP twins; unsupported infrastructure returns incomplete.

Install a customer-repository workflow with separately pinned AgentTwin tooling:

```bash
agenttwin ci install --tooling-revision FULL_REVIEWED_AGENTTWIN_SHA \
  --regression .agenttwin/regressions/retry_safety.json
```

The selected tooling commit must be available on GitHub and contain these commands. The installer creates `.github/workflows/agenttwin.yml` once, refuses to overwrite a workflow, checks out trusted tooling separately from the application, and fetches the exact candidate commit without executing candidate installation scripts. Configure the reviewed runner image and protect the workflow through repository rules or an organization-required workflow. A template alone cannot make a check mandatory. Local process execution supplies evidence but never grants protected approval.

The complete loop is: discover → confirm → prepare → reproduce → patch → rerun unchanged checks → retain the regression on future pull requests.