[abrichr]

Builds on #1436. That PR stops browser teach from teaching or running any write tool. This one turns writes back on, under the signed teach authorization.

What changes

Teaching a write. teach_start with a contract needs the server to be started with --teach-authorization. The statement must:

• verify against the approver roster, for purpose teach and task taught.<name>, and not be expired;
• name the app's origin;
• give the contract as its record_kind;
• name a write adapter;
• take exactly run 1's inputs;
• have as its identity and fields exactly the record fields the contract checks, with run 1's values.

If it's missing or anything differs, nothing starts.

During run 1.

• The write adapter reads every write the wire check would send, before it goes. A wrong record or value, or a write it can't attribute, is blocked.
• Only the statement's values may be typed.
• Clicks on forbidden controls are refused.

Running a taught tool.

• The tool folder keeps a copy of the statement, and program.json is signed with the local admission key.
• Before every call, the server checks the program's signature. It then checks the kept statement's digest, signature, roster membership, purpose, task and expiry, and that the statement still names the program's origin and contract.
• If any check fails, the call returns did_not_run.

Other changes.

• The example app ships its adapter, openadapt_flow.agent.example_app:OrderWrites.
• serve --teach-browser takes the roster pin only from the deployment config.

Limits

• The statement binds run 1's values only. Later calls take new inputs; the contract's read-back and the pinned run-1 writes bound them.
• A tool stops working when its statement expires (at most 90 days) and has to be taught again.
• Forbidden-control checks in this lane go by the ref's label.

Tests

• The two browser-write end-to-end files run again: real Chromium, the real MCP server, a real roster and real signatures.
• New unit tests refuse each of these before a browser opens: no statement; a statement that doesn't cover the write (another record kind, no adapter, another tool, undeclared inputs, other values, another app); an expired statement; an edited one; the wrong signer (a key that isn't on the roster, and a key signing in the approver's name).
• Run-time tests: no trust configured, an edited program, a removed signer, an expired statement, and a statement swapped in the tool folder.
• Results, run locally through the CPU-slot wrapper: 64 passed (browser teach unit and e2e tests, teach authorization tests, capabilities map). mypy and ruff are clean.

[abrichr]

Independent adversarial review (round 1), head 0acc432

A fresh reviewer got only the diff and the goal. It read the code and ran one python -c check, not the test suite.

Verdict: request changes.

What holds: a write can't be taught without a statement that verifies for taught.<name>, and every call checks the tool's signature again, along with the kept statement's digest, the roster as it is now, the purpose, the task and the expiry. Edited, renamed or copied programs, and swapped statements, are refused. The read-only lane is unchanged.

Findings:

1. Major: run-1 adapter check fails open. Coverage merges identity and fields, so a statement can put the record's key (customer) under fields. claim_refusal never compares the adapter's claim.record against the statement's fields. Reproduced: a write for another customer goes.
2. Major: the program-signing key directory can come from OPENADAPT_JIT_KEY_DIR. This happens when the config doesn't set approvers.key_dir, and the key is created on demand. An agent that sets the variable and copies in the root-signed roster holds the signing key, and can forge program.json.
3. Major (correctness): teaching a tool again under a new statement fails after run 1's write is made. copy_into refuses a different statement that is already kept, and the error isn't a BridgeError.
4. Minor: a contract match with a literal value ({"literal": ...} after model_dump) can never be taught.
5. Minor: coverage reads only effects[].match. field_equals and exact_new_set checks are ignored, so the docs' "exactly the checked fields" doesn't hold.
6. Minor: the statement's forbidden actions (other than delete_request) and its expected_rows aren't enforced in this lane, and the lane doesn't refuse statements that name them. Run 1 can repeat the approved POST.
7. Minor: press with single characters or paste chords gets around "only the statement's values may be typed".
8. Major (policy/doc): the signed values bind run 1 only, and render doesn't tell the signer. A hand-built statement with no expires_at runs forever; the 90-day cap is enforced only in create.
9. Minor: running taught tools depends on the server's startup --teach-authorization still being valid. Run-time trust should come from the config's approvers.
10. Minor (tests): no test runs the adapter inside the real browser route. There is no replace case, and the e2e lost its "secret in a GET address" case.
11. Nits:
    • Redirects skip the adapter.
    • The signed program has no domain tag.
    • A VERIFY_WRITES example is missing flags.
    • CAPABILITIES names Teach authorization signed with approver keys, bound to every teach path #1436 for this change.
    • Forbidden controls match on the label from observe time.

[abrichr]

Independent adversarial review (round 2), head a8bb412

A fresh reviewer got only the diff and the goals. It read the code and ran two small headless-Chromium probes; it did not run the test suite.

Verdict: request changes.

The write-lane binding is mostly sound. Teaching or running a write without a valid statement that covers it is refused, and edited, swapped, expired or wrongly signed statements fail closed. Run 1's writes go through the adapter in the route handler. The keyboard guard has two holes, which the reviewer reproduced in Chromium.

Findings:

1. Blocker: with focus inside a same-origin iframe, focused_control_label sees nothing focused and allows the key. getFullAXTree reads the main frame only.
2. Blocker: Enter in a text field submits the form through its default button, which can be the forbidden one. The check reads only the focused field.
3. Major: browser-teach clicks, presses with a ref, and selects still check the listing label built by page script, not the accessibility name. That label ignores aria-labelledby and is cut to 80 characters.
4. Major (key provenance): the server signs programs with the admission key, so it must be able to read it. If the server runs as the agent's user, the agent can read the key too. Separately, checking for ed25519.pub alone lets load_or_create_private_key rotate the key.
5. Minor: on surfaces without a page, clicks are not checked while keys are refused, contrary to the docs.
6. Minor: the docs overclaim. A page can still rename a control through ARIA; only prototype tampering is defeated.
7. Minor: the statement's origins aren't enforced on reads during run 1.
8. Minor: a missing admission key is only reported after run 1 has already written.
9. Minor (design): the statement binds only run 1's values. The reviewer suggests an explicit signed reusable_tool flag.
10. Nits:
    • expected_count: 0 is read as 1.
    • A ValueExpr with extra keys is treated as plain equality.
    • The kept statement is read twice.
    • secrets_token is public.
    • Staged copies are left behind.
    • Tab away from a forbidden control is refused.

Missing tests: frame focus, implicit submission, a forbidden control reached through teach_act whose listing label differs, and a surface without a page.

[abrichr]

Independent adversarial review (round 3), head 21c18d8

A fresh reviewer read the code and ran headless-Chromium probes. It did not run the test suite.

Verdict: request changes.

The authorization binding held: the reviewer couldn't teach or run a write without a valid statement that covers it.

• Trust comes only from --config.
• Edited, renamed or re-tasked programs, and swapped statements, are refused.
• Expiry, roster, purpose and task are checked again on every call.
• Every probe failure the reviewer could cause refused, including off-viewport points and OOPIFs.
• Focus reads were correct across same-origin and OOPIF frames.

Findings

1. Major: WebSockets skip run 1's scope. Playwright's context.route never sees them, so page JS can write over WebSocket, or reach origins the statement doesn't name.
2. Major: for Enter, the default-button logic can name the wrong button. It walks into shadow roots and iframes, and it treats a <button type=foo> as not-submit. In all three probes, a forbidden "Delete patient" default slipped through.
3. Major (regression on honest pages): the accessibility name misses non-semantic controls. A <div onclick>Delete patient</div> returns '', and so does a <label for> click that toggles a forbidden checkbox.
4. Minor: in the browser lane, a below-the-fold control is measured before it's scrolled into view, so the click is always refused (fails closed).
5. Minor: the browser lane shares the taught.<name> task namespace with serve --teach, so a one-time --teach statement can authorize a reusable browser tool.
6. Minor: after a tool is taught again, the agent can roll back to the older signed program and statement. Programs are also keyed by program["name"], not by folder.
7. Minor (docs): after run 1, only the signature, roster, purpose, task, expiry, origin and record kind apply, but the docs read wider.
8. Nit: the example adapter drops undeclared form fields.
9. Nit: in the browser lane, focus can move between the check and the key (hostile page only).

[abrichr]

Independent adversarial review (round 4), head c92461f

Recorded by the pr-backlog session, which paused before posting it. The round 1–3 fixes hold. Verdict: request changes.

Blockers

• Requests from a SharedWorker skip context.route, and WebSockets opened from dedicated or shared workers skip route_web_socket. Page JavaScript can send an authenticated POST, or open a WebSocket, that the write adapter never sees. Tracked in Worker traffic skips context.route: SharedWorker POSTs and worker WebSockets aren't seen by write guards #1814. feat(flow): worker and new-window containment for guarded browser contexts #1828 adds the containment building block (backends/worker_containment.py: CSP worker-src 'none', a window.open lock, a route that aborts other pages' requests, and a DevTools worker tripwire). This PR should wire it into the browser-teach lane and refuse when problem is set.

Major

• Later calls of a taught tool block no WebSockets at all.
• The click check reads the bounding-box centre, but Playwright clicks the first content quad, so a link that wraps onto two lines gets past the check.

Minor

• The key check reads fewer element names than the click check.
• Redirects aren't routed.
• The kept statement is read twice.
• GET writes aren't covered.

Next: land #1828 (after its review), wire it in here, add real-browser tests for a SharedWorker POST, a dedicated-worker fetch and a worker WebSocket on this lane, then request round 5.