@reticlehq/server 3.5.0 → 3.7.0

package/dist/language/flows/verify-change-tools.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { sessionRoot, sessionProjectId } from '../../memory/project/session-root.js';
 import { verdictForSuite } from '../../judgement/outcome/verify-change-verdict.js';
 import { attributedFailures } from '../../judgement/outcome/attributed-failure.js';
-import { Verified } from '@reticlehq/core';
+import { Verified, isAdvisory } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { workerCountSchema } from '../../surface/tools/args/numeric-bounds.js';
@@ -10,207 +10,217 @@ import { loadNamedFlows, resolveChangedFiles } from '../../command/cli/cli-flow-
 import { projectDirFor } from '../../memory/project/session-root.js';
 import { affectedSavedFlows } from './change/flow-sources.js';
 import { FLOW_TOOLS } from './flow-tools.js';
+import { RESULT_FIELD, changeResult } from '../../surface/tools/reticle-result.js';
 import { findContradictions } from '@reticlehq/engine/disagreement/contradictions.js';
 import { parseControls } from '../../surface/tools/coverage-tools.js';
 import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
-export const VERIFY_CHANGE_TOOLS = [
-    {
-        name: ReticleTool.VERIFY_CHANGE,
-        description: 'Did my change break anything? Give it the files you edited (or `since` for a git ref) and it works out which saved flows cover them, replays exactly those, and answers with one `verified` (yes|no|unknown) plus `because`. `unknown` when NO saved flow covers the change — that is the honest answer, never a green: nothing ran, so nothing was proved. Returns { verified, because, changedFiles, flowsRun, suite, unknownProvenance }.',
-        example: { files: ['src/App.tsx'] },
-        inputSchema: {
-            files: z
-                .array(z.string())
-                .optional()
-                .describe('Changed file paths, repo-relative (e.g. ["src/App.tsx"]).'),
-            since: z
-                .string()
-                .optional()
-                .describe('Git ref to diff against (e.g. "HEAD~1", "main"). Unioned with `files`.'),
-            parallel: workerCountSchema
-                .optional()
-                .describe('Replay this many affected flows at once (needs the browser pool).'),
-            sessionId: z
-                .string()
-                .optional()
-                .describe('OMIT THIS unless you mean a specific tab — Reticle resolves it.'),
-        },
-        outputSchema: {
-            verified: z
-                .string()
-                .describe('yes | no | unknown. `unknown` means the evidence could not decide — most often that no saved flow covers these files, which is NOT a pass.'),
-            because: z.string(),
-            changedFiles: z.array(z.string()),
-            flowsRun: z.array(z.string()),
-            suite: z.unknown().optional(),
-            // Session-EXEMPT: declare the one-shot human feedback ask or a validating profile strips it.
-            feedback_prompt: z.unknown().optional(),
-            unknownProvenance: z.array(z.string()),
-            contradictions: z
-                .array(z.unknown())
-                .optional()
-                .describe('Channels that disagreed DURING the replay. Any entry forces verified:"no" even when every flow passed — a suite that goes green over a failed write is the false green this exists to catch. OMITTED when clean; see `measured` when it could not be looked for.'),
-            untouched: z
-                .array(z.unknown())
-                .optional()
-                .describe('Controls on the page that the covering flows never drove. A green over a small untouched list is stronger evidence than the same green over a large one.'),
-            measured: z
-                .array(z.string())
-                .describe('What was actually looked for. An absent `contradictions` means "none found" ONLY if "contradictions" appears here — otherwise it was never measured.'),
-        },
-        handler: async (deps, args) => {
-            const files = Array.isArray(args['files'])
-                ? args['files'].filter((f) => 'string' === typeof f)
-                : [];
-            const since = asString(args['since']);
-            // The tree to diff is the SESSION's project, and it is neither of the two things this line
-            // used to say it was: `deps.reticleRoot` is the daemon's `.reticle` SUBDIRECTORY, and the
-            // daemon's cwd is wherever the MCP host started it — `/` or `$HOME` for a globally-registered
-            // server. Both answer about the wrong repository while reporting a clean "nothing changed",
-            // which reads as a pass. `projectDirFor` is the directory holding the resolved root.
-            const changed = await resolveChangedFiles(files, since, projectDirFor(deps, asString(args['sessionId'])));
-            const changedFiles = changed.files;
-            // Same root flow_save wrote to. A read that resolved differently would report "no flows
-            // covered this change" over flows that exist, which reads as a clean result rather than
-            // an error, so the disagreement would be invisible.
-            // Both halves of the address from one place. The root was already resolved from the session;
-            // the id used to come from the daemon's cwd, so they named different projects.
-            const sid = asString(args['sessionId']);
-            const flows = await loadNamedFlows(deps.fs, sessionRoot(deps, sid), sessionProjectId(deps, sid));
-            const { affected, unknownProvenance } = affectedSavedFlows(flows, changedFiles);
-            if (0 === changedFiles.length) {
-                return {
-                    verified: Verified.UNKNOWN,
-                    // A git failure and a clean tree both arrive here with no files, and they are opposite
-                    // answers: one means there was nothing to decide about, the other means the question was
-                    // never asked. `unknown` is right either way, but the REASON is what the caller acts on.
-                    because: changed.failed
-                        ? `could not read the diff for \`${String(since)}\`, so nothing was compared: ${changed.reason ?? 'git failed'}`
-                        : 'no changed files were given, so there was nothing to decide about',
-                    changedFiles,
-                    flowsRun: [],
-                    unknownProvenance,
-                    // Nothing was looked for, and the schema requires this field to say so. Omitting it made
-                    // the MCP layer reject the whole response, turning an honest UNKNOWN into a protocol error.
-                    measured: [],
-                };
-            }
-            // The guard: an uncovered change is UNKNOWN. Reporting `yes` here would mean "your change is
-            // fine" on the strength of having run nothing at all.
-            if (0 === affected.length) {
-                return {
-                    verified: Verified.UNKNOWN,
-                    /*
-                     * The way out named here has to be one the CALLER can take.
-                     *
-                     * This used to say "record one with reticle_record { action: start } then
-                     * reticle_flow_save". Neither is advertised on the default surface, and that surface has
-                     * no dispatch hatch — so the honest answer to "nothing covers this change" ended in two
-                     * calls that come back "Tool not found". Driving is reachable from every surface, and a
-                     * drive is captured as a flow automatically at teardown, so it is also the instruction
-                     * that makes the NEXT change to these files replay instead of drive.
-                     */
-                    because: `no saved flow covers ${1 === changedFiles.length ? 'this file' : 'these files'} — nothing ran, so nothing is proved. Drive it and prove it directly; the drive is saved as a flow, so the next change here replays instead`,
-                    changedFiles,
-                    flowsRun: [],
-                    unknownProvenance,
-                    // No flow ran, so nothing was measured — said explicitly rather than left undefined.
-                    measured: [],
-                };
-            }
-            const provenanceNote = unknownProvenance.length > 0
-                ? ` (${String(unknownProvenance.length)} of them re-run only because Reticle cannot tell which sources they cover)`
-                : '';
-            // Marked BEFORE the replay so the contradiction sweep afterwards reads exactly the window the
-            // flows produced, and never events from whatever the agent did before calling this.
-            const cursor = cursorBeforeReplay(deps, args);
-            const verify = FLOW_TOOLS.find((tool) => tool.name === ReticleTool.FLOW_VERIFY);
-            if (verify === undefined)
-                throw new Error('the whole-suite replay tool is not registered');
-            const suite = asRecord(await verify.handler(deps, {
-                names: affected,
-                ...(asNumber(args['parallel']) === undefined ? {} : { parallel: args['parallel'] }),
-                ...(asString(args['sessionId']) === undefined ? {} : { sessionId: args['sessionId'] }),
-            }));
-            const failed = suite.failed ?? 0;
-            const passed = suite.passed ?? 0;
-            // `unverifiable` is NOT a failure — the suite ran and proved nothing, which is the same fact
-            // this tool answers UNKNOWN for an uncovered change. Treating it as a red emitted a bug_found
-            // that nothing earned. See verify-change-verdict.
-            const verdict = verdictForSuite(String(suite.status), failed);
-            // A NO must be EARNED by a failing flow genuinely tied to the changed files. `affectedSavedFlows`
-            // re-runs any flow whose sources it cannot determine — over-running beats skipping — and those
-            // land in `unknownProvenance`. Judging the change on them produced a negative verdict whose own
-            // explanation admitted the evidence was not tied to the file. See attributed-failure.
-            const failingNames = Array.isArray(suite.failures)
-                ? suite.failures
-                    .map((f) => 'object' === typeof f && f !== null ? asString(asRecord(f)['flow']) : undefined)
-                    .filter((n) => n !== undefined)
-                : // No per-failure detail: the failure is somewhere in the set that ran, so ask the question
-                    // of all of them rather than guessing which.
-                    affected;
-            const attributed = attributedFailures(failingNames, unknownProvenance);
-            const earnedNo = verdict === Verified.NO && attributed.length > 0;
-            const reported = verdict === Verified.NO && !earnedNo ? Verified.UNKNOWN : verdict;
-            if (reported !== Verified.YES) {
-                return {
-                    verified: reported,
-                    because: earnedNo
-                        ? `${String(failed)} of ${String(suite.total ?? affected.length)} covering flows failed, including ${attributed.join(', ')}, which cover the changed files${provenanceNote}`
-                        : verdict === Verified.NO
-                            ? `flows failed, but Reticle cannot tell which sources any of them cover (${failingNames.join(', ')}) — so this says nothing about the files you changed. Re-record them so their sources are stamped, or read the replay yourself`
-                            : `the covering flows ran but proved nothing (${String(suite.status)}) — they assert no observable consequence, so a green from them would not have meant your change is safe${provenanceNote}`,
-                    changedFiles,
-                    flowsRun: affected,
-                    suite,
-                    unknownProvenance,
-                    measured: ['flows'],
-                };
-            }
-            // The suite went green. That is exactly when the remaining two channels are worth reading:
-            // a replay that passes while a write fails is the false green this whole product is about.
-            const extra = await inspectAfterReplay(deps, args, cursor);
-            if (extra.contradictions.length > 0) {
-                const kinds = extra.contradictions.map((c) => c.kind).join(', ');
-                const earned = attributedFailures(affected, unknownProvenance).length > 0;
-                return {
-                    verified: earned ? Verified.NO : Verified.UNKNOWN,
-                    because: earned
-                        ? `every covering flow passed, but channels disagreed during the replay (${kinds}) — a green suite over a failed write is the false green worth looking at${provenanceNote}`
-                        : `channels disagreed during the replay (${kinds}), but Reticle cannot tell which sources any of the flows that ran cover (${affected.join(', ')}), so this says nothing about the files you changed. Drive the change directly; the drive is saved as a flow with its sources stamped`,
-                    changedFiles,
-                    flowsRun: affected,
-                    suite,
-                    unknownProvenance,
-                    contradictions: extra.contradictions,
-                    ...(extra.untouched === undefined ? {} : { untouched: extra.untouched }),
-                    measured: extra.measured,
-                };
-            }
-            // The mirror of `earnedNo`: a green from flows that ran only because their sources are unknown
-            // says nothing about these files either. At least one attributed flow has to have passed.
-            if (0 === attributedFailures(affected, unknownProvenance).length) {
-                return {
-                    verified: Verified.UNKNOWN,
-                    because: `the flows that ran passed, but Reticle cannot tell which sources any of them cover (${affected.join(', ')}), so this says nothing about the files you changed. Drive the change directly; the drive is saved as a flow with its sources stamped`,
-                    changedFiles,
-                    flowsRun: affected,
-                    suite,
-                    unknownProvenance,
-                    measured: extra.measured,
-                };
-            }
+const VERIFY_CHANGE = {
+    name: ReticleTool.VERIFY_CHANGE,
+    description: 'Did my change break anything? Give it the files you edited (or `since` for a git ref) and it works out which saved flows cover them, replays exactly those, and answers with one `verified` (yes|no|unknown) plus `because`. `unknown` when NO saved flow covers the change — that is the honest answer, never a green: nothing ran, so nothing was proved. Returns { verified, because, changedFiles, flowsRun, suite, unknownProvenance }.',
+    example: { files: ['src/App.tsx'] },
+    inputSchema: {
+        files: z
+            .array(z.string())
+            .optional()
+            .describe('Changed file paths, repo-relative (e.g. ["src/App.tsx"]).'),
+        since: z
+            .string()
+            .optional()
+            .describe('Git ref to diff against (e.g. "HEAD~1", "main"). Unioned with `files`.'),
+        parallel: workerCountSchema
+            .optional()
+            .describe('Replay this many affected flows at once (needs the browser pool).'),
+        sessionId: z
+            .string()
+            .optional()
+            .describe('OMIT THIS unless you mean a specific tab — Reticle resolves it.'),
+    },
+    outputSchema: {
+        verified: z
+            .string()
+            .describe('yes | no | unknown. `unknown` means the evidence could not decide — most often that no saved flow covers these files, which is NOT a pass.'),
+        because: z.string(),
+        changedFiles: z.array(z.string()),
+        flowsRun: z.array(z.string()),
+        suite: z.unknown().optional(),
+        // Session-EXEMPT: declare the one-shot human feedback ask or a validating profile strips it.
+        feedback_prompt: z.unknown().optional(),
+        unknownProvenance: z.array(z.string()),
+        contradictions: z
+            .array(z.unknown())
+            .optional()
+            .describe('Findings from channels inspected during replay. Advisory entries are reported without changing the verdict; verdict-deciding entries can turn a green suite into no or unknown. OMITTED when clean; see `measured` when it could not be looked for.'),
+        untouched: z
+            .array(z.unknown())
+            .optional()
+            .describe('Controls on the page that the covering flows never drove. A green over a small untouched list is stronger evidence than the same green over a large one.'),
+        [RESULT_FIELD]: z.string().optional(),
+        measured: z
+            .array(z.string())
+            .describe('What was actually looked for. An absent `contradictions` means "none found" ONLY if "contradictions" appears here — otherwise it was never measured.'),
+    },
+    handler: async (deps, args) => {
+        const files = Array.isArray(args['files'])
+            ? args['files'].filter((f) => 'string' === typeof f)
+            : [];
+        const since = asString(args['since']);
+        // The tree to diff is the SESSION's project, and it is neither of the two things this line
+        // used to say it was: `deps.reticleRoot` is the daemon's `.reticle` SUBDIRECTORY, and the
+        // daemon's cwd is wherever the MCP host started it — `/` or `$HOME` for a globally-registered
+        // server. Both answer about the wrong repository while reporting a clean "nothing changed",
+        // which reads as a pass. `projectDirFor` is the directory holding the resolved root.
+        const changed = await resolveChangedFiles(files, since, projectDirFor(deps, asString(args['sessionId'])));
+        const changedFiles = changed.files;
+        // Same root flow_save wrote to. A read that resolved differently would report "no flows
+        // covered this change" over flows that exist, which reads as a clean result rather than
+        // an error, so the disagreement would be invisible.
+        // Both halves of the address from one place. The root was already resolved from the session;
+        // the id used to come from the daemon's cwd, so they named different projects.
+        const sid = asString(args['sessionId']);
+        const flows = await loadNamedFlows(deps.fs, sessionRoot(deps, sid), sessionProjectId(deps, sid));
+        const { affected, unknownProvenance } = affectedSavedFlows(flows, changedFiles);
+        if (0 === changedFiles.length) {
+            return {
+                verified: Verified.UNKNOWN,
+                // A git failure and a clean tree both arrive here with no files, and they are opposite
+                // answers: one means there was nothing to decide about, the other means the question was
+                // never asked. `unknown` is right either way, but the REASON is what the caller acts on.
+                because: changed.failed
+                    ? `could not read the diff for \`${String(since)}\`, so nothing was compared: ${changed.reason ?? 'git failed'}`
+                    : 'no changed files were given, so there was nothing to decide about',
+                changedFiles,
+                flowsRun: [],
+                unknownProvenance,
+                // Nothing was looked for, and the schema requires this field to say so. Omitting it made
+                // the MCP layer reject the whole response, turning an honest UNKNOWN into a protocol error.
+                measured: [],
+            };
+        }
+        // The guard: an uncovered change is UNKNOWN. Reporting `yes` here would mean "your change is
+        // fine" on the strength of having run nothing at all.
+        if (0 === affected.length) {
+            return {
+                verified: Verified.UNKNOWN,
+                /*
+                 * The way out named here has to be one the CALLER can take.
+                 *
+                 * This used to say "record one with reticle_record { action: start } then
+                 * reticle_flow_save". Neither is advertised on the default surface, and that surface has
+                 * no dispatch hatch — so the honest answer to "nothing covers this change" ended in two
+                 * calls that come back "Tool not found". Driving is reachable from every surface, and a
+                 * drive is captured as a flow automatically at teardown, so it is also the instruction
+                 * that makes the NEXT change to these files replay instead of drive.
+                 */
+                because: `no saved flow covers ${1 === changedFiles.length ? 'this file' : 'these files'} — nothing ran, so nothing is proved. Drive it and prove it directly; the drive is saved as a flow, so the next change here replays instead`,
+                changedFiles,
+                flowsRun: [],
+                unknownProvenance,
+                // No flow ran, so nothing was measured — said explicitly rather than left undefined.
+                measured: [],
+            };
+        }
+        const provenanceNote = unknownProvenance.length > 0
+            ? ` (${String(unknownProvenance.length)} of them re-run only because Reticle cannot tell which sources they cover)`
+            : '';
+        // Marked BEFORE the replay so the contradiction sweep afterwards reads exactly the window the
+        // flows produced, and never events from whatever the agent did before calling this.
+        const cursor = cursorBeforeReplay(deps, args);
+        const verify = FLOW_TOOLS.find((tool) => tool.name === ReticleTool.FLOW_VERIFY);
+        if (verify === undefined)
+            throw new Error('the whole-suite replay tool is not registered');
+        const suite = asRecord(await verify.handler(deps, {
+            names: affected,
+            ...(asNumber(args['parallel']) === undefined ? {} : { parallel: args['parallel'] }),
+            ...(asString(args['sessionId']) === undefined ? {} : { sessionId: args['sessionId'] }),
+        }));
+        const failed = suite.failed ?? 0;
+        const passed = suite.passed ?? 0;
+        // `unverifiable` is NOT a failure — the suite ran and proved nothing, which is the same fact
+        // this tool answers UNKNOWN for an uncovered change. Treating it as a red emitted a bug_found
+        // that nothing earned. See verify-change-verdict.
+        const verdict = verdictForSuite(String(suite.status), failed);
+        // A NO must be EARNED by a failing flow genuinely tied to the changed files. `affectedSavedFlows`
+        // re-runs any flow whose sources it cannot determine — over-running beats skipping — and those
+        // land in `unknownProvenance`. Judging the change on them produced a negative verdict whose own
+        // explanation admitted the evidence was not tied to the file. See attributed-failure.
+        const failingNames = Array.isArray(suite.failures)
+            ? suite.failures
+                .map((f) => 'object' === typeof f && f !== null ? asString(asRecord(f)['flow']) : undefined)
+                .filter((n) => n !== undefined)
+            : // No per-failure detail: the failure is somewhere in the set that ran, so ask the question
+                // of all of them rather than guessing which.
+                affected;
+        const attributed = attributedFailures(failingNames, unknownProvenance);
+        const earnedNo = verdict === Verified.NO && attributed.length > 0;
+        const reported = verdict === Verified.NO && !earnedNo ? Verified.UNKNOWN : verdict;
+        if (reported !== Verified.YES) {
+            return {
+                verified: reported,
+                because: earnedNo
+                    ? `${String(failed)} of ${String(suite.total ?? affected.length)} covering flows failed, including ${attributed.join(', ')}, which cover the changed files${provenanceNote}`
+                    : verdict === Verified.NO
+                        ? `flows failed, but Reticle cannot tell which sources any of them cover (${failingNames.join(', ')}) — so this says nothing about the files you changed. Re-record them so their sources are stamped, or read the replay yourself`
+                        : `the covering flows ran but proved nothing (${String(suite.status)}) — they assert no observable consequence, so a green from them would not have meant your change is safe${provenanceNote}`,
+                changedFiles,
+                flowsRun: affected,
+                suite,
+                unknownProvenance,
+                measured: ['flows'],
+            };
+        }
+        // The suite went green. That is exactly when the remaining two channels are worth reading:
+        // a replay that passes while a write fails is the false green this whole product is about.
+        const extra = await inspectAfterReplay(deps, args, cursor);
+        const decidingContradictions = extra.contradictions.filter((c) => !isAdvisory(c.kind));
+        if (decidingContradictions.length > 0) {
+            const kinds = decidingContradictions.map((c) => c.kind).join(', ');
+            const earned = attributedFailures(affected, unknownProvenance).length > 0;
             return {
-                verified: Verified.YES,
-                because: `all ${String(passed)} flows covering these files passed${provenanceNote}${extra.untouched === undefined ? '' : `, with ${String(extra.untouched.length)} controls left undriven`}`,
+                verified: earned ? Verified.NO : Verified.UNKNOWN,
+                because: earned
+                    ? `every covering flow passed, but channels disagreed during the replay (${kinds}) — a green suite over a failed write is the false green worth looking at${provenanceNote}`
+                    : `channels disagreed during the replay (${kinds}), but Reticle cannot tell which sources any of the flows that ran cover (${affected.join(', ')}), so this says nothing about the files you changed. Drive the change directly; the drive is saved as a flow with its sources stamped`,
                 changedFiles,
                 flowsRun: affected,
                 suite,
                 unknownProvenance,
+                contradictions: extra.contradictions,
                 ...(extra.untouched === undefined ? {} : { untouched: extra.untouched }),
                 measured: extra.measured,
             };
-        },
+        }
+        // The mirror of `earnedNo`: a green from flows that ran only because their sources are unknown
+        // says nothing about these files either. At least one attributed flow has to have passed.
+        if (0 === attributedFailures(affected, unknownProvenance).length) {
+            return {
+                verified: Verified.UNKNOWN,
+                because: `the flows that ran passed, but Reticle cannot tell which sources any of them cover (${affected.join(', ')}), so this says nothing about the files you changed. Drive the change directly; the drive is saved as a flow with its sources stamped`,
+                changedFiles,
+                flowsRun: affected,
+                suite,
+                unknownProvenance,
+                ...(0 === extra.contradictions.length ? {} : { contradictions: extra.contradictions }),
+                measured: extra.measured,
+            };
+        }
+        return {
+            verified: Verified.YES,
+            because: `all ${String(passed)} flows covering these files passed${provenanceNote}${extra.untouched === undefined ? '' : `, with ${String(extra.untouched.length)} controls left undriven`}`,
+            changedFiles,
+            flowsRun: affected,
+            suite,
+            unknownProvenance,
+            ...(0 === extra.contradictions.length ? {} : { contradictions: extra.contradictions }),
+            ...(extra.untouched === undefined ? {} : { untouched: extra.untouched }),
+            measured: extra.measured,
+        };
+    },
+};
+/** Every answer carries the Reticle result block, under the verdict this tool decided. */
+export const VERIFY_CHANGE_TOOLS = [
+    {
+        ...VERIFY_CHANGE,
+        handler: async (deps, args, call) => changeResult(sessionRoot(deps, asString(args['sessionId'])), await VERIFY_CHANGE.handler(deps, args, call)),
     },
 ];
 /** The event cursor to sweep from, or 0 when there is no readable session (nothing to sweep). */
@@ -243,6 +253,7 @@ async function inspectAfterReplay(deps, args, cursor) {
             currentEditEpoch: session.currentEditEpoch,
             appOrigin: session.url,
             background: session.background,
+            namedNetUrls: [],
             // The replay is the action, and the cursor is where it started.
             actionSince: cursor,
         });

package/dist/launch-chromium.d.ts

@@ -14,7 +14,7 @@
  * line there corrupts the client's stream.
  */
 import { type ChromiumLaunchOptions } from './chromium-launch-options.js';
-import { type ChromiumProbe } from './command/cli/doctor/browser/chromium-hint.js';
+import { type ChromiumPathProblem, type ChromiumProbe } from './command/cli/doctor/browser/chromium-hint.js';
 /** The installed-browser channels Playwright can drive in place of its own build. */
 export declare const ChromiumChannel: {
     readonly CHROME: "chrome";
@@ -31,6 +31,8 @@ export interface ChromiumTargetDeps {
     /** Where the bundled playwright expects its Chromium build. */
     executablePath: () => string;
     exists: (path: string) => boolean;
+    /** What stops the executable RETICLE_CHROMIUM_PATH names from launching, if anything. */
+    pathProblem: (path: string) => ChromiumPathProblem | undefined;
     platform: NodeJS.Platform;
     env: NodeJS.ProcessEnv;
     /** Run the pinned Chromium install; resolves true when it succeeded. */
@@ -38,16 +40,29 @@ export interface ChromiumTargetDeps {
     /** A progress line for a human — stderr in production. */
     announce: (line: string) => void;
 }
-/** Which browser to launch: the bundled build (no channel), an installed channel, or none at all. */
+/**
+ * Which browser to launch: the bundled build (no channel), an installed channel, the executable
+ * RETICLE_CHROMIUM_PATH names, or none at all. `unusableConfigured` is a named executable that
+ * cannot be launched, and why.
+ */
 export type ChromiumTarget = {
     found: true;
     channel?: ChromiumChannel;
+    executablePath?: string;
 } | {
     found: false;
+    unusableConfigured?: {
+        path: string;
+        problem: ChromiumPathProblem;
+    };
 };
 /**
  * Decide which browser a launch will use, installing the pinned Chromium only as the last resort.
- * Order: bundled build on disk → installed Chrome → installed Edge → install, then bundled.
+ * Order: RETICLE_CHROMIUM_PATH → bundled build on disk → installed Chrome → installed Edge →
+ * install, then bundled.
+ *
+ * A named executable ends the search either way. It is set on a machine where the usual places are
+ * empty or unusable, so falling back from a typo to a download would only hide the typo.
  */
 export declare function resolveChromiumTarget(deps: ChromiumTargetDeps): Promise<ChromiumTarget>;
 /** The subset of Playwright's `BrowserType` this file needs, so tests can pass a fake. */
@@ -67,14 +82,21 @@ export declare function announceOnce(write: (line: string) => void): (line: stri
  * turns into the pinned install command, so the user still gets the one line that fixes it.
  */
 export declare function launchChromium<B>(chromium: LaunchableChromium<B>, headless: boolean, deps?: ChromiumTargetDeps): Promise<B>;
+/** What the probes read off the machine, injected so a test can name a browser that is not there. */
+interface ProbeMachine {
+    env: NodeJS.ProcessEnv;
+    exists: (path: string) => boolean;
+    pathProblem: (path: string) => ChromiumPathProblem | undefined;
+}
 /**
  * The lease preflight's probe: "can a launch succeed?", which now includes the Chrome/Edge fallback
  * and the automatic install. Without this the preflight would refuse a lease on a machine the
  * launcher itself could serve. Falls back to the plain probe so a real refusal keeps its evidence.
  */
-export declare function probeLaunchableChromium(): Promise<ChromiumProbe>;
+export declare function probeLaunchableChromium(machine?: ProbeMachine): Promise<ChromiumProbe>;
 /**
  * `doctor`'s probe: the plain Chromium probe, plus the installed browser that stands in when the
  * bundled build is missing. Never installs — a diagnostic that downloads 150 MiB is not one.
  */
-export declare function probeChromiumWithFallback(): Promise<ChromiumProbe>;
+export declare function probeChromiumWithFallback(machine?: ProbeMachine): Promise<ChromiumProbe>;
+export {};

package/dist/launch-chromium.js

@@ -18,7 +18,7 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { chromiumLaunchOptions } from './chromium-launch-options.js';
-import { bundledPlaywrightVersion, chromiumInstallCommand, probeChromium, } from './command/cli/doctor/browser/chromium-hint.js';
+import { bundledPlaywrightVersion, chromiumInstallCommand, chromiumPathProblem, configuredChromiumPath, configuredChromiumProbe, configuredChromiumRefusal, probeChromium, } from './command/cli/doctor/browser/chromium-hint.js';
 /** The installed-browser channels Playwright can drive in place of its own build. */
 export const ChromiumChannel = {
     CHROME: 'chrome',
@@ -72,9 +72,20 @@ const installingLine = (command) => `[reticle] No Chromium, Chrome or Edge found
 const INSTALL_FAILED_LINE = '[reticle] The Chromium install did not complete.\n';
 /**
  * Decide which browser a launch will use, installing the pinned Chromium only as the last resort.
- * Order: bundled build on disk → installed Chrome → installed Edge → install, then bundled.
+ * Order: RETICLE_CHROMIUM_PATH → bundled build on disk → installed Chrome → installed Edge →
+ * install, then bundled.
+ *
+ * A named executable ends the search either way. It is set on a machine where the usual places are
+ * empty or unusable, so falling back from a typo to a download would only hide the typo.
  */
 export async function resolveChromiumTarget(deps) {
+    const configured = configuredChromiumPath(deps.env);
+    if (configured !== undefined) {
+        const problem = deps.pathProblem(configured);
+        return problem === undefined
+            ? { found: true, executablePath: configured }
+            : { found: false, unusableConfigured: { path: configured, problem } };
+    }
     let bundled;
     try {
         bundled = deps.executablePath();
@@ -168,6 +179,7 @@ function defaultDeps(chromium) {
     return {
         executablePath: () => chromium.executablePath(),
         exists: existsSync,
+        pathProblem: (path) => chromiumPathProblem(path, process.platform),
         platform: process.platform,
         env: process.env,
         install: installPinnedChromium,
@@ -181,15 +193,30 @@ function defaultDeps(chromium) {
  */
 export async function launchChromium(chromium, headless, deps = defaultDeps(chromium)) {
     const target = await resolveChromiumTarget(deps);
-    const channel = target.found ? target.channel : undefined;
-    return chromium.launch(chromiumLaunchOptions(headless, channel));
+    // Refused here rather than launched: Playwright's error for a missing executable is the one
+    // `chromiumLaunchHint` answers with the install command, which cannot fix a wrong path.
+    if (!target.found && target.unusableConfigured !== undefined) {
+        const { path, problem } = target.unusableConfigured;
+        throw new Error(configuredChromiumRefusal(path, problem));
+    }
+    return target.found
+        ? chromium.launch(chromiumLaunchOptions(headless, target.channel, target.executablePath))
+        : chromium.launch(chromiumLaunchOptions(headless));
 }
+const THIS_MACHINE = {
+    env: process.env,
+    exists: existsSync,
+    pathProblem: (path) => chromiumPathProblem(path, process.platform),
+};
 /**
  * The lease preflight's probe: "can a launch succeed?", which now includes the Chrome/Edge fallback
  * and the automatic install. Without this the preflight would refuse a lease on a machine the
  * launcher itself could serve. Falls back to the plain probe so a real refusal keeps its evidence.
  */
-export async function probeLaunchableChromium() {
+export async function probeLaunchableChromium(machine = THIS_MACHINE) {
+    const configured = configuredChromiumProbe(machine.env, machine.pathProblem);
+    if (configured !== undefined)
+        return configured;
     try {
         const { chromium } = await import('playwright');
         const target = await resolveChromiumTarget(defaultDeps(chromium));
@@ -205,14 +232,17 @@ export async function probeLaunchableChromium() {
  * `doctor`'s probe: the plain Chromium probe, plus the installed browser that stands in when the
  * bundled build is missing. Never installs — a diagnostic that downloads 150 MiB is not one.
  */
-export async function probeChromiumWithFallback() {
+export async function probeChromiumWithFallback(machine = THIS_MACHINE) {
+    const configured = configuredChromiumProbe(machine.env, machine.pathProblem);
+    if (configured !== undefined)
+        return configured;
     const probe = await probeChromium();
     if (probe.exists)
         return probe;
     const channel = findInstalledChannel({
-        exists: existsSync,
+        exists: machine.exists,
         platform: process.platform,
-        env: process.env,
+        env: machine.env,
     });
     return channel === undefined ? probe : { ...probe, fallback: CHANNEL_LABEL[channel] };
 }