---
title: "Reproduce, fix, and retest"
description: "Use operation contracts, shared scenarios, reusable worlds and coding-agent tools to verify a source fix."
canonical: "https://agenttwin.si/docs/worlds/"
---

# Reproduce, fix, and retest

Use operation contracts, shared scenarios, reusable worlds and coding-agent tools to verify a source fix.


A useful test world reproduces a failure, identifies the state that went wrong, and lets you verify a source patch against the same starting conditions. AgentTwin supports that loop with explicit service contracts, immutable scenario versions, reusable local HTTP worlds and state-based safety checks.

## Check service support

```sh
agenttwin contracts --file agenttwin.world.json --json
```

The operation matrix lists endpoints, authentication, state changes, errors and limitations for each configured service. Current adapters are custom JSON collections and a bounded Slack subset. Collection services support GET/list and POST/create with idempotency replay. Slack supports chat.postMessage and conversations.list/history through JSON or form bodies.

An unmodeled operation or parameter returns HTTP 501 with `X-AgentTwin-Unsupported: true`, records an unsupported event and makes the test incomplete. It is never forwarded to a production API. Discovery of a provider does not establish a working twin for that provider.

## Save a shared scenario

A scenario supplies the exact starting records across services. Its schema is `agenttwin/scenario-v1`; it contains an id, positive integer version, description, service seeds and optional shared entities. Each entity links selectors that resolve to exactly one seeded record in at least two services. For example, a CRM customer and a Slack support channel can refer to the same customer.

```sh
agenttwin scenario save --file support.scenario.json --json
agenttwin scenario list --json
agenttwin scenario show --scenario support_retry@1 --json
```

Versions are immutable. Increment the version when fixtures change. Scenario services, adapter types and collection paths must match the world exactly. Receipts include the scenario id, version and content digest.

You can also use a saved scenario in a one-shot run:

```sh
agenttwin run --file agenttwin.world.json --scenario support_retry@1 --json
```

## Reuse a world while fixing source

```sh
agenttwin world create --file agenttwin.world.json --scenario support_retry@1 --ttl 3600 --json
agenttwin world run --id WORLD_ID --json
agenttwin receipt --id RUN_ID --json
```

Replace WORLD_ID and RUN_ID with the returned identifiers. Creation starts a background host and returns loopback service endpoints and fresh test credentials. The lifecycle is provisioning, ready, running and ready again, ending in terminated, expired or failed.

Every run stages the current explicitly listed source files and resets service state to the captured baseline. Patch the original source, then run the same world again. Source digests change; the scenario and world specification remain fixed. If you change the specification or scenario, create another world.

```sh
agenttwin world status --id WORLD_ID --json
agenttwin world reset --id WORLD_ID --json
agenttwin world extend --id WORLD_ID --ttl 3600 --json
agenttwin world teardown --id WORLD_ID --json
```

Reset clears mutable state, idempotency keys, events, delayed responses and fault activation. TTL is 1–86400 seconds; expiration closes the endpoints and interrupts active execution. Control requests require a separate token and reject browser origins. Test credentials are stored in private local session metadata; keep them local.

Reusable worlds support local HTTP services. They execute Node code on your machine and provide no host network or filesystem isolation. Use one-shot hosted/E2B execution for an isolated workload or PostgreSQL/Redis. World state is held in memory; recreate a world after its host process is lost.

## Check outcomes and unwanted effects

Existing `assertions` describe required final-state counts, optionally filtered by record fields. Add `forbiddenEffects` to reject particular recorded operations and `preservedState` to protect seeded records:

```json
{
  "forbiddenEffects": [
    {"id": "no_customer_write", "service": "crm", "path": "/customers", "operation": "write"}
  ],
  "preservedState": [
    {"id": "keep_customers", "service": "crm", "path": "/customers"}
  ]
}
```

These are fields added to a complete world specification, not a standalone specification. A forbidden-effect selector can use `where`; supported operations are write, read and replay. Filtered effects without a recorded payload fail conservatively as an evidence gap. Preserved-state selectors compare matching records from before and after execution.

The receipt's evaluation separates taskPassed from safe. An unsafe result fails the run even if every required task assertion passed. Checks include state JSON pointers and event sequence numbers. Dashboard failure explanations and fix prompts include these checks. Unsupported behavior remains incomplete, and execution errors remain errors.

```sh
agenttwin verify --file .agenttwin/runs/RUN_ID/run.json --world agenttwin.world.json --scenario support_retry@1 --json
agenttwin sync
```

Verification checks current source/specification digests and recomputes local evidence. It does not independently attest execution. Sync uses your existing account connection and sends receipts to your dashboard; scenario storage and reusable lifecycle remain local.

## Connect a coding agent

Start the MCP stdio server from your repository:

```sh
agenttwin mcp
```

Configure your MCP client with command `agenttwin`, arguments `["mcp"]`, and the repository as its working directory. The client can discover operation contracts, save/list scenarios, create/list worlds, read status, run a scenario, inspect receipts, reset/extend/teardown a world, and verify a run.

The intended sequence is create_world → run_scenario → inspect_run → patch application source → run_scenario → verify_run. The coding agent performs the patch in the original repository. AgentTwin does not silently rewrite source or weaken tests.

## Try the complete loop

```sh
agenttwin example --out ./agenttwin-example
agenttwin scenario save --file ./agenttwin-example/support.scenario.json --json
agenttwin world create --file ./agenttwin-example/reusable.world.json --scenario support_retry@1 --ttl 3600 --json
agenttwin world run --id WORLD_ID --json
```

The example creates duplicate tickets after a lost response. Inspect its failing receipt, then fix workflow.mjs to use a stable idempotency key on the original request and retry. In this example, replacing the safe flag assignment with `const safe = true` activates that fix. Rerun the same world: it should contain one ticket and one Slack notification, with unchanged customer records. Keep the specification and scenario intact, verify the new receipt and tear down the world.