@harness-fe/runtime 3.4.0 → 4.0.0-next.0

package/dist/capture.d.ts

@@ -65,7 +65,7 @@ export declare class CaptureStore {
     }>;
     readonly storage: RingBuffer<{
         op: "set" | "remove" | "clear";
-        which: "local" | "session" | "cookie";
+        which: "session" | "local" | "cookie";
         ts: number;
         key?: string | undefined;
         value?: string | undefined;

package/dist/client.d.ts

@@ -4,7 +4,7 @@
  *
  * Started lazily by `auto-start.ts` when the script is imported.
  */
-import { COMMAND } from '@harness-fe/protocol';
+import { COMMAND, type ConsentDecision, type ConsentRequest } from '@harness-fe/protocol';
 import type { QueryMethod } from '@harness-fe/protocol';
 export interface ClientOptions {
     projectId: string;
@@ -54,6 +54,11 @@ export declare class RuntimeClient {
     /** WebSocket state: 'connecting' | 'open' | 'closed'. */
     getConnectionState(): 'connecting' | 'open' | 'closed';
     private pageLoadSent;
+    private consentMode;
+    /** Set once the user grants blanket control for this pageload (mode=session). */
+    private consentSessionGranted;
+    /** Set by the overlay to collect the user's decision. Absent ⇒ fail-safe deny. */
+    private consentPrompter?;
     private readonly ctx;
     private readonly recorder;
     private reconnectAttempts;
@@ -69,8 +74,20 @@ export declare class RuntimeClient {
     private onClose;
     private onMessage;
     private onQueryResponse;
+    /**
+     * Register the consent prompter (the overlay installs this). When the
+     * policy is on and a control command arrives, the client asks this for the
+     * user's decision. Without it, gated commands are denied (fail-safe).
+     */
+    setConsentPrompter(fn: (req: ConsentRequest) => Promise<ConsentDecision>): void;
     private onHelloAck;
     private handleCommand;
+    /**
+     * Ask the user (via the overlay-registered prompter) to approve a control
+     * command. Fail-safe: if no prompter is registered, or it throws, deny —
+     * a consent policy that can't ask must not silently allow.
+     */
+    private requestConsent;
     sendEvent(name: string, payload: unknown): void;
     /**
      * Request/reply RPC to the daemon. Currently used by the in-page

package/dist/client.js

@@ -4,7 +4,7 @@
  *
  * Started lazily by `auto-start.ts` when the script is imported.
  */
-import { COMMAND, DEFAULT_WS_PORT, EVENT_NAME, frameSchema, } from '@harness-fe/protocol';
+import { ALWAYS_CONFIRM_COMMANDS, COMMAND, DEFAULT_WS_PORT, EVENT_NAME, requiresConsent, frameSchema, } from '@harness-fe/protocol';
 import { getCaptureStore } from './capture.js';
 import { commandHandlers } from './commands.js';
 import { Outbox } from './outbox.js';
@@ -89,6 +89,14 @@ export class RuntimeClient {
         }
     }
     pageLoadSent = false;
+    // Browser consent (4.0 · P2). Mode comes from the daemon in hello.ack;
+    // default `off` so a daemon that never sends a policy (or loopback solo
+    // dev) keeps running control commands without prompting.
+    consentMode = 'off';
+    /** Set once the user grants blanket control for this pageload (mode=session). */
+    consentSessionGranted = false;
+    /** Set by the overlay to collect the user's decision. Absent ⇒ fail-safe deny. */
+    consentPrompter;
     ctx = { capture: getCaptureStore() };
     // Initialized in constructor (parameter property `opts` isn't readable at
     // class-field-initializer time — field initializers run before parameter
@@ -209,11 +217,21 @@ export class RuntimeClient {
             pending.reject(new Error(frame.error?.message ?? 'query failed'));
         }
     }
+    /**
+     * Register the consent prompter (the overlay installs this). When the
+     * policy is on and a control command arrives, the client asks this for the
+     * user's decision. Without it, gated commands are denied (fail-safe).
+     */
+    setConsentPrompter(fn) {
+        this.consentPrompter = fn;
+    }
     onHelloAck(frame) {
         if (frame.error) {
             // Bridge rejected this hello — do not send PAGE_LOAD.
             return;
         }
+        // Adopt the daemon's consent policy for this connection (4.0 · P2).
+        this.consentMode = frame.consent?.mode ?? 'off';
         // Force a fresh rrweb FullSnapshot on every ack — including reconnects
         // after daemon restart, network blips, or page-recovery from sleep.
         // Without this, the only baseline for the session is whatever rrweb
@@ -247,6 +265,23 @@ export class RuntimeClient {
             });
             return;
         }
+        // Browser-consent gate (4.0 · P2): control commands need the user's
+        // OK in the page before they run when the daemon enabled consent.
+        if (requiresConsent(frame.command, this.consentMode, this.consentSessionGranted)) {
+            const decision = await this.requestConsent(frame);
+            if (decision === 'deny') {
+                this.send({
+                    type: 'response',
+                    id: frame.id,
+                    ok: false,
+                    error: { code: 'CONSENT_DENIED', message: `user denied "${frame.command}"` },
+                });
+                return;
+            }
+            if (decision === 'session')
+                this.consentSessionGranted = true;
+            // 'once' → run this one without granting the rest of the session.
+        }
         try {
             const result = await handler(frame.args ?? {}, this.ctx);
             this.send({
@@ -266,6 +301,27 @@ export class RuntimeClient {
             });
         }
     }
+    /**
+     * Ask the user (via the overlay-registered prompter) to approve a control
+     * command. Fail-safe: if no prompter is registered, or it throws, deny —
+     * a consent policy that can't ask must not silently allow.
+     */
+    async requestConsent(frame) {
+        if (!this.consentPrompter)
+            return 'deny';
+        const req = {
+            command: frame.command,
+            args: frame.args,
+            tabId: this.tabId,
+            alwaysConfirm: ALWAYS_CONFIRM_COMMANDS.has(frame.command),
+        };
+        try {
+            return await this.consentPrompter(req);
+        }
+        catch {
+            return 'deny';
+        }
+    }
     sendEvent(name, payload) {
         const event = {
             type: 'event',

package/dist/overlay.d.ts

@@ -13,7 +13,7 @@
  * Single Shadow DOM root attached to <body>; host page styles never leak in
  * or out. State machine: idle → info → (picker → question) → flash → idle.
  */
-import { type TaskAttachment } from '@harness-fe/protocol';
+import { type ConsentDecision, type ConsentRequest, type TaskAttachment } from '@harness-fe/protocol';
 import { type OverlayPluginLogs, type OverlayPluginGetLogsOptions } from './pluginRegistry.js';
 export interface OverlayClient {
     readonly projectId: string;
@@ -37,6 +37,12 @@ export interface OverlayClient {
      * tasks. Resolves with `result`, rejects with the remote error message.
      */
     query?<TResult = unknown>(method: string, args?: unknown): Promise<TResult>;
+    /**
+     * Register the browser-consent prompter (4.0 · P2). The client calls this
+     * to ask the user before running a control command. Optional so embedders
+     * with a non-RuntimeClient overlay client still type-check.
+     */
+    setConsentPrompter?(fn: (req: ConsentRequest) => Promise<ConsentDecision>): void;
 }
 export declare function installOverlay(client: OverlayClient): void;
 interface ArrowStroke {

package/dist/overlay.js

@@ -77,8 +77,9 @@ export function installOverlay(client) {
     const pickerBar = buildPickerBar();
     const annotateModal = buildAnnotateModal();
     const questionPanel = buildQuestionPanel();
+    const consentPanel = buildConsentPanel();
     const highlight = buildHighlight();
-    root.append(fab, infoCard, reportsCard, pickerBar, annotateModal, questionPanel, highlight);
+    root.append(fab, infoCard, reportsCard, pickerBar, annotateModal, questionPanel, consentPanel, highlight);
     const mount = () => {
         if (!document.body)
             return false;
@@ -256,6 +257,7 @@ export function installOverlay(client) {
         pickerBar.style.display = next === 'picker' ? 'flex' : 'none';
         annotateModal.style.display = next === 'annotate' ? 'flex' : 'none';
         questionPanel.style.display = next === 'question' ? 'flex' : 'none';
+        consentPanel.style.display = next === 'consent' ? 'flex' : 'none';
         document.documentElement.style.cursor = next === 'picker' ? 'crosshair' : '';
         fab.dataset.state = (next === 'picker' || next === 'annotate') ? 'active' : 'idle';
         if (next !== 'picker' && next !== 'question' && next !== 'annotate') {
@@ -284,6 +286,40 @@ export function installOverlay(client) {
             requestAnimationFrame(() => repositionCards());
         }
     };
+    // ─── Browser consent prompter (4.0 · P2) ─────────────────────────────
+    // The client calls this before running a control command when the daemon
+    // enabled consent. We show a modal and resolve with the user's choice.
+    const consentCmdEl = consentPanel.querySelector('[data-role="consent-cmd"]');
+    const consentAllowOnce = consentPanel.querySelector('[data-role="consent-once"]');
+    const consentAllowSession = consentPanel.querySelector('[data-role="consent-session"]');
+    const consentDeny = consentPanel.querySelector('[data-role="consent-deny"]');
+    let consentChain = Promise.resolve();
+    const promptConsent = (req) => new Promise((resolve) => {
+        consentCmdEl.textContent = formatConsentCommand(req);
+        // page.evaluate (alwaysConfirm) can never be granted session-wide.
+        consentAllowSession.style.display = req.alwaysConfirm ? 'none' : '';
+        setState('consent');
+        const finish = (decision) => {
+            consentAllowOnce.removeEventListener('click', onOnce);
+            consentAllowSession.removeEventListener('click', onSession);
+            consentDeny.removeEventListener('click', onDeny);
+            setState('idle');
+            resolve(decision);
+        };
+        const onOnce = () => finish('once');
+        const onSession = () => finish('session');
+        const onDeny = () => finish('deny');
+        consentAllowOnce.addEventListener('click', onOnce);
+        consentAllowSession.addEventListener('click', onSession);
+        consentDeny.addEventListener('click', onDeny);
+    });
+    // Serialize prompts so a burst of control commands queues one dialog at a time.
+    const showConsentPrompt = (req) => {
+        const result = consentChain.then(() => promptConsent(req));
+        consentChain = result.catch(() => undefined);
+        return result;
+    };
+    client.setConsentPrompter?.(showConsentPrompt);
     // ─── Picker handlers ─────────────────────────────────────────────────
     const setHighlight = (el) => {
         if (!el || !(el instanceof HTMLElement || el instanceof SVGElement)) {
@@ -2044,6 +2080,43 @@ function buildHighlight() {
     div.className = 'highlight';
     return div;
 }
+/**
+ * Browser-consent modal (4.0 · P2). Self-contained inline styles (no reliance
+ * on buildStyle) — a fixed, centered card with command preview + 3 choices.
+ */
+function buildConsentPanel() {
+    const panel = document.createElement('div');
+    panel.className = 'consent';
+    panel.style.cssText = [
+        'display:none', 'position:fixed', 'left:50%', 'top:24px', 'transform:translateX(-50%)',
+        'z-index:2147483647', 'flex-direction:column', 'gap:10px', 'max-width:380px',
+        'width:calc(100% - 32px)', 'box-sizing:border-box', 'padding:16px',
+        'background:#fff', 'color:#111', 'border:1px solid #e5e7eb', 'border-radius:10px',
+        'box-shadow:0 8px 28px rgba(0,0,0,.16)',
+        'font:13px/1.45 -apple-system,BlinkMacSystemFont,system-ui,sans-serif',
+    ].join(';');
+    panel.innerHTML = `
+        <div style="font-weight:600">Agent wants to control this page</div>
+        <code data-role="consent-cmd" style="display:block;padding:8px 10px;background:#f6f6f7;border-radius:6px;font:12px ui-monospace,SFMono-Regular,Menlo,monospace;word-break:break-all"></code>
+        <div style="display:flex;gap:8px;justify-content:flex-end;flex-wrap:wrap">
+            <button data-role="consent-deny" type="button" style="padding:7px 12px;border:1px solid #d1d5db;border-radius:6px;background:#fff;color:#111;cursor:pointer">Deny</button>
+            <button data-role="consent-session" type="button" style="padding:7px 12px;border:0;border-radius:6px;background:#f0f0f0;color:#111;cursor:pointer">Allow for session</button>
+            <button data-role="consent-once" type="button" style="padding:7px 12px;border:0;border-radius:6px;background:#111;color:#fff;cursor:pointer">Allow once</button>
+        </div>
+    `;
+    return panel;
+}
+/** Render a control command + its most telling arg for the consent prompt. */
+function formatConsentCommand(req) {
+    const args = req.args && typeof req.args === 'object'
+        ? req.args
+        : undefined;
+    const detail = args?.selector ?? args?.url ?? args?.expr ?? args?.value ?? args?.predicate;
+    if (detail === undefined)
+        return req.command;
+    const s = String(detail);
+    return `${req.command}(${s.length > 80 ? `${s.slice(0, 80)}…` : s})`;
+}
 // ─── Element / payload helpers (unchanged from annotation.ts) ────────────
 function describeElement(el) {
     const tag = el.tagName.toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-fe/runtime",
-  "version": "3.4.0",
+  "version": "4.0.0-next.0",
   "description": "Browser-side SDK injected into the dev page. Connects to the MCP server via WebSocket and executes commands.",
   "type": "module",
   "license": "MIT",
@@ -30,8 +30,8 @@
   "dependencies": {
     "@zumer/snapdom": "^2.12.0",
     "rrweb": "2.0.0-alpha.4",
-    "@harness-fe/sandbox": "^3.2.0",
-    "@harness-fe/protocol": "3.2.0"
+    "@harness-fe/protocol": "4.0.0-next.0",
+    "@harness-fe/sandbox": "^3.2.0"
   },
   "devDependencies": {
     "happy-dom": "^20.9.0",

package/src/client.ts

@@ -6,10 +6,15 @@
  */
 
 import {
+    ALWAYS_CONFIRM_COMMANDS,
     COMMAND,
     DEFAULT_WS_PORT,
     EVENT_NAME,
+    requiresConsent,
     type CommandFrame,
+    type ConsentDecision,
+    type ConsentMode,
+    type ConsentRequest,
     type EventFrame,
     type Frame,
     type HelloAckFrame,
@@ -143,6 +148,14 @@ export class RuntimeClient {
         }
     }
     private pageLoadSent = false;
+    // Browser consent (4.0 · P2). Mode comes from the daemon in hello.ack;
+    // default `off` so a daemon that never sends a policy (or loopback solo
+    // dev) keeps running control commands without prompting.
+    private consentMode: ConsentMode = 'off';
+    /** Set once the user grants blanket control for this pageload (mode=session). */
+    private consentSessionGranted = false;
+    /** Set by the overlay to collect the user's decision. Absent ⇒ fail-safe deny. */
+    private consentPrompter?: (req: ConsentRequest) => Promise<ConsentDecision>;
     private readonly ctx: CommandContext = { capture: getCaptureStore() };
     // Initialized in constructor (parameter property `opts` isn't readable at
     // class-field-initializer time — field initializers run before parameter
@@ -271,11 +284,22 @@ export class RuntimeClient {
         }
     }
 
+    /**
+     * Register the consent prompter (the overlay installs this). When the
+     * policy is on and a control command arrives, the client asks this for the
+     * user's decision. Without it, gated commands are denied (fail-safe).
+     */
+    setConsentPrompter(fn: (req: ConsentRequest) => Promise<ConsentDecision>): void {
+        this.consentPrompter = fn;
+    }
+
     private onHelloAck(frame: HelloAckFrame): void {
         if (frame.error) {
             // Bridge rejected this hello — do not send PAGE_LOAD.
             return;
         }
+        // Adopt the daemon's consent policy for this connection (4.0 · P2).
+        this.consentMode = frame.consent?.mode ?? 'off';
         // Force a fresh rrweb FullSnapshot on every ack — including reconnects
         // after daemon restart, network blips, or page-recovery from sleep.
         // Without this, the only baseline for the session is whatever rrweb
@@ -309,6 +333,22 @@ export class RuntimeClient {
             } satisfies ResponseFrame);
             return;
         }
+        // Browser-consent gate (4.0 · P2): control commands need the user's
+        // OK in the page before they run when the daemon enabled consent.
+        if (requiresConsent(frame.command, this.consentMode, this.consentSessionGranted)) {
+            const decision = await this.requestConsent(frame);
+            if (decision === 'deny') {
+                this.send({
+                    type: 'response',
+                    id: frame.id,
+                    ok: false,
+                    error: { code: 'CONSENT_DENIED', message: `user denied "${frame.command}"` },
+                } satisfies ResponseFrame);
+                return;
+            }
+            if (decision === 'session') this.consentSessionGranted = true;
+            // 'once' → run this one without granting the rest of the session.
+        }
         try {
             const result = await handler(frame.args ?? {}, this.ctx);
             this.send({
@@ -328,6 +368,26 @@ export class RuntimeClient {
         }
     }
 
+    /**
+     * Ask the user (via the overlay-registered prompter) to approve a control
+     * command. Fail-safe: if no prompter is registered, or it throws, deny —
+     * a consent policy that can't ask must not silently allow.
+     */
+    private async requestConsent(frame: CommandFrame): Promise<ConsentDecision> {
+        if (!this.consentPrompter) return 'deny';
+        const req: ConsentRequest = {
+            command: frame.command,
+            args: frame.args,
+            tabId: this.tabId,
+            alwaysConfirm: ALWAYS_CONFIRM_COMMANDS.has(frame.command),
+        };
+        try {
+            return await this.consentPrompter(req);
+        } catch {
+            return 'deny';
+        }
+    }
+
     sendEvent(name: string, payload: unknown): void {
         const event: EventFrame = {
             type: 'event',

package/src/consentGate.test.ts

@@ -0,0 +1,115 @@
+// @vitest-environment happy-dom
+/**
+ * Browser-consent gate (4.0 · P2) in RuntimeClient.handleCommand. We drive
+ * handleCommand directly with a stubbed `send` and a mocked command-handler
+ * table, so the test isolates the consent decision wiring from real DOM ops.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// rrweb has CJS/ESM interop issues under happy-dom; stub it (same as the e2e).
+vi.mock('rrweb', () => ({ record: () => () => {}, EventType: { Custom: 5 } }));
+
+const handlerCalls: string[] = [];
+vi.mock('./commands.js', () => ({
+    commandHandlers: new Proxy(
+        {},
+        {
+            get: (_t, prop) =>
+                typeof prop === 'string'
+                    ? async () => {
+                          handlerCalls.push(prop);
+                          return { ran: prop };
+                      }
+                    : undefined,
+        },
+    ),
+}));
+
+import { COMMAND, type ConsentDecision, type ConsentMode } from '@harness-fe/protocol';
+import { RuntimeClient } from './client.js';
+import { getCaptureStore } from './capture.js';
+
+type Sent = { type: string; ok?: boolean; error?: { code?: string } };
+
+function makeClient(mode: ConsentMode) {
+    const c = new RuntimeClient({ projectId: 'p' });
+    (c as unknown as { consentMode: ConsentMode }).consentMode = mode;
+    const sent: Sent[] = [];
+    (c as unknown as { send: (f: Sent) => void }).send = (f) => sent.push(f);
+    return { c, sent };
+}
+
+const command = (cmd: string, id = 'id-1') => ({ type: 'command' as const, id, command: cmd, args: { selector: '.x' } });
+const run = (c: RuntimeClient, frame: ReturnType<typeof command>) =>
+    (c as unknown as { handleCommand: (f: unknown) => Promise<void> }).handleCommand(frame);
+
+beforeEach(() => {
+    handlerCalls.length = 0;
+    getCaptureStore().dispose();
+});
+
+describe('consent gate', () => {
+    it('off mode: control command runs without prompting', async () => {
+        const { c, sent } = makeClient('off');
+        const prompter = vi.fn();
+        c.setConsentPrompter(prompter);
+        await run(c, command(COMMAND.PAGE_CLICK));
+        expect(prompter).not.toHaveBeenCalled();
+        expect(handlerCalls).toEqual([COMMAND.PAGE_CLICK]);
+        expect(sent[0].ok).toBe(true);
+    });
+
+    it('deny → CONSENT_DENIED, handler never runs', async () => {
+        const { c, sent } = makeClient('session');
+        c.setConsentPrompter(async () => 'deny' as ConsentDecision);
+        await run(c, command(COMMAND.PAGE_CLICK));
+        expect(handlerCalls).toEqual([]);
+        expect(sent[0].ok).toBe(false);
+        expect(sent[0].error?.code).toBe('CONSENT_DENIED');
+    });
+
+    it('fail-safe: consent on but no prompter registered → deny', async () => {
+        const { c, sent } = makeClient('session');
+        await run(c, command(COMMAND.PAGE_CLICK));
+        expect(handlerCalls).toEqual([]);
+        expect(sent[0].error?.code).toBe('CONSENT_DENIED');
+    });
+
+    it('once: runs this command but does not grant the session', async () => {
+        const { c } = makeClient('session');
+        const prompter = vi.fn(async () => 'once' as ConsentDecision);
+        c.setConsentPrompter(prompter);
+        await run(c, command(COMMAND.PAGE_CLICK, 'a'));
+        await run(c, command(COMMAND.PAGE_CLICK, 'b'));
+        expect(prompter).toHaveBeenCalledTimes(2); // prompted each time
+        expect(handlerCalls).toEqual([COMMAND.PAGE_CLICK, COMMAND.PAGE_CLICK]);
+    });
+
+    it('session: first prompt grants blanket control for the rest of the session', async () => {
+        const { c } = makeClient('session');
+        const prompter = vi.fn(async () => 'session' as ConsentDecision);
+        c.setConsentPrompter(prompter);
+        await run(c, command(COMMAND.PAGE_CLICK, 'a'));
+        await run(c, command(COMMAND.PAGE_TYPE, 'b'));
+        expect(prompter).toHaveBeenCalledTimes(1); // second command not prompted
+        expect(handlerCalls).toEqual([COMMAND.PAGE_CLICK, COMMAND.PAGE_TYPE]);
+    });
+
+    it('page.evaluate always prompts even after a session grant', async () => {
+        const { c } = makeClient('session');
+        const prompter = vi.fn(async () => 'session' as ConsentDecision);
+        c.setConsentPrompter(prompter);
+        await run(c, command(COMMAND.PAGE_CLICK, 'a')); // grants session
+        await run(c, command(COMMAND.PAGE_EVALUATE, 'b')); // still prompts
+        expect(prompter).toHaveBeenCalledTimes(2);
+    });
+
+    it('read-only command is never gated', async () => {
+        const { c } = makeClient('session');
+        const prompter = vi.fn();
+        c.setConsentPrompter(prompter);
+        await run(c, command(COMMAND.CONSOLE_TAIL));
+        expect(prompter).not.toHaveBeenCalled();
+        expect(handlerCalls).toEqual([COMMAND.CONSOLE_TAIL]);
+    });
+});

package/src/overlay.ts

@@ -16,6 +16,8 @@
 
 import {
     EVENT_NAME,
+    type ConsentDecision,
+    type ConsentRequest,
     type TaskSubmitPayload,
     type TaskAttachment,
     type NetworkEntry,
@@ -101,6 +103,12 @@ export interface OverlayClient {
      * tasks. Resolves with `result`, rejects with the remote error message.
      */
     query?<TResult = unknown>(method: string, args?: unknown): Promise<TResult>;
+    /**
+     * Register the browser-consent prompter (4.0 · P2). The client calls this
+     * to ask the user before running a control command. Optional so embedders
+     * with a non-RuntimeClient overlay client still type-check.
+     */
+    setConsentPrompter?(fn: (req: ConsentRequest) => Promise<ConsentDecision>): void;
 }
 
 /** Subset of @harness-fe/protocol Task that the overlay renders. */
@@ -135,8 +143,9 @@ export function installOverlay(client: OverlayClient): void {
     const pickerBar = buildPickerBar();
     const annotateModal = buildAnnotateModal();
     const questionPanel = buildQuestionPanel();
+    const consentPanel = buildConsentPanel();
     const highlight = buildHighlight();
-    root.append(fab, infoCard, reportsCard, pickerBar, annotateModal, questionPanel, highlight);
+    root.append(fab, infoCard, reportsCard, pickerBar, annotateModal, questionPanel, consentPanel, highlight);
 
     const mount = () => {
         if (!document.body) return false;
@@ -300,7 +309,7 @@ export function installOverlay(client: OverlayClient): void {
     window.addEventListener('resize', onWindowResize);
 
     // ─── State machine ────────────────────────────────────────────────────
-    type State = 'idle' | 'info' | 'reports' | 'picker' | 'annotate' | 'question';
+    type State = 'idle' | 'info' | 'reports' | 'picker' | 'annotate' | 'question' | 'consent';
     let state: State = 'idle';
     let hoveredEl: Element | null = null;
     let lockedEl: Element | null = null;
@@ -317,6 +326,7 @@ export function installOverlay(client: OverlayClient): void {
         pickerBar.style.display = next === 'picker' ? 'flex' : 'none';
         annotateModal.style.display = next === 'annotate' ? 'flex' : 'none';
         questionPanel.style.display = next === 'question' ? 'flex' : 'none';
+        consentPanel.style.display = next === 'consent' ? 'flex' : 'none';
         document.documentElement.style.cursor = next === 'picker' ? 'crosshair' : '';
         fab.dataset.state = (next === 'picker' || next === 'annotate') ? 'active' : 'idle';
         if (next !== 'picker' && next !== 'question' && next !== 'annotate') {
@@ -345,6 +355,44 @@ export function installOverlay(client: OverlayClient): void {
         }
     };
 
+    // ─── Browser consent prompter (4.0 · P2) ─────────────────────────────
+    // The client calls this before running a control command when the daemon
+    // enabled consent. We show a modal and resolve with the user's choice.
+    const consentCmdEl = consentPanel.querySelector('[data-role="consent-cmd"]') as HTMLElement;
+    const consentAllowOnce = consentPanel.querySelector('[data-role="consent-once"]') as HTMLButtonElement;
+    const consentAllowSession = consentPanel.querySelector('[data-role="consent-session"]') as HTMLButtonElement;
+    const consentDeny = consentPanel.querySelector('[data-role="consent-deny"]') as HTMLButtonElement;
+    let consentChain: Promise<unknown> = Promise.resolve();
+
+    const promptConsent = (req: ConsentRequest): Promise<ConsentDecision> =>
+        new Promise<ConsentDecision>((resolve) => {
+            consentCmdEl.textContent = formatConsentCommand(req);
+            // page.evaluate (alwaysConfirm) can never be granted session-wide.
+            consentAllowSession.style.display = req.alwaysConfirm ? 'none' : '';
+            setState('consent');
+            const finish = (decision: ConsentDecision) => {
+                consentAllowOnce.removeEventListener('click', onOnce);
+                consentAllowSession.removeEventListener('click', onSession);
+                consentDeny.removeEventListener('click', onDeny);
+                setState('idle');
+                resolve(decision);
+            };
+            const onOnce = () => finish('once');
+            const onSession = () => finish('session');
+            const onDeny = () => finish('deny');
+            consentAllowOnce.addEventListener('click', onOnce);
+            consentAllowSession.addEventListener('click', onSession);
+            consentDeny.addEventListener('click', onDeny);
+        });
+
+    // Serialize prompts so a burst of control commands queues one dialog at a time.
+    const showConsentPrompt = (req: ConsentRequest): Promise<ConsentDecision> => {
+        const result = consentChain.then(() => promptConsent(req));
+        consentChain = result.catch(() => undefined);
+        return result;
+    };
+    client.setConsentPrompter?.(showConsentPrompt);
+
     // ─── Picker handlers ─────────────────────────────────────────────────
     const setHighlight = (el: Element | null) => {
         if (!el || !(el instanceof HTMLElement || el instanceof SVGElement)) {
@@ -2182,6 +2230,44 @@ function buildHighlight(): HTMLDivElement {
     return div;
 }
 
+/**
+ * Browser-consent modal (4.0 · P2). Self-contained inline styles (no reliance
+ * on buildStyle) — a fixed, centered card with command preview + 3 choices.
+ */
+function buildConsentPanel(): HTMLDivElement {
+    const panel = document.createElement('div');
+    panel.className = 'consent';
+    panel.style.cssText = [
+        'display:none', 'position:fixed', 'left:50%', 'top:24px', 'transform:translateX(-50%)',
+        'z-index:2147483647', 'flex-direction:column', 'gap:10px', 'max-width:380px',
+        'width:calc(100% - 32px)', 'box-sizing:border-box', 'padding:16px',
+        'background:#fff', 'color:#111', 'border:1px solid #e5e7eb', 'border-radius:10px',
+        'box-shadow:0 8px 28px rgba(0,0,0,.16)',
+        'font:13px/1.45 -apple-system,BlinkMacSystemFont,system-ui,sans-serif',
+    ].join(';');
+    panel.innerHTML = `
+        <div style="font-weight:600">Agent wants to control this page</div>
+        <code data-role="consent-cmd" style="display:block;padding:8px 10px;background:#f6f6f7;border-radius:6px;font:12px ui-monospace,SFMono-Regular,Menlo,monospace;word-break:break-all"></code>
+        <div style="display:flex;gap:8px;justify-content:flex-end;flex-wrap:wrap">
+            <button data-role="consent-deny" type="button" style="padding:7px 12px;border:1px solid #d1d5db;border-radius:6px;background:#fff;color:#111;cursor:pointer">Deny</button>
+            <button data-role="consent-session" type="button" style="padding:7px 12px;border:0;border-radius:6px;background:#f0f0f0;color:#111;cursor:pointer">Allow for session</button>
+            <button data-role="consent-once" type="button" style="padding:7px 12px;border:0;border-radius:6px;background:#111;color:#fff;cursor:pointer">Allow once</button>
+        </div>
+    `;
+    return panel;
+}
+
+/** Render a control command + its most telling arg for the consent prompt. */
+function formatConsentCommand(req: ConsentRequest): string {
+    const args = req.args && typeof req.args === 'object'
+        ? (req.args as Record<string, unknown>)
+        : undefined;
+    const detail = args?.selector ?? args?.url ?? args?.expr ?? args?.value ?? args?.predicate;
+    if (detail === undefined) return req.command;
+    const s = String(detail);
+    return `${req.command}(${s.length > 80 ? `${s.slice(0, 80)}…` : s})`;
+}
+
 // ─── Element / payload helpers (unchanged from annotation.ts) ────────────
 
 function describeElement(el: Element): string {