Reviewing and Merging
When all agents finish their work and the coordinator assembles the combined output, the run enters the review stage. This is your gate — nothing merges until you explicitly approve.
The review pipeline
Children hand off assemble-ready output. The coordinator combines it and evaluates the selected workflow's collective gates. Built-in software workflows run RAI → Build & Test → Human Review before merge and Scribe. These gates do not run per child. Feedback returns to coordinator steering and any required reassembly, not straight from an agent revision to another human-review screen. When an assembly gate (including rubber-duck or Build & Test) or a human reviewer requests a fresh revision, its workspace starts from the exact integrated tree reviewed at that gate. The revised output retains those files alongside the new edits; retrying that revision keeps the same pinned input. Collective revisions retain the complete integrated file tree across repeated corrections, including when the coordinator has no executable-workflow pin. The current tree's captured files must still validate before review approval and merge; a missing or corrupt capture is not treated as complete.
The coordinator verifies each file-producing child's recorded tree against its Git branch and assembles from that exact verified commit, even if the branch moves later. A missing child run, branch, or recorded tree blocks assembly instead of quietly reducing its inputs. A task explicitly declaring no file outputs ([]) and with no recorded Git output needs no branch; any recorded branch or tree must still verify. A committed no-change child with a matching tree remains valid. Dependent work also waits for a base containing every required upstream commit; if verification fails, recover or retry the named producer rather than launching from the original branch. Independent edits to the same path, including a rename, deletion, or directory/file collision, stop integration for explicit resolution. The conflict event identifies the affected paths and both contributors' commit identities; no later child silently overwrites an earlier one. An unresolved build leaves the previous integration revision unchanged.
This verification does not yet provide a durable immutable output receipt, approval binding to an exact revision, or an in-product conflict-resolution record. Those capabilities are tracked separately in #1396 and #1401.
The single-run default below makes the review, revision, merge and PR-publication branches explicit. It is not the collective workflow definition: collective input, applicable Build & Test gates and coordinator-directed revision follow the coordinator journey, rather than an invented per-child merge.
Automatic RAI check
When selected by the workflow, RAI checks the assembled output. Gate outcomes determine whether execution can advance or requires coordinator-directed correction. The coordinator decides whether to steer an existing child, dispatch fresh work, proceed, or record an advisory no-op.
Build & Test preview
For projects that produce a browser preview, the run tree shows the preview state on the Build & Test step:
- Open preview opens the preview URL in a new tab.
- Preview pending approval means the preview is waiting for a tool-approval decision.
- Preview unavailable includes the reason and does not block human review; you can still inspect the diff and approve, request changes, or decline.
The same preview status appears in the human-review file panel so you do not have to search the event timeline for the URL. If autonomous review exhausts its correction budget before reaching an applicable Build & Test gate, the coordinator runs that gate and records a preview outcome for the current assembled tree before opening human review. Documentation-only work without a Build & Test gate remains preview-not-applicable; no app server is started. An earlier revision's preview URL is not evidence for the current tree. A ready URL is shown only while its published session still belongs to the current sandbox and its supervised app process is healthy. Preview failures remain visible and do not prevent a human decision; the platform discovers the application's actual port rather than assuming port 3000. Pending approvals and failures for the current tree appear while assembly is still running, before the human-review card opens. A manually started sandbox preview is a separate operator view: a still-active manual session can be reopened after a page reload, but its URL never counts as Build & Test readiness for the current candidate.
For the full contract behind this stage, see Decoupled live-preview provisioning.
Tool approvals
The run tree, Needs input count, approval cards, board badge, and global notification center use the same server-projected pending set. Each request appears once, even when the live stream reconnects or both a durable gate event and a display event exist. Resolved, denied, expired, cleared, duplicate, terminal-run, and orphaned requests are not actionable.
Approval-sensitive run settings are snapshotted before coordinator activation. The immutable snapshot records the launch auto-approve/autopilot flags, preview approval timeout, launch source, and source project update timestamp. Preview approval uses the captured launch defaults and timeout instead of re-reading mutable project pickup settings. Live run controls remain separate and are cleared at completion; the launch snapshot remains available for audit, terminal details, and retry.
Coordinator approvals can originate from the coordinator itself, a coordinator phase, or a child run. Agentweaver maps the request to its owning scope while keeping the operator on the top-level run review page. Approval authorization is unchanged, and Agentweaver never approves a request automatically because it disappeared from the pending set.
The pending set is independent of how a run was launched. A per-run auto-approval policy controls the approval gate; it is not evidence that a run came from backlog heartbeat pickup. If a request is durably pending, review surfaces keep showing it until the gate resolves it or its owning run is no longer actionable.
start_preview approval waits and preview registration calls have finite deadlines. An approval-window timeout returns an explicit retryable response, and MCP or in-sandbox tool calls stop after three minutes rather than holding a run indefinitely. If that client deadline expires before approval or publication completes, verify the run and preview process, then retry start_preview; Agentweaver creates a new approval request when one is still required.
If approval data cannot be loaded, the review page shows an error with Retry. An empty panel is shown only after the server successfully confirms that no actionable approval remains.
Request changes and steering
When review feedback asks for changes, it goes through the coordinator's unified steering path. The timeline shows the feedback source and then the coordinator's decision: steer the existing child in place, dispatch fresh work, proceed, or record an advisory no-op. See Unified autonomous steering.
When the coordinator dispatches a fresh child to revise assembled work, that child starts from the exact integrated file tree reviewed by the gate. Existing files remain in its workspace for a focused edit; they do not need to be recreated from the feedback text. An infrastructure retry starts in a new workspace from the same pinned tree, without carrying over the failed attempt's uncommitted changes. If the reviewed tree cannot be verified, the coordinator reports an input error instead of dispatching against the project's original base.
The file panel
Stored review diffs (ordinary runs)
For an ordinary run that reaches review, Agentweaver stores the UTF-8 diff bytes and reviewed Git tree as an immutable output revision in the run database. GET /api/runs/{id}/output-revisions lists revision identities, digests, generation and predecessor links; GET /api/runs/{id}/output-revisions/{revisionId} returns the exact stored diff. Both require current viewer access to the run. Requesting changes creates a new revision without replacing the old diff. Storage lasts as long as the run database and its backups; there is no independent expiry job. Unknown IDs return 404; missing or corrupt stored content and unsupported schemas return 410 rather than substituting live workspace data.
POST /api/runs/{id}/review accepts optional output_revision_id on approval. When omitted, the server binds approval to the current stored revision before queuing it; a stale explicit ID is rejected. The bound ID is checked again at merge, including after a deferred workflow resumes. /commit similarly binds the current revision before staging and refuses to merge if the committed tree differs. Runs created before revision storage retain the legacy review path without pretending to have a stored revision; new revisions with no executable workflow pin are marked manifest_incomplete.
This slice stores diff bytes, not independent copies of every file. The ordinary file panel still reads workspace or, after merge, the recorded Git commit. Collective assembly, independent full-file retention, and MCP/UI revision-history readers are not yet covered by the output-revision contract.
When a run reaches the review stage, the file panel on the left side of the run detail page automatically expands to show the review controls.
The panel has two tabs:
- Changes — lists every file the agents modified, with added/removed line counts. Click a file to open a diff viewer.
- Files — full workspace browser showing all files in the agent's worktree.
Take your time. There is no timeout on the review step.
Check the event timeline
The event timeline gives you the full audit trail — every agent message, tool call, and result. If you want to understand why a change was made, the timeline has the complete context.
Approving
If the changes look correct, click Commit and Merge in the file panel.
Agentweaver merges the combined worktree output to the originating branch. The run status changes to Merged.
Merge conflicts
If the merge surfaces a conflict (the target branch has moved since the run started), Agentweaver reports the conflict and preserves the worktree for manual resolution.
Requesting changes
If the output needs revision:
- Click Change in the file panel.
- Describe what the agent should change in the text field.
- Click Send.
Feedback enters the coordinator's unified steering path. Its recorded decision determines the next work and any required reassembly; a submitted request is not proof that a child has already revised the output.
Be specific
The more specific your feedback ("The error message in auth.ts line 42 should describe the specific validation failure, not a generic error"), the more targeted the revision.
Declining
To discard the changes entirely, click Decline in the file panel.
The run status changes to Declined. The worktrees are discarded and the originating branch stays unchanged.
Declining is final
A declined run cannot be restarted. Submit a new orchestration with a revised task if you want to try again.
What happens after merge
- Changes land on the branch — the combined diff is merged to the originating branch
- Scribe runs — writes a session summary and captures decisions and memories the agents produced
- Team Memory is updated — new entries appear on the Team Memory page for you to review and curate
- Run status is Merged — terminal state, no further changes
The originating branch now contains exactly the changes you approved.
Gate nodes
Which gates run before merge is determined by gate nodes placed directly in a workflow's OutcomeSpec, not by a project-level setting. A workflow can include any combination of three gate kinds:
| Gate kind | What it does |
|---|---|
| Human approval gate | Requires your explicit approve / decline / request-changes decision before the run can proceed past that point. |
| Automatic gate | Evaluates a condition automatically — for example, that tests pass — and proceeds without human input when the condition is met. |
| Triage gate | Waits for an external event, such as a GitHub webhook or label change, before the run proceeds. |
The default workflow places an automatic RAI gate before the run reaches you, followed by a human approval gate for the review stage described above — that human approval gate is mandatory and cannot be removed from a workflow. Additional gates (automatic or triage) can be composed into custom workflows to fit a team's process.
Human review is always present
The human approval gate before merge is mandatory. The platform enforces it regardless of how a workflow's other gates are configured.
Diagram details and constraints
| Element | Contract |
|---|---|
| title | Generic default workflow |
| subtitle | Built-in template • merge → PR publication → Scribe |
| returns-heading | SOURCE / RETURN |
| outcomes-heading | OUTCOMES |
| footer | PR action can skip / fail and still reach Scribe. No-changes also reaches Scribe. |
| Agent work | Agent |
| Agent work | Agent task |
| Agent work | agent |
| RAI gate | Rai |
| RAI gate | Verdict routing |
| RAI gate | rai |
| Human review | Review |
| Human review | human-review |
| Merge | Merge |
| Merge | Merge outcome routing |
| Merge | merge |
| Publish / reuse PR | Publish / reuse PR |
| Publish / reuse PR | Create / reuse; not git push |
| Publish / reuse PR | action |
| Scribe | Scribe |
| Scribe | Record the run outcome |
| Scribe | scribe |
| Safety failed | Safety failed |
| Safety failed | Workflow endpoint |
| Declined | Declined |
| Done | Done |
| edge-02-label | revise |
| edge-03-label | safety- failed |
| edge-04-label | no- changes |
| edge-05-label | review |
| edge-06-label | approved |
| edge-07-label | request-changes |
| edge-08-label | declined |
| edge-09-label | merged |
| edge-10-label | blocked |