@harness-fe/runtime 3.4.1 → 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;
@@ -249,12 +250,6 @@ export function installOverlay(client) {
     let pendingAttachment = null;
     /** Set while the picker is collecting an element for a `requiresElement` plugin. */
     let pluginAwaitingElement = null;
-    /**
-     * Purpose of the current picker session:
-     * - 'copy': copy element info to clipboard for use with an agent (default)
-     * - 'report': legacy report-a-problem flow (still used internally by plugins)
-     */
-    let pickerPurpose = 'copy';
     const setState = (next) => {
         state = next;
         infoCard.style.display = next === 'info' ? 'flex' : 'none';
@@ -262,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') {
@@ -290,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)) {
@@ -328,7 +358,7 @@ export function installOverlay(client) {
         lockedEl = hoveredEl;
         setHighlight(lockedEl);
         // A plugin requested the element — hand it straight to its onClick and
-        // skip all other flows.
+        // skip the report/question flow entirely.
         if (pluginAwaitingElement) {
             const plugin = pluginAwaitingElement;
             pluginAwaitingElement = null;
@@ -338,18 +368,9 @@ export function installOverlay(client) {
             void invokePlugin(plugin, el);
             return;
         }
-        // Copy mode: build element info and copy to clipboard for agent use.
-        if (pickerPurpose === 'copy') {
-            const el = lockedEl;
-            lockedEl = null;
-            const text = buildElementCopyText(el);
-            void copyText(text).then(() => {
-                showToast('✓ Element info copied');
-            });
-            setState('idle');
-            return;
-        }
-        // Report mode (legacy, no longer exposed in UI but kept for plugin compatibility).
+        // Go straight to the question step. Screenshots are now opt-in via
+        // the "Add screenshot" button inside the question panel — users
+        // shouldn't have to draw on every report.
         pendingAttachment = null;
         const info = questionPanel.querySelector('[data-role=info]');
         info.textContent = describeElement(lockedEl);
@@ -373,7 +394,6 @@ export function installOverlay(client) {
                 lockedEl = null;
                 pendingAttachment = null;
                 pluginAwaitingElement = null;
-                pickerPurpose = 'copy';
                 setState('info');
             }
             else if (state === 'info') {
@@ -444,31 +464,6 @@ export function installOverlay(client) {
             }, 1200);
         }
     };
-    /**
-     * Build a compact element-info block for pasting into an agent prompt.
-     * Omits HTML (too verbose); includes source location, component name, css
-     * path, and session context — enough for the agent to locate and fix the
-     * element without any further investigation.
-     */
-    const buildElementCopyText = (el) => {
-        const tag = el.tagName.toLowerCase();
-        const comp = el.getAttribute('data-morphix-comp');
-        const loc = el.getAttribute('data-morphix-loc');
-        const css = buildCssPath(el);
-        const lines = [];
-        lines.push(`### Element context`);
-        lines.push('');
-        if (comp)
-            lines.push(`- component: \`${comp}\``);
-        if (loc)
-            lines.push(`- source: \`${loc}\``);
-        lines.push(`- tag: \`${tag}\``);
-        lines.push(`- css: \`${css}\``);
-        lines.push(`- project: \`${client.projectId}\`${client.displayName ? ` (${client.displayName})` : ''}`);
-        lines.push(`- session: \`${client.sessionId}\``);
-        lines.push(`- url: ${location.href}`);
-        return lines.join('\n') + '\n';
-    };
     const buildSnapshot = () => {
         const lines = [];
         lines.push(`### Harness-FE snapshot`);
@@ -566,10 +561,6 @@ export function installOverlay(client) {
             btn.addEventListener('click', () => {
                 if (plugin.requiresElement) {
                     pluginAwaitingElement = plugin;
-                    pickerPurpose = 'report'; // plugins use the legacy element-selection flow
-                    const label = pickerBar.querySelector('[data-role=picker-label]');
-                    if (label)
-                        label.textContent = '🎯 Click an element';
                     setState('picker');
                 }
                 else {
@@ -798,17 +789,16 @@ export function installOverlay(client) {
         setState(state === 'idle' ? 'info' : 'idle');
     });
     infoCard.querySelector('[data-role=close]').addEventListener('click', () => setState('idle'));
-    infoCard.querySelector('[data-role=pick-element]').addEventListener('click', () => {
-        pickerPurpose = 'copy';
-        const label = pickerBar.querySelector('[data-role=picker-label]');
-        if (label)
-            label.textContent = '🔍 Click element to copy info';
+    infoCard.querySelector('[data-role=report]').addEventListener('click', () => {
         setState('picker');
     });
     infoCard.querySelector('[data-role=copy-snapshot]').addEventListener('click', (ev) => {
         const btn = ev.currentTarget;
         void copyText(buildSnapshot(), btn);
     });
+    infoCard.querySelector('[data-role=view-reports]').addEventListener('click', () => {
+        setState('reports');
+    });
     // "Open dashboard" — derive the daemon's dashboard URL from mcpUrl and
     // pop it in a new tab, deep-linked to this session. Show the button
     // only when we actually know the daemon address (mcpUrl was supplied by
@@ -861,7 +851,6 @@ export function installOverlay(client) {
     pickerBar.querySelector('[data-role=cancel]').addEventListener('click', () => {
         lockedEl = null;
         pluginAwaitingElement = null;
-        pickerPurpose = 'copy';
         setState('info');
     });
     questionPanel.querySelector('[data-role=cancel]').addEventListener('click', () => {
@@ -1986,15 +1975,16 @@ function buildInfoCard() {
             <div class="row"><span class="key">url</span><span class="pill url" data-role="url"></span></div>
         </div>
         <div class="actions">
-            <button class="primary" data-role="pick-element" type="button">
-                <span class="icon">🔍</span>
-                <span class="label">Copy element info</span>
-                <span class="hint">pick element →</span>
+            <button class="primary" data-role="report" type="button">
+                <span class="icon">🎯</span>
+                <span class="label">Report a problem</span>
+                <span class="hint">Pick an element →</span>
             </button>
             <button class="secondary" data-role="open-dashboard" type="button" style="display:none">
                 <span class="icon">↗</span>
                 <span>Open dashboard</span>
             </button>
+            <button class="secondary" data-role="view-reports" type="button">📁 My reports</button>
             <button class="secondary" data-role="copy-snapshot" type="button">📋 Copy snapshot</button>
         </div>
         <div class="plugin-actions" data-role="plugin-actions" style="display:none"></div>
@@ -2025,7 +2015,7 @@ function buildPickerBar() {
     const bar = document.createElement('div');
     bar.className = 'picker-bar';
     bar.innerHTML = `
-        <span class="label" data-role="picker-label">🔍 Click element to copy info</span>
+        <span class="label">🎯 Click an element to flag it</span>
         <span class="hint">esc to cancel</span>
         <button data-role="cancel" type="button">Cancel</button>
     `;
@@ -2090,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.1",
+  "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,7 +30,7 @@
   "dependencies": {
     "@zumer/snapdom": "^2.12.0",
     "rrweb": "2.0.0-alpha.4",
-    "@harness-fe/protocol": "3.2.0",
+    "@harness-fe/protocol": "4.0.0-next.0",
     "@harness-fe/sandbox": "^3.2.0"
   },
   "devDependencies": {

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.test.ts

@@ -73,20 +73,20 @@ describe('installOverlay', () => {
         expect(root.querySelector('[data-role=build]')!.textContent).toBe('—');
     });
 
-    it('"Copy element info" enters picker mode (FAB turns active, info card hidden)', () => {
+    it('"Report a problem" enters picker mode (FAB turns active, info card hidden)', () => {
         setupDom();
         const client = makeFakeClient();
         installOverlay(client);
         const root = document.getElementById('__harness_fe_overlay__')!.shadowRoot!;
         (root.querySelector('.fab') as HTMLButtonElement).click();
-        (root.querySelector('[data-role=pick-element]') as HTMLButtonElement).click();
+        (root.querySelector('[data-role=report]') as HTMLButtonElement).click();
         const fab = root.querySelector('.fab') as HTMLButtonElement;
         expect(fab.dataset.state).toBe('active');
         expect((root.querySelector('.info-card') as HTMLElement).style.display).toBe('none');
         expect((root.querySelector('.picker-bar') as HTMLElement).style.display).toBe('flex');
     });
 
-    it('"Copy element info" returns to idle after element click (no task.submit fired)', () => {
+    it('submits a task.submit event payload with selector + element on Submit', () => {
         const { doc } = setupDom();
         const target = doc.createElement('button');
         target.setAttribute('data-morphix-loc', 'app/cart/CartBadge.tsx:18:5');
@@ -94,31 +94,47 @@ describe('installOverlay', () => {
         target.textContent = 'Cart (3)';
         doc.body.appendChild(target);
 
-        // Stub clipboard so copyText does not throw in happy-dom.
-        const written: string[] = [];
-        Object.defineProperty(globalThis.navigator, 'clipboard', {
-            value: { writeText: (t: string) => { written.push(t); return Promise.resolve(); } },
-            configurable: true,
-        });
-
         const client = makeFakeClient();
         installOverlay(client);
         const root = document.getElementById('__harness_fe_overlay__')!.shadowRoot!;
 
-        // Open info card → enter pick-element picker mode.
+        // Open → report → fake-pick → submit.
         (root.querySelector('.fab') as HTMLButtonElement).click();
-        (root.querySelector('[data-role=pick-element]') as HTMLButtonElement).click();
-        expect((root.querySelector('.picker-bar') as HTMLElement).style.display).toBe('flex');
-
-        // Simulate hover + click on the target element.
-        target.dispatchEvent(new MouseEvent('mousemove', { bubbles: true, clientX: 0, clientY: 0 }));
+        (root.querySelector('[data-role=report]') as HTMLButtonElement).click();
+
+        // Simulate the picker click flow by directly invoking the state we'd
+        // be in after the user picks. We can't easily simulate
+        // elementFromPoint in happy-dom, so reach into the question panel
+        // and submit a payload — overlay.ts's submit handler reads lockedEl
+        // from a closure, so we go through a synthesized click instead.
+        // Trick: dispatch a capture-phase click on the body with the target.
+        // overlay's onClickCapture relies on `hoveredEl` set by mousemove.
+        // To avoid coupling to mousemove geometry, we test the submit handler
+        // is wired by inspecting the question textarea wiring instead.
+
+        // Force the panel into "question" state by clicking the target via
+        // the document; we first set hoveredEl by dispatching mousemove with
+        // matching screen coords.
+        target.dispatchEvent(new MouseEvent('mousemove', {
+            bubbles: true, clientX: 0, clientY: 0,
+        }));
+        // Direct click on the picker target triggers the capture handler.
         target.click();
 
-        // After the pick: overlay should be idle (picker bar hidden, no question panel).
-        // The question panel must NOT open — copy mode skips the report flow.
-        expect((root.querySelector('.question') as HTMLElement).style.display).toBe('none');
-        // No task.submit event should be sent — copy mode never fires a report.
-        expect(client.sent).toHaveLength(0);
+        // If the picker accepted, the question panel is now visible.
+        const question = root.querySelector('.question') as HTMLElement;
+        if (question.style.display === 'flex') {
+            (root.querySelector('.question textarea') as HTMLTextAreaElement).value = 'broken';
+            (root.querySelector('.question [data-role=submit]') as HTMLButtonElement).click();
+            expect(client.sent).toHaveLength(1);
+            expect(client.sent[0].name).toBe('task.submit');
+            const payload = client.sent[0].payload as { selector: { loc?: string }; question: string };
+            expect(payload.question).toBe('broken');
+            expect(payload.selector.loc).toBe('app/cart/CartBadge.tsx:18:5');
+        }
+        // If happy-dom's elementFromPoint didn't cooperate, the test still
+        // exercises mount/open/copy paths above — submit path is asserted
+        // separately by buildCssPath unit + bridge.test integration.
     });
 
     it('Esc closes the info card when open', () => {

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;
@@ -309,12 +318,6 @@ export function installOverlay(client: OverlayClient): void {
     let pendingAttachment: TaskAttachment | null = null;
     /** Set while the picker is collecting an element for a `requiresElement` plugin. */
     let pluginAwaitingElement: OverlayPlugin | null = null;
-    /**
-     * Purpose of the current picker session:
-     * - 'copy': copy element info to clipboard for use with an agent (default)
-     * - 'report': legacy report-a-problem flow (still used internally by plugins)
-     */
-    let pickerPurpose: 'copy' | 'report' = 'copy';
 
     const setState = (next: State) => {
         state = next;
@@ -323,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') {
@@ -351,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)) {
@@ -387,7 +429,7 @@ export function installOverlay(client: OverlayClient): void {
         lockedEl = hoveredEl;
         setHighlight(lockedEl);
         // A plugin requested the element — hand it straight to its onClick and
-        // skip all other flows.
+        // skip the report/question flow entirely.
         if (pluginAwaitingElement) {
             const plugin = pluginAwaitingElement;
             pluginAwaitingElement = null;
@@ -397,18 +439,9 @@ export function installOverlay(client: OverlayClient): void {
             void invokePlugin(plugin, el);
             return;
         }
-        // Copy mode: build element info and copy to clipboard for agent use.
-        if (pickerPurpose === 'copy') {
-            const el = lockedEl;
-            lockedEl = null;
-            const text = buildElementCopyText(el);
-            void copyText(text).then(() => {
-                showToast('✓ Element info copied');
-            });
-            setState('idle');
-            return;
-        }
-        // Report mode (legacy, no longer exposed in UI but kept for plugin compatibility).
+        // Go straight to the question step. Screenshots are now opt-in via
+        // the "Add screenshot" button inside the question panel — users
+        // shouldn't have to draw on every report.
         pendingAttachment = null;
         const info = questionPanel.querySelector<HTMLElement>('[data-role=info]')!;
         info.textContent = describeElement(lockedEl);
@@ -432,7 +465,6 @@ export function installOverlay(client: OverlayClient): void {
                 lockedEl = null;
                 pendingAttachment = null;
                 pluginAwaitingElement = null;
-                pickerPurpose = 'copy';
                 setState('info');
             } else if (state === 'info') {
                 setState('idle');
@@ -502,30 +534,6 @@ export function installOverlay(client: OverlayClient): void {
         }
     };
 
-    /**
-     * Build a compact element-info block for pasting into an agent prompt.
-     * Omits HTML (too verbose); includes source location, component name, css
-     * path, and session context — enough for the agent to locate and fix the
-     * element without any further investigation.
-     */
-    const buildElementCopyText = (el: Element): string => {
-        const tag = el.tagName.toLowerCase();
-        const comp = el.getAttribute('data-morphix-comp');
-        const loc = el.getAttribute('data-morphix-loc');
-        const css = buildCssPath(el);
-        const lines: string[] = [];
-        lines.push(`### Element context`);
-        lines.push('');
-        if (comp) lines.push(`- component: \`${comp}\``);
-        if (loc) lines.push(`- source: \`${loc}\``);
-        lines.push(`- tag: \`${tag}\``);
-        lines.push(`- css: \`${css}\``);
-        lines.push(`- project: \`${client.projectId}\`${client.displayName ? ` (${client.displayName})` : ''}`);
-        lines.push(`- session: \`${client.sessionId}\``);
-        lines.push(`- url: ${location.href}`);
-        return lines.join('\n') + '\n';
-    };
-
     const buildSnapshot = (): string => {
         const lines: string[] = [];
         lines.push(`### Harness-FE snapshot`);
@@ -624,9 +632,6 @@ export function installOverlay(client: OverlayClient): void {
             btn.addEventListener('click', () => {
                 if (plugin.requiresElement) {
                     pluginAwaitingElement = plugin;
-                    pickerPurpose = 'report'; // plugins use the legacy element-selection flow
-                    const label = pickerBar.querySelector<HTMLElement>('[data-role=picker-label]');
-                    if (label) label.textContent = '🎯 Click an element';
                     setState('picker');
                 } else {
                     setState('idle');
@@ -846,10 +851,7 @@ export function installOverlay(client: OverlayClient): void {
 
     infoCard.querySelector('[data-role=close]')!.addEventListener('click', () => setState('idle'));
 
-    infoCard.querySelector('[data-role=pick-element]')!.addEventListener('click', () => {
-        pickerPurpose = 'copy';
-        const label = pickerBar.querySelector<HTMLElement>('[data-role=picker-label]');
-        if (label) label.textContent = '🔍 Click element to copy info';
+    infoCard.querySelector('[data-role=report]')!.addEventListener('click', () => {
         setState('picker');
     });
 
@@ -858,6 +860,10 @@ export function installOverlay(client: OverlayClient): void {
         void copyText(buildSnapshot(), btn);
     });
 
+    infoCard.querySelector('[data-role=view-reports]')!.addEventListener('click', () => {
+        setState('reports');
+    });
+
     // "Open dashboard" — derive the daemon's dashboard URL from mcpUrl and
     // pop it in a new tab, deep-linked to this session. Show the button
     // only when we actually know the daemon address (mcpUrl was supplied by
@@ -911,7 +917,6 @@ export function installOverlay(client: OverlayClient): void {
     pickerBar.querySelector('[data-role=cancel]')!.addEventListener('click', () => {
         lockedEl = null;
         pluginAwaitingElement = null;
-        pickerPurpose = 'copy';
         setState('info');
     });
 
@@ -2114,15 +2119,16 @@ function buildInfoCard(): HTMLDivElement {
             <div class="row"><span class="key">url</span><span class="pill url" data-role="url"></span></div>
         </div>
         <div class="actions">
-            <button class="primary" data-role="pick-element" type="button">
-                <span class="icon">🔍</span>
-                <span class="label">Copy element info</span>
-                <span class="hint">pick element →</span>
+            <button class="primary" data-role="report" type="button">
+                <span class="icon">🎯</span>
+                <span class="label">Report a problem</span>
+                <span class="hint">Pick an element →</span>
             </button>
             <button class="secondary" data-role="open-dashboard" type="button" style="display:none">
                 <span class="icon">↗</span>
                 <span>Open dashboard</span>
             </button>
+            <button class="secondary" data-role="view-reports" type="button">📁 My reports</button>
             <button class="secondary" data-role="copy-snapshot" type="button">📋 Copy snapshot</button>
         </div>
         <div class="plugin-actions" data-role="plugin-actions" style="display:none"></div>
@@ -2155,7 +2161,7 @@ function buildPickerBar(): HTMLDivElement {
     const bar = document.createElement('div');
     bar.className = 'picker-bar';
     bar.innerHTML = `
-        <span class="label" data-role="picker-label">🔍 Click element to copy info</span>
+        <span class="label">🎯 Click an element to flag it</span>
         <span class="hint">esc to cancel</span>
         <button data-role="cancel" type="button">Cancel</button>
     `;
@@ -2224,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 {