toolroll 0.9.20 → 0.9.22

package/dist/operate.js

@@ -180,6 +180,7 @@ import { isDirectChatProvider, isSubscriptionChatProvider, priceOf, PRICED_MODEL
 import { resolvePhaseAgent, resolveScopeProfile, resolveScopeChain, resolveRouteCandidates, routeOfTask, INSTALLATION_SCOPE } from "./agentconfig.js";
 import { isRiskLevel, legOf, projectRoute, riskConsequence, routeDigestOf, routeWords, RISK_LEVELS, PHASES as ROUTE_PHASES } from "./phase-routing.js";
 import { observeProviderReadiness, reportProviderReadinessAuthed } from "./runner.js";
+import { parseDemoUrl, projectDemoUrl, saveProjectDemo } from "./project-demo.js";
 import { effectiveConcurrency, maySlotTake, parseProjectConcurrency, PROJECT_CONCURRENCY_DEFAULT, ProjectPasses, projectConcurrency, saveProjectConcurrency, savedProjectConcurrency } from "./project-concurrency.js";
 import { clearWebhook, effectivePrimary, isMessagingChannel, loadConsoleUrl, loadPrimary, loadWebhookTargets, phoneOrigin, saveConsoleUrl, savePrimary, saveWebhook, webhookPass, SLACK_ENV, DISCORD_ENV } from "./webhooks.js";
 import { auditOf, inspectionOf, isProviderId, MONEY_CAPABILITIES, PROVIDER_IDS, validModelId, validateSpec, ALL_CREDENTIAL_ENV } from "./provider.js";
@@ -233,6 +234,9 @@ export const OPERATE_HELP = `toolroll — operating the queue
   toolroll project concurrency [<n>] --repo <p>
                                         how many of a project's tasks build at once (default 2, never past the
                                         worker's capacity); an approver changes it with <n>
+  toolroll project demo [<url>|off] --repo <p>
+                                        the project's own demo or dev server, the one non-public address a
+                                        report's scout may screenshot
   toolroll task evidence <id>        the task's evidence pack as JSON (--html for a printable page; --out <file>)
   toolroll storage                   where the disk goes: database, build checkouts, releases, evidence, leftover test temp folders
   toolroll storage clean [--yes]     preview removing finished tasks' clean checkouts (their branches stay) and test temp folders older than a day; --yes removes them
@@ -971,6 +975,8 @@ async function dispatch(command, positional, flags, context) {
                 return projectDeleteCommand(positional, flags, context);
             if (positional[0] === "concurrency")
                 return projectConcurrencyCommand(positional, flags, context);
+            if (positional[0] === "demo")
+                return projectDemoCommand(positional, flags, context);
             return runProjectCommand(positional, flags, context);
         case "assignment":
             // The person's own lead (its lead token) claims as the lead; coordinator credentials keep their own path.
@@ -3465,6 +3471,7 @@ async function tickCommand(flags, context) {
                 onProviderSpawn: pid => { worktrees.recordProviderOccupancy(scoutLeased.worktree.path, runner, pid, scoutLeased.worktree.leaseEpoch); },
                 evidenceRoot: context.evidenceRoot,
                 answers: scoutAnswers,
+                demoUrl: projectDemoUrl(context.databaseFile, repo),
                 provider: spec.provider,
                 model: proof.effective.model,
                 ...(proof.effective.maxTurns === undefined ? {} : { maxTurns: proof.effective.maxTurns }),
@@ -12024,6 +12031,40 @@ async function projectConcurrencyCommand(positional, flags, context) {
         ...(changed.before > changed.after ? ["Builds already running carry on; the new number applies to the next one."] : []),
     ]);
 }
+/** `project demo [<url>|off] --repo <p>` (review 827): the project's own demo or dev server, which its scouts may
+ * screenshot. Changing it is an approver's act. */
+async function projectDemoCommand(positional, flags, context) {
+    const command = "project demo";
+    const allowed = new Set(["repo", "as", "token", "token-file", "token-env", "db", "json"]);
+    for (const name of flags.keys())
+        if (!allowed.has(name))
+            return fail(context.write, context.json, command, "usage", `--${name} is not a project demo option.`, EXIT.usage);
+    const repoFlag = text(flags, "repo");
+    if (positional.length > 2 || repoFlag === undefined)
+        return fail(context.write, context.json, command, "usage", "Use project demo [<url>|off] --repo <project path>.", EXIT.usage);
+    const registered = await loadRepos(registryPathOf(context)).catch(() => ({ error: "unreadable" }));
+    const known = [...new Set([...context.store.knownRepos(), ...("error" in registered ? [] : registered.repos)])];
+    const repo = known.find(one => one === repoFlag || one === resolve(repoFlag) || one === canonicalProject(repoFlag));
+    if (repo === undefined)
+        return fail(context.write, context.json, command, "not-found", "That isn't a project Toolroll knows.", EXIT.refused);
+    const words = (url) => url === null ? `${repo}: no demo; scouts screenshot public pages only.` : `${repo}: scouts may also screenshot ${url}.`;
+    const given = positional[1];
+    if (given === undefined) {
+        const current = projectDemoUrl(context.databaseFile, repo);
+        return succeed(context.write, context.json, command, { repo, demoUrl: current }, () => [words(current)]);
+    }
+    const url = given.trim().toLowerCase() === "off" ? null : parseDemoUrl(given);
+    if (url === null && given.trim().toLowerCase() !== "off")
+        return fail(context.write, context.json, command, "usage", "The demo is an http or https address without a sign-in, or off.", EXIT.usage);
+    const acting = await askCredentials(flags, context);
+    const verified = acting === null ? null : authenticateApprover(context.store, acting.name, acting.token);
+    if (acting === null || verified === null || !verified.ok || !context.store.accountCanAccess(acting.name, repo)) {
+        return fail(context.write, context.json, command, "refused", "An approver for this project sets its demo: pass --as and --token (or use the remembered login).", EXIT.refused);
+    }
+    const changed = saveProjectDemo(context.databaseFile, repo, url);
+    context.store.recordProjectDemo(acting.name, repo, changed.before, changed.after, context.clock());
+    return succeed(context.write, context.json, command, { repo, before: changed.before, demoUrl: changed.after }, () => [words(changed.after)]);
+}
 /** Write a pack or export where asked (never over an existing file), or to the terminal. */
 function writeOut(context, command, out, content, summary, line, data) {
     if (out === undefined) {

package/dist/project-delete.js

@@ -216,6 +216,8 @@ function deleteRows(store, repo, d, now) {
         del(`${surface}_action`, IN("proposal"), proposals);
         del(`${surface}_flow_action`, IN("card"), C);
         del(`${surface}_flow_prompt`, IN("card"), C);
+        del(`${surface}_flow_choice`, IN("card"), C);
+        del(`${surface}_flow_note`, IN("card"), C);
         del(`${surface}_question_action`, IN("question"), questions);
         del(`${surface}_question_prompt`, IN("question"), questions);
         del(`${surface}_ask_action`, IN("turn"), U);
@@ -226,6 +228,8 @@ function deleteRows(store, repo, d, now) {
     del("telegram_proposal_action", IN("proposal"), proposals);
     del("telegram_flow_action", IN("card"), C);
     del("telegram_flow_prompt", IN("card"), C);
+    del("telegram_flow_choice", IN("card"), C);
+    del("flow_send", IN("card"), C);
     del("telegram_question_action", IN("question"), questions);
     del("telegram_question_prompt", IN("question"), questions);
     del("chat_decide_action", IN("task_id"), K);

package/dist/project-demo.d.ts

@@ -0,0 +1,12 @@
+export declare const projectDemoPath: (databaseFile: string) => string;
+/** A demo URL as typed: an http(s) address with no sign-in details, at most 500 characters, or null. */
+export declare function parseDemoUrl(value: string): string | null;
+/** Every saved demo URL, by canonical project path. An unreadable file reads as none saved. */
+export declare function savedProjectDemos(databaseFile: string): Map<string, string>;
+/** The project's demo URL, or null when it has none. */
+export declare function projectDemoUrl(databaseFile: string, repo: string): string | null;
+/** Save (or, with null, clear) one project's demo URL atomically; returns it before and after. */
+export declare function saveProjectDemo(databaseFile: string, repo: string, url: string | null): {
+    before: string | null;
+    after: string | null;
+};

package/dist/project-demo.js

@@ -0,0 +1,71 @@
+/**
+ * A project's own demo or dev server (review 827): the one address a scout
+ * may reach that is not on the public internet, so it can take screenshots
+ * of the project's UI. An approver sets it with
+ * `toolroll project demo --repo <p> <url>|off`; it is kept in a small file
+ * beside the database, like a project's builds-at-once number, and recorded
+ * in the ledger as before → after. A project without one has none.
+ */
+import { lstatSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname, join } from "node:path";
+export const projectDemoPath = (databaseFile) => join(dirname(databaseFile), "project-demo.json");
+/** A demo URL as typed: an http(s) address with no sign-in details, at most 500 characters, or null. */
+export function parseDemoUrl(value) {
+    const typed = value.trim();
+    if (typed === "" || typed.length > 500)
+        return null;
+    try {
+        const url = new URL(typed);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return null;
+        if (url.username !== "" || url.password !== "")
+            return null;
+        return url.href;
+    }
+    catch {
+        return null;
+    }
+}
+/** Every saved demo URL, by canonical project path. An unreadable file reads as none saved. */
+export function savedProjectDemos(databaseFile) {
+    const saved = new Map();
+    const file = projectDemoPath(databaseFile);
+    try {
+        const stat = lstatSync(file, { throwIfNoEntry: false });
+        if (stat === undefined || !stat.isFile() || stat.size > 262_144)
+            return saved;
+        const value = JSON.parse(readFileSync(file, "utf8"));
+        const projects = value !== null && typeof value === "object" ? value.projects : undefined;
+        if (projects === null || typeof projects !== "object")
+            return saved;
+        for (const [repo, url] of Object.entries(projects)) {
+            const parsed = typeof url === "string" ? parseDemoUrl(url) : null;
+            if (parsed !== null)
+                saved.set(repo, parsed);
+        }
+    }
+    catch {
+        // A damaged file never stops a scout: it simply has no demo to open.
+    }
+    return saved;
+}
+/** The project's demo URL, or null when it has none. */
+export function projectDemoUrl(databaseFile, repo) {
+    return savedProjectDemos(databaseFile).get(repo) ?? null;
+}
+/** Save (or, with null, clear) one project's demo URL atomically; returns it before and after. */
+export function saveProjectDemo(databaseFile, repo, url) {
+    const saved = savedProjectDemos(databaseFile);
+    const before = saved.get(repo) ?? null;
+    if (url === null)
+        saved.delete(repo);
+    else
+        saved.set(repo, url);
+    const file = projectDemoPath(databaseFile);
+    const temp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(temp, `${JSON.stringify({ version: 1, projects: Object.fromEntries([...saved].sort(([a], [b]) => a.localeCompare(b))) }, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    renameSync(temp, file);
+    return { before, after: url };
+}

package/dist/provider.d.ts

@@ -72,6 +72,12 @@ export type Invocation = {
      * report rides the terminal result event instead of a file plan mode
      * would refuse to write. Ignored by providers without `--json-schema`. */
     jsonSchema?: Readonly<Record<string, unknown>>;
+    /** Claude tools allowed without asking, for a `dontAsk` launch: the scout's
+     * research and screenshot tools, and nothing that edits or runs commands. */
+    allowedTools?: readonly string[];
+    /** More MCP servers for this launch only, beside the project's own (the
+     * scout's headless browser). Claude-only; ignored for a review. */
+    extraMcpServers?: Readonly<Record<string, unknown>>;
 };
 export type ProviderRunner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
 /** The harness's own account of how a turn ended. */

package/dist/provider.js

@@ -229,7 +229,10 @@ const claudeArgv = (invocation) => [
             // Headless (run 2085): a wakeup, cron job or monitor needs a later
             // turn that a -p process never gets. Denied at the harness too.
             "--disallowedTools", HEADLESS_DISALLOWED_TOOLS.join(","),
-            ...(invocation.toolArgv ?? []), ...(invocation.fence !== undefined && invocation.fence.length > 0 ? ["--settings", claudeFenceSettings(invocation.fence)] : []),
+            ...(invocation.allowedTools === undefined || invocation.allowedTools.length === 0 ? [] : ["--allowedTools", invocation.allowedTools.join(",")]),
+            ...(invocation.toolArgv ?? []),
+            ...(invocation.extraMcpServers === undefined ? [] : ["--mcp-config", JSON.stringify({ mcpServers: invocation.extraMcpServers })]),
+            ...(invocation.fence !== undefined && invocation.fence.length > 0 ? ["--settings", claudeFenceSettings(invocation.fence)] : []),
             ...(invocation.jsonSchema === undefined ? [] : ["--json-schema", JSON.stringify(invocation.jsonSchema)])
         ]),
 ];

package/dist/report-summary.d.ts

@@ -1,4 +1,5 @@
 import type { Store } from "./store.js";
+import type { ParsedReport } from "./scout-report.js";
 /** The report a scout delivered, for get_task: title, summary, follow-ups —
  * verified before it is read; the document itself stays on the task page. */
 export declare function reportSummaryFor(store: Store, evidenceRoot: string | undefined, taskRef: number): {
@@ -11,3 +12,11 @@ export declare function reportSummaryFor(store: Store, evidenceRoot: string | un
 } | {
     problem: string;
 } | null;
+/** The longest full report a later flow step is given through {{stage.<id>.report}}. */
+export declare const REPORT_FILL_LIMIT = 20000;
+/** What a report zone gives the zones after it besides its summary: its items as a numbered list (title, why, URL)
+ * and the report's markdown, capped. Empty strings when it has neither. */
+export declare function reportFillIns(report: Pick<ParsedReport, "items" | "report">): {
+    items: string;
+    report: string;
+};

package/dist/report-summary.js

@@ -13,3 +13,12 @@ export function reportSummaryFor(store, evidenceRoot, taskRef) {
         return { problem: view.problem };
     return { title: view.report.title, summary: view.report.summary, followUps: view.report.followUps };
 }
+/** The longest full report a later flow step is given through {{stage.<id>.report}}. */
+export const REPORT_FILL_LIMIT = 20_000;
+/** What a report zone gives the zones after it besides its summary: its items as a numbered list (title, why, URL)
+ * and the report's markdown, capped. Empty strings when it has neither. */
+export function reportFillIns(report) {
+    const items = report.items.map((one, index) => `${index + 1}. ${one.title}\n   ${one.why.replace(/\s*\n\s*/g, " ")}\n   ${one.url}`).join("\n");
+    const document = report.report.length <= REPORT_FILL_LIMIT ? report.report : `${report.report.slice(0, REPORT_FILL_LIMIT)}\n… (the rest of the report is on its task)`;
+    return { items, report: document };
+}

package/dist/result-shots.d.ts

@@ -39,6 +39,8 @@ export type ResultShotsPlan =
  * no wait in between, or asks again.
  */
 export declare function resultShotsFor(store: Store, evidenceRoot: string | undefined, repos: readonly string[], row: Pick<Notification, "kind" | "recipient" | "taskId" | "taskRef" | "run">, sent?: ReadonlySet<number>): ResultShotsPlan;
+/** A row that carries a result's screenshots: one a person asked for with results, or one a flow sends them. */
+export declare function isShotsKind(kind: string): boolean;
 /** A screenshot whose result message is not posted yet waits for that message's own next try (at least a second). */
 export declare function shotWaitsUntil(resultNextAt: unknown, now: Date): string;
 /** Retention removed this result's files: its screenshots go quietly, never as a complaint. */

package/dist/result-shots.js

@@ -15,11 +15,11 @@
  */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { imageDimensions, readVerifiedProofForRun, RETENTION_NOTE } from "./evidence.js";
+import { imageDimensions, readVerifiedProofForRun, readVerifiedReport, RETENTION_NOTE } from "./evidence.js";
 import { resultImageFileName, verifyResultImage } from "./chat-evidence.js";
 import { publicChatText } from "./chat-display.js";
 import { chatTitle } from "./chat-voice.js";
-import { RESULT_SHOTS_KIND } from "./store.js";
+import { FLOW_SHOTS_KIND, RESULT_SHOTS_KIND } from "./store.js";
 /** "Up to 4": the most screenshots one result ever sends. */
 export const RESULT_SHOTS_MAX = 4;
 /** The choices in the order Settings and the CLI show them. */
@@ -45,6 +45,19 @@ function ownCaptions(store, root, run) {
     }
     return captions;
 }
+/** A scout's screenshots keep the captions its report gave them, by evidence id. */
+function reportCaptions(store, root, taskRef, run) {
+    const captions = new Map();
+    const view = readVerifiedReport(store, root, taskRef);
+    if (view === null || !view.ok || view.run !== run)
+        return captions;
+    for (const image of view.report.images) {
+        const words = publicChatText(image.caption, 200).trim();
+        if (image.artifact !== undefined && words !== "" && !words.includes("[sensitive text hidden]"))
+            captions.set(image.artifact, words);
+    }
+    return captions;
+}
 function isPhoto(bytes, format) {
     const size = imageDimensions(bytes, format);
     if (size === null || size.width === 0 || size.height === 0)
@@ -59,9 +72,10 @@ function isPhoto(bytes, format) {
  * no wait in between, or asks again.
  */
 export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()) {
-    if (row.kind !== RESULT_SHOTS_KIND || row.recipient === null || row.taskId === null || row.taskRef === null || row.run === null)
+    if (!isShotsKind(row.kind) || row.recipient === null || row.taskId === null || row.taskRef === null || row.run === null)
         return { kind: "none", why: "none" };
-    const limit = resultShotLimit(store.notificationPreference(row.recipient).screenshots);
+    // A flow's "Send to me" or "Person chooses" asked for them: up to four, whatever the person chose for results.
+    const limit = row.kind === FLOW_SHOTS_KIND ? RESULT_SHOTS_MAX : resultShotLimit(store.notificationPreference(row.recipient).screenshots);
     if (limit === 0)
         return { kind: "none", why: "off" };
     const title = chatTitle(store, row.taskId);
@@ -82,6 +96,7 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
     if (chosen.length === 0)
         return { kind: "none", why: "none" };
     const captions = ownCaptions(store, evidenceRoot, row.run);
+    const reported = latest.role === "scout" ? reportCaptions(store, evidenceRoot, row.taskRef, row.run) : new Map();
     const shots = [];
     for (const [index, artifact] of chosen.entries()) {
         const verified = verifyResultImage(store, evidenceRoot, repos, { taskId: row.taskId, run: row.run, artifact: artifact.id, sha256: artifact.sha256 });
@@ -91,7 +106,7 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
                 return { kind: "none", why: "pruned" };
             return line(verified.problem);
         }
-        const own = captions.get(SCREENSHOT_CAPTURE.exec(artifact.capture)?.[1] ?? "") ?? null;
+        const own = captions.get(SCREENSHOT_CAPTURE.exec(artifact.capture)?.[1] ?? "") ?? reported.get(artifact.id) ?? null;
         shots.push({
             artifact: artifact.id, sha256: artifact.sha256, bytes: verified.bytes, format: verified.format,
             fileName: resultImageFileName(row.taskId, row.run, artifact.id, verified.format),
@@ -102,6 +117,10 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
     const remaining = shots.filter(one => !sent.has(one.artifact));
     return remaining.length === 0 ? { kind: "none", why: "sent" } : { kind: "send", taskId: row.taskId, run: row.run, shots: remaining };
 }
+/** A row that carries a result's screenshots: one a person asked for with results, or one a flow sends them. */
+export function isShotsKind(kind) {
+    return kind === RESULT_SHOTS_KIND || kind === FLOW_SHOTS_KIND;
+}
 /** A screenshot whose result message is not posted yet waits for that message's own next try (at least a second). */
 export function shotWaitsUntil(resultNextAt, now) {
     const soonest = new Date(now.getTime() + 1_000).toISOString();

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-net.d.ts

@@ -0,0 +1,22 @@
+import { type Socket } from "node:net";
+/** Whether an IP literal is a public internet address. IPv4 inside IPv6 (mapped, compatible or NAT64) is judged as IPv4. */
+export declare function isPublicAddress(address: string): boolean;
+export type Lookup = (host: string) => Promise<readonly string[]>;
+/**
+ * A connection to the first of the checked addresses that answers, tried in turn (review 827): a host whose IPv6
+ * address is unreachable from here is still reached over IPv4. Null when none answers.
+ */
+export declare function connectFirst(addresses: readonly string[], port: number, timeoutMs?: number): Promise<Socket | null>;
+export type ScoutProxy = {
+    url: string;
+    close: () => Promise<void>;
+};
+/**
+ * Start the scout browser's proxy on loopback. `refused` hears every request it turned away (for the live log and
+ * tests). `lookup` resolves a host name to its addresses (the system resolver unless a test supplies one).
+ */
+export declare function startScoutProxy(options?: {
+    demoUrl?: string | null;
+    lookup?: Lookup;
+    refused?: (target: string, why: string) => void;
+}): Promise<ScoutProxy>;