flowviant 0.125.28 → 0.125.29

package/bin/lib/browserHandoff.mjs

@@ -0,0 +1,25 @@
+/** A human browser handoff holds the existing turn, worktree and browser.
+ * No model process polls while the person signs in. A returned handoff resumes
+ * the same CLI conversation before final delivery/verification can settle. */
+export const BROWSER_HANDOFF_CONTINUATIONS = 2;
+
+export function browserHandoffPrompt({ reason }) {
+  return reason === 'returned'
+    ? 'A person returned control of the SAME managed browser session. Inspect its current page and verify whether sign-in or the requested interaction succeeded, then continue the existing card and its checks. Reuse the running dev server and browser; do not restart them. Report only actual observations and retained evidence.'
+    : `The managed browser handoff ${reason === 'expired' ? 'expired' : 'was stopped by a person'}. This browser is no longer interactive. Respect that stop; report the unfinished browser checks as unverified, complete any other available verification, and finish the existing card. Do not claim sign-in or interactive checks succeeded.`;
+}
+
+export async function completeBrowserReview(initial, { browser, signal, finish, resume }) {
+  let out = initial, finished = false, continuations = 0;
+  for (;;) {
+    if (signal?.aborted) return out;
+    const handoff = await browser?.waitForHandoff?.();
+    if (signal?.aborted || handoff?.reason === 'closed') return out;
+    if (handoff) {
+      if (continuations >= BROWSER_HANDOFF_CONTINUATIONS) throw new Error('The browser handoff continuation limit was reached. Interactive verification is incomplete.');
+      out = await resume(handoff, ++continuations);
+      finished = false;
+    } else if (finished) return out;
+    else { out = await finish(out); finished = true; }
+  }
+}

package/bin/lib/desktopContract.mjs

@@ -12,7 +12,7 @@ import { installChannel } from './launchCommand.mjs';
 import { boxesUrlFrom, classifyMachineResponse, fetchBoxesFor } from './machines.mjs';
 import { daemonLockPid, daemonLogPath, readDaemonState } from './daemonState.mjs';
 import { detectRuntimes } from './runtimeDetection.mjs';
-import { readClaudeAuthStatus } from './runtimeAuth.mjs';
+import { readClaudeAuthStatus, readCodexAuthStatus } from './runtimeAuth.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 
 /**
@@ -42,11 +42,13 @@ export function busyOf(liveState, now = Date.now()) {
 // One home for the channel (launchCommand.mjs); re-exported for views.mjs.
 export { installChannel };
 
-export function desktopStatus({ entries = listStoredProjects(), runtimes = detectRuntimes(), runningFor = daemonRunningFor, stateFor = readDaemonState, pidFor = daemonLockPid, drainFor = drainingFor, nowMs = Date.now(), authFor = readClaudeAuthStatus, refreshAuth = false } = {}) {
+export function desktopStatus({ entries = listStoredProjects(), runtimes = detectRuntimes(), runningFor = daemonRunningFor, stateFor = readDaemonState, pidFor = daemonLockPid, drainFor = drainingFor, nowMs = Date.now(), authFor = readClaudeAuthStatus, codexAuthFor = readCodexAuthStatus, refreshAuth = false } = {}) {
   const runtimeRows = runtimes.map((rt) => ({
     id: rt.id, installed: rt.installed, version: rt.version ?? null, dispatchable: rt.dispatchable,
-    ...(rt.id === 'claude' ? (rt.installed ? authFor({ refresh: refreshAuth }) : { signedIn: null, billing: null, subscriptionType: null }) :
-      { signedIn: null, billing: null, subscriptionType: null }),
+    authSource: 'local',
+    signedIn: null, billing: null, subscriptionType: null, checkedAt: null, expiresAt: null, expiryKind: null,
+    ...(rt.installed && rt.id === 'claude' ? authFor({ refresh: refreshAuth }) :
+      rt.installed && rt.id === 'codex' ? codexAuthFor({ refresh: refreshAuth }) : {}),
   }));
   return {
     schema: 1,
@@ -148,10 +150,10 @@ const refusalWords = (r) =>
 
 export async function desktopStatusRemote({ entries = listStoredProjects(), runtimes = detectRuntimes(),
   runningFor = daemonRunningFor, stateFor = readDaemonState, pidFor = daemonLockPid,
-  authFor = readClaudeAuthStatus, refreshAuth = false,
+  authFor = readClaudeAuthStatus, codexAuthFor = readCodexAuthStatus, refreshAuth = false,
   fetchImpl = fetch, envpub = readStoredPubB64(), fleetUrl = FLEET_URL, host = MACHINE_HOST,
   now = () => new Date().toISOString(), timeoutMs = REMOTE_TIMEOUT_MS, log = console.error } = {}) {
-  const status = desktopStatus({ entries, runtimes, runningFor, stateFor, pidFor, authFor, refreshAuth });
+  const status = desktopStatus({ entries, runtimes, runningFor, stateFor, pidFor, authFor, codexAuthFor, refreshAuth });
   const boxesUrl = boxesUrlFrom(fleetUrl);
   const liveUrl = fleetEndpoint('live-agents', fleetUrl);
   const remotes = await Promise.all(entries.map(async (entry) => {

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, 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; 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.');
@@ -94,11 +125,19 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
   const call = async (name, input) => {
     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.');
     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.');
@@ -107,22 +146,29 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
         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) {
+          openingNew = true;
+          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.'); }
+          pageOrigin = upstream; pageMeasured = measured;
+        }
         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 (name === 'open' && status.mode !== 'user') { release(); if (!stopped && !closed) change({ state: 'error', error: reviewDiagnostic(error.message) }); }
+      if (openingNew && status.mode !== 'user') { release(); if (!stopped && !closed) change({ state: 'error', error: reviewDiagnostic(error.message) }); }
       throw error;
     } finally { busy = false; }
   };
@@ -133,10 +179,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 +193,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 +220,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 +236,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) => {
@@ -204,16 +258,24 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
   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]);
   };
   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.' };
+    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/runtimeAuth.mjs

@@ -1,4 +1,4 @@
-/** Claude Code's own auth verdict for the local desktop contract.
+/** Coding tools' own auth verdicts for the local desktop contract.
  *
  * The credential file is only a context clue (claudeAuth.mjs): on some boxes
  * Claude stores a working login in a keychain. Only `claude auth status --json`
@@ -15,6 +15,28 @@ const UNKNOWN = Object.freeze({ signedIn: null, billing: null, subscriptionType:
 const TTL_MS = 90_000;
 const SUBSCRIPTIONS = new Set(['pro', 'max', 'team', 'enterprise']);
 
+function cachedAuth(cachePath, bin, now, refresh) {
+  if (refresh) return null;
+  try {
+    const cached = JSON.parse(readFileSync(cachePath, 'utf8'));
+    if (cached.bin === bin && Number.isFinite(cached.at) && now >= cached.at && now - cached.at < TTL_MS &&
+        cached.result?.checkedAt === new Date(cached.at).toISOString() &&
+        [true, false, null].includes(cached.result?.signedIn) &&
+        [null, 'api', 'subscription'].includes(cached.result?.billing)) return cached.result;
+  } catch { /* No usable cache: ask the CLI, including after an upgrade. */ }
+  return null;
+}
+
+function retainAuth(cachePath, bin, now, result) {
+  const measured = { ...result, checkedAt: new Date(now).toISOString(),
+    expiresAt: result.expiresAt ?? null, expiryKind: result.expiryKind ?? null };
+  try {
+    mkdirSync(dirname(cachePath), { recursive: true, mode: 0o700 });
+    writeFileSync(cachePath, JSON.stringify({ bin, at: now, result: measured }), { mode: 0o600 });
+  } catch { /* Caching is optional; never break status. */ }
+  return measured;
+}
+
 export function parseClaudeAuthStatus(raw) {
   let value;
   try { value = JSON.parse(raw); } catch { return UNKNOWN; }
@@ -31,14 +53,8 @@ export function parseClaudeAuthStatus(raw) {
 
 export function readClaudeAuthStatus({ bin = 'claude', cachePath = join(homedir(), '.flowviant', 'claude-auth-status.json'),
   refresh = false, timeoutMs = 3_000, now = Date.now(), spawn = spawnSync, contextFor = claudeAuthContext } = {}) {
-  if (!refresh) {
-    try {
-      const cached = JSON.parse(readFileSync(cachePath, 'utf8'));
-      if (cached.bin === bin && Number.isFinite(cached.at) && now >= cached.at && now - cached.at < TTL_MS &&
-          [true, false, null].includes(cached.result?.signedIn) &&
-          [null, 'api', 'subscription'].includes(cached.result?.billing)) return cached.result;
-    } catch { /* no cache, or unreadable cache: ask the CLI */ }
-  }
+  const cached = cachedAuth(cachePath, bin, now, refresh);
+  if (cached) return cached;
   let result = UNKNOWN;
   try {
     const child = spawn(bin, ['auth', 'status', '--json'], {
@@ -46,16 +62,40 @@ export function readClaudeAuthStatus({ bin = 'claude', cachePath = join(homedir(
       stdio: ['ignore', 'pipe', 'ignore'],
     });
     if (!child.error && (child.status === 0 || child.status === 1)) result = parseClaudeAuthStatus(child.stdout);
-    if (result.signedIn === true && result.billing === 'subscription' && result.subscriptionType === null) {
+    if (result.signedIn === true && result.billing === 'subscription') {
       const context = contextFor();
-      if (context.source === 'file' && SUBSCRIPTIONS.has(context.subscriptionType)) {
-        result = { ...result, subscriptionType: context.subscriptionType };
+      if (context.source === 'file') {
+        if (result.subscriptionType === null && SUBSCRIPTIONS.has(context.subscriptionType)) {
+          result = { ...result, subscriptionType: context.subscriptionType };
+        }
+        // Access-token expiry is renewable. Only the store's explicit refresh
+        // expiry can describe the end of this login; absent stays unknown.
+        const expiry = Date.parse(context.refreshExpiresAt ?? '');
+        if (Number.isFinite(expiry)) result = { ...result, expiresAt: new Date(expiry).toISOString(), expiryKind: 'refresh' };
       }
     }
   } catch { /* A failed probe means unknown, not signed out. */ }
+  return retainAuth(cachePath, bin, now, result);
+}
+
+/** `codex login status` writes its verdict to stderr. Keep only the verdict,
+ * never its output: API-key mode can include credential material. */
+export function readCodexAuthStatus({ bin = 'codex', cachePath = join(homedir(), '.flowviant', 'codex-auth-status.json'),
+  refresh = false, timeoutMs = 3_000, now = Date.now(), spawn = spawnSync } = {}) {
+  const cached = cachedAuth(cachePath, bin, now, refresh);
+  if (cached) return cached;
+  let result = UNKNOWN;
   try {
-    mkdirSync(dirname(cachePath), { recursive: true, mode: 0o700 });
-    writeFileSync(cachePath, JSON.stringify({ bin, at: now, result }), { mode: 0o600 });
-  } catch { /* Caching is optional; never break status. */ }
-  return result;
+    const child = spawn(bin, ['login', 'status'], {
+      encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const words = `${child.stdout ?? ''}\n${child.stderr ?? ''}`.trim();
+    if (!child.error && child.status === 0 && /^logged in\b/im.test(words)) {
+      result = { signedIn: true, billing: /api.?key/i.test(words) ? 'api' : /chatgpt/i.test(words) ? 'subscription' : null, subscriptionType: null };
+    } else if (!child.error && child.status === 1 && /^not logged in\b/im.test(words)) {
+      result = { ...UNKNOWN, signedIn: false };
+    }
+  } catch { /* Unknown, never a fabricated sign-out. */ }
+  return retainAuth(cachePath, bin, now, result);
 }

package/bin/lib/workAgentTurnExecution.mjs

@@ -71,6 +71,7 @@ import { createIntermediateArtifacts, IntermediateArtifactCapacityError } from '
 import { createUiReview } from './uiReview.mjs';
 import { createVideoRender } from './videoRender.mjs';
 import { createManagedBrowser } from './managedBrowser.mjs';
+import { completeBrowserReview, browserHandoffPrompt } from './browserHandoff.mjs';
 import { withUiReview, appendUiReviewEvidence } from './uiReviewTurn.mjs';
 
 export function createAgentTurnExecution({
@@ -518,6 +519,7 @@ export function createAgentTurnExecution({
       projectTools = tools.projectTools;
       localCleanup?.begin(turnId);
       const { toolsNote } = tools;
+      let browserThread = agentResume.resumeThreadId;
       const agentTurnArgs = {
         ...((liveInput || orchestrator) ? { liveMessages: (run.live = makeLiveMessages({
           scope: 'agent', turnId, cwd: wt, sessionMetaPath, interrupted: () => run.interrupted,
@@ -565,12 +567,14 @@ export function createAgentTurnExecution({
         resume: agentResume.resume,
         resumeThreadId: agentResume.resumeThreadId,
         onInit: (init) => {
+          if (rt === 'claude' && typeof init.sessionId === 'string') browserThread = init.sessionId;
           orchestrator?.root(init.sessionId);
           // A server that did not connect, as the CLI said (unknown: nothing).
           trace.mcpStatus(init.mcpServers);
           agentResume.sawSession(init.sessionId);
         },
         onThreadId: (id) => {
+          browserThread = id;
           orchestrator?.root(id);
           agentResume.sawThread(id);
         },
@@ -741,6 +745,7 @@ export function createAgentTurnExecution({
           runtime: rt,
           beforeFresh: () => {
             agentResume.forgetThread();
+            browserThread = undefined;
             lastAnswer = null;
             model = null;
           },
@@ -751,19 +756,34 @@ export function createAgentTurnExecution({
           void postAgentActivity(agentId, 'resuming after an internal wait');
         } }
       );
-      out = await finishRepositoryDelivery({
-        job, run: repositoryRun, out, answer: () => lastAnswer,
-        resume: async (prompt) => {
+      out = await completeBrowserReview(out, {
+        browser: managedBrowser, signal: setupController.signal,
+        resume: async (handoff) => {
+          const thread = agentResume.threadNow() ?? browserThread;
+          if (!thread) throw new Error('The browser handoff could not resume: the CLI reported no conversation id. Interactive verification is incomplete.');
           lastAnswer = null;
           const counted = usage;
-          return runCli({
-            ...agentTurnArgs, prompt, liveContinuation: true,
-            onUsage: (next) => agentTurnArgs.onUsage(addUsage(counted, next)),
-            writableDirs: repositoryRun.sourcesNow().filter((r) => r.wt !== wt).map((r) => r.wt),
-            resume: true,
-            resumeThreadId: agentResume.threadNow() ?? agentTurnArgs.resumeThreadId,
+          trace.prose('text', handoff.reason === 'returned' ? 'Browser control returned. Resuming verification.' : 'The browser handoff ended. Resuming to report incomplete interactive checks.');
+          return runAgentWithInternalWaits(args => runCli(args), {
+            ...agentTurnArgs, prompt: browserHandoffPrompt(handoff), resume: true, resumeThreadId: thread, liveContinuation: true,
+            ...(repositoryRun ? { writableDirs: repositoryRun.sourcesNow().filter(r => r.wt !== wt).map(r => r.wt) } : {}),
+            onUsage: next => agentTurnArgs.onUsage(addUsage(counted, next)),
           });
         },
+        finish: current => finishRepositoryDelivery({
+          job, run: repositoryRun, out: current, answer: () => lastAnswer,
+          resume: async (prompt) => {
+            lastAnswer = null;
+            const counted = usage;
+            return runCli({
+              ...agentTurnArgs, prompt, liveContinuation: true,
+              onUsage: (next) => agentTurnArgs.onUsage(addUsage(counted, next)),
+              writableDirs: repositoryRun.sourcesNow().filter((r) => r.wt !== wt).map((r) => r.wt),
+              resume: true,
+              resumeThreadId: agentResume.threadNow() ?? browserThread,
+            });
+          },
+        }),
       });
     } finally {
       // The loopback capability stays registered until every retained CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.125.28",
+  "version": "0.125.29",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {