toolroll 0.9.20 → 0.9.21

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-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>;

package/dist/scout-net.js

@@ -0,0 +1,214 @@
+/**
+ * The scout reaches only the public web (reviews 826, 827): every request
+ * its browser and its web fetch make goes through this local proxy, which resolves the host
+ * itself and refuses anything that is not a public internet address —
+ * loopback, private, link-local, carrier-grade NAT, multicast and reserved
+ * ranges, in IPv4 and IPv6 — then connects to the very addresses it
+ * checked, each in turn until one answers, so a name that re-resolves
+ * somewhere private gets nowhere. The one
+ * exception is the project's own demo URL, when one is set, matched by its
+ * exact scheme, host and port. Redirects and a page's own requests pass
+ * through the same check; file: never reaches a proxy, and the pinned
+ * Playwright refuses to open it.
+ */
+import { createServer, request as httpRequest } from "node:http";
+import { BlockList, connect, isIP } from "node:net";
+import { lookup as dnsLookup } from "node:dns/promises";
+/** Address ranges a scout's browser may never reach. */
+const NOT_PUBLIC = (() => {
+    const list = new BlockList();
+    for (const [net, prefix] of [
+        ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8], ["169.254.0.0", 16], ["172.16.0.0", 12],
+        ["192.0.0.0", 24], ["192.0.2.0", 24], ["192.88.99.0", 24], ["192.168.0.0", 16], ["198.18.0.0", 15], ["198.51.100.0", 24],
+        ["203.0.113.0", 24], ["224.0.0.0", 4], ["240.0.0.0", 4],
+    ])
+        list.addSubnet(net, prefix, "ipv4");
+    for (const [net, prefix] of [
+        ["::", 128], ["::1", 128], ["64:ff9b:1::", 48], ["100::", 64], ["2001::", 23], ["2001:db8::", 32], ["fc00::", 7], ["fe80::", 10], ["fec0::", 10], ["ff00::", 8],
+    ])
+        list.addSubnet(net, prefix, "ipv6");
+    return list;
+})();
+/** Whether an IP literal is a public internet address. IPv4 inside IPv6 (mapped, compatible or NAT64) is judged as IPv4. */
+export function isPublicAddress(address) {
+    const bare = address.replace(/^\[|\]$/g, "").replace(/%.*$/, "");
+    const family = isIP(bare);
+    if (family === 4)
+        return !NOT_PUBLIC.check(bare, "ipv4");
+    if (family !== 6)
+        return false;
+    const embedded = /^(?:::ffff:(?:0:)?|::|64:ff9b::)(\d+\.\d+\.\d+\.\d+)$/i.exec(bare)?.[1];
+    if (embedded !== undefined)
+        return isPublicAddress(embedded);
+    const mappedHex = /^(?:::ffff:|64:ff9b::)([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(bare);
+    if (mappedHex !== null) {
+        const high = parseInt(mappedHex[1], 16);
+        const low = parseInt(mappedHex[2], 16);
+        return isPublicAddress(`${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`);
+    }
+    if (/^::ffff:/i.test(bare))
+        return false;
+    return !NOT_PUBLIC.check(bare, "ipv6");
+}
+const systemLookup = async (host) => (await dnsLookup(host, { all: true, verbatim: true })).map(one => one.address);
+/** The demo URL's own origin, or null when none is set or it is not an http(s) address. */
+function demoTarget(demoUrl) {
+    if (demoUrl === undefined || demoUrl === null || demoUrl === "")
+        return null;
+    try {
+        const url = new URL(demoUrl);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return null;
+        const scheme = url.protocol === "http:" ? "http" : "https";
+        return { scheme, host: url.hostname.toLowerCase(), port: Number(url.port || (scheme === "http" ? 80 : 443)) };
+    }
+    catch {
+        return null;
+    }
+}
+/** How long one address may take to answer before the next is tried. */
+const CONNECT_TIMEOUT_MS = 10_000;
+/**
+ * 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 async function connectFirst(addresses, port, timeoutMs = CONNECT_TIMEOUT_MS) {
+    for (const address of addresses) {
+        const socket = await new Promise(done => {
+            const attempt = connect({ host: address, port });
+            const give = (value) => {
+                attempt.removeAllListeners("connect").removeAllListeners("error").removeAllListeners("timeout");
+                attempt.setTimeout(0);
+                if (value === null)
+                    attempt.destroy();
+                done(value);
+            };
+            attempt.setTimeout(timeoutMs);
+            attempt.once("connect", () => give(attempt));
+            attempt.once("error", () => give(null));
+            attempt.once("timeout", () => give(null));
+        });
+        if (socket !== null)
+            return socket;
+    }
+    return null;
+}
+/**
+ * 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 async function startScoutProxy(options = {}) {
+    const lookup = options.lookup ?? systemLookup;
+    const demo = demoTarget(options.demoUrl);
+    const sockets = new Set();
+    /** The addresses this request may reach, in the resolver's order, or why it may not. */
+    const resolve = async (target) => {
+        const host = target.host.replace(/^\[|\]$/g, "").toLowerCase();
+        const isDemo = demo !== null && demo.scheme === target.scheme && demo.host.replace(/^\[|\]$/g, "") === host && demo.port === target.port;
+        let addresses;
+        try {
+            addresses = isIP(host) !== 0 ? [host] : await lookup(host);
+        }
+        catch {
+            return { ok: false, why: "the host does not resolve" };
+        }
+        if (addresses.length === 0)
+            return { ok: false, why: "the host does not resolve" };
+        if (isDemo)
+            return { ok: true, addresses };
+        if (!addresses.every(isPublicAddress))
+            return { ok: false, why: "not a public internet address" };
+        return { ok: true, addresses };
+    };
+    const refuse = (target, why) => {
+        try {
+            options.refused?.(target, why);
+        }
+        catch { /* a listener's trouble is not the browser's */ }
+    };
+    const server = createServer((incoming, outgoing) => {
+        void (async () => {
+            let url;
+            try {
+                url = new URL(incoming.url ?? "");
+            }
+            catch {
+                outgoing.writeHead(400).end();
+                return;
+            }
+            if (url.protocol !== "http:") {
+                refuse(url.protocol, "only web pages");
+                outgoing.writeHead(403, { "content-type": "text/plain" }).end("Toolroll's scout browser opens only public web pages.");
+                return;
+            }
+            const target = { scheme: "http", host: url.hostname, port: Number(url.port || 80) };
+            const reached = await resolve(target);
+            if (!reached.ok) {
+                refuse(url.origin, reached.why);
+                outgoing.writeHead(403, { "content-type": "text/plain" }).end("Toolroll's scout browser opens only public web pages.");
+                return;
+            }
+            const upstream = await connectFirst(reached.addresses, target.port);
+            if (upstream === null) {
+                outgoing.writeHead(502).end();
+                return;
+            }
+            sockets.add(upstream);
+            upstream.on("close", () => sockets.delete(upstream));
+            const headers = { ...incoming.headers };
+            delete headers["proxy-connection"];
+            delete headers["proxy-authorization"];
+            const forward = httpRequest({ createConnection: () => upstream, method: incoming.method, path: `${url.pathname}${url.search}`, headers, setHost: false }, answer => {
+                outgoing.writeHead(answer.statusCode ?? 502, answer.headers);
+                answer.pipe(outgoing);
+            });
+            forward.on("error", () => { if (!outgoing.headersSent)
+                outgoing.writeHead(502); outgoing.end(); });
+            incoming.pipe(forward);
+        })();
+    });
+    server.on("connect", (incoming, client, head) => {
+        sockets.add(client);
+        client.on("close", () => sockets.delete(client));
+        client.on("error", () => client.destroy());
+        void (async () => {
+            const match = /^(\[[0-9a-fA-F:.]+\]|[^:[\]]+):(\d{1,5})$/.exec(incoming.url ?? "");
+            const target = match === null ? null : { scheme: "https", host: match[1], port: Number(match[2]) };
+            const reached = target === null ? { ok: false, why: "not a host and port" } : await resolve(target);
+            if (!reached.ok) {
+                refuse(incoming.url ?? "", reached.why);
+                client.end("HTTP/1.1 403 Forbidden\r\nContent-Length: 0\r\n\r\n");
+                return;
+            }
+            const upstream = await connectFirst(reached.addresses, target.port);
+            if (upstream === null) {
+                if (!client.destroyed)
+                    client.end("HTTP/1.1 502 Bad Gateway\r\nContent-Length: 0\r\n\r\n");
+                return;
+            }
+            sockets.add(upstream);
+            upstream.on("close", () => { sockets.delete(upstream); client.destroy(); });
+            upstream.on("error", () => client.destroy());
+            client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+            if (head.length > 0)
+                upstream.write(head);
+            upstream.pipe(client);
+            client.pipe(upstream);
+        })();
+    });
+    server.on("connection", socket => { sockets.add(socket); socket.on("close", () => sockets.delete(socket)); });
+    await new Promise((done, fail) => {
+        server.once("error", fail);
+        server.listen(0, "127.0.0.1", () => { server.off("error", fail); done(); });
+    });
+    const address = server.address();
+    const port = typeof address === "object" && address !== null ? address.port : 0;
+    return {
+        url: `http://127.0.0.1:${port}`,
+        close: () => new Promise(done => {
+            for (const socket of sockets)
+                socket.destroy();
+            server.close(() => done());
+        }),
+    };
+}

package/dist/scout-report.d.ts

@@ -20,6 +20,24 @@ export type ParsedReport = {
         title: string;
         goal: string;
     }[];
+    /** What the scout found, as a short list later steps can read: each cites its URL, and may show one of `images`. */
+    items: ReportItem[];
+    /** Screenshots the scout saved during the run. From the scout, `file` names a file in its output folder; once
+     * stored, the runner adds the bytes' sha256 and the evidence row that holds them. */
+    images: ReportImage[];
+};
+export type ReportItem = {
+    title: string;
+    why: string;
+    url: string;
+    image: string | null;
+};
+export type ReportImage = {
+    file: string;
+    caption: string;
+    url: string;
+    sha256?: string;
+    artifact?: number;
 };
 export type ReportParseResult = {
     ok: true;
@@ -38,7 +56,15 @@ export declare const REPORT_LIMITS: {
     readonly followUps: 5;
     readonly followUpTitle: 200;
     readonly followUpGoal: 2000;
+    readonly items: 6;
+    readonly itemTitle: 200;
+    readonly itemWhy: 1000;
+    readonly url: 2000;
+    readonly images: 8;
+    readonly caption: 300;
 };
+/** A screenshot's name in the scout's output folder: one plain file name, PNG or JPEG, never a path. */
+export declare const REPORT_IMAGE_FILE: RegExp;
 /**
  * The scout's handback for Claude's `--json-schema` (run 2334's fix): plan
  * mode only lets a session write its own plan file, so a Claude scout
@@ -82,6 +108,47 @@ export declare const SCOUT_OUTPUT_JSON_SCHEMA: {
                         readonly additionalProperties: false;
                     };
                 };
+                readonly items: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly title: {
+                                readonly type: "string";
+                            };
+                            readonly why: {
+                                readonly type: "string";
+                            };
+                            readonly url: {
+                                readonly type: "string";
+                            };
+                            readonly image: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["title", "why", "url"];
+                        readonly additionalProperties: false;
+                    };
+                };
+                readonly images: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly file: {
+                                readonly type: "string";
+                            };
+                            readonly caption: {
+                                readonly type: "string";
+                            };
+                            readonly url: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["file", "caption", "url"];
+                        readonly additionalProperties: false;
+                    };
+                };
             };
             readonly required: readonly ["title", "summary", "report"];
             readonly additionalProperties: false;