@reticlehq/server 3.8.2 → 3.10.0

package/dist/language/flows/steps/page-steps.js

@@ -0,0 +1,198 @@
+/**
+ * Steps that reach past the page the journey is on: one opens another page (`navigate`), one sends a
+ * request to the app (`request`). Neither acts on an element, and both depend on a caller that owns
+ * what the replay cannot reach by itself: the sessions, the origin, the cookies.
+ */
+import { FlowStepTool, } from '@reticlehq/core';
+/*
+ * A step that opens a page in the middle of a journey. The replay goes on with the page that loaded,
+ * and the step's `expect` is judged there (see `OpenPage`).
+ */
+/** The step's result before its `expect` is judged, and the session to go on with. */
+export async function openStepPage(step, index, open) {
+    const url = step.navigate ?? '';
+    const base = { step: index, tool: FlowStepTool.NAVIGATE, anchor: url };
+    // Never skipped: a journey that reports green without the page it was meant to check is a false
+    // green arriving through the step meant to make the check stronger.
+    if (open === undefined) {
+        return {
+            result: {
+                ...base,
+                ok: false,
+                error: `this replay cannot open a page, so the step that opens ${url} did not run`,
+            },
+        };
+    }
+    const opened = await open(url);
+    if ('error' in opened) {
+        return { result: { ...base, ok: false, error: opened.error } };
+    }
+    return { result: { ...base, ok: true }, session: opened.session };
+}
+/** Why an answer does not match the step's `response`, or undefined when it does. */
+function responseMismatch(response, answer) {
+    const statuses = response.status === undefined ? [] : [response.status].flat();
+    if (statuses.length > 0 && !statuses.includes(answer.status)) {
+        return `the answer was ${String(answer.status)}, expected ${statuses.join(' or ')}`;
+    }
+    if (response.contains !== undefined && !answer.body.includes(response.contains)) {
+        return `the answer (${String(answer.status)}) does not contain "${response.contains}"`;
+    }
+    if (response.absent !== undefined && answer.body.includes(response.absent)) {
+        return `the answer (${String(answer.status)}) contains "${response.absent}", which it must not`;
+    }
+    return undefined;
+}
+/*
+ * A step that sends one request and judges the answer. It never skips: a rule the flow says it
+ * checks and did not is a false green.
+ */
+/** Methods that only read. Any other method changes data and needs the run's confirmation. */
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+export async function runRequestStep(step, index, send, judged, 
+/**
+ * The run's own yes to steps that change data, never the flow file's: flow files are shared, and a
+ * saved `DELETE` would otherwise run with the user's cookies on any app the flow is pointed at.
+ */
+confirmDangerous) {
+    const request = step.request;
+    const label = request === undefined ? '' : `${request.method} ${request.url}`;
+    const base = { step: index, tool: FlowStepTool.REQUEST, anchor: label };
+    if (request === undefined || send === undefined) {
+        return {
+            ...base,
+            ok: false,
+            error: `this replay cannot send a request, so ${label} did not run`,
+        };
+    }
+    if (!READ_METHODS.has(request.method.toUpperCase()) && !confirmDangerous) {
+        return {
+            ...base,
+            ok: false,
+            error: `potentially destructive request blocked: ${label} changes data, so it was not sent. ` +
+                'Confirm it for this run: reticle_verify{action:"flows", confirmDangerous: true}, or ' +
+                '`reticle verify <url> --confirm-dangerous`. It cannot be confirmed in the flow file.',
+        };
+    }
+    const answer = await send(request);
+    if ('error' in answer) {
+        return { ...base, ok: false, error: answer.error };
+    }
+    const mismatch = !judged || step.response === undefined ? undefined : responseMismatch(step.response, answer);
+    return mismatch === undefined ? { ...base, ok: true } : { ...base, ok: false, error: mismatch };
+}
+/** True for a step that reaches past the page: `navigate` or `request`. */
+export function isPageStep(step) {
+    return step.navigate !== undefined || step.request !== undefined;
+}
+/**
+ * Run a `navigate` or `request` step. `judge` evaluates an `expect` on a page; it comes from the
+ * replay so this file does not import the replay back. `checked` is false for a setup step, whose
+ * consequence is not checked. A navigate step returns the session to go on with.
+ */
+export async function runPageStep(step, index, ctx) {
+    if (step.request !== undefined) {
+        return {
+            result: await runRequestStep(step, index, ctx.send, ctx.checked, ctx.confirmDangerous),
+        };
+    }
+    const opened = await openStepPage(step, index, ctx.open);
+    if (opened.session === undefined) {
+        return opened;
+    }
+    const result = opened.result;
+    const page = ctx.route(opened.session);
+    if (page !== undefined) {
+        result.page = page;
+    }
+    const drift = step.expect === undefined || !ctx.checked
+        ? undefined
+        : await ctx.judge(opened.session, step.expect);
+    if (drift !== undefined) {
+        result.ok = false;
+        result.drift = drift;
+    }
+    return { result, session: opened.session };
+}
+/** How long a `request` step waits for the answer. */
+const REQUEST_TIMEOUT_MS = 15_000;
+/** The `Cookie` header the page would send to `host`, from the driven browser's storage state. */
+function cookieHeader(state, host) {
+    const cookies = state?.cookies;
+    if (!Array.isArray(cookies)) {
+        return '';
+    }
+    return cookies
+        .filter((c) => {
+        const domain = c.domain;
+        if (typeof domain !== 'string') {
+            return false;
+        }
+        const bare = domain.replace(/^\./, '');
+        return host === bare || host.endsWith(`.${bare}`);
+    })
+        .map((c) => `${c.name}=${c.value}`)
+        .join('; ');
+}
+/**
+ * The sender a `request` step uses: same origin as the page only, the page's cookies unless the step
+ * is anonymous, no redirects followed (a 302 is the answer to judge). `pageUrl` is read at send time,
+ * because a `navigate` step changes the page.
+ */
+export function requestSender(pageUrl, provider, 
+/** The `Cookie` header of the account a step names in `as`, or undefined when not supplied. */
+accountCookie = () => undefined) {
+    return async (request) => {
+        const url = pageUrl();
+        if (url === undefined) {
+            return { error: 'the page has no known address, so the request has nowhere to go' };
+        }
+        const origin = new URL(url).origin;
+        const target = new URL(request.url, origin);
+        if (target.origin !== origin) {
+            return {
+                error: `${request.url} is not on the app's origin ${origin}; a flow sends requests only to its app`,
+            };
+        }
+        const headers = {};
+        if (request.body !== undefined) {
+            headers['content-type'] = request.contentType ?? 'application/json';
+        }
+        if (request.as !== undefined) {
+            const cookie = accountCookie(request.as);
+            if (cookie === undefined || '' === cookie) {
+                return {
+                    error: `the session of the account "${request.as}" was not supplied, so the request was not ` +
+                        'sent. Supply its Cookie header as a secret for this run.',
+                };
+            }
+            headers['cookie'] = cookie;
+        }
+        else if (true !== request.anonymous) {
+            const state = await provider?.storageState?.(url);
+            if (state === undefined) {
+                return {
+                    error: 'the page cookies cannot be read here (this is not a driven browser), so the request ' +
+                        'cannot go as the signed-in user. Mark it `anonymous`, or replay with `reticle verify`.',
+                };
+            }
+            const cookie = cookieHeader(state, target.hostname);
+            if (cookie !== '') {
+                headers['cookie'] = cookie;
+            }
+        }
+        try {
+            const answer = await fetch(target, {
+                method: request.method,
+                headers,
+                ...(request.body === undefined ? {} : { body: request.body }),
+                redirect: 'manual',
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            return { status: answer.status, body: await answer.text() };
+        }
+        catch (error) {
+            return { error: `the request ${request.method} ${target.pathname} failed: ${String(error)}` };
+        }
+    };
+}

package/dist/language/flows/suite/sequential-run.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The sequential half of `reticle_verify { action: "flows" | "change" }`.
+ *
+ * Flows replay one after the other against one live tab, with no limit on the total time. When the
+ * browser session was lost part-way through, every remaining flow waited for a page that never came,
+ * and the MCP client gave up (about 300 s) with no result at all - including for the flows that had
+ * already run. So the loop now stops at two points, and says so:
+ *
+ * - the total time budget is spent: no further flow is started;
+ * - the session is gone after a flow: the rest cannot run, so they are not attempted.
+ *
+ * Kept free of IO (the clock, the liveness probe and the replay are injected) so both stops are
+ * tested with a fake clock.
+ */
+import { z } from 'zod';
+import { SuiteStopReason, SuiteVerdictStatus } from '@reticlehq/core';
+/** Below the roughly 300 s at which common MCP clients stop waiting, so a result can still be returned. */
+export declare const DEFAULT_SUITE_BUDGET_MS = 240000;
+/** An hour: more than that is not a budget, and a client will have given up long before. */
+export declare const MAX_SUITE_BUDGET_MS = 3600000;
+export interface SuiteStop {
+    reason: SuiteStopReason;
+    /** For SESSION_LOST: the flow that was running when the session went. */
+    flow?: string;
+    budgetMs?: number;
+    nextAction: string;
+}
+export interface SequentialRun<R> {
+    results: R[];
+    /** Selected flows that were never started, in order. */
+    notRun: string[];
+    stopped?: SuiteStop;
+}
+export interface SequentialRunOptions<R> {
+    now: () => number;
+    budgetMs: number;
+    /** True while the session the flows drive is still there. Probed after each flow. */
+    sessionAlive: () => boolean;
+    run: (name: string) => Promise<R>;
+}
+export declare function runSequentially<R>(names: readonly string[], options: SequentialRunOptions<R>): Promise<SequentialRun<R>>;
+/**
+ * Mark a verdict `partial` when the suite stopped early. The ran flows keep their counts and
+ * failures; the summary leads with what did not run, because a green count over half a suite must
+ * not read as a pass.
+ */
+export declare function withStop<V extends {
+    status: SuiteVerdictStatus;
+    summary: string;
+}>(verdict: V, notRun: readonly string[], stopped: SuiteStop | undefined): V & {
+    notRun?: string[];
+    stopped?: SuiteStop;
+};
+/** The `budgetMs` input of the suite tools. */
+export declare const BUDGET_MS_ARG: z.ZodOptional<z.ZodNumber>;
+/** The two output fields a "partial" suite adds. */
+export declare const PARTIAL_OUTPUT: {
+    notRun: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    stopped: z.ZodOptional<z.ZodObject<{
+        reason: z.ZodEnum<{
+            time_budget: "time_budget";
+            session_lost: "session_lost";
+        }>;
+        flow: z.ZodOptional<z.ZodString>;
+        budgetMs: z.ZodOptional<z.ZodNumber>;
+        nextAction: z.ZodString;
+    }, z.core.$strip>>;
+};

package/dist/language/flows/suite/sequential-run.js

@@ -0,0 +1,96 @@
+/**
+ * The sequential half of `reticle_verify { action: "flows" | "change" }`.
+ *
+ * Flows replay one after the other against one live tab, with no limit on the total time. When the
+ * browser session was lost part-way through, every remaining flow waited for a page that never came,
+ * and the MCP client gave up (about 300 s) with no result at all - including for the flows that had
+ * already run. So the loop now stops at two points, and says so:
+ *
+ * - the total time budget is spent: no further flow is started;
+ * - the session is gone after a flow: the rest cannot run, so they are not attempted.
+ *
+ * Kept free of IO (the clock, the liveness probe and the replay are injected) so both stops are
+ * tested with a fake clock.
+ */
+import { z } from 'zod';
+import { SuiteStopReason, SuiteVerdictStatus } from '@reticlehq/core';
+/** Below the roughly 300 s at which common MCP clients stop waiting, so a result can still be returned. */
+export const DEFAULT_SUITE_BUDGET_MS = 240_000;
+/** An hour: more than that is not a budget, and a client will have given up long before. */
+export const MAX_SUITE_BUDGET_MS = 3_600_000;
+export async function runSequentially(names, options) {
+    const deadline = options.now() + options.budgetMs;
+    const results = [];
+    for (const [index, name] of names.entries()) {
+        // The first flow always starts: a budget that stops a suite before anything ran proves nothing.
+        if (index > 0 && options.now() >= deadline) {
+            return {
+                results,
+                notRun: names.slice(index),
+                stopped: {
+                    reason: SuiteStopReason.TIME_BUDGET,
+                    budgetMs: options.budgetMs,
+                    nextAction: 'run the flows listed in notRun in a new call (pass `names`), or raise `budgetMs` if your client waits longer',
+                },
+            };
+        }
+        results.push(await options.run(name));
+        if (index < names.length - 1 && !options.sessionAlive()) {
+            return {
+                results,
+                notRun: names.slice(index + 1),
+                stopped: {
+                    reason: SuiteStopReason.SESSION_LOST,
+                    flow: name,
+                    nextAction: 'reconnect the app (open it in a tab, or call reticle_sessions to find the live one), then run the flows listed in notRun with `names`',
+                },
+            };
+        }
+    }
+    return { results, notRun: [] };
+}
+/**
+ * Mark a verdict `partial` when the suite stopped early. The ran flows keep their counts and
+ * failures; the summary leads with what did not run, because a green count over half a suite must
+ * not read as a pass.
+ */
+export function withStop(verdict, notRun, stopped) {
+    if (stopped === undefined) {
+        return verdict;
+    }
+    const why = stopped.reason === SuiteStopReason.TIME_BUDGET
+        ? `the ${String(Math.round((stopped.budgetMs ?? 0) / 1000))} s total budget ran out`
+        : `the browser session was lost while "${stopped.flow ?? ''}" was running`;
+    return {
+        ...verdict,
+        status: SuiteVerdictStatus.PARTIAL,
+        summary: `PARTIAL - ${why}; ${String(notRun.length)} flow(s) did not run (${notRun.join(', ')}). Of those that ran: ${verdict.summary}`,
+        notRun: [...notRun],
+        stopped,
+    };
+}
+/** The `budgetMs` input of the suite tools. */
+export const BUDGET_MS_ARG = z
+    .number()
+    .finite()
+    .int()
+    .positive()
+    .max(MAX_SUITE_BUDGET_MS)
+    .optional()
+    .describe(`Total time budget for the sequential run, in milliseconds (default ${String(DEFAULT_SUITE_BUDGET_MS)}, below the ~300 s at which common MCP clients stop waiting). When it is spent no further flow is started: the call returns status "partial" with the finished results and the flows in notRun.`);
+/** The two output fields a "partial" suite adds. */
+export const PARTIAL_OUTPUT = {
+    notRun: z
+        .array(z.string())
+        .optional()
+        .describe('Present on a "partial" suite: the selected flows that were never started because the time budget ran out or the session was lost.'),
+    stopped: z
+        .object({
+        reason: z.enum([SuiteStopReason.TIME_BUDGET, SuiteStopReason.SESSION_LOST]),
+        flow: z.string().optional(),
+        budgetMs: z.number().optional(),
+        nextAction: z.string(),
+    })
+        .optional()
+        .describe('Present on a "partial" suite: why it ended early (time_budget | session_lost), the flow that lost the session, and one next action.'),
+};

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

@@ -1,19 +1,21 @@
 import { z } from 'zod';
-import { sessionRoot, sessionProjectId } from '../../memory/project/session-root.js';
+import { sessionRoot } 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, 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';
-import { loadNamedFlows, resolveChangedFiles } from '../../command/cli/cli-flow-commands.js';
-import { projectDirFor } from '../../memory/project/session-root.js';
+import { resolveChangedFiles } from '../../command/cli/cli-flow-commands.js';
+import { namedFlowsForSession } from './flow-store-for-session.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 { isOneActionOnly } from './flow-cross-step.js';
 import { parseControls } from '../../surface/tools/coverage-tools.js';
 import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { BUDGET_MS_ARG } from './suite/sequential-run.js';
 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 }.',
@@ -30,6 +32,11 @@ const VERIFY_CHANGE = {
         parallel: workerCountSchema
             .optional()
             .describe('Replay this many affected flows at once (needs the browser pool).'),
+        ignoreHTTPSErrors: z
+            .boolean()
+            .optional()
+            .describe('Accept a self-signed or local-CA certificate for parallel flow leases. Omit to inherit the source lease setting; otherwise certificate checks stay on.'),
+        budgetMs: BUDGET_MS_ARG,
         sessionId: z
             .string()
             .optional()
@@ -68,16 +75,14 @@ const VERIFY_CHANGE = {
         // 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'])));
+        // which reads as a pass. `projectDir` is the directory holding the resolved root.
+        //
+        // The flows come from the store `flows` replays from, and flow_save writes 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 (#1996).
+        const { flows, projectDir } = await namedFlowsForSession(deps, asString(args['sessionId']));
+        const changed = await resolveChangedFiles(files, since, projectDir);
         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 {
@@ -126,11 +131,16 @@ const VERIFY_CHANGE = {
         // 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)
+        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'] }),
+            ...(asNumber(args['budgetMs']) === undefined ? {} : { budgetMs: args['budgetMs'] }),
+            ...('boolean' === typeof args['ignoreHTTPSErrors']
+                ? { ignoreHTTPSErrors: args['ignoreHTTPSErrors'] }
+                : {}),
             ...(asString(args['sessionId']) === undefined ? {} : { sessionId: args['sessionId'] }),
         }));
         const failed = suite.failed ?? 0;
@@ -254,9 +264,10 @@ async function inspectAfterReplay(deps, args, cursor) {
             appOrigin: session.url,
             background: session.background,
             namedNetUrls: [],
-            // The replay is the action, and the cursor is where it started.
+            // The cursor is where the replay started. The replay is many user actions, not one, so a
+            // finding that only means something inside one action's window is left to the steps (#2013).
             actionSince: cursor,
-        });
+        }).filter((found) => !isOneActionOnly(found));
         const snapshot = await session.command(ReticleCommand.SNAPSHOT, {
             mode: SnapshotMode.INTERACTIVE,
         });

package/dist/launch-chromium.d.ts

@@ -87,6 +87,7 @@ interface ProbeMachine {
     env: NodeJS.ProcessEnv;
     exists: (path: string) => boolean;
     pathProblem: (path: string) => ChromiumPathProblem | undefined;
+    platform?: NodeJS.Platform;
 }
 /**
  * The lease preflight's probe: "can a launch succeed?", which now includes the Chrome/Edge fallback

package/dist/launch-chromium.js

@@ -48,11 +48,15 @@ const CHANNEL_PATHS = {
     },
 };
 const WINDOWS_INSTALL_ROOTS = ['LOCALAPPDATA', 'PROGRAMFILES', 'PROGRAMFILES(X86)'];
+function darwinChannelCandidates(appPath, env) {
+    const home = env['HOME']?.replace(/\/+$/, '');
+    return undefined === home || 0 === home.length ? [appPath] : [appPath, `${home}${appPath}`];
+}
 /** Candidate executable paths for a channel on this platform; empty where it is not installable. */
 export function channelExecutableCandidates(channel, platform, env) {
     const paths = CHANNEL_PATHS[channel];
     if ('darwin' === platform)
-        return [paths.darwin];
+        return darwinChannelCandidates(paths.darwin, env);
     if ('linux' === platform)
         return [paths.linux];
     if ('win32' === platform) {
@@ -63,9 +67,21 @@ export function channelExecutableCandidates(channel, platform, env) {
     }
     return [];
 }
+function findInstalledBrowser(deps) {
+    for (const channel of CHANNEL_ORDER) {
+        const found = channelExecutableCandidates(channel, deps.platform, deps.env).find((p) => deps.exists(p));
+        if (undefined !== found) {
+            // Playwright resolves a channel from its own registry (/Applications on macOS). A browser in
+            // ~/Applications is not in that registry, so launch it by executablePath instead.
+            const outsideRegistry = 'darwin' === deps.platform && found !== CHANNEL_PATHS[channel].darwin;
+            return outsideRegistry ? { channel, executablePath: found } : { channel };
+        }
+    }
+    return undefined;
+}
 /** The first installed Chrome/Edge on this machine, or undefined. Looks only; installs nothing. */
 export function findInstalledChannel(deps) {
-    return CHANNEL_ORDER.find((channel) => channelExecutableCandidates(channel, deps.platform, deps.env).some((p) => deps.exists(p)));
+    return findInstalledBrowser(deps)?.channel;
 }
 const usingChannelLine = (channel) => `[reticle] Playwright's Chromium is not installed; using the installed ${CHANNEL_LABEL[channel]} instead.\n`;
 const installingLine = (command) => `[reticle] No Chromium, Chrome or Edge found; installing Playwright's Chromium (${command}) — a one-time download…\n`;
@@ -98,10 +114,12 @@ export async function resolveChromiumTarget(deps) {
     }
     if (deps.exists(bundled))
         return { found: true };
-    const channel = findInstalledChannel(deps);
-    if (channel !== undefined) {
-        deps.announce(usingChannelLine(channel));
-        return { found: true, channel };
+    const installed = findInstalledBrowser(deps);
+    if (undefined !== installed) {
+        deps.announce(usingChannelLine(installed.channel));
+        return undefined === installed.executablePath
+            ? { found: true, channel: installed.channel }
+            : { found: true, executablePath: installed.executablePath };
     }
     deps.announce(installingLine(chromiumInstallCommand(bundledPlaywrightVersion())));
     const ok = await deps.install();
@@ -207,6 +225,7 @@ const THIS_MACHINE = {
     env: process.env,
     exists: existsSync,
     pathProblem: (path) => chromiumPathProblem(path, process.platform),
+    platform: process.platform,
 };
 /**
  * The lease preflight's probe: "can a launch succeed?", which now includes the Chrome/Edge fallback
@@ -217,16 +236,29 @@ export async function probeLaunchableChromium(machine = THIS_MACHINE) {
     const configured = configuredChromiumProbe(machine.env, machine.pathProblem);
     if (configured !== undefined)
         return configured;
+    const platform = machine.platform ?? process.platform;
     try {
         const { chromium } = await import('playwright');
-        const target = await resolveChromiumTarget(defaultDeps(chromium));
+        const target = await resolveChromiumTarget({
+            ...defaultDeps(chromium),
+            exists: machine.exists,
+            pathProblem: machine.pathProblem,
+            platform,
+            env: machine.env,
+            ...(machine === THIS_MACHINE
+                ? {}
+                : {
+                    install: () => Promise.resolve(false),
+                    announce: () => { },
+                }),
+        });
         if (target.found)
             return { exists: true };
     }
     catch {
-        // No playwright at all — probeChromium below says so, with where it looked.
+        // No playwright at all — probeChromiumWithFallback below says so, with where it looked.
     }
-    return probeChromium();
+    return probeChromiumWithFallback(machine);
 }
 /**
  * `doctor`'s probe: the plain Chromium probe, plus the installed browser that stands in when the
@@ -236,13 +268,18 @@ export async function probeChromiumWithFallback(machine = THIS_MACHINE) {
     const configured = configuredChromiumProbe(machine.env, machine.pathProblem);
     if (configured !== undefined)
         return configured;
-    const probe = await probeChromium();
+    const probe = await probeChromium(machine.exists);
     if (probe.exists)
         return probe;
+    const platform = machine.platform ?? process.platform;
     const channel = findInstalledChannel({
         exists: machine.exists,
-        platform: process.platform,
+        platform,
         env: machine.env,
     });
-    return channel === undefined ? probe : { ...probe, fallback: CHANNEL_LABEL[channel] };
+    if (undefined !== channel) {
+        return { ...probe, fallback: CHANNEL_LABEL[channel] };
+    }
+    const fallbackPaths = CHANNEL_ORDER.flatMap((ch) => channelExecutableCandidates(ch, platform, machine.env));
+    return 0 === fallbackPaths.length ? probe : { ...probe, fallbackPaths };
 }

package/dist/memory/cloud/background-sync.d.ts

@@ -15,6 +15,19 @@ export interface BackgroundSyncGate {
     /** Who is sending, when it is ON: a new value after a new sign-in or a new key. */
     credential?: string;
 }
+/**
+ * The switch a person set to stop sending without being asked, or undefined when nobody set it.
+ *
+ * Every send that nobody asked for reads it, the daemon's and the one `start()` runs on close. The
+ * close cycle read nothing, so a person who switched it off still sent this project and every
+ * other linked one when `reticle drive` or a self-booting `verify` closed.
+ */
+export declare function backgroundSyncOptOut(reticleRoot: string, env: NodeJS.ProcessEnv): BackgroundSyncGate | undefined;
+/**
+ * The gate of the one cycle `start()` sends on close, with nobody signed in. CI's key in the
+ * environment still sends there, as the docs promise. A switch that a person set still stops it.
+ */
+export declare function closeCycleGate(reticleRoot: string, env: NodeJS.ProcessEnv): BackgroundSyncGate;
 /** May the daemon send this root's work now? Reads the disk, never the network. */
 export declare function backgroundSyncGate(input: {
     reticleRoot: string;

package/dist/memory/cloud/background-sync.js

@@ -29,9 +29,14 @@ export const BackgroundSyncState = {
 };
 const OFF_VALUES = new Set(['0', 'false', 'off', 'no']);
 const BACKGROUND_SYNC_SETTING = 'backgroundSync';
-/** May the daemon send this root's work now? Reads the disk, never the network. */
-export function backgroundSyncGate(input) {
-    const { reticleRoot, cloud, env, signedIn } = input;
+/**
+ * The switch a person set to stop sending without being asked, or undefined when nobody set it.
+ *
+ * Every send that nobody asked for reads it, the daemon's and the one `start()` runs on close. The
+ * close cycle read nothing, so a person who switched it off still sent this project and every
+ * other linked one when `reticle drive` or a self-booting `verify` closed.
+ */
+export function backgroundSyncOptOut(reticleRoot, env) {
     if (OFF_VALUES.has((env[ReticleEnv.BACKGROUND_SYNC] ?? '').toLowerCase())) {
         return {
             state: BackgroundSyncState.OPTED_OUT,
@@ -44,6 +49,22 @@ export function backgroundSyncGate(input) {
             why: `off in this project ("${BACKGROUND_SYNC_SETTING}": false in .reticle.json)`,
         };
     }
+    return undefined;
+}
+/**
+ * The gate of the one cycle `start()` sends on close, with nobody signed in. CI's key in the
+ * environment still sends there, as the docs promise. A switch that a person set still stops it.
+ */
+export function closeCycleGate(reticleRoot, env) {
+    return (backgroundSyncOptOut(reticleRoot, env) ?? { state: BackgroundSyncState.ON, why: 'on close' });
+}
+/** May the daemon send this root's work now? Reads the disk, never the network. */
+export function backgroundSyncGate(input) {
+    const { reticleRoot, cloud, env, signedIn } = input;
+    const optedOut = backgroundSyncOptOut(reticleRoot, env);
+    if (optedOut !== undefined) {
+        return optedOut;
+    }
     // `link` is set only from the project's own link file; an environment key leaves it unset.
     if (cloud.link === undefined) {
         return {