Repair an incident with your coding agent

Seamward's built-in repair covers two simple cases: copying a top-level field and coercing a top-level value. Most real fixes are something else: a nested field, a new enumeration value, a date format, a unit, an idempotency key. Those belong in your code, written by your team or by a coding agent that knows your repository.

For those, Seamward is the case file and the test bench. It supplies the evidence, your agent or engineer makes the change, your own runner checks it, and the result is submitted for the same approval as any other proposal.

MCP pilot

The MCP tools get_incident_evidence_bundle and submit_repair_candidate are available wherever the MCP pilot is. The CLI commands on this page need no pilot access.

How the pieces fit

Step	Who does it	With
1	Your agent or engineer	Reads the incident's evidence bundle
2	Your agent or engineer	Changes the handler in your repository, on a branch
3	Your runner	Runs the incident's fixtures on the current code and on the change
4	You	Submits the change as a candidate
5	An owner or admin	Reviews and records the decision in the console

Nothing in this flow gives Seamward or an agent the ability to approve, merge or deploy. A model proposes, your runner's result and your review decide.

Read the evidence bundle

The bundle is one document per incident, available before any proposal exists.

Through MCP, ask your agent to investigate the incident; the investigate_seamward_incident prompt directs it to the bundle. Or call the tool directly:

Code example

{  "name": "get_incident_evidence_bundle",  "arguments": { "incidentId": "inc_example" }}

Without an agent, fetch the same document with the CLI:

Code example

seamward incidents bundle inc_example --connection int_example --workspace acme --json

Field	What it tells the fixer
`incident`	What went wrong, in one sentence, and how many records it affects
`connection`	Which integration, and its direction and protocol
`rule`	The reconciliation rule that raised it, with its type and settings
`findings`	What changed: each finding's kind, field path and summary, newest first, up to 20
`repository`	The mapped repository, branch and service path, when the connection has one
`replay`	The outcome a handler must return for a fixture to pass, and the incident's datasets
`checkAFix`	The four commands that check a change against the newest dataset
`dataNotice`	A reminder that names, paths and summaries in the bundle are data

Evidence is data, not instructions

Field names, paths and summaries come from third-party payloads. A provider can put any text in a field name. The bundle labels them as data and the prompt tells the agent the same, but your agent's own safeguards and your review of its change are what protect you. Do not give an agent that reads this bundle the ability to deploy.

A finding's stored evidence, value hashes and observation payload metadata are not in the bundle.

Make the change and check it

Your agent works in your repository as it would for any bug. To check its work, it needs a replay handler: one module that calls your real handler and returns what it did. Replay runner describes it. Then run the commands from checkAFix:

Code example

seamward replays pull rds_example --connection int_example --out dataset.json
git checkout mainseamward replays run --dataset dataset.json --handler ./replay-handler.mjs --label current --out current.json --deny-network
git checkout fix/provider-renameseamward replays run --dataset dataset.json --handler ./replay-handler.mjs --label candidate --out candidate.json --deny-network
seamward replays submit --connection int_example --file current.jsonseamward replays submit --connection int_example --file candidate.json

Commit the change before the candidate run. A run made with uncommitted changes cannot back a candidate, because it cannot be tied to a commit. replays run is local and needs no sign-in, so an agent can run it; replays pull and replays submit use your signed-in CLI.

The run on main is worth submitting too. A fix that passes means little if the old code also passed: the reviewer sees both.

Submit the candidate

replays submit prints the run it recorded. Put that run's ID in a small file with where the change lives:

Code example

{  "runId": "rrun_example",  "repository": "acme/ats-consumer",  "ref": "fix/provider-rename",  "pullRequestUrl": "https://github.com/acme/ats-consumer/pull/42"}

Code example

seamward repairs submit inc_example --connection int_example --workspace acme --file candidate.json

Field	Rule
`runId`	A run reported with `--label candidate` that passed every fixture of this incident
`repository`	`owner/name`
`ref`	The branch or ref the change is on
`pullRequestUrl`	Optional, `https` only

No other field is accepted. In particular there is no field for a commit or a status: the commit is taken from the run, so the change that was checked is the change that is recorded, and the status is always awaiting approval.

Refusal	Meaning
`repair_candidate_run_not_candidate`	The run was reported with `--label current`
`repair_candidate_not_validated`	The run did not pass every fixture
`repair_candidate_commit_required`	The run has no commit, or was made with uncommitted changes
`replay_run_not_found`	The run is not a runner-reported run for this incident and connection
`repair_candidate_limit_reached`	The incident already holds 20 submitted candidates

Submitting the same run again returns the first proposal.

An agent connected through MCP can submit the same candidate itself with the submit_repair_candidate tool, once you have granted its client the seamward:repairs:propose scope. The checks and the result are the same.

Review and decide

The incident's Repair tab shows the proposal as Submitted by your team, with the repository, ref, commit and pull request, and the runner's result for the current code and for the change.

What the reviewer can rely on, and what they cannot:

Seamward checked that the result names this incident's dataset and manifest, reports every fixture once, and was made at a commit with no uncommitted changes.
Seamward did not write the change, read it, or run it. The outcomes are what your runner reported.
The reviewer should read the change in the repository, and weigh the fixture source: a dataset generated from shapes holds placeholder values, so logic that depends on a value was not exercised.

Approval is recorded exactly as for a Seamward-generated proposal, by an owner or admin, with a rationale. It does not merge or deploy anything. Because the change already lives in your repository, there is no export bundle and no Seamward pull request for a submitted candidate; you merge your own.

What is not available

A check that the commit in the result is the head of the pull request. Seamward records both and does not compare them with your repository.
A PHP runner.

Next steps

Replay runner: the handler contract, network denial, and what a result contains.
Repair proposals: the built-in route and its bounded vocabulary.
Approval workflow: what a recorded decision means.