teamshare-bridge 0.26.19 → 0.26.21

package/dist/lib/orchestrator/handlers/browser.js

@@ -36,6 +36,26 @@ async function screenOf(session) {
         return null;
     }
 }
+/**
+ * Pre-action settle context (2026-11): the current URL + timestamp, captured
+ * BEFORE a navigation-capable action runs. The post-action settle compares
+ * against these so an SPA route change or full load is visible. Best-effort
+ * and cheap (one pageInfo); a failure just means `fromUrl` is absent.
+ */
+async function settleContext(session) {
+    const since = Date.now();
+    if (!session?.pageInfo)
+        return { since };
+    try {
+        const info = await session.pageInfo();
+        if (info?.url)
+            return { since, fromUrl: info.url };
+    }
+    catch {
+        /* best-effort */
+    }
+    return { since };
+}
 /**
  * Emit an action result, attaching an inline screenshot when the session is in
  * QA vision mode (2026-10) AND a bounded per-action network delta (2026-10).
@@ -52,8 +72,34 @@ async function screenOf(session) {
  * payloads get one too: the toast or validation error that explains a failure
  * is exactly what the agent needs to see. The capture is BEST-EFFORT - a
  * screenshot problem must never turn a successful action into a failed one.
+ *
+ * 2026-11: in qaVision mode the screen is read AFTER a settle
+ * (`waitForScreenSettle`): the observer's mutation score, SPA route changes
+ * and full navigations are awaited first, so the screen + screenshot show the
+ * page the action produced instead of the mid-transition DOM. Pass
+ * `settle: false` to skip (e.g. a deliberate double-click sequence).
  */
-async function emitWithVision(emit, session, cmdId, payload) {
+async function emitWithVision(emit, session, cmdId, payload, opts) {
+    const wantSettle = session?.connected === true &&
+        session?.qaVision === true &&
+        opts?.settle !== false &&
+        typeof session?.waitForScreenSettle === 'function';
+    const settled = wantSettle && session
+        ? await session.waitForScreenSettle({
+            since: opts?.since ?? Date.now(),
+            fromUrl: opts?.fromUrl,
+        }).catch(() => null)
+        : null;
+    if (settled && opts?.rescreen) {
+        try {
+            const fresh = await opts.rescreen();
+            if (fresh)
+                payload.screen = fresh;
+        }
+        catch {
+            /* keep the pre-settle screen */
+        }
+    }
     if (session?.connected && session.qaVision === true) {
         try {
             const shot = await session.screenshot('jpeg', 62);
@@ -66,6 +112,9 @@ async function emitWithVision(emit, session, cmdId, payload) {
             /* vision is best-effort */
         }
     }
+    if (settled && (settled.changed || settled.navigated)) {
+        payload.change = settled;
+    }
     if (session?.connected && typeof session.networkDelta === 'function') {
         try {
             const delta = await session.networkDelta(Date.now() - 8000, 10);
@@ -79,14 +128,30 @@ async function emitWithVision(emit, session, cmdId, payload) {
     emit('orchestrator:browser-result', cmdId, payload);
 }
 /**
- * The session an identity used most recently (2026-10).
+ * Sessions an identity opened, most recent last (2026-10, multi-window 2026-11).
  *
  * An agent that opened a NAMED session and then calls browser_action without a
- * sessionId must keep driving that same browser, not silently jump back to its
- * default one. Cleared when the session is closed.
+ * sessionId keeps driving that same browser. With TWO or more live windows and
+ * no sessionId the command is AMBIGUOUS and refused — acting on "whichever was
+ * touched last" would drive the wrong Chrome. Pruned when sessions close.
  */
-const lastSessionByAgent = new Map();
-/** The identity key used by `lastSessionByAgent` and the fallback session. */
+const sessionsByAgent = new Map();
+function rememberSession(identityKey, sessionId) {
+    const list = sessionsByAgent.get(identityKey) ?? [];
+    const next = [...list.filter((id) => id !== sessionId), sessionId];
+    sessionsByAgent.set(identityKey, next.slice(-20));
+}
+function forgetSession(identityKey, sessionId) {
+    const list = sessionsByAgent.get(identityKey);
+    if (!list)
+        return;
+    const next = list.filter((id) => id !== sessionId);
+    if (next.length)
+        sessionsByAgent.set(identityKey, next);
+    else
+        sessionsByAgent.delete(identityKey);
+}
+/** The identity key used by `sessionsByAgent` and the fallback session. */
 function identityKeyOf(agentUserId) {
     const normalized = (0, session_pool_1.normalizeSessionKey)(agentUserId);
     return normalized ? `agent:${normalized}` : 'shared';
@@ -109,19 +174,49 @@ async function handleBrowserCommand(data, emit) {
         });
         return;
     }
-    // SESSION PER IDENTITY (2026-10, multi-browser): the old fixed 'default'
-    // made every agent on this PC share one Chrome. The key is now the explicit
-    // sessionId, else the caller's identity, with the last named session
-    // remembered so later actions stay on the browser they opened.
+    // SESSION PER IDENTITY (2026-10, multi-window 2026-11): the old fixed
+    // 'default' made every agent on this PC share one Chrome. The key is the
+    // explicit sessionId, else the caller's remembered windows. With two or more
+    // live windows and no sessionId the command is AMBIGUOUS and refused.
     const identityKey = identityKeyOf(agentUserId);
     const explicitSession = (0, session_pool_1.normalizeSessionKey)(data.sessionId);
-    const sessionId = explicitSession ??
-        (action === 'connect' ? undefined : lastSessionByAgent.get(identityKey)) ??
-        (0, session_pool_1.deriveSessionKey)(null, agentUserId);
+    const manager = (0, manager_1.getBrowserManager)();
+    const liveWindows = manager.list().map((id) => {
+        const s = manager.get(id);
+        return { id, actor: s?.actor ?? null };
+    });
+    const remembered = (sessionsByAgent.get(identityKey) ?? []).filter((id) => manager.get(id));
+    let sessionId;
+    if (explicitSession) {
+        sessionId = explicitSession;
+    }
+    else if (action === 'connect') {
+        sessionId = (0, session_pool_1.deriveSessionKey)(null, agentUserId);
+    }
+    else {
+        const resolved = (0, session_pool_1.resolveSessionForCommand)({
+            explicit: null,
+            remembered,
+            derived: (0, session_pool_1.deriveSessionKey)(null, agentUserId),
+            live: liveWindows,
+        });
+        if ('ambiguous' in resolved) {
+            const list = resolved.ambiguous
+                .map((w) => `${w.id}${w.actor ? ` (${w.actor})` : ''}`)
+                .join(', ');
+            emit('orchestrator:browser-result', String(data.cmdId ?? ''), {
+                success: false,
+                error: `BROWSER_SESSION_AMBIGUOUS: this agent has ${resolved.ambiguous.length} browser windows open ` +
+                    `(${list}). Pass sessionId on every browser_action — each test account has its own window.`,
+                sessions: resolved.ambiguous,
+            });
+            return;
+        }
+        sessionId = resolved.sessionId;
+    }
     if (explicitSession || action === 'connect') {
-        lastSessionByAgent.set(identityKey, sessionId);
+        rememberSession(identityKey, sessionId);
     }
-    const manager = (0, manager_1.getBrowserManager)();
     // Any command counts as activity, so the idle-close grace restarts.
     manager.touch(sessionId);
     log.info(`Browser command: ${action} (session: ${sessionId})`);
@@ -167,6 +262,29 @@ async function handleBrowserCommand(data, emit) {
                 // OPT-IN QA vision mode (default false, 2026-10): every mutating action
                 // returns a screenshot. Only the QA brief turns it on.
                 const qaVision = data.qaVision === true;
+                // One window per identity (2026-11): the caller names the account this
+                // window belongs to, and isolated forces a per-session profile so a QA
+                // window never inherits the human's shared debug profile.
+                const callActor = typeof data.actor === 'string' && data.actor.trim()
+                    ? data.actor.trim().slice(0, 80)
+                    : null;
+                const isolated = data.isolated === true;
+                // A tagged window never changes hands.
+                const tagged = manager.get(sessionId);
+                if (tagged?.actor && callActor) {
+                    const gate = (0, session_pool_1.assertActorForLogin)({
+                        sessionActor: tagged.actor,
+                        callActor,
+                    });
+                    if (gate) {
+                        emit('orchestrator:browser-result', data.cmdId, {
+                            success: false,
+                            error: gate.message,
+                            code: gate.code,
+                        });
+                        break;
+                    }
+                }
                 // REUSE only a LIVE session. A disconnected one may have lost its port
                 // and its profile to a concurrent browser while it was down, so it is
                 // re-allocated below instead of silently reconnecting onto them.
@@ -174,6 +292,7 @@ async function handleBrowserCommand(data, emit) {
                 if (existing?.connected) {
                     existing.setAllowCredentials(allowCredentials);
                     existing.setQaVision(qaVision);
+                    existing.setActor(callActor);
                     // reset:true drops a crashed run's leftovers (open modal, corrupted
                     // field values, stale validation errors) before the new run starts.
                     // A resumed run omits it and keeps its page.
@@ -193,6 +312,7 @@ async function handleBrowserCommand(data, emit) {
                         alreadyConnected: true,
                         sessionId,
                         port: existing.port,
+                        ...(existing.actor ? { actor: existing.actor } : {}),
                         qaVision: existing.qaVision,
                         ...pageState,
                         ...(screen ? { screen } : {}),
@@ -218,6 +338,7 @@ async function handleBrowserCommand(data, emit) {
                     sessionKey: sessionId,
                     usedDirs: manager.usedProfileDirs(sessionId),
                     ...(namedProfileDir ? { namedDir: namedProfileDir } : {}),
+                    ...(isolated ? { forceIsolated: true } : {}),
                 });
                 if (profile.conflict) {
                     emit('orchestrator:browser-result', data.cmdId, {
@@ -236,11 +357,13 @@ async function handleBrowserCommand(data, emit) {
                     profileDir: profile.dir,
                     allowCredentials,
                     qaVision,
+                    ...(callActor ? { actor: callActor } : {}),
                 });
                 // A reused session keeps its flag from a previous connect; honour the
                 // explicit value on every connect so the caller stays in control.
                 session.setAllowCredentials(allowCredentials);
                 session.setQaVision(qaVision);
+                session.setActor(callActor);
                 const info = await session.connect(port);
                 const actualPort = session.port;
                 log.info(`Browser session "${sessionId}" on port ${actualPort} ` +
@@ -254,6 +377,7 @@ async function handleBrowserCommand(data, emit) {
                     sessionId,
                     port: actualPort,
                     profile: profile.shared ? 'shared' : 'isolated',
+                    ...(callActor ? { actor: callActor } : {}),
                     qaVision: session.qaVision,
                     ...pageState,
                     ...(screen ? { screen } : {}),
@@ -265,7 +389,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -284,7 +409,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -296,12 +422,24 @@ async function handleBrowserCommand(data, emit) {
                     });
                     return;
                 }
+                // Capture the pre-navigation URL + time BEFORE navigating: the settle
+                // compares against these, so it can see an SPA route change and a full
+                // load alike.
+                const navFrom = await session
+                    .pageInfo()
+                    .then((info) => info.url ?? null)
+                    .catch(() => null);
+                const navSince = Date.now();
                 const info = await session.navigate(url);
                 const screen = await screenOf(session);
                 await emitWithVision(emit, session, data.cmdId, {
                     success: true,
                     ...info,
                     ...(screen ? { screen } : {}),
+                }, {
+                    since: navSince,
+                    ...(navFrom ? { fromUrl: navFrom } : {}),
+                    rescreen: () => screenOf(session),
                 });
                 break;
             }
@@ -310,7 +448,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -393,6 +532,7 @@ async function handleBrowserCommand(data, emit) {
                     }
                     clicked = { x, y };
                 }
+                const settleFrom = await settleContext(session);
                 const screen = await screenOf(session);
                 await emitWithVision(emit, session, data.cmdId, {
                     success: true,
@@ -401,6 +541,9 @@ async function handleBrowserCommand(data, emit) {
                     x: clicked.x,
                     y: clicked.y,
                     ...(screen ? { screen } : {}),
+                }, {
+                    ...settleFrom,
+                    rescreen: () => screenOf(session),
                 });
                 break;
             }
@@ -409,7 +552,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -448,6 +592,7 @@ async function handleBrowserCommand(data, emit) {
                     const observed = await session.type(text, {
                         clearFirst: data.clearFirst === true,
                     });
+                    const settleFrom = await settleContext(session);
                     const screen = await screenOf(session);
                     await emitWithVision(emit, session, data.cmdId, {
                         success: true,
@@ -455,6 +600,9 @@ async function handleBrowserCommand(data, emit) {
                         length: text.length,
                         observed,
                         ...(screen ? { screen } : {}),
+                    }, {
+                        ...settleFrom,
+                        rescreen: () => screenOf(session),
                     });
                 }
                 catch (err) {
@@ -472,10 +620,30 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
+                    });
+                    return;
+                }
+                // One window per identity (2026-11): a tagged window only signs in
+                // its own account. Never sign in as B in A's window.
+                const callActor = typeof data.actor === 'string' && data.actor.trim()
+                    ? data.actor.trim()
+                    : null;
+                const gate = (0, session_pool_1.assertActorForLogin)({
+                    sessionActor: session.actor,
+                    callActor,
+                });
+                if (gate) {
+                    emit('orchestrator:browser-result', data.cmdId, {
+                        success: false,
+                        error: gate.message,
+                        code: gate.code,
                     });
                     return;
                 }
+                if (callActor)
+                    session.setActor(callActor);
                 if (data.allowCredentials === true)
                     session.setAllowCredentials(true);
                 // Password is optional: an `email_otp` / OTP-only step sends the email
@@ -495,11 +663,15 @@ async function handleBrowserCommand(data, emit) {
                         : {}),
                 });
                 // Never echo the password: the payload carries booleans + an error code.
+                const settleFrom = await settleContext(session);
                 const screen = await screenOf(session);
                 await emitWithVision(emit, session, data.cmdId, {
                     success: true,
                     ...result,
                     ...(screen ? { screen } : {}),
+                }, {
+                    ...settleFrom,
+                    rescreen: () => screenOf(session),
                 });
                 break;
             }
@@ -508,7 +680,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -534,12 +707,21 @@ async function handleBrowserCommand(data, emit) {
                             : {}),
                         ...(data.clearFirst === false ? {} : {}),
                     });
+                    // An OTP submit navigates (2026-11): settle before reading, like
+                    // every other navigation-capable action, or the screen shows the
+                    // pre-submit form while the app is already on the next page.
+                    const settleFrom = await settleContext(session);
                     const screen = await screenOf(session);
                     await emitWithVision(emit, session, data.cmdId, {
                         success: result.ok,
-                        ...(result.ok ? {} : { error: result.error ?? 'OTP_FILL_FAILED' }),
+                        ...(result.ok
+                            ? {}
+                            : { error: result.error ?? 'OTP_FILL_FAILED' }),
                         ...result,
                         ...(screen ? { screen } : {}),
+                    }, {
+                        ...settleFrom,
+                        rescreen: () => screenOf(session),
                     });
                 }
                 catch (err) {
@@ -557,17 +739,22 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
                 const key = String(data.key ?? '');
+                const settleFrom = await settleContext(session);
                 await session.press(key);
                 const screen = await screenOf(session);
                 await emitWithVision(emit, session, data.cmdId, {
                     success: true,
                     pressed: key,
                     ...(screen ? { screen } : {}),
+                }, {
+                    ...settleFrom,
+                    rescreen: () => screenOf(session),
                 });
                 break;
             }
@@ -579,7 +766,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -633,7 +821,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -689,7 +878,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -704,16 +894,19 @@ async function handleBrowserCommand(data, emit) {
             }
             // 2026-10: the interactive-element ref list (`e1 … eN`), including
             // portalled menus/popovers/dialogs. Actions accept `ref`.
+            // 2026-11: `filter` narrows by substring over role + name + tag
+            // (`getRefs {filter:"button"}`); numbering is always full-scan.
             case 'getRefs': {
                 const session = manager.get(sessionId);
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
-                const refs = await session.getRefs();
+                const refs = await session.getRefs(typeof data.filter === 'string' ? data.filter : undefined);
                 let oneTimeCode;
                 try {
                     const snap = await session.snapshot({ refs: false });
@@ -741,7 +934,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -760,7 +954,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -773,12 +968,65 @@ async function handleBrowserCommand(data, emit) {
                 });
                 break;
             }
+            // 2026-11: set the viewport before a design-verification screenshot.
+            // The design's viewport IS the contract; the backend clamps to
+            // 320–8192 and the read-back reports what the page actually uses.
+            case 'setViewport': {
+                const session = manager.get(sessionId);
+                if (!session?.connected) {
+                    emit('orchestrator:browser-result', data.cmdId, {
+                        success: false,
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
+                    });
+                    return;
+                }
+                const width = typeof data.viewportWidth === 'number'
+                    ? data.viewportWidth
+                    : typeof data.width === 'number'
+                        ? data.width
+                        : NaN;
+                const height = typeof data.viewportHeight === 'number'
+                    ? data.viewportHeight
+                    : typeof data.height === 'number'
+                        ? data.height
+                        : NaN;
+                if (!Number.isFinite(width) || !Number.isFinite(height)) {
+                    emit('orchestrator:browser-result', data.cmdId, {
+                        success: false,
+                        error: 'setViewport needs viewportWidth + viewportHeight (320-8192).',
+                    });
+                    return;
+                }
+                try {
+                    const applied = await session.setViewport(width, height, typeof data.deviceScaleFactor === 'number'
+                        ? data.deviceScaleFactor
+                        : 1);
+                    const screen = await screenOf(session);
+                    await emitWithVision(emit, session, data.cmdId, {
+                        success: true,
+                        viewport: true,
+                        ...applied,
+                        ...(screen ? { screen } : {}),
+                    });
+                }
+                catch (err) {
+                    const screen = await screenOf(session);
+                    await emitWithVision(emit, session, data.cmdId, {
+                        success: false,
+                        error: err instanceof Error ? err.message : String(err),
+                        ...(screen ? { screen } : {}),
+                    });
+                }
+                break;
+            }
             case 'evaluate': {
                 const session = manager.get(sessionId);
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -795,7 +1043,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -812,7 +1061,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -831,7 +1081,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -871,7 +1122,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -929,7 +1181,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -951,7 +1204,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -961,11 +1215,15 @@ async function handleBrowserCommand(data, emit) {
                         ? { promptText: data.promptText }
                         : {}),
                 });
+                const settleFrom = await settleContext(session);
                 const screen = await screenOf(session);
                 await emitWithVision(emit, session, data.cmdId, {
                     success: result.ok,
                     ...result,
                     ...(screen ? { screen } : {}),
+                }, {
+                    ...settleFrom,
+                    rescreen: () => screenOf(session),
                 });
                 break;
             }
@@ -978,7 +1236,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1003,7 +1262,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1028,7 +1288,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1053,7 +1314,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1074,7 +1336,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session. Call browser_open first.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1106,7 +1369,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1123,7 +1387,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1140,7 +1405,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1161,7 +1427,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1204,7 +1471,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1245,7 +1513,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1281,7 +1550,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1314,7 +1584,8 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
@@ -1354,17 +1625,22 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
                 const result = await session.submit(typeof data.selector === 'string' ? data.selector : undefined);
+                const settleFrom = await settleContext(session);
                 await emitWithVision(emit, session, data.cmdId, {
                     success: result?.ok === true,
                     submitted: result?.ok === true,
                     ...(result?.ok
                         ? {}
                         : { error: result?.error ?? 'the form could not be submitted' }),
+                }, {
+                    ...settleFrom,
+                    rescreen: () => screenOf(session),
                 });
                 break;
             }
@@ -1377,18 +1653,30 @@ async function handleBrowserCommand(data, emit) {
                 if (!session?.connected) {
                     emit('orchestrator:browser-result', data.cmdId, {
                         success: false,
-                        error: 'No active browser session.',
+                        error: `No active browser session "${sessionId}". ` +
+                            `Call browser_open({ sessionId: "${sessionId}" }) first.`,
                     });
                     return;
                 }
                 const steps = data.actions;
-                const summary = await (0, batch_1.executeBatch)(session, steps ?? []);
+                // One window per identity (2026-11): the batch carries ONE session, so
+                // a top-level `actor` applies to every step that does not name its own.
+                // Without this, a batched login could not be attributed (or gated).
+                const batchActor = typeof data.actor === 'string' && data.actor.trim()
+                    ? data.actor.trim()
+                    : null;
+                const resolvedSteps = (steps ?? []).map((step) => batchActor && !step.actor ? { ...step, actor: batchActor } : step);
+                const settleFrom = await settleContext(session);
+                const summary = await (0, batch_1.executeBatch)(session, resolvedSteps);
                 const screen = await screenOf(session);
                 await emitWithVision(emit, session, data.cmdId, {
                     success: true,
                     batch: true,
                     ...summary,
                     ...(screen ? { screen } : {}),
+                }, {
+                    ...settleFrom,
+                    rescreen: () => screenOf(session),
                 });
                 break;
             }
@@ -1403,9 +1691,7 @@ async function handleBrowserCommand(data, emit) {
                 // never claims a termination that did not happen (the pre-check flag
                 // could say `true` while the kill silently failed).
                 const terminated = await manager.close(sessionId);
-                if (lastSessionByAgent.get(identityKey) === sessionId) {
-                    lastSessionByAgent.delete(identityKey);
-                }
+                forgetSession(identityKey, sessionId);
                 emit('orchestrator:browser-result', data.cmdId, {
                     success: true,
                     closed: true,