toolroll 0.9.21 → 0.9.23

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.9.23 — 2026-10-04
+
+- After a research step, a flow's message to you now carries that research's
+  screenshots. Before, it only looked for a build's.
+
+## 0.9.22 — 2026-10-04
+
+- **Research takes screenshots again.** The research step's browser now runs
+  outside the agent's sandbox with Chrome's own sandbox on, reached on a
+  private local port. It still opens public pages only. A short check before
+  research starts says once, in plain words, if the browser can't start.
+
 ## 0.9.21 — 2026-10-03
 
 - **Flows send you what was done.** A new "Send to me" step sends the last

package/dist/desktop-update.d.ts

@@ -125,20 +125,20 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
-    error?: never;
-    version?: never;
     active: boolean;
     phase: string;
     detail: string;
     running: boolean;
     canResume: boolean;
     canCancel: boolean;
+    error?: never;
     automaticRecovery?: never;
     recoveryAttempts?: never;
     recoveryRepairs?: never;
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
+    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

package/dist/flow-send.js

@@ -55,6 +55,14 @@ function resultOf(store, taskId, now, evidenceRoot) {
         shots: receipt !== null && store.artifactsFor(receipt.runId).some(one => one.kind === "screenshot") ? { taskId: receipt.taskId, run: receipt.runId } : null,
     };
 }
+/** A research task's latest delivered report, when its run saved screenshots: what that step produced to show. */
+function reportShotsOf(store, taskId) {
+    const ref = store.lookupRef(taskId);
+    if (ref === null)
+        return null;
+    const run = store.runsFor(ref.id).find(one => one.finishedAt !== null && one.role === "scout");
+    return run !== undefined && run.outcome === "built" && store.artifactsFor(run.id).some(one => one.kind === "screenshot") ? { taskId, run: run.id } : null;
+}
 /** What a visit sends its person, worked out from the card as it is now. */
 export function flowSendContent(store, flow, definition, stage, card, now, evidenceRoot) {
     const before = stepBefore(store, definition, card);
@@ -90,7 +98,8 @@ export function flowSendContent(store, flow, definition, stage, card, now, evide
     const options = stage.kind === "choose" ? (stage.options ?? []).map((one, choice) => ({ choice, label: one.label })) : undefined;
     return {
         title: cut(plain(before === null ? card.title : `${card.title} · ${before.title}`), 200), ...(before === null ? {} : { from: before.title }),
-        summary: plain(lines.join("\n\n")), links, shots: result?.shots ?? null,
+        // After research, its own screenshots are what that step produced; otherwise the build's.
+        summary: plain(lines.join("\n\n")), links, shots: (report === null ? null : reportShotsOf(store, report)) ?? result?.shots ?? null,
         ...(options === undefined ? {} : { options, reply: replyTarget(stage) !== null }),
     };
 }

package/dist/scout-browser.d.ts

@@ -0,0 +1,48 @@
+export type BrowserLaunch = {
+    command: string;
+    args: readonly string[];
+};
+export type ScoutBrowserServer = {
+    url: string;
+    close: () => Promise<void>;
+};
+export type BrowserStart = {
+    ok: true;
+    server: ScoutBrowserServer;
+} | {
+    ok: false;
+    reason: string;
+};
+export type BrowserStarter = (launch: BrowserLaunch, options: BrowserOptions) => Promise<BrowserStart>;
+export type BrowserOptions = {
+    /** The browser tool's environment: the scout's own, its proxy settings included. */
+    env: Record<string, string | undefined>;
+    /** Where it saves screenshots (its `--output-dir`), also its working folder. */
+    folder: string;
+    /** The whole start and check, from spawn to screenshot (review 828: at most 60 seconds). */
+    timeoutMs?: number;
+};
+/** The public page the check opens through the scout's proxy. */
+export declare const PREFLIGHT_PAGE = "https://example.com/";
+/** How a scout gets its browser: started for real, or, for a test's stub agent, a placeholder that starts nothing. */
+export declare function starterFor(agentInjected: boolean): BrowserStarter;
+/** Start the browser tool outside the fence and check it opens a public page and saves a screenshot. */
+export declare function startScoutBrowser(launch: BrowserLaunch, options: BrowserOptions): Promise<BrowserStart>;
+export type McpSession = {
+    start: () => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    call: (tool: string, input: Record<string, unknown>) => Promise<{
+        ok: true;
+        result: Record<string, unknown>;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    close: () => Promise<void>;
+};
+/** A client of the browser's HTTP transport, as the scout's own is: every step answers by `deadline`, or says why not. */
+export declare function openSession(url: string, deadline: number, late: string): McpSession;

package/dist/scout-browser.js

@@ -0,0 +1,228 @@
+/**
+ * The scout's browser (run 2356, review 828). Chrome's own sandbox can't start inside the agent fence (nested
+ * Seatbelt: every page crashed, even example.com), and switching that sandbox off is not an option. So the browser
+ * tool runs beside the agent instead of under it: the worker starts the pinned Playwright MCP itself, outside the
+ * fence with Chrome's sandbox on, serving its HTTP transport on a random loopback port, and the fenced agent gets
+ * only that URL. Every page still goes through the scout's public-web-only proxy, and screenshots land in the run's
+ * image folder. Before research begins the browser is checked once, through that proxy, on a public page, with one
+ * time limit for the whole check; a browser that can't start is said in one line and the scout researches
+ * without it.
+ *
+ * Playwright MCP 0.0.82 has no per-client token for its HTTP transport; it answers only on 127.0.0.1, only for
+ * that host name (its own host check), and only while this run's scout does.
+ */
+import { spawn } from "node:child_process";
+import { request as httpRequest } from "node:http";
+import { connect, createServer } from "node:net";
+import { readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+/** The public page the check opens through the scout's proxy. */
+export const PREFLIGHT_PAGE = "https://example.com/";
+const PREFLIGHT_TIMEOUT_MS = 60_000;
+const CLOSE_GRACE_MS = 5_000;
+const IMAGE = /\.(png|jpe?g)$/i;
+/** How a scout gets its browser: started for real, or, for a test's stub agent, a placeholder that starts nothing. */
+export function starterFor(agentInjected) {
+    return agentInjected ? unstarted : startScoutBrowser;
+}
+const unstarted = async () => ({ ok: true, server: { url: "http://127.0.0.1:9/mcp", close: async () => undefined } });
+/** Start the browser tool outside the fence and check it opens a public page and saves a screenshot. */
+export async function startScoutBrowser(launch, options) {
+    const timeoutMs = options.timeoutMs ?? PREFLIGHT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    const late = `the browser did not start within ${Math.round(timeoutMs / 1000)} seconds`;
+    const served = await serveBrowser(launch, options, deadline, late);
+    if (!served.ok)
+        return served;
+    const before = new Set(entries(options.folder));
+    const session = openSession(served.server.url, deadline, late);
+    try {
+        let checked = await preflight(session);
+        if (checked.ok && !entries(options.folder).some(name => !before.has(name) && IMAGE.test(name)))
+            checked = { ok: false, reason: "the browser saved no screenshot" };
+        if (!checked.ok) {
+            await served.server.close();
+            return checked;
+        }
+        return served;
+    }
+    finally {
+        await session.close();
+        // The check's own screenshot and page notes are not the scout's.
+        for (const name of entries(options.folder))
+            if (!before.has(name))
+                rmSync(join(options.folder, name), { recursive: true, force: true });
+    }
+}
+async function preflight(session) {
+    const started = await session.start();
+    if (!started.ok)
+        return started;
+    for (const [tool, input] of [["browser_navigate", { url: PREFLIGHT_PAGE }], ["browser_take_screenshot", { type: "png" }]]) {
+        const done = await session.call(tool, input);
+        if (!done.ok)
+            return done;
+    }
+    return { ok: true };
+}
+/** Spawn the tool with its HTTP transport on a free 127.0.0.1 port and wait until it answers there. */
+async function serveBrowser(launch, options, deadline, late) {
+    const port = await freePort();
+    const child = spawn(launch.command, [...launch.args, "--host", "127.0.0.1", "--port", String(port), "--allowed-hosts", `127.0.0.1:${port}`], {
+        cwd: options.folder,
+        env: options.env,
+        stdio: ["ignore", "ignore", "pipe"],
+        detached: process.platform !== "win32",
+    });
+    let stderr = "";
+    let stopped = null;
+    child.on("error", error => { stopped ??= `the browser tool could not run (${error.message})`; });
+    child.on("exit", (code, sig) => { stopped ??= `the browser tool stopped (${sig ?? `exit ${code}`})${lastLine(stderr) === "" ? "" : `: ${lastLine(stderr)}`}`; });
+    child.stderr.on("data", chunk => { stderr = (stderr + String(chunk)).slice(-4_000); });
+    const close = async () => {
+        if (child.exitCode === null && child.signalCode === null) {
+            const exited = new Promise(done => child.once("exit", () => done()));
+            signal(child.pid, "SIGTERM");
+            await Promise.race([exited, new Promise(done => setTimeout(done, CLOSE_GRACE_MS).unref())]);
+        }
+        // Its browser and helpers go with it.
+        signal(child.pid, "SIGKILL");
+    };
+    // First runs download the pinned tool; it listens once it is ready.
+    while (stopped === null && Date.now() < deadline && !(await answers(port)))
+        await new Promise(done => setTimeout(done, 250));
+    if (stopped !== null || Date.now() >= deadline) {
+        const reason = stopped ?? late;
+        await close();
+        return { ok: false, reason };
+    }
+    return { ok: true, server: { url: `http://127.0.0.1:${port}/mcp`, close } };
+}
+function freePort() {
+    return new Promise((done, fail) => {
+        const probe = createServer();
+        probe.once("error", fail);
+        probe.listen(0, "127.0.0.1", () => {
+            const address = probe.address();
+            probe.close(() => (typeof address === "object" && address !== null ? done(address.port) : fail(new Error("no free port"))));
+        });
+    });
+}
+function answers(port) {
+    return new Promise(done => {
+        const socket = connect({ host: "127.0.0.1", port });
+        socket.setTimeout(1_000);
+        socket.once("connect", () => { socket.destroy(); done(true); });
+        socket.once("error", () => done(false));
+        socket.once("timeout", () => { socket.destroy(); done(false); });
+    });
+}
+function signal(pid, name) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(process.platform === "win32" ? pid : -pid, name);
+    }
+    catch { /* already gone */ }
+}
+function entries(folder) {
+    try {
+        return readdirSync(folder);
+    }
+    catch {
+        return [];
+    }
+}
+/** A client of the browser's HTTP transport, as the scout's own is: every step answers by `deadline`, or says why not. */
+export function openSession(url, deadline, late) {
+    let session = null;
+    let next = 0;
+    const post = (body, method = "POST") => new Promise(done => {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return done({ ok: false, reason: late });
+        const headers = { accept: "application/json, text/event-stream", "content-type": "application/json" };
+        if (session !== null)
+            headers["mcp-session-id"] = session;
+        const sent = httpRequest(url, { method, headers }, answer => {
+            let text = "";
+            answer.on("data", chunk => { text += String(chunk); });
+            answer.on("end", () => { clearTimeout(timer); done({ ok: true, status: answer.statusCode ?? 0, headers: answer.headers, text }); });
+            answer.on("error", error => { clearTimeout(timer); done({ ok: false, reason: `the browser stopped answering (${error.message})` }); });
+        });
+        const timer = setTimeout(() => { sent.destroy(); done({ ok: false, reason: late }); }, remaining);
+        sent.on("error", error => { clearTimeout(timer); done({ ok: false, reason: `the browser stopped answering (${error.message})` }); });
+        sent.end(method === "POST" ? JSON.stringify(body) : undefined);
+    });
+    const request = async (method, params) => {
+        const id = ++next;
+        const sent = await post({ jsonrpc: "2.0", id, method, params });
+        if (!sent.ok)
+            return sent;
+        const message = messages(sent.text).find(one => one["id"] === id);
+        if (message === undefined)
+            return { ok: false, reason: `the browser tool answered ${sent.status}${sent.text.trim() === "" ? "" : `: ${oneLine(sent.text)}`}` };
+        const header = sent.headers["mcp-session-id"];
+        if (typeof header === "string")
+            session = header;
+        return { ok: true, message };
+    };
+    return {
+        start: async () => {
+            const hello = await request("initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "toolroll-scout-preflight", version: "1" } });
+            if (!hello.ok)
+                return hello;
+            if (hello.message["error"] !== undefined)
+                return { ok: false, reason: `the browser tool refused to start: ${errorText(hello.message)}` };
+            const ready = await post({ jsonrpc: "2.0", method: "notifications/initialized" });
+            return ready.ok ? { ok: true } : ready;
+        },
+        call: async (tool, input) => {
+            const answer = await request("tools/call", { name: tool, arguments: input });
+            if (!answer.ok)
+                return answer;
+            const failed = toolFailure(answer.message);
+            return failed === null ? { ok: true, result: (answer.message["result"] ?? {}) } : { ok: false, reason: failed };
+        },
+        close: async () => {
+            // Ending the session closes its browser context.
+            if (session !== null)
+                await post({}, "DELETE");
+        },
+    };
+}
+/** The JSON-RPC messages in an answer: a plain JSON body, or the data lines of an event stream. */
+function messages(text) {
+    const bodies = text.trimStart().startsWith("{") ? [text] : text.split("\n").filter(line => line.startsWith("data:")).map(line => line.slice(5));
+    return bodies.flatMap(body => {
+        try {
+            const parsed = JSON.parse(body);
+            return typeof parsed === "object" && parsed !== null ? [parsed] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** Why a tool call failed, in one line, or null when it worked. */
+function toolFailure(answer) {
+    if (answer["error"] !== undefined)
+        return errorText(answer);
+    const result = answer["result"];
+    if (result?.isError !== true)
+        return null;
+    const text = result.content?.map(one => (typeof one.text === "string" ? one.text : "")).join("\n") ?? "";
+    const line = text.split("\n").map(one => one.replace(/^#+\s*Error\s*$/i, "").replace(/^Error:\s*/, "").replace(/^browserBackend\.callTool:\s*/, "").trim()).find(one => one !== "");
+    return oneLine(line ?? "unknown error");
+}
+function errorText(answer) {
+    const error = answer["error"];
+    return oneLine(typeof error?.message === "string" ? error.message : "unknown error");
+}
+function lastLine(text) {
+    return oneLine(text.trim().split("\n").at(-1) ?? "");
+}
+function oneLine(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").trim().slice(0, 200);
+}

package/dist/scout.d.ts

@@ -3,6 +3,7 @@ import { type ParsedDecision, type Problem } from "./decision.js";
 import { type ParsedReport, type ReportProblem } from "./scout-report.js";
 import type { Runner } from "./builder.js";
 import { type ToolSpec } from "./project-tools.js";
+import * as browserCheck from "./scout-browser.js";
 /** The scout's own headless browser: the pinned Playwright tool, saving its
  * screenshots straight into the run's image folder. */
 export declare const SCOUT_BROWSER = "toolroll-browser";
@@ -15,12 +16,17 @@ export declare const SCOUT_BROWSER = "toolroll-browser";
  */
 export declare const SCOUT_ALLOWED_TOOLS: readonly string[];
 /** The scout's browser launch, or null when this install has no Playwright entry (the scout then researches without
- * screenshots). Every request it makes goes through `proxy` (scout-net.ts), which lets only public pages and the
- * project's own demo through; loopback is proxied too, never bypassed, and file: stays blocked. */
-export declare function scoutBrowser(tool: Pick<ToolSpec, "command" | "args"> | null, imageFolder: string, proxy: string): Record<string, unknown> | null;
+ * screenshots). The worker runs it outside the agent fence with Chrome's own sandbox on (run 2356, review 828:
+ * scout-browser.ts). Every request it makes goes through `proxy` (scout-net.ts), which lets only public pages and the
+ * project's own demo through; loopback is proxied too, never bypassed, and file: stays blocked. Screenshots are saved
+ * in `imageFolder`. */
+export declare function scoutBrowserLaunch(tool: Pick<ToolSpec, "command" | "args"> | null, imageFolder: string, proxy: string): browserCheck.BrowserLaunch | null;
+/** What the fenced scout gets: the running browser's loopback address, nothing it could launch itself. */
+export declare function scoutBrowser(url: string): Record<string, unknown>;
 /** The scout's environment while its proxy runs (review 827): web fetch and the provider's own traffic go through
- * the same public-web-only proxy as its browser, so only public addresses (and the project's demo) are reachable. */
-export declare function scoutProxyEnv(proxy: string): Record<string, string>;
+ * the same public-web-only proxy as its browser, so only public addresses (and the project's demo) are reachable.
+ * The one direct address is its own browser's port, when it has one (review 828): the proxy refuses loopback. */
+export declare function scoutProxyEnv(proxy: string, browserUrl?: string | null): Record<string, string>;
 export type ScoutRequest = {
     /** v105: what's left of a monthly budget this API-key work counts toward (the CLI's own cap), when one does. */
     maxBudgetUsd?: number;

package/dist/scout.js

@@ -20,7 +20,6 @@ import { currentClaim, heartbeat } from "./claim.js";
 import { heartbeat as runnerHeartbeat } from "./runner.js";
 import { parseDecision } from "./decision.js";
 import { parseReport, REPORT_IMAGE_FILE, REPORT_LIMITS, SCOUT_OUTPUT_JSON_SCHEMA } from "./scout-report.js";
-import { invokeAgent } from "./invoke.js";
 import { TOKEN_ENVS as TELEGRAM_TOKEN_ENVS } from "./telegram.js";
 import { evidenceRoot, mailboxName, quarantineMailboxes, readMailbox, reportFileName, SCREENSHOT_BYTE_CAP, storeEvidence, validateScreenshotBytes, writeEvidenceFile, } from "./evidence.js";
 import { MARKER as LEASE_MARKER } from "./worktree.js";
@@ -30,6 +29,8 @@ import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { CLAUDE_LIMITS } from "./scope.js";
 import { catalogTool } from "./project-tools.js";
 import { startScoutProxy } from "./scout-net.js";
+import * as browserCheck from "./scout-browser.js";
+import { invokeAgent } from "./invoke.js";
 const GIT = "git";
 const AGENT_ENV_DENYLIST = [...TELEGRAM_TOKEN_ENVS];
 const DEFAULT_SCOUT_TIMEOUT_MS = 20 * 60_000;
@@ -49,19 +50,27 @@ const SCOUT_BROWSER_TOOLS = ["browser_navigate", "browser_navigate_back", "brows
 export const SCOUT_ALLOWED_TOOLS = ["WebSearch", "WebFetch", ...SCOUT_BROWSER_TOOLS.map(tool => `mcp__${SCOUT_BROWSER}__${tool}`)];
 const SCOUT_RESEARCH_TOOLS = ["WebSearch", "WebFetch"];
 /** The scout's browser launch, or null when this install has no Playwright entry (the scout then researches without
- * screenshots). Every request it makes goes through `proxy` (scout-net.ts), which lets only public pages and the
- * project's own demo through; loopback is proxied too, never bypassed, and file: stays blocked. */
-export function scoutBrowser(tool, imageFolder, proxy) {
+ * screenshots). The worker runs it outside the agent fence with Chrome's own sandbox on (run 2356, review 828:
+ * scout-browser.ts). Every request it makes goes through `proxy` (scout-net.ts), which lets only public pages and the
+ * project's own demo through; loopback is proxied too, never bypassed, and file: stays blocked. Screenshots are saved
+ * in `imageFolder`. */
+export function scoutBrowserLaunch(tool, imageFolder, proxy) {
     if (tool === null || tool.command === null)
         return null;
-    return { [SCOUT_BROWSER]: { type: "stdio", command: tool.command, args: [...tool.args, "--isolated", "--output-dir", imageFolder, "--proxy-server", proxy, "--proxy-bypass", "<-loopback>"], env: {} } };
+    return { command: tool.command, args: [...tool.args, "--isolated", "--output-dir", imageFolder, "--proxy-server", proxy, "--proxy-bypass", "<-loopback>"] };
+}
+/** What the fenced scout gets: the running browser's loopback address, nothing it could launch itself. */
+export function scoutBrowser(url) {
+    return { [SCOUT_BROWSER]: { type: "http", url } };
 }
 /** What would let the scout's own requests skip its proxy: never passed on while one runs. */
 const PROXY_BYPASS_ENV = ["NO_PROXY", "no_proxy", "ALL_PROXY", "all_proxy"];
 /** The scout's environment while its proxy runs (review 827): web fetch and the provider's own traffic go through
- * the same public-web-only proxy as its browser, so only public addresses (and the project's demo) are reachable. */
-export function scoutProxyEnv(proxy) {
-    return { HTTP_PROXY: proxy, HTTPS_PROXY: proxy, http_proxy: proxy, https_proxy: proxy };
+ * the same public-web-only proxy as its browser, so only public addresses (and the project's demo) are reachable.
+ * The one direct address is its own browser's port, when it has one (review 828): the proxy refuses loopback. */
+export function scoutProxyEnv(proxy, browserUrl = null) {
+    const direct = browserUrl === null ? {} : { NO_PROXY: new URL(browserUrl).host, no_proxy: new URL(browserUrl).host };
+    return { HTTP_PROXY: proxy, HTTPS_PROXY: proxy, http_proxy: proxy, https_proxy: proxy, ...direct };
 }
 /** One line of untrusted text made inert for the brief (audit IV-4). */
 function inert(text, cap = 300) {
@@ -101,15 +110,21 @@ function scoutBrief(title, goal, outOfScope, mailbox, reportFile, answers, struc
             : ["The web is unavailable in this run: research from the repository alone."]),
         ...(browser === null
             ? ["No browser is available for screenshots in this run, so leave images empty."]
-            : [
-                "You may take screenshots (PNG or JPEG) of public web pages you actually",
-                `visited${browser.demoUrl === null ? "" : `, and of this project's own UI at \`${inert(browser.demoUrl, 500)}\``}. The browser`,
-                "opens public web pages only. Open the page with the",
-                `\`${SCOUT_BROWSER}\` browser, then take its screenshot with a plain file`,
-                "name such as home.png; it is saved in this folder outside the",
-                `repository: \`${browser.folder}\`. At most ${REPORT_LIMITS.images}, each under ${SCREENSHOT_BYTE_CAP / (1024 * 1024)} MB.`,
-                "Never screenshot a page you did not visit.",
-            ]),
+            : "problem" in browser
+                ? [
+                    `The browser couldn't start (${inert(browser.problem, 200)}), so this run has no screenshots:`,
+                    "leave images empty. The report already says so; don't repeat it.",
+                ]
+                : [
+                    "You may take screenshots (PNG or JPEG) of public web pages you actually",
+                    `visited${browser.demoUrl === null ? "" : `, and of this project's own UI at \`${inert(browser.demoUrl, 500)}\``}. The browser`,
+                    "opens public web pages only. Open the page with the",
+                    `\`${SCOUT_BROWSER}\` browser, then save its screenshot by its full path in`,
+                    `this folder outside the repository, such as \`${join(browser.folder, "home.png")}\`,`,
+                    "and name it by its plain file name (home.png) in the report. A screenshot",
+                    `saved anywhere else is not kept. At most ${REPORT_LIMITS.images}, each under ${SCREENSHOT_BYTE_CAP / (1024 * 1024)} MB.`,
+                    "Never screenshot a page you did not visit.",
+                ]),
         answeredBlock,
         ...(structured
             ? [
@@ -253,13 +268,28 @@ async function scoutWith(store, request, outputDir) {
     const browserTool = request.browserTool === undefined ? catalogTool("playwright") : request.browserTool;
     const demoUrl = request.demoUrl ?? null;
     let proxy = null;
+    let browserServer = null;
+    let browserProblem = null;
     let invoked;
     try {
         proxy = await startScoutProxy({ demoUrl }).catch(() => null);
-        const browser = proxy === null || !structured ? null : scoutBrowser(browserTool, imageFolder, proxy.url);
+        const launch = proxy === null || !structured ? null : scoutBrowserLaunch(browserTool, imageFolder, proxy.url);
+        // The preflight (run 2356, review 828): the worker starts the browser outside the fence and opens a public page
+        // through the proxy before research begins. One that can't start is said once, in the brief and the report, and
+        // the scout researches without it.
+        const started = launch === null || proxy === null ? null : await browserCheck.starterFor(agent !== undefined)(launch, {
+            env: { ...withoutEnv(process.env, [...AGENT_ENV_DENYLIST, ...PROXY_BYPASS_ENV]), ...scoutProxyEnv(proxy.url) },
+            folder: imageFolder,
+        }).catch((error) => ({ ok: false, reason: error instanceof Error ? error.message : String(error) }));
+        if (started !== null && started.ok)
+            browserServer = started.server;
+        browserProblem = started !== null && !started.ok ? started.reason : null;
+        const browser = browserServer === null ? null : scoutBrowser(browserServer.url);
+        const proxyEnv = proxy === null ? {} : scoutProxyEnv(proxy.url, browserServer?.url ?? null);
+        const briefBrowser = browserProblem !== null ? { problem: browserProblem } : browser === null ? null : { folder: imageFolder, demoUrl };
         invoked = await invokeAgent(store, request.runId, { provider: request.provider ?? "claude", model: request.model ?? null }, {
             phase: "plan",
-            brief: projectSkillContext + scoutBrief(request.taskTitle, request.goal, request.outOfScope, mailbox, reportFile, request.answers ?? [], structured, browser === null ? null : { folder: imageFolder, demoUrl }, proxy !== null),
+            brief: projectSkillContext + scoutBrief(request.taskTitle, request.goal, request.outOfScope, mailbox, reportFile, request.answers ?? [], structured, briefBrowser, proxy !== null),
             maxTurns,
             // Read-only by policy AND by check: `dontAsk` with only research and
             // screenshot tools allowed is the permission posture (plan mode
@@ -275,8 +305,8 @@ async function scoutWith(store, request, outputDir) {
         }, {
             cwd: worktree,
             idleTimeoutMs: timeoutMs,
-            omitEnv: [...AGENT_ENV_DENYLIST, ...(proxy === null ? [] : PROXY_BYPASS_ENV)],
-            ...(proxy === null ? {} : { env: scoutProxyEnv(proxy.url) }),
+            omitEnv: [...AGENT_ENV_DENYLIST, ...(proxy === null ? [] : PROXY_BYPASS_ENV.filter(name => !(name in proxyEnv)))],
+            ...(proxy === null ? {} : { env: proxyEnv }),
             ...(agent === undefined ? {} : { runner: agent }),
             ...(request.onProviderSpawn === undefined ? {} : { onSpawn: request.onProviderSpawn }),
             clock,
@@ -286,6 +316,7 @@ async function scoutWith(store, request, outputDir) {
     finally {
         if (pulseTimer !== undefined)
             clearInterval(pulseTimer);
+        await browserServer?.close();
         await proxy?.close();
         liveLog?.close();
     }
@@ -477,7 +508,8 @@ async function scoutWith(store, request, outputDir) {
             kept.push({ file, caption: image.caption, url, sha256: createHash("sha256").update(checked.bytes).digest("hex"), artifact });
         }
         const files = new Set(kept.map(one => one.file));
-        const note = refused.length === 0 ? "" : `\n\n_Screenshots left out: ${refused.join("; ")}._`;
+        const note = (browserProblem === null ? "" : `\n\n_No screenshots: the browser couldn't start (${browserProblem})._`) +
+            (refused.length === 0 ? "" : `\n\n_Screenshots left out: ${refused.join("; ")}._`);
         const document = note !== "" && Buffer.byteLength(report.report + note, "utf8") <= REPORT_LIMITS.document ? report.report + note : report.report;
         return {
             ...report,
@@ -650,6 +682,12 @@ function scrubbedImageNames(images) {
         return [one.file, name];
     }));
 }
+function withoutEnv(env, names) {
+    const kept = { ...env };
+    for (const name of names)
+        delete kept[name];
+    return kept;
+}
 function cleanup(worktree, names) {
     for (const name of names) {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.21",
+  "version": "0.9.23",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"