flowviant 0.125.28 → 0.125.30

package/bin/lib/managedBrowser.mjs

@@ -40,6 +40,8 @@ export function browserAction(input) {
 }
 
 const TOOLS = [
+  { name: 'handoff', description: 'Keep this browser open while a person signs in or tries the app. Call before asking for human input. The daemon waits without model polling and resumes this turn after control is returned or the handoff expires.', inputSchema: { type: 'object', additionalProperties: false,
+    properties: { kind: { type: 'string', enum: ['signin', 'control'] }, reason: { type: 'string', minLength: 1, maxLength: 300 } }, required: ['kind', 'reason'] } },
   { name: 'open', description: 'Open the shared managed browser on a dev-server port measured in this worktree. Start the dev server first. Requires disposable test fixtures. Returns the actual page as native image input.', inputSchema: { type: 'object', additionalProperties: false,
     properties: { port: { type: 'integer', minimum: 1, maximum: 65535 }, hostname: { type: 'string', enum: ['localhost'], description: 'Use localhost when the app’s configured authentication callback or cookies require that hostname instead of the measured loopback IP.' }, scheme: { type: 'string', enum: ['http', 'https'], description: 'Match the dev server protocol. HTTPS uses normal browser certificate validation.' }, path: { type: 'string' }, fixture: { type: 'string', description: 'Describe the disposable test data/account and why these interactions are safe.' } }, required: ['port', 'fixture'] } },
   { name: 'act', description: 'Interact with the SAME browser shown in Flowviant. Snapshot returns page text, controls, console/network errors and a screenshot. User control pauses agent actions; continue other work until returned.', inputSchema: { type: 'object', additionalProperties: false,
@@ -58,7 +60,7 @@ export function managedPreviewOrigin(wt, port, hostname, scheme = 'http') {
 }
 
 export async function createManagedBrowser({ wt, turnId, signal, onChild, openPage = openManagedPage,
-  measuredOrigin = managedPreviewOrigin, connect = url => new WebSocket(url, {
+  measuredOrigin = managedPreviewOrigin, handoffTimeoutMs = 10 * 60_000, connect = url => new WebSocket(url, {
     headers: { ...fleetHeaders({ json: false }), 'X-Flowviant-Instance': DAEMON_INSTANCE },
     handshakeTimeout: 10_000, maxPayload: 16_384,
   }) }) {
@@ -68,11 +70,40 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
   let lastRxAt = 0;
   let captures = 0;
   let observationEpoch = 0, pageEpoch = 0;
+  let pageOrigin = null, pageMeasured = null, pageScope = null, statusPending = false, statusRetry = null;
+  let handoff = null, handoffResult = null;
+  let transportStarted = false;
   const controller = new AbortController();
-  const send = message => { if (ws?.readyState === 1 && ws.bufferedAmount < 1_200_000) ws.send(JSON.stringify(message)); };
-  const change = patch => { status = { ...status, ...patch }; send(status.private ? { ...status, path: '/', error: undefined } : status); };
-  const frame = message => { if (closed || stopped) return; lastFrame = message; send(message); };
-  const release = () => { pageEpoch++; observationEpoch++; page?.close(); page = null; lastFrame = null; };
+  const send = message => {
+    if (ws?.readyState !== 1 || ws.bufferedAmount >= 1_200_000) return false;
+    ws.send(JSON.stringify(message)); return true;
+  };
+  const flushStatus = () => {
+    if (!statusPending) return;
+    if (send(status.private ? { ...status, path: '/', error: undefined } : status)) {
+      statusPending = false; clearTimeout(statusRetry); statusRetry = null;
+    } else if (!closed && ws?.readyState === 1 && !statusRetry) {
+      statusRetry = setTimeout(() => { statusRetry = null; flushStatus(); }, 100);
+    }
+  };
+  const change = patch => { status = { ...status, ...patch }; statusPending = true; flushStatus(); };
+  const frame = message => { if (closed || stopped) return; lastFrame = message; flushStatus(); if (!statusPending) send(message); };
+  const release = () => { pageEpoch++; observationEpoch++; page?.close(); page = null; pageOrigin = null; pageMeasured = null; pageScope = null; lastFrame = null; };
+  const endHandoff = reason => {
+    if (!handoff) return;
+    const active = handoff; handoff = null; clearTimeout(active.timer);
+    handoffResult = { reason }; active.resolve(handoffResult);
+  };
+  const beginHandoff = () => {
+    if (handoff) return;
+    let resolve;
+    const promise = new Promise(done => { resolve = done; });
+    const timer = setTimeout(() => {
+      endHandoff('expired'); stopped = true; controller.abort(); release();
+      change({ state: 'ended', mode: 'agent', private: false, handoff: undefined, error: 'The browser handoff expired. Run the app again to start a new session.' });
+    }, handoffTimeoutMs);
+    handoff = { promise, resolve, timer }; handoffResult = null;
+  };
   const observe = async (retain = false) => {
     const epoch = observationEpoch;
     if (status.mode === 'user') throw new Error('A person has control. Browser observations are paused until control is returned.');
@@ -91,38 +122,89 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
     }
     return { content: [text({ page: shot.observation, diagnostics: shot.diagnostics, path: status.path, pendingOrigins: status.pendingOrigins, networkError: status.networkError, ...(artifact ? { artifact } : {}) }), { type: 'image', data: shot.data, mimeType: 'image/jpeg' }] };
   };
-  const call = async (name, input) => {
+  const requireModelControl = () => {
     if (closed || signal?.aborted) throw new Error('This browser turn has ended.');
     if (stopped) throw new Error('A person stopped the browser for this turn.');
+    if (status.handoff && name !== 'handoff') throw new Error('The browser is waiting for a person. Continue other work or finish this invocation; the daemon will resume after the handoff.');
     if (status.mode === 'user') throw new Error('A person has control of the shared browser. Continue other work and retry after they return control.');
     if (busy) throw new Error('A browser action is already running.');
+  };
+  const call = async (name, input, scope = wt) => {
+    requireModelControl();
     busy = true;
+    let openingNew = false;
     try {
-      if (name === 'open') {
+      if (name === 'handoff') {
+        if (status.protocol !== 2) throw new Error('Update the app and daemon to use browser handoff.');
+        if (!page || status.state !== 'live') throw new Error('Open the managed browser before requesting handoff.');
+        if (!['signin', 'control'].includes(input.kind) || typeof input.reason !== 'string' || !input.reason.trim() || input.reason.length > 300) throw new Error('Supply a handoff kind and a short reason.');
+        beginHandoff(); change({ handoff: { kind: input.kind, reason: input.reason.trim() } });
+        return { content: [text({ waiting: input.kind, reason: input.reason.trim(), instruction: 'Ask the person to take control in the Live app frame. Do other work or return your current result; the daemon holds this turn and resumes it after the handoff.' })] };
+      } else if (name === 'open') {
         const path = browserPath(input.path ?? '/');
         if (typeof input.fixture !== 'string' || input.fixture.trim().length < 12 || input.fixture.length > 2000) throw new Error('Describe the disposable test fixtures before opening the browser.');
         if (input.hostname != null && input.hostname !== 'localhost') throw new Error('The optional preview hostname must be localhost.');
-        const measured = measuredOrigin(wt, input.port, undefined, input.scheme);
+        const measured = measuredOrigin(scope, input.port, undefined, input.scheme);
         const upstreamUrl = new URL(measured);
         const connectHost = upstreamUrl.hostname === '[::1]' ? '::1' : upstreamUrl.hostname;
         if (input.hostname === 'localhost') upstreamUrl.hostname = 'localhost';
         const upstream = upstreamUrl.origin;
-        release(); change({ state: 'starting', error: undefined, networkError: undefined, pendingOrigins: [], path });
-        const opening = pageEpoch;
-        page = await openPage({ origin: upstream, connectHost: input.hostname === 'localhost' ? connectHost : undefined, signal: controller.signal, stillOwned: () => {
-          try { return measuredOrigin(wt, input.port, undefined, input.scheme) === measured; } catch { return false; }
-        }, onFrame: message => { if (opening === pageEpoch) frame(message); },
-          onChange: patch => { if (opening === pageEpoch && !closed && !stopped) change(patch.error ? { ...patch, state: 'error' } : patch); }, onChild });
-        if (opening !== pageEpoch || closed || stopped) { page.close(); page = null; throw new Error('The browser turn has ended.'); }
+        if (!transportStarted) { transportStarted = true; openSocket(); }
+        if (!page || status.state !== 'live' || pageOrigin !== upstream || pageMeasured !== measured || pageScope !== scope) {
+          openingNew = true;
+          release(); change({ state: 'starting', surface: 'browser', target: undefined, error: undefined, networkError: undefined, pendingOrigins: [], path });
+          const opening = pageEpoch;
+          page = await openPage({ origin: upstream, connectHost: input.hostname === 'localhost' ? connectHost : undefined, signal: controller.signal, stillOwned: () => {
+            try { return measuredOrigin(scope, input.port, undefined, input.scheme) === measured; } catch { return false; }
+          }, onFrame: message => { if (opening === pageEpoch) frame(message); },
+            onChange: patch => { if (opening === pageEpoch && !closed && !stopped) change(patch.error ? { ...patch, state: 'error' } : patch); }, onChild });
+          if (opening !== pageEpoch || closed || stopped) { page.close(); page = null; throw new Error('The browser turn has ended.'); }
+          pageOrigin = upstream; pageMeasured = measured; pageScope = scope;
+        }
         await page.act({ type: 'navigate', path });
         change({ state: 'live' });
       } else {
         if (!page || status.state !== 'live') throw new Error('Open the managed browser first.');
         await page.act(browserAction(input));
       }
-      return await observe(name === 'act' && input.type === 'snapshot');
+      const result = await observe(name === 'act' && input.type === 'snapshot');
+      if (!handoff) handoffResult = null;
+      return result;
+    } catch (error) {
+      if (openingNew && status.mode !== 'user') { release(); if (!stopped && !closed) change({ state: 'error', error: reviewDiagnostic(error.message) }); }
+      throw error;
+    } finally { busy = false; }
+  };
+  /** Runtime adapters share this transport, ownership and private handoff.
+   * The factory is daemon-owned; no raw desktop/debugging API crosses the relay. */
+  const openSurface = async ({ key, target, surface, open }) => {
+    requireModelControl();
+    if (!['desktop', 'engine'].includes(surface) || typeof key !== 'string' || key.length > 300 || !/^[A-Za-z0-9_-]{1,60}$/.test(target)) throw new Error('Invalid runtime surface.');
+    busy = true;
+    try {
+      if (!transportStarted) { transportStarted = true; openSocket(); }
+      if (!page || status.state !== 'live' || pageOrigin !== key) {
+        release(); change({ state: 'starting', surface, target, path: '/', error: undefined, networkError: undefined, pendingOrigins: [] });
+        const opening = pageEpoch;
+        const opened = await open({ signal: controller.signal, onChild,
+          onFrame: message => { if (opening === pageEpoch) frame(message); },
+          onChange: patch => {
+            if (opening !== pageEpoch || closed || stopped) return;
+            if (patch.ended) {
+              release(); change({ state: 'ended', mode: 'agent', private: false, handoff: undefined, error: undefined }); endHandoff('returned');
+            } else if (patch.error) change({ state: 'error', error: reviewDiagnostic(patch.error) });
+          } });
+        if (opening !== pageEpoch || closed || stopped) { opened.close(); throw new Error('The interactive turn has ended.'); }
+        page = opened; pageOrigin = key;
+        if (status.mode === 'user') beginHandoff();
+        if (status.private) await page.setPrivate(true);
+      }
+      change({ state: 'live' });
+      return await observe();
     } catch (error) {
-      if (name === 'open' && status.mode !== 'user') { release(); if (!stopped && !closed) change({ state: 'error', error: reviewDiagnostic(error.message) }); }
+      // Taking control while startup is finishing fences this model result;
+      // the newly opened app still belongs to the person holding the frame.
+      if (status.mode !== 'user') { release(); if (!closed && !stopped) change({ state: 'error', error: reviewDiagnostic(error.message) }); }
       throw error;
     } finally { busy = false; }
   };
@@ -133,10 +215,11 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
       observationEpoch++;
       if (Number.isSafeInteger(msg.controlId) && msg.controlId >= 0) status.controlId = msg.controlId;
     }
-    if (msg.action === 'take') { change({ mode: 'user' }); return; }
+    if (msg.action === 'take') { if (!stopped && page) beginHandoff(); change({ mode: 'user' }); return; }
     if (msg.action === 'signin') {
       if (status.protocol !== 2) throw new Error('Update the app and daemon to use private sign-in.');
       const epoch = observationEpoch;
+      if (!stopped && page) beginHandoff();
       status = { ...status, mode: 'user', private: true }; lastFrame = null;
       await page?.setPrivate?.(true);
       if (epoch === observationEpoch && !closed && !stopped) change({});
@@ -146,10 +229,10 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
       const epoch = observationEpoch;
       lastFrame = null;
       await page?.setPrivate?.(false);
-      if (epoch === observationEpoch && !closed && !stopped) change({ mode: 'agent', private: false });
+      if (epoch === observationEpoch && !closed && !stopped) { change({ mode: 'agent', private: false, handoff: undefined }); endHandoff('returned'); }
       return;
     }
-    if (msg.action === 'stop') { stopped = true; controller.abort(); release(); change({ state: 'ended', mode: 'agent', private: false, error: undefined }); return; }
+    if (msg.action === 'stop') { endHandoff('stopped'); stopped = true; controller.abort(); release(); change({ state: 'ended', mode: 'agent', private: false, handoff: undefined, error: undefined }); return; }
     if (status.mode !== 'user') throw new Error('Take control before interacting with the browser.');
     if (busy) throw new Error('The preceding browser action is still finishing.');
     if (!page || status.state !== 'live') throw new Error('The browser is not open.');
@@ -173,13 +256,14 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
     if (closed) return;
     try { ws = connect(FLEET_URL.replace(/\/agents\/?$/, `/managed-browser/${encodeURIComponent(turnId)}`).replace(/^http/, 'ws')); }
     catch { reconnect = setTimeout(openSocket, 3000); return; }
-    ws.on('open', () => {
-      lastRxAt = Date.now(); send(status); if (lastFrame) send(lastFrame);
+    const connected = () => {
+      lastRxAt = Date.now(); change({}); if (lastFrame && !statusPending) send(lastFrame);
       ping = setInterval(() => {
         if (Date.now() - lastRxAt > 45_000) { ws.terminate(); return; }
-        send({ type: 'heartbeat' });
+        flushStatus(); send({ type: 'heartbeat' });
       }, 15_000);
-    });
+    };
+    ws.on('open', connected);
     ws.on('message', data => {
       lastRxAt = Date.now();
       let msg; try { msg = JSON.parse(data.toString()); } catch { return; }
@@ -188,7 +272,13 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
       void control(msg).catch(error => { if (!closed && !stopped) send({ type: 'notice', message: reviewDiagnostic(error.message) }); });
     });
     ws.on('error', () => {});
-    ws.on('close', code => { clearInterval(ping); if (!status.private) status = { ...status, mode: 'agent' }; if (!closed && code !== 1008) reconnect = setTimeout(openSocket, 3000); });
+    ws.on('close', code => {
+      clearInterval(ping); clearTimeout(statusRetry); statusRetry = null; statusPending = true;
+      if (!status.private && status.mode === 'user') { status = { ...status, mode: 'agent', handoff: undefined }; endHandoff('returned'); }
+      if (!closed && code !== 1008) reconnect = setTimeout(openSocket, 3000);
+    });
+    // Test transports and already-open local adapters can connect immediately.
+    if (ws.readyState === 1) connected();
   };
   const held = await listenHeldTool({ envPrefix: 'FLOWVIANT_BROWSER', verb: '__managed-browser-mcp', requestTimeoutMs: 35_000,
     isClosed: () => closed, respond: async (req, res) => {
@@ -200,20 +290,32 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
         res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify(result));
       } catch (error) { res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify({ isError: true, content: [text(reviewDiagnostic(error.message))] })); }
     } });
-  learnExtraSecrets([held.capability]);
+  const secretKey = `browser:${held.capability.slice(0, 12)}`;
+  learnExtraSecrets(secretKey, [{ name: 'FLOWVIANT_BROWSER_CAPABILITY', value: held.capability }]);
   const close = async () => {
     if (closed) return;
     closed = true; signal?.removeEventListener('abort', abort);
-    clearTimeout(reconnect); clearInterval(ping);
+    clearTimeout(reconnect); clearInterval(ping); clearTimeout(statusRetry); statusRetry = null; endHandoff('closed');
     controller.abort(); release(); change({ state: 'ended', mode: 'agent' });
     ws?.close(1000); held.server.close(); held.server.closeAllConnections();
-    forgetExtraSecrets([held.capability]);
+    forgetExtraSecrets(secretKey);
   };
   const abort = () => { void close(); };
   signal?.addEventListener('abort', abort, { once: true });
-  if (signal?.aborted) await close(); else openSocket();
+  if (signal?.aborted) await close();
   return { env: held.env, config: { command: process.execPath, args: held.args, env: held.env }, close,
-    instructions: 'Use card_browser.open and card_browser.act for interactive browser work. Both CLIs use this same Flowviant-managed browser, visible live to the project. Start the repository-supported dev server in this worktree first; open its measured port with disposable fixtures. Match the app’s configured auth callback hostname: pass hostname localhost to open when its callback/cookies use localhost rather than 127.0.0.1. Use a disposable test account when provided. If login, MFA or SSO needs a person, ask them to use Sign in privately in the Live app frame; never ask for passwords or one-time codes in chat. Human control pauses browser actions and observations. Do other work while waiting; do not end the turn while the person is signing in, since ending closes this browser. Additional HTTP(S) origins require a person to approve the actual requested origin in the frame and retry. You cannot approve network access through tools. Popups, frames, workers, sockets and downloads are blocked; use same-tab sign-in and report unsupported passkey, client-certificate or popup flows. Network access is that of the daemon machine, including its VPN/DNS/certificates; do not claim a VPN is connected from a timeout. Report observed failures, ask the person to connect that machine if needed, and retry after they confirm. Do not open an independent browser or publish a preview to bypass access. Screenshots are native image input: inspect them and report actual observations, errors and skipped checks. Call act with type snapshot before finishing to retain a screenshot as a task artifact. Interactions do not establish a passing test or final-source verification; use the local UI review helper for retained scenario evidence.' };
+    open: (input, scope = wt) => call('open', input, scope), act: input => call('act', input), handoff: input => call('handoff', input), openSurface,
+    assertControl: requireModelControl,
+    stopSurface() { requireModelControl(); release(); change({ state: 'ended', mode: 'agent', private: false, handoff: undefined }); },
+    async waitForHandoff() {
+      for (;;) {
+        const result = handoff ? await handoff.promise : handoffResult;
+        if (handoff) continue;
+        if (handoffResult === result) handoffResult = null;
+        return result;
+      }
+    },
+    instructions: 'Use card_browser.open and card_browser.act for interactive browser work. Both CLIs use this same Flowviant-managed browser, visible live to the project. Start the repository-supported dev server in this worktree first; open its measured port with disposable fixtures. Match the app’s configured auth callback hostname: pass hostname localhost to open when its callback/cookies use localhost rather than 127.0.0.1. Use a disposable test account when provided. If login, MFA or SSO needs a person, call card_browser.handoff with kind signin and a short reason BEFORE asking them to use Sign in privately in the Live app frame; never ask for passwords or one-time codes in chat. For human testing use handoff kind control. Human control pauses browser actions and observations. After requesting handoff, do other work or return your current result; the daemon keeps this turn and browser open without model polling for up to ten minutes, then resumes the same conversation after return, stop or expiry. Repeated open calls on the same measured origin preserve login and origin approvals; another origin gets a fresh profile. Additional HTTP(S) origins require a person to approve the actual requested origin in the frame and retry. You cannot approve network access through tools. Popups, frames, workers, sockets and downloads are blocked; use same-tab sign-in and report unsupported passkey, client-certificate or popup flows. Network access is that of the daemon machine, including its VPN/DNS/certificates; do not claim a VPN is connected from a timeout. Report observed failures, ask the person to connect that machine if needed, and retry after they confirm. Do not open an independent browser or publish a preview to bypass access. Screenshots are native image input: inspect them and report actual observations, errors and skipped checks. Call act with type snapshot before finishing to retain a screenshot as a task artifact. Interactions do not establish a passing test or final-source verification; use the local UI review helper for retained scenario evidence.' };
 }
 
 export async function managedBrowserMain() {

package/bin/lib/managedBrowserPage.mjs

@@ -15,7 +15,7 @@ import { createBrowserNetwork, MANAGED_BROWSER_CSP } from './managedBrowserNetwo
 const SNAPSHOT = `JSON.stringify({title:document.title,path:location.pathname,
   text:document.body?.innerText.slice(0,12000),controls:Array.from(document.querySelectorAll('a,button,input,textarea,select,[role="button"]')).slice(0,100).map(e=>({tag:e.tagName,id:e.id,name:e.getAttribute('name'),type:e.getAttribute('type'),text:(e.innerText||e.getAttribute('aria-label')||e.getAttribute('placeholder')||'').slice(0,160)}))})`;
 
-export async function openManagedPage({ origin, connectHost, stillOwned, signal, onFrame = () => {}, onChange = () => {}, onChild = () => () => {}, browser = resolveBrowser() }) {
+export async function openManagedPage({ origin, connectHost, stillOwned, signal, onFrame = () => {}, onChange = () => {}, onChild = () => () => {}, browser = resolveBrowser(), navigationTimeoutMs = 15_000 }) {
   if (!browser) throw new Error('No Chrome/Chromium/Edge found on this machine.');
   if (browser.viaWindows) throw new Error('A Windows browser reached through WSL cannot carry the scoped DevTools pipe.');
   if (signal?.aborted) throw new Error('The browser turn has ended.');
@@ -34,24 +34,29 @@ export async function openManagedPage({ origin, connectHost, stillOwned, signal,
   let streamActive = true, streamEpoch = 0, streamQueue = Promise.resolve();
   const screencast = { format: 'jpeg', quality: 65, maxWidth: 1440, maxHeight: 900, everyNthFrame: 1 };
   const note = text => { if (privateInput) return; diagnostics.push(reviewDiagnostic(text)); if (diagnostics.length > 40) diagnostics.shift(); };
-  const close = () => {
+  const close = reason => {
     if (closed) return;
     closed = true;
     clearTimeout(frameTimer);
     socketDeny.close();
     signal?.removeEventListener('abort', close);
-    cdp?.close('Managed browser closed.');
+    cdp?.close(typeof reason === 'string' ? reason : 'Managed browser closed.');
     if (child) killGroup(child);
     untrack?.();
     // Reap only after Chromium exits; Windows cannot unlink an open profile.
     if (child && child.exitCode == null && child.signalCode == null) child.once('close', () => rmSync(home, { recursive: true, force: true }));
     else rmSync(home, { recursive: true, force: true });
   };
+  const fail = reason => { if (!closed) { onChange({ error: reviewDiagnostic(reason) }); close(reason); } };
   signal?.addEventListener('abort', close, { once: true });
   const raw = (method, params = {}, session) => {
     let timer;
     return Promise.race([cdp.send(method, params, session), new Promise((_, reject) => {
-      timer = setTimeout(() => { close(); reject(new Error('The managed browser did not answer within 15 seconds.')); }, 15_000);
+      const timeoutMs = method === 'Page.navigate' ? navigationTimeoutMs : 15_000;
+      timer = setTimeout(() => {
+        const reason = `The managed browser did not answer within ${timeoutMs / 1000} seconds.`;
+        fail(reason); reject(new Error(reason));
+      }, timeoutMs);
     })]).finally(() => clearTimeout(timer));
   };
   const send = (method, params) => raw(method, params, sessionId);
@@ -73,8 +78,8 @@ export async function openManagedPage({ origin, connectHost, stillOwned, signal,
     if (!child.stdio?.[3] || !child.stdio?.[4]) throw new Error('No DevTools pipe is available.');
     cdp = createCdpClient(child.stdio[3], child.stdio[4], { maxMessageBytes: 8 * 1024 * 1024 });
     child.stderr.on('data', data => note(data.toString()));
-    child.on('error', error => { cdp.close(error.message); onChange({ error: reviewDiagnostic(error.message) }); });
-    child.on('exit', () => { cdp.close('Chromium exited.'); if (!closed) onChange({ error: 'The managed browser exited.' }); });
+    child.on('error', error => fail(error.message));
+    child.on('exit', () => fail('The managed browser exited.'));
     for (const pipe of [child.stdio[3], child.stdio[4]]) pipe.on('error', () => {});
     let lastFrame = 0;
     cdp.on(msg => {
@@ -95,7 +100,7 @@ export async function openManagedPage({ origin, connectHost, stillOwned, signal,
               responsePhrase: p.responseStatusText ?? '', responseHeaders: [...(p.responseHeaders ?? []), { name: 'Content-Security-Policy', value: MANAGED_BROWSER_CSP }] });
           } else await send('Fetch.continueRequest', { requestId: p.requestId });
         })().catch(error => {
-          note(error.message); onChange({ error: 'Browser network policy could not be applied.' }); close();
+          note(error.message); fail('Browser network policy could not be applied.');
         });
       }
       if (msg.method === 'Page.screencastFrame') {

package/bin/lib/mergeBatch.mjs

@@ -65,7 +65,7 @@ export async function integrateMergeBatch({ spec, progress = {}, previousError,
   await report(states);
   for (const r of rows) {
     const stamp = resolve(r.wt, git(['rev-parse', '--git-path', 'flowviant-batch-setup'], r.wt));
-    if (!existsSync(stamp)) { await setup(r.repoRoot, r.wt); writeFileSync(stamp, 'ready'); }
+    if (!existsSync(stamp)) { await setup(r.repoRoot, r.wt, { baseRef: r.baseRef }); writeFileSync(stamp, 'ready'); }
   }
   const worktrees = rows.map((r) => ({ wt: r.wt, branch: r.branch, repoRoot: r.repoRoot }));
   if (spec.prMode && pr.ghReady()) throw new Error('This project merges through pull requests. GitHub CLI is not installed or signed in on this machine.');

package/bin/lib/noWindowEnv.mjs

@@ -67,8 +67,10 @@ export function withoutWindows(env, browserHome = null) {
 /**
  * EVERY CLI CHILD THE DAEMON SPAWNS UNATTENDED, ONE RULE (2026-10-10, the
  * audit): no machine credential (machineEnv.mjs), and no way to a window
- * unless a person at the keyboard asked for one (`display: true`, a Terminal
- * tab's alone). It was composed by hand twice — a turn's `cliEnv`
+ * unless a person at the keyboard asked for one (a Terminal tab), or the
+ * runtime-review daemon leaf supplied its own private X display/authority.
+ * `display: true` is never used to inherit a personal display on a code-agent
+ * CLI. It was composed by hand twice — a turn's `cliEnv`
  * (runTurn.mjs) and the project check's `checkEnv` (workAgentCheck.mjs) — and
  * skipped outright by the two spawns the daemon makes for its own purposes:
  * the startup skills probe (runtimeCapabilities.mjs), whose `claude` started

package/bin/lib/projectToolRuntimes.mjs

@@ -80,6 +80,7 @@ function codexServerTables(servers) {
   let out = '';
   for (const [name, server] of Object.entries(servers ?? {})) {
     out += `\n[mcp_servers.${name}]\n`;
+    if (Number.isInteger(server.toolTimeoutSec) && server.toolTimeoutSec > 0) out += `tool_timeout_sec = ${server.toolTimeoutSec}\n`;
     const approve = 'default_tools_approval_mode = "approve"\n';
     if (typeof server.command === 'string') {
       out += `command = ${toml(server.command)}\nargs = [${(server.args ?? []).map(toml).join(', ')}]\n${approve}`;
@@ -282,7 +283,8 @@ function reviewedClaudePlugin(dir, snapshot) {
  * turn)` returns the runner-specific part of prepareAgentTools' result — under
  * `dir`, which dies with the turn, except what `turn.codexHome` names a
  * lasting place for. `turn.mcpServers` is the base branch's servers this
- * runtime takes, expanded; `turn.fenced` a posture that reads no config file
+ * runtime takes, expanded; `turn.turnServers` retains daemon-owned metadata
+ * omitted from Claude's file; `turn.fenced` a posture that reads no config file
  * of the runner's own.
  */
 const TOOL_RUNTIMES = {
@@ -301,7 +303,7 @@ const TOOL_RUNTIMES = {
     // dies with the turn, as every home did before. A fenced turn ignores the
     // home's config.toml, so no server is written into it (2026-10-17).
     prepare: (dir, _snapshot, env, worktree, turn) => {
-      const isolated = isolatedCodexHome(turn?.codexHome ?? join(dir, 'codex-home'), env, worktree, turn?.fenced ? {} : turn?.mcpServers);
+      const isolated = isolatedCodexHome(turn?.codexHome ?? join(dir, 'codex-home'), env, worktree, turn?.fenced ? {} : { ...turn?.mcpServers, ...turn?.turnServers });
       return { codexHome: isolated.path, personalDeveloperInstructions: isolated.personalDeveloperInstructions, codexApprovals: turn?.fenced ? [] : isolated.approvals, codexMachineServers: turn?.fenced ? null : isolated.machineServers };
     },
     // A fenced posture ignores that home's config.toml (2026-10-10).

package/bin/lib/projectTools.mjs

@@ -220,7 +220,7 @@ export function prepareAgentTools(snapshot, runner, callerEnv = process.env, wor
     }
   }
   // Daemon-owned names cannot be replaced by project config. A turn server's
-  // `toolTimeoutSec` is the Codex mount's alone (codexFencedMount.mjs); it is
+  // `toolTimeoutSec` belongs to Codex's config.toml or fenced mount; it is
   // no key of Claude's mcp.json.
   for (const [name, { toolTimeoutSec: _codexOnly, ...config }] of Object.entries(turnServers)) mcpServers[name] = config;
   const mcpPath = join(dir, 'mcp.json');
@@ -238,7 +238,7 @@ export function prepareAgentTools(snapshot, runner, callerEnv = process.env, wor
   ].filter(Boolean).join('\n\n');
   let prepared;
   try {
-    prepared = prepareForRunner(runner, dir, snapshot, env, worktree, { codexHome: keptCodexHome, mcpServers, fenced });
+    prepared = prepareForRunner(runner, dir, snapshot, env, worktree, { codexHome: keptCodexHome, mcpServers, turnServers, fenced });
   } catch (error) {
     rmSync(dir, { recursive: true, force: true });
     throw error;

package/bin/lib/repositoryPlaces.mjs

@@ -137,7 +137,7 @@ export function createRepositoryPlaces({ repoRoot, baseDir, repositories, setup
       const repo = catalog.find((r) => r.id === item.id);
       if (!repo?.repoRoot) throw new Error(`Repository ${item.name} is not checked out on this machine.`);
       setupOptions.signal?.throwIfAborted();
-      await setup(repo.repoRoot, join(home, item.folder), setupOptions);
+      await setup(repo.repoRoot, join(home, item.folder), { ...setupOptions, baseRef: repo.baseRef });
       item.setup = true;
       save(home, state);
     }

package/bin/lib/repositorySetup.mjs

@@ -2,15 +2,25 @@
  * A checked-in .flowviant/setup.sh replaces the default dependency install. */
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { spawn } from 'node:child_process';
-import { killGroup } from './processGroup.mjs';
 import { git } from './git.mjs';
-import { unattendedEnv } from './noWindowEnv.mjs';
 import { workLanesStopped } from './standDownGate.mjs';
+import { environmentCommand } from './environmentProcess.mjs';
+import { readEnvironmentRecipe } from './reviewEnvironmentConfig.mjs';
+import { prepareWorktreeEnvironment } from './reviewEnvironment.mjs';
 
-export async function setupRepository(root, wt, { signal, onSpawn = () => {}, onClose = () => {} } = {}) {
+export async function setupRepository(root, wt, { signal, onSpawn = () => {}, onClose = () => {}, baseRef = 'HEAD', snapshot = readEnvironmentRecipe(root, baseRef) } = {}) {
   signal?.throwIfAborted();
   if (workLanesStopped()) throw new Error('The daemon is stopping. Repository setup has not started.');
+  const command = existsSync(join(wt, '.flowviant/setup.sh')) ? ['sh', '.flowviant/setup.sh'] :
+    ['bun.lock', 'bun.lockb'].some((f) => existsSync(join(wt, f))) ? ['bun', 'install', '--frozen-lockfile'] :
+    existsSync(join(wt, 'pnpm-lock.yaml')) ? ['pnpm', 'install', '--frozen-lockfile'] :
+    existsSync(join(wt, 'package-lock.json')) ? ['npm', 'ci'] :
+    existsSync(join(wt, 'yarn.lock')) ? ['yarn', 'install', '--frozen-lockfile'] : null;
+  const options = { signal, onSpawn, onClose };
+  // An explicit recipe replaces blind environment copying. Allocate first so
+  // even an install/setup hook receives the worktree's scoped database.
+  if (snapshot) return prepareWorktreeEnvironment(root, wt, { ...options, snapshot,
+    install: command ? env => environmentCommand(command, { ...options, cwd: wt, env, label: 'Repository setup', captureOutput: false, includeDiagnostics: true }) : null });
   const copyEnv = (relative = '') => {
     for (const name of readdirSync(join(root, relative))) {
       if (['.git', 'node_modules', '.flowviant', 'dist', 'target', '.next', '.cache', '.venv'].includes(name)) continue;
@@ -28,27 +38,8 @@ export async function setupRepository(root, wt, { signal, onSpawn = () => {}, on
     }
   };
   copyEnv();
-  const command = existsSync(join(wt, '.flowviant/setup.sh')) ? ['sh', '.flowviant/setup.sh'] :
-    ['bun.lock', 'bun.lockb'].some((f) => existsSync(join(wt, f))) ? ['bun', 'install', '--frozen-lockfile'] :
-    existsSync(join(wt, 'pnpm-lock.yaml')) ? ['pnpm', 'install', '--frozen-lockfile'] :
-    existsSync(join(wt, 'package-lock.json')) ? ['npm', 'ci'] :
-    existsSync(join(wt, 'yarn.lock')) ? ['yarn', 'install', '--frozen-lockfile'] : null;
   if (!command) return;
-  await new Promise((resolve, reject) => {
-    const child = spawn(command[0], command.slice(1), { cwd: wt, env: unattendedEnv({ ...process.env, GIT_TERMINAL_PROMPT: '0' }), detached: true, stdio: ['ignore', 'ignore', 'pipe'] });
-    const abort = () => killGroup(child);
-    signal?.addEventListener('abort', abort, { once: true });
-    if (signal?.aborted) abort();
-    onSpawn(child);
-    let tail = '';
-    child.stderr.on('data', (s) => { tail = (tail + s).slice(-2000); });
-    const timer = setTimeout(() => { killGroup(child); }, 10 * 60_000);
-    child.once('error', (e) => { clearTimeout(timer); reject(e); });
-    child.once('close', (code) => {
-      clearTimeout(timer); signal?.removeEventListener('abort', abort); onClose(child);
-      code === 0 ? resolve() : reject(new Error(`${command.join(' ')} failed in ${wt}: ${tail}`));
-    });
-  });
+  await environmentCommand(command, { ...options, cwd: wt, env: process.env, label: 'Repository setup', captureOutput: false, includeDiagnostics: true });
 }
 
 /** Installs are daemon children too: shutdown must drain their process groups. */

package/bin/lib/reviewBridge.mjs

@@ -0,0 +1,110 @@
+/** Native/engine helpers speak bounded JSON-RPC over a private stdio pipe. */
+import { startReviewProcess } from './reviewProcess.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+import { StringDecoder } from 'node:string_decoder';
+
+function image(value) {
+  if (!value || value.width !== 1440 || value.height !== 900 || typeof value.data !== 'string' || value.data.length > 1_000_000 || !/^[A-Za-z0-9+/]+={0,2}$/.test(value.data)) throw new Error('The runtime bridge returned an invalid bounded frame.');
+  const bytes = Buffer.from(value.data, 'base64');
+  if (bytes[0] !== 0xff || bytes[1] !== 0xd8) throw new Error('Runtime bridge frames must be JPEG images.');
+  return { type: 'frame', data: value.data, width: 1440, height: 900 };
+}
+
+export async function openBridgePage({ command, cwd, worktree, configuration = {}, env, signal, timeoutMs = 600_000, onChild, onFrame = () => {}, onChange = () => {}, requestTimeoutMs = 20_000, closeGraceMs = 500 }) {
+  signal?.throwIfAborted();
+  // Engine helpers may need to end their own play session over MCP before
+  // their child can be killed. Cancellation therefore closes the parent pipe.
+  const child = startReviewProcess(command, { cwd, env, onChild, timeoutMs: timeoutMs + closeGraceMs, stdio: ['pipe', 'pipe', 'pipe'], captureStdout: false });
+  const pending = new Map();
+  let serial = 0, epoch = 0, closed = false, ready = false, buffer = '', closeTimer, lifetime;
+  const decoder = new StringDecoder('utf8');
+  const close = (reason = new Error('The runtime bridge closed.')) => {
+    if (closed) return child.done;
+    closed = true;
+    clearTimeout(lifetime); signal?.removeEventListener('abort', abort);
+    for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(reason); }
+    pending.clear(); child.child.stdin.end();
+    // Let a well-behaved host helper release its session on parent-pipe EOF.
+    // A stalled helper still loses its owned group within a bounded grace.
+    closeTimer = setTimeout(() => { void child.close(); }, closeGraceMs); closeTimer.unref?.();
+    if (!child.running()) clearTimeout(closeTimer);
+    return child.done;
+  };
+  const exited = result => new Error(result.error ?? `The runtime bridge exited (${result.code}).`);
+  const abort = () => { void close(); };
+  const fail = error => { if (!closed) { onChange({ error: reviewDiagnostic(error.message) }); close(error); } };
+  lifetime = setTimeout(() => fail(new Error('The runtime bridge reached its time limit.')), timeoutMs); lifetime.unref?.();
+  signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) abort();
+  child.done.then(result => { clearTimeout(closeTimer); if (!closed) fail(exited(result)); });
+  child.child.stdout.on('data', bytes => {
+    if (closed) return;
+    buffer += decoder.write(bytes);
+    if (Buffer.byteLength(buffer) > 1_400_000) { fail(new Error('The runtime bridge exceeded its message bound.')); return; }
+    let newline;
+    while (!closed && (newline = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+      try {
+        const message = JSON.parse(line);
+        if (message.jsonrpc !== '2.0') throw new Error('The runtime bridge protocol is invalid.');
+        if (message.id != null) {
+          const entry = pending.get(message.id); if (!entry) continue;
+          pending.delete(message.id); clearTimeout(entry.timer);
+          if (message.error) entry.reject(new Error(reviewDiagnostic(message.error.message ?? 'Runtime bridge operation failed.')));
+          else entry.resolve(message.result);
+        } else if (ready && message.params?.epoch === epoch) {
+          if (message.method === 'frame') onFrame(image(message.params));
+          else if (message.method === 'ended') onChange({ ended: true });
+          else if (message.method === 'failure') fail(new Error(reviewDiagnostic(message.params.message)));
+        }
+      } catch (error) { fail(error); }
+    }
+  });
+  const request = (method, params) => {
+    if (closed) return Promise.reject(new Error('The runtime bridge is closed.'));
+    const id = ++serial;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { pending.delete(id); const error = new Error('The runtime bridge did not answer in time.'); reject(error); fail(error); }, requestTimeoutMs);
+      pending.set(id, { resolve, reject, timer });
+      child.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n', error => {
+        if (!error || closed) return;
+        // A fast launcher refusal (e.g. a held flock) can close stdin before
+        // Node observes its exit. Preserve that measured refusal over EPIPE.
+        void (async () => {
+          let timer;
+          try {
+            const result = await Promise.race([child.done, new Promise(resolve => { timer = setTimeout(() => resolve(null), 250); })]);
+            fail(result ? exited(result) : error);
+          } finally { clearTimeout(timer); }
+        })();
+      });
+    });
+  };
+  try {
+    const hello = await request('initialize', { protocol: 1, worktree, width: 1440, height: 900, configuration });
+    if (hello?.protocol !== 1 || !['owned-session', 'consented-window'].includes(hello.isolation) || hello.privateHandoff !== true) throw new Error('The bridge must bind an owned session or consented window and support private handoff fences.');
+    await request('open', { epoch }); ready = true;
+    return { kind: 'engine', pid: child.child.pid, close,
+      async setPrivate(privateInput) {
+        ready = false; const next = ++epoch;
+        const ack = await request('privacy', { private: privateInput, epoch: next });
+        if (ack?.epoch !== next || ack.drained !== true) { close(); throw new Error('The bridge did not acknowledge its private capture fence.'); }
+        ready = true;
+      },
+      async act(input) {
+        if (input.type === 'snapshot') return;
+        if (input.selector || ['navigate', 'retry'].includes(input.type)) throw new Error('Use this runtime’s coordinate input or engine tools; browser navigation is unavailable.');
+        await request('act', { input, epoch });
+      },
+      async snapshot() {
+        const current = epoch, shot = await request('snapshot', { epoch: current });
+        // A deliberate handoff invalidates this model observation, not the
+        // native session the person just took control of.
+        if (current !== epoch || !ready) throw new Error('Runtime control changed during capture.');
+        try {
+          if (shot?.epoch !== current) throw new Error('The runtime bridge returned a stale snapshot epoch.');
+          return { data: image(shot).data, observation: reviewDiagnostic(shot.observation ?? 'Native runtime observation.'), diagnostics: [] };
+        } catch (error) { fail(error); throw error; }
+      },
+    };
+  } catch (error) { close(); throw error; }
+}