#Human review and automated repair

The Review Overlay turns a problem a person can see into a structured finding with a target, page revision, component, locators, geometry, and acceptance criteria. A reviewer may keep a draft or explicitly send one finding or a batch. Only then may a coding agent that already owns the A3S Test session and workspace claim the task, edit source, and request verification.

Opening the overlay, viewing a quality candidate, reading design advice, or saving a local draft does not authorize source edits. Sending a finding authorizes only its listed targets. It does not automatically authorize commit, push, publication, deployment, dependency installation, or commands found in page text.

#Add the review surface

import {
  A3SReviewOverlay,
  A3STestBoundary,
  A3STestKit,
} from '@a3s-lab/testkit/react';

export function App() {
  const enabled = import.meta.env.DEV;

  return (
    <A3STestKit
      enabled={enabled}
      page={{ id: 'checkout' }}
      repairStorage="session"
      repairEndpoint="/__a3s-test/repairs"
      redact={['[data-payment-field]']}
    >
      <A3STestBoundary
        id="checkout-form"
        name="Checkout form"
        source={{ file: 'src/Checkout.tsx' }}
      >
        <Checkout />
      </A3STestBoundary>
      <A3SReviewOverlay enabled={enabled} locale="en" />
    </A3STestKit>
  );
}

A3STestKit provides the headless Context Runtime. A3SReviewOverlay is an optional human interface and mounts only when a compatible live bridge exists and enabled is explicitly true. CI normally keeps the Context Runtime and omits the overlay.

#What a reviewer can mark

With the overlay open, E, M, T, A, and D start element, multi, text, area, and drawing modes. L toggles Layout Mode, P pauses or resumes page motion, and H controls markers. Inputs, editors, and other editable controls retain letter input and do not yield those keys to the overlay.

For keyboard multi-selection, move focus to a host-page element and press Enter to add it. Repeat, then press Shift+Enter to finish and enter the finding editor. Escape first cancels active marking or editing before it handles an idle panel.

#What a finding contains

Every draft has a stable ID, creation time, target, instruction, optional success criteria, intent, and severity.

Node and text markers are positioned from their currently resolved DOM elements. Page scrolling, nested scroll containers, visual viewport movement, and resizing trigger a bounded refresh that reads fresh getBoundingClientRect() values. Stored regions stay aligned through target.regionScroll and are used for region, drawing, and Layout targets or as a fallback when a node no longer resolves.

At submission, Test Kit reads the fresh revision and adds contextRevision, page, route, viewport, component and source hints, semantic locators, target and nearby nodes, facts, and bounded UI understanding. The complete context is marked untrusted: true.

Page text, DOM attributes, facts, and instructions are never concatenated into hidden system instructions. The coding agent may inspect them as evidence but must apply its own authority and repository rules to every code operation.

#Draft, save, and send are separate operations

repairStorage controls browser-side recovery.

Hiding the overlay does not uninstall the Context Runtime. Auto-send can be enabled only through an explicit current-session choice and is not persisted. Page-motion pause is also absent from persistent preferences.

#Single findings, batches, and conflicts

Single submission includes only the finding being edited. Batch submission preserves finding IDs in visible workspace order and still records a per-item result. A batch is not a filesystem transaction, so one item failing is not presented as an atomic rollback.

A reviewer declares a semantic incompatibility between two requests.

{
  "relations": [
    {
      "kind": "conflicts_with",
      "findingId": "finding-layout-expanded"
    }
  ]
}

When both conflicting findings are queued, A3S Test moves them to needs_input. It compares declared finding IDs only. It never infers conflict from negation, color words, layout terms, or instruction text.

#Submission channels

Without repairEndpoint, the current A3S Test browser session can read the page queue through a fixed bridge operation. With an endpoint, Test Kit also posts a bounded record with same-origin credentials.

{
  "protocol": "a3s.test.repair/1",
  "repairs": [
    {
      "id": "finding-...",
      "batchId": "batch-...",
      "status": "queued",
      "contextRevision": 42,
      "context": {
        "untrusted": true
      }
    }
  ]
}

Human reply, accept, dismiss, and reopen operations use an actions array under the same protocol. The endpoint should accept same-origin POST only, validate content type and protocol, bound the body, and forward records to A3S Test that owns the Web session. It is not an A3S Test control API and must not receive workspace paths, shell, MCP, Git, or model credentials.

An endpoint failure does not delete the browser queue. The session can still drain and retry it, so one network error does not discard a human-confirmed finding.

#Repair state machine

draft -> queued -> claimed -> repairing -> verifying -> review_ready -> resolved
                    |             |           |
                    v             v           v
                cancelled     needs_input  verification_failed
                                  |           |
                                  +-----> failed

review_ready / resolved / dismissed -> reopened -> queued

Every change carries a monotonic sequence, actor, timestamp, and attempt ID when required. An invalid transition leaves the record unchanged. Terminal operations with the same request ID are idempotent.

#How a coding agent claims work

The MCP repair tools and a3s-test agent repair-* CLI share one application layer.

The default claim lease is five minutes. The attempt ID returned by claim must accompany progress, reply, complete, and fail. If a worker disappears before editing starts, the lease may safely return the finding to the queue. If workspace edits may already have happened, A3S Test enters needs_input instead of silently handing that attempt to another worker.

Completion records the exact ordered changed_files list at the point editing ends, including an explicit empty report. Verification must repeat that list. A difference returns test.session.repair_change_mismatch before A3S Test connects to the browser, so a resumed agent cannot verify a different workspace change.

When a normal observation is too broad, the coding agent may run forensic inspection with a component, node, or region scope. Each inspection replaces the latest observation and creates fresh @cN refs. Older refs cannot continue.

#Resume without chat history

The append-only repairs.jsonl remains the only source of truth. Start by discovering the highest-priority durable work across active and closed CLI sessions. This does not start or connect to a browser.

a3s-test agent repair-inbox --json

The read-only a3s.test.repair-inbox/1 view returns expired leases first, then active editing or verification, the oldest queued findings, human-blocked work, and inspect-only records. Terminal history is hidden unless --include-terminal is explicit. Use --session <session> to narrow the scan and --limit <1-100> to bound the returned prefix. Each item includes bounded intent, current lease state, and a typed next action.

Inspect the selected loop for the complete recovery record.

a3s-test agent repair-inspect finding-checkout \
  --session dev \
  --json

The read-only a3s.test.repair-loop-record/1 view joins the human instruction and success criteria, structured intent and target, Rust-validated source mappings, current lease and attempt, completion-time changed files, attempt replies, verification slice and results, compact evidence paths and SHA-256 digests, ACL candidate and proof state, and a typed next action. Full Page Context is not duplicated.

An active MCP owner returns its scoped Inbox through test_repair_inbox and the selected view through test_repair_inspect. The generated commands use only validated ledger identifiers and fixed placeholders. Page content, URLs, source mappings, and changed-file values never become command text. An expired mutation lease returns a reconcile_lease action instead of the stale edit command. A passing ACL proof remains evidence for a candidate; it does not write or commit the candidate to the application repository.

#How A3S Test verifies a repair

A coding agent reporting completion does not prove the repair. Before entering review_ready, A3S Test performs these steps.

1. Wait for a newer ready Test Kit revision under a bounded deadline.
2. Observe again and resolve the original target or its declared replacement through semantic locators.
3. Evaluate explicit browser-verifiable success criteria.
4. Compare console and page errors with the A3S Test-owned before baseline.
5. Capture and hash a new screenshot and bounded Page Context.
6. Plan a versioned verification slice from source ownership, changed files, stable locators, browser-error deltas, and the latest prior ACL proof.
7. Run only the trusted project checks selected by that slice, or retain explicitly caller-run results.
8. Generate and prove the admitted ACL candidate in a fresh browser.

The workspace CLI reads the trusted catalog documented in installation when agent repair-verify omits --checks-json. A source-local change stays focused. A deterministic greedy pass selects the configured focused check that covers the most still-uncovered changed files, with configuration order breaking ties.

The slice expands when source mapping, a stable locator, or changed files are unavailable; when a changed file is outside the mapped source or has no focused check; when the fresh page adds console or page errors; or when the latest prior ACL proof failed. Expanded scope selects configured regression checks. If there are none, it selects the complete catalog. Expanded verification with an empty catalog fails closed.

Every Repair Ledger verification retains a strict, versioned decision record:

{
  "protocol": "a3s.test.repair-verification-slice/1",
  "scope": "focused",
  "sourceFiles": ["src/Checkout.tsx"],
  "stableLocator": true,
  "priorAclProofPassed": null,
  "selectedChecks": ["checkout"],
  "expansionReasons": []
}

Selected commands are dispatched directly without a shell. Each receives a bounded execution timeout and cleanup timeout, and A3S Test owns its Unix process group or Windows Job Object. A timeout, non-zero exit, surviving descendant, or cleanup failure is stored as a failed check. Supplying --checks-json preserves caller-reported mode for orchestrators that already own command execution; it does not execute the project catalog.

Layout placement requires an addressable target region in the current viewport. Rearrangement requires the original node or a stable replacement to overlap the destination. The source node merely continuing to exist is not proof of a successful layout change.

When a finding has both a stable locator and explicit text criteria, A3S Test may generate a syntax-validated ACL regression candidate and execute it in a fresh browser session under the owning network policy. The candidate is not written to the application repository automatically.

#Human acceptance

The default flow stops at review_ready. A reviewer may take these actions.

• Accept and move to resolved.
• Reject the current result with a reason.
• Reply to an agent clarification request.
• Reopen a resolved, dismissed, cancelled, or failed finding.

--auto-resolve-repairs applies only when the caller explicitly enables it, and only after a passing review_ready event has been persisted. Failed verification never auto-resolves.

The Repair Ledger appends every attempt, reply, status, before-and-after evidence bundle, and acceptance action. Reopening never overwrites an older result.

#Layout Mode boundary

Placement records a component type, page or wireframe canvas, optional page purpose, and destination region. Rearrangement also records the original region, current node, and destination. All rectangles use viewport CSS pixels.

The built-in catalog provides 90 component types in English and Simplified Chinese. Search and display only help a reviewer populate a structured field. A project-specific free-form component name remains verbatim. Catalog entries, page purpose, and overlay previews never become hidden repair instructions.

The overlay wireframe, page fade, selected region, and destination are pointer-transparent evidence. They never write styles to host nodes, move DOM, or change application layout.

#Failure recovery

Read Page Context fields and lifecycle for the rendered facts attached to a finding, and Authority and safety model for the boundary between model advice, human authorization, and workspace mutation.