Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions docs/adr/0079-s16-modern-browser-mediation.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
---
status: selected for bounded prototype; physical guest-root and product activation acceptance pending
status: selected protected-browser feasibility contract; reference guest-root and dispatch-crash evidence recorded; product activation pending
date: 2026-11-05
scope: BROW16-01A; S16-AC06/07; FR-07/10/17/18/35/36/37/38/40/41; NFR-07/10/11/14
---

# Modern browser mediation on the protected host

Keep the existing protected Chromium `general` engine and request broker as the first S16 candidate. Demonstrate an authenticated task whose UI requires real JavaScript, fetch and XMLHttpRequest before a native form exists. Compare its actual server effects with a static-mode negative control. The prototype uses production engine/POLICY ports, disposable profiles and controlled HTTP, not an offline DOM or a screenshot-only mock.
Keep the existing protected Chromium `general` engine and request broker as the selected S16 sensitive-site feasibility architecture. An authenticated task requires real JavaScript, fetch and XMLHttpRequest before its native form exists; the static-mode negative control cannot complete it. The probe uses production engine/POLICY ports, disposable profiles and controlled HTTP. [The reference evidence](../evidence/s16-protected-browser-reference.md) records actual separate-VM guest-root attempts and process-crash/read-back results. This selection does not activate general mode in the provisioned runtime.

S16-D09 ([ADR 0084](0084-s16-grok-style-default-autonomy.md)) narrows this boundary to sensitive sites. Public and owner-marked trusted sites use the working VM browser delivered by #410/[ADR 0092](0092-s16-agent-use-of-the-working-computer-browser.md); guest access to trusted sessions is the accepted residual. Their product path does not inherit the protected-browser claims below.

## Alternatives and source audit

| Candidate | Useful capability | Boundary/cost | Decision |
| --- | --- | --- | --- |
| Existing protected general Chromium + host broker | JS rendering, opaque observed targets, actual request bytes, immutable POLICY action/approval/claim, transient owner login, unknown/reconcile continuity | Provisioned runtime is still static; asynchronous mutation attribution, generic safe authenticated observations, downloads and guest-root placement need additional proof | Select for bounded conformance before #409 rollout |
| Existing protected general Chromium + host broker | JS rendering, opaque observed targets, actual request bytes, immutable POLICY action/approval/claim, transient owner login, unknown/reconcile continuity | Separate-controller reference placement and process-crash recovery are demonstrated; provisioned runtime is still static. Asynchronous mutation attribution, generic safe authenticated observations, downloads and installation-specific placement remain delivery obligations | Select bounded contract for #409 implementation |
| Rakazo live computer browser | Shared graphical Chrome and CDP page operations on the Bot computer, with explicit fallback to computer input | Jit's root-administrable guest cannot receive a sensitive reusable session/CDP endpoint. Moving the endpoint alone supplies no request semantics or protected approval proof | Reuse experience/adapter ideas; do not copy the guest CDP/session placement |
| Separate remote browser service | Explicit process/VM/host boundary and centralized lifecycle | Adds authentication, network protocol, deployment and recovery ownership while still needing request/effect semantics; does not itself solve JS mutation attribution | Retain as a placement alternative if real host proof rejects protected local custody |

Expand All @@ -32,10 +34,12 @@ The exact selected native form/anchor request may become an immutable held effec

The current native binding does not attribute non-document fetch/XHR mutation, even when its endpoint semantics are known. An input timing window cannot supply that authority. #409 must deliver a reviewed protected intent-to-request binding for representative asynchronous applications, or a simpler alternative with equivalent semantics; copying a raw CDP tool is not that contract. Until implemented, report the exact unsupported reason rather than offering an approval that could not make the request safe. This is an unresolved delivery requirement, not a scope reduction of S16.

Protected handlers must classify exact URL/query/body, private data, actual recipient and action class; unknown methods/paths/effects refuse. Generic public rendering can use reviewed destination/content rules without a custom business API, but safe authenticated observation and business outcomes need evidence. #433/#407 own guarded file transfer/collection; browser downloads are not silently enabled. #410 owns authored graphical takeover/client lifecycle; this prototype exercises the existing real transient owner port, with no new UI design.
Protected handlers must classify exact URL/query/body, private data, actual recipient and action class; unknown methods/paths/effects refuse. Generic public rendering can use reviewed destination/content rules without a custom business API, but safe authenticated observation and business outcomes need evidence. #433/#407 own guarded file transfer/collection; browser downloads are not silently enabled. #410 delivered working-computer graphical takeover/client lifecycle. Protected modern-browser integration remains #409; this probe exercises the existing real transient owner port, with no new UI design.

## Recovery, compatibility and acceptance

Keep current continuity armed before dispatch. A crash or lost response remains unknown and reconcile-only until protected service evidence resolves the exact action. Restart cannot reconstruct a callable paused request or retry the input. Cancellation/takeover fences new input but cannot claim to recall a released transport. Owner statements do not verify remote outcomes.

This slice changes no runtime default, installed policy, profile/store schema, existing receipts or owner-host configuration. #402's independent memory worktree is untouched. The controlled probe supplies no live account/physical Linux proof. #408 remains open until its review and remaining acceptance evidence are satisfied; #397/#392 cannot close from this bounded result. Exact conformance results and physical proof obligations belong in the linked contract and implementation PR.
An absent reconciliation verifier returns a fulfilled unknown read result: the read lane settles while the original effect remains uncertain, charged and non-replayable. A later protected verifier may read actual service state without resending the effect. Native cancellation retains the input lease until the actual browser operation/frame settles; otherwise an old denied navigation can interrupt the next generation. Closing the browser first unblocks pending renderer input while broker/continuity custody remains until its scopes settle. Renderer closure does not recall an already dispatched HTTP effect.

This slice changes no runtime default, installed policy, profile/store schema, existing receipts or owner-host configuration. Existing independent worktrees are untouched. The reference proof covers a Linux controller and separate root-administrable QEMU working VM managed from macOS, with synthetic accounts and actual protected ports. It does not certify default nested Linux KVM, a hypervisor/browser exploit boundary, live accounts, power-loss durability or owner-host adoption (#431/#432). #408 delivers this bounded contract and evidence for review; #409 retains asynchronous intent/request binding and protected product integration, and #397/#392 remain open. Exact tested revisions, builds, results and remaining gates are in the linked evidence record and implementation PR.
4 changes: 2 additions & 2 deletions docs/contracts/s15-protected-browser-v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Agent operations are the closed `BrowserOperation` union: navigate, read, find,

Text is capped at 32 KiB with explicit truncation, observations expose at most 64 controls, screenshots at 2 MiB and request bodies at 64 KiB. URLs/ordinary input are capped at 4096 bytes. Captures exclude field values, hidden DOM and script text, and refuse password/2FA/file surfaces. A trusted safe-surface policy remains mandatory: field masking cannot certify arbitrary authenticated pages. The actual observed URL must match the admitted safe document. Each network read and each text/image capture has its own policy read claim and final current-authority/publication checks; output cannot renew a lease or grant an effect.

Input completion waits for native command acknowledgement, the expected navigation (including Chromium frame-stop after a refused request), and every intercepted request actually started by that input. A protected 30-second operation deadline reports an unknown outcome rather than inferring completion from elapsed time. `execute` and `resume` accept an optional AbortSignal; final input guards run after readiness waits and immediately before protocol enqueue, and cancellation suppresses later request release and result publication. If an effect's broker request has already been released, cancellation/deadline never aborts that transport or retries it: the original policy claim/capacity and reconcile-only continuity remain until actual settlement. Graceful close waits for retained transports instead of treating cancellation as proof of settlement.
Input completion waits for native command acknowledgement, the expected navigation (including Chromium frame-stop after a refused request), and every intercepted request actually started by that input. A protected 30-second operation deadline reports an unknown outcome rather than inferring completion from elapsed time. `execute` and `resume` accept an optional AbortSignal; final input guards run after readiness waits and immediately before protocol enqueue, and cancellation suppresses later request release and result publication. If an effect's broker request has already been released, cancellation/deadline never aborts that transport or retries it: the original policy claim/capacity and reconcile-only continuity remain until actual settlement. Graceful close starts native browser shutdown to settle pending renderer operations, then waits for retained scopes/transports before closing broker/continuity custody; browser closure is not proof of remote effect settlement.

JSON results distinguish observed content, image bytes, held exact action, denied/unsupported reason, unknown outcome and completed input. Completed input does not assert a remote business outcome. Page content is untrusted evidence. The Schway tool uses only the public `ToolDefinition` surface, with its work closure supplied by the host.

Expand Down Expand Up @@ -59,7 +59,7 @@ Takeover advances the current durable generation, fences agent input/publication

The host-only `BrowserWork.settled()` waits for the current lease's already-started native/network scopes. It neither dispatches nor renews authority, and old leases cannot wait on or release a newer lease. The effects/CHAT bridge uses this completion for cancellation/deadline cleanup and releases only after actual settlement; it reaps denied/stopped actions before a new browser admission. Cleanup aborts paused input, never an already-released broker transport.

The additive [effect contract](s15-effects-v1.md) supplies one controlled record-service verifier. `BrowserSitePolicy.reconcileEffect(request, context)` is optional trusted read-only code and calls the original recovery context before actual I/O. `BrowserOwner.reconcile` invokes POLICY's authenticated charged recovery lane and clears only the matching continuity record after conclusive service evidence. Missing verifiers remain unsupported; owner statements never clear uncertainty.
The additive [effect contract](s15-effects-v1.md) supplies one controlled record-service verifier. `BrowserSitePolicy.reconcileEffect(request, context)` is optional trusted read-only code and calls the original recovery context before actual I/O. `BrowserOwner.reconcile` invokes POLICY's authenticated charged recovery lane and clears only the matching continuity record after conclusive service evidence. Missing verifiers or unsupported retained request semantics return a fulfilled unknown read result: the recovery read lane settles while the original effect remains uncertain and charged, allowing a later protected verifier without resending the effect. Owner statements never clear uncertainty. [The S16 reference proof](../evidence/s16-protected-browser-reference.md) exercises actual process loss and service read-back through these ports.

A small protected SQLite record outside the browser profile retains monotonic input generation and an armed/uncertain exact action reference. It is armed before action dispatch; crash/restart cannot clear it or reconstruct a callable request context. Unknown business outcomes remain reconcile-only and block fresh effect retries. Owner statements are not verification. The real policy ledger remains the authority for exact payloads, claims, approvals, nonrefundable budget charges and remote observations. Generic business reconciliation is unsupported until its protected verifier exists; opening a new browser/profile is not a retry mechanism.

Expand Down
Loading
Loading