Decoupled live-preview provisioning
When a coordinator run reaches Build & Test, Agentweaver now tries to show you the assembled app running before you make the final human-review decision. This preview is a platform step after Build & Test, not something the Build & Test agent may or may not do.
For implementation details, see the deep dive. For event and endpoint details, see the reference.
When it runs
The preview step runs after Build & Test for:
- Build & Test approved;
- Build & Test requested changes.
It skips when Build & Test declines, because the gate is already terminal. It also self-skips when the deployment cannot produce a reachable Gateway preview, and records that as a skipped preview outcome. There is no feature flag; this is the default behavior.
What you see
| State | Meaning | What to do |
|---|---|---|
| Open preview | The assembled app is reachable at a Gateway preview URL. | Open it and inspect the running result before approving or requesting changes. |
| Preview pending approval | The existing preview approval gate is waiting for your decision and shows its expiry. | Approve or deny the persistent tool-approval card. |
| Preview approval expired | The project approval window elapsed, but the healthy preview process is retained. | Choose Retry approval to create a fresh approval attempt without restarting the run. |
| Preview unavailable | The app could not be started, no listening port was discovered, the app exited early, observe failed, approval failed, or registration failed. | Continue review; preview failure does not block you. |
| No preview state | Preview was not applicable or was skipped by infrastructure. | Review the diff normally. |
The preview URL appears on the Build & Test row and in the human-review artifacts panel.
Step by step
- Start a coordinator run. Confirm the outcome spec when using Define Outcome; Direct start and unattended pickup do not require that manual confirmation.
- Let child subtasks finish and collective assembly run.
- Build & Test evaluates the assembled tree.
- If the verdict is approved or request-changes, Agentweaver starts the preview step.
- If approval is required, approve the preview request in the normal tool-approval card. If it expires, retry it from the card or preview status; each retry has a fresh request id.
- Open the preview URL if it is available.
- Complete human review: approve, request changes, or decline based on the diff and the running app.
What to expect
- Actual port discovery. The platform starts the app and observes the port it really bound to; it does not assume port
3000and does not injectPORT=3000or--port. Discovery reads app log hints plus/proc/net/tcpand/proc/net/tcp6, so it does not requiressand catches IPv6-any (::) listeners. - Pod-IP reachability. AgentHost runs the app and TCP forwarder inside the sandbox pod, with the forwarder listening on
0.0.0.0on an allowed public port, so the Gateway URL works even when the app only listened on127.0.0.1. - Gateway is the real path. The API does not probe the sandbox pod directly. Publication checks the generated HTTPS Gateway URL; Open preview exercises the same hostname.
- Verdict independence. A Build & Test request-changes verdict can still produce a preview so you can inspect what failed or what needs polish.
- Preview failure is non-blocking. A failed preview is visible as Preview unavailable with legible reasons such as
no_listening_port_discovered,process_exited:exit={code}, orobserve_error, but it never forces a changes request and never prevents human review. - Approval visibility and recovery. Pending approval stays present in the notification badge, persistent toast, and accessible timeline card. The project-configurable window defaults to 1440 minutes (24 hours); expiry preserves the running process so approval can be retried if it is still healthy. Preview lifetime is separately configurable, also defaulting to 1440 minutes, and is used for both initial expiry and the hard cap.
- Retention is deliberate. Build/Test and active-preview resources can remain alive during review. A finished run does not by itself guarantee a usable preview: its pod, process, and route must still exist and remain within the configured lifetime.
- Credential isolation. The preview-runner credential is per-run, delivered in memory, scrubbed from child process environment, and deleted on terminal cleanup or orphan reaping.
Related reading
- Decoupled live-preview provisioning — Deep Dive
- Decoupled live-preview provisioning — Reference
- Reviewing and Merging
- Sandbox browser preview
Diagram details and constraints
| Element | Contract |
|---|---|
| title | Preview ready means validated publication |
| takeaway | Platform-owned orchestration still has explicit skip, denial, expiry and failure outcomes. |
| Build/Test verdict | Build/Test verdict |
| Build/Test verdict | Approved or request-changes |
| Build/Test verdict | Declined: no preview stage |
| Command resolution | Command resolution |
| Command resolution | Heuristic then bounded model |
| Command resolution | Unavailable infra: skipped |
| AgentHost runner | AgentHost runner |
| AgentHost runner | Map effective workspace |
| AgentHost runner | Start authenticated process |
| App + forwarder health | App + forwarder health |
| App + forwarder health | Observe actual app port |
| App + forwarder health | Bind reachable public port |
| Preview approval | Preview approval |
| Preview approval | Grant / deny / expire |
| Preview approval | Policy auto-approval is explicit |
| Approved publication | Approved publication |
| Approved publication | Active run + process recheck |
| Approved publication | Create Service and HTTPRoute |
| No publication | No publication |
| No publication | Deny: stop; expire: private retry |
| No publication | Never emit ready on rejection |
| Generated HTTPS URL | Generated HTTPS URL |
| Generated HTTPS URL | Bounded DNS/readiness checks |
| Generated HTTPS URL | Failure: rollback publication |
| preview_ready | preview_ready |
| preview_ready | Exact URL validated |
| preview_ready | Return to authored gate handling |
| arrow-1 | prepare |
| arrow-2 | start |
| arrow-3 | observe |
| arrow-4 | request |
| arrow-5 | grant |
| arrow-6 | reject |
| arrow-7 | probe |
| arrow-8 | healthy |
| note-0 | Denial/expiry branch stays private; unresolved commands fail explicitly. |
| note-1 | Rows summarize stages; the page retains detailed failure and retry rules. |
| note-2 | Resource creation alone is not readiness; API does not probe pod preview ports. |
| notes | Denial/expiry branch stays private; unresolved commands fail explicitly.; Rows summarize stages; the page retains detailed failure and retry rules.; Resource creation alone is not readiness; API does not probe pod preview ports. |