@reticlehq/server 2.12.0 → 2.13.0

package/dist/setup/desktop-shape.js

@@ -0,0 +1,63 @@
+/**
+ * How a desktop app differs from a web app, for the phases that run after the files are written.
+ *
+ * `init` already understands Electron and Tauri when it writes files: desktop-doctor.ts checks the
+ * Tauri CSP for a blocked bridge or IPC, the Electron preload, the capture helper. The runtime
+ * phases did not, and they made three web-shaped assumptions that are wrong here — one of them
+ * actively harmful.
+ *
+ * 1. **Do not open a browser.** The app's own window IS the client. Opening a tab creates a SECOND
+ *    session that is not the app, and the session picker would then have to choose between them —
+ *    which is exactly the stale-tab false green, arranged deliberately.
+ * 2. **Do not wait for an HTTP port.** Tauri serves `tauri://localhost` (`http://tauri.localhost`
+ *    on Windows) from inside the webview; there is nothing for `fetch` to probe. Electron under
+ *    electron-vite does serve a renderer over HTTP, but the window is what matters, not the port.
+ * 3. **Wait for the app to launch instead.** `tauri dev` builds Rust before a window appears, which
+ *    is minutes on a cold cache, so the budget has to be the app's, not a web app's.
+ */
+/** What kind of thing setup is about to run. */
+export const AppShape = {
+    WEB: 'web',
+    ELECTRON: 'electron',
+    TAURI: 'tauri',
+};
+export const isDesktop = (shape) => AppShape.WEB !== shape;
+/**
+ * Which shell this is.
+ *
+ * Tauri wins when both are present: a project with a Tauri config is a Tauri app whatever else it
+ * has installed, and electron sometimes appears in a monorepo's root devDependencies.
+ */
+export function readShape(evidence) {
+    if (evidence.hasTauriConf)
+        return AppShape.TAURI;
+    if (evidence.hasElectronDep)
+        return AppShape.ELECTRON;
+    return AppShape.WEB;
+}
+/** A Tauri webview's own origin, which no HTTP probe from outside can reach. */
+const TAURI_ORIGINS = ['tauri://localhost', 'http://tauri.localhost'];
+export function isDesktopOrigin(url) {
+    return TAURI_ORIGINS.some((origin) => url.startsWith(origin));
+}
+const WEB_CONNECT_MS = 120_000;
+/** A cold `tauri dev` compiles the Rust side before a window exists. */
+const DESKTOP_CONNECT_MS = 10 * 60_000;
+export function policyFor(shape) {
+    if (AppShape.WEB === shape) {
+        return {
+            openBrowser: true,
+            requireHttpReady: true,
+            connectBudgetMs: WEB_CONNECT_MS,
+            note: undefined,
+        };
+    }
+    return {
+        openBrowser: false,
+        requireHttpReady: false,
+        connectBudgetMs: DESKTOP_CONNECT_MS,
+        note: AppShape.TAURI === shape
+            ? 'Tauri app: not opening a browser, because its own window is the client. A cold `tauri dev` builds the Rust side first, so the window can take minutes to appear.'
+            : 'Electron app: not opening a browser, because its own window is the client. Waiting for the app to launch and dial in.',
+    };
+}

package/dist/setup/dev-server-wait.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Deciding when a dev server we started is up, hung, or gone.
+ *
+ * Nothing else in the package owns a spawned dev server, so this is the one genuinely new decision
+ * setup contributes. All three cases below were failures in the field:
+ *
+ * - a url in the output is an ANNOUNCEMENT, not readiness. Next prints `- Local: …` before it can
+ *   serve, so a tab opened on that line lands on a 404 and the whole connect budget is then spent
+ *   blaming the SDK for a server that had not finished starting.
+ * - a launcher that EXITS is not necessarily a dead server. `astro dev` forks the real one, prints
+ *   the url and returns, which was read as death and failed Astro every time.
+ * - a fixed budget is the wrong instrument for "is this hung?". The heaviest real monorepo builds
+ *   two shared packages before its app serves and was measured taking twenty minutes, while a
+ *   genuinely wedged server writes nothing at all and gets exactly the same budget.
+ */
+/** Everything the decision needs, gathered by the caller. */
+export interface WaitFacts {
+    /** The dev server's own output so far. */
+    readonly output: string;
+    /** Whether the process we spawned has exited. */
+    readonly launcherExited: boolean;
+    /** Whether the url we are watching answers. */
+    readonly serving: boolean;
+    /** Milliseconds since the dev server last wrote anything. */
+    readonly quietForMs: number;
+    /** Milliseconds since the wait began. */
+    readonly elapsedMs: number;
+}
+export declare const WaitVerdict: {
+    /** It is up. Carry on. */
+    readonly READY: "ready";
+    /** Still building or still starting; keep waiting. */
+    readonly WAITING: "waiting";
+    /** The launcher exited and nothing it started is answering. */
+    readonly DEAD: "dead";
+    /** It has gone silent without ever serving. */
+    readonly HUNG: "hung";
+};
+export type WaitVerdict = (typeof WaitVerdict)[keyof typeof WaitVerdict];
+/** Silence for this long, with nothing served, means hung rather than busy. */
+export declare const QUIET_MEANS_HUNG_MS = 45000;
+/** Even a talkative dev server has had enough rope by here. */
+export declare const WAIT_CEILING_MS: number;
+/**
+ * Whether to keep waiting.
+ *
+ * `serving` outranks everything: a launcher that exited while the port answers has DAEMONIZED, and
+ * that is a live server whatever its parent did.
+ */
+export declare function judgeWait(facts: WaitFacts): WaitVerdict;
+export declare function announcedUrl(output: string): string | undefined;
+/**
+ * The url to watch: whatever the tool announced, else one composed from a port we OBSERVED our own
+ * process group binding.
+ *
+ * The second is not a guess. `react-scripts` prints no parseable url outside a tty, so a CRA app
+ * compiled successfully, served happily, and setup timed out insisting no url appeared — the
+ * evidence there is the process we spawned, not a convention.
+ */
+export declare function urlToWatch(output: string, observedPorts: readonly number[]): string | undefined;

package/dist/setup/dev-server-wait.js

@@ -0,0 +1,65 @@
+/**
+ * Deciding when a dev server we started is up, hung, or gone.
+ *
+ * Nothing else in the package owns a spawned dev server, so this is the one genuinely new decision
+ * setup contributes. All three cases below were failures in the field:
+ *
+ * - a url in the output is an ANNOUNCEMENT, not readiness. Next prints `- Local: …` before it can
+ *   serve, so a tab opened on that line lands on a 404 and the whole connect budget is then spent
+ *   blaming the SDK for a server that had not finished starting.
+ * - a launcher that EXITS is not necessarily a dead server. `astro dev` forks the real one, prints
+ *   the url and returns, which was read as death and failed Astro every time.
+ * - a fixed budget is the wrong instrument for "is this hung?". The heaviest real monorepo builds
+ *   two shared packages before its app serves and was measured taking twenty minutes, while a
+ *   genuinely wedged server writes nothing at all and gets exactly the same budget.
+ */
+export const WaitVerdict = {
+    /** It is up. Carry on. */
+    READY: 'ready',
+    /** Still building or still starting; keep waiting. */
+    WAITING: 'waiting',
+    /** The launcher exited and nothing it started is answering. */
+    DEAD: 'dead',
+    /** It has gone silent without ever serving. */
+    HUNG: 'hung',
+};
+/** Silence for this long, with nothing served, means hung rather than busy. */
+export const QUIET_MEANS_HUNG_MS = 45_000;
+/** Even a talkative dev server has had enough rope by here. */
+export const WAIT_CEILING_MS = 25 * 60_000;
+/**
+ * Whether to keep waiting.
+ *
+ * `serving` outranks everything: a launcher that exited while the port answers has DAEMONIZED, and
+ * that is a live server whatever its parent did.
+ */
+export function judgeWait(facts) {
+    if (facts.serving)
+        return WaitVerdict.READY;
+    if (facts.launcherExited)
+        return WaitVerdict.DEAD;
+    if (facts.elapsedMs >= WAIT_CEILING_MS)
+        return WaitVerdict.HUNG;
+    // Output IS progress. Silence is what distinguishes a build from a wedge.
+    return facts.quietForMs >= QUIET_MEANS_HUNG_MS ? WaitVerdict.HUNG : WaitVerdict.WAITING;
+}
+/** A url the dev server announced, if it has announced one. Never composed, only read. */
+const URL_IN_OUTPUT = /https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d+/;
+export function announcedUrl(output) {
+    return URL_IN_OUTPUT.exec(output)?.[0];
+}
+/**
+ * The url to watch: whatever the tool announced, else one composed from a port we OBSERVED our own
+ * process group binding.
+ *
+ * The second is not a guess. `react-scripts` prints no parseable url outside a tty, so a CRA app
+ * compiled successfully, served happily, and setup timed out insisting no url appeared — the
+ * evidence there is the process we spawned, not a convention.
+ */
+export function urlToWatch(output, observedPorts) {
+    const announced = announcedUrl(output);
+    if (undefined !== announced)
+        return announced;
+    const port = observedPorts[0];
+    return undefined === port ? undefined : `http://localhost:${port}`;
+}

package/dist/setup/drive-agent.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Asking a child agent to drive the app, and reading what it says back.
+ *
+ * The drive needs a model, and the model does not need to be the caller. A client reads its MCP
+ * server list once at startup and cannot reload it, so an agent that has just run `init` does not
+ * yet have the reticle_* tools — which is why the hand-driven procedure asks for a restart, and why
+ * three runs in five ended there having shown the user nothing. A child process started after init
+ * reads the list init just wrote. No restart, no lost context, no waiting on a human.
+ *
+ * Two details here are not stylistic, and both cost a real run to learn.
+ */
+import { type DriverSpec } from './drive-plan.js';
+/** Ten minutes. Long, because the drive is a model working, and bounded, because it can wedge. */
+export declare const DRIVE_TIMEOUT_MS: number;
+export interface DriveRequest {
+    readonly url: string;
+    readonly sessionId: string;
+    /** The journey to drive, in the caller's own words. Absent means the child picks one. */
+    readonly flow?: string | undefined;
+    /** The capabilities file, when the session says it was never finished. */
+    readonly unfinishedCapabilitiesFile?: string | undefined;
+    /** The tab is hidden or throttled, so the child should not blame the app for a frozen page. */
+    readonly tabThrottled: boolean;
+    readonly budgetUsd: number;
+    readonly model?: string | undefined;
+}
+export interface DriveReport {
+    /** The agent's own account, kept verbatim and never treated as a pass on its own. */
+    readonly text: string;
+    readonly grade?: string | undefined;
+    readonly turns?: number | undefined;
+    readonly costUsd?: number | undefined;
+    /** Set when the run was cut short, naming where it had got to. */
+    readonly incomplete?: string | undefined;
+}
+/**
+ * Findings are the point, not the verdict.
+ *
+ * A green verdict demonstrates the mechanism. What people remember is Reticle telling them
+ * something they did not know — measured on a real app, a drive's own assertion passed and Reticle
+ * overruled it on a 504 fired inside the action window, which the drive then reported rather than
+ * explaining away. That only happens if the drive is asked for it: asked for a verdict alone, it
+ * returns a verdict alone, and everything else the page did goes unmentioned.
+ */
+/**
+ * The task LEADS.
+ *
+ * Measured: with the situation first and a capabilities dump in the middle, a model answered "I
+ * don't see an actual task or request from you yet" and drove nothing — one turn, no verdict, and
+ * setup reported success. Context goes after the ask, never before it.
+ */
+export declare function buildDrivePrompt(req: DriveRequest): string;
+/**
+ * NDJSON, one event per line.
+ *
+ * `--output-format json` emits nothing until the run completes, so a drive killed at the timeout
+ * left no trace of what it had been doing — measured four times on one app, every one reporting
+ * "the drive produced no output". Streaming turns that into evidence, because spawnSync hands back
+ * the stdout it collected before killing the child.
+ */
+export declare function readDriveOutput(out: string): DriveReport;
+/**
+ * The prompt goes on STDIN.
+ *
+ * `--allowedTools` is variadic: with the prompt passed positionally after it, the flag swallowed
+ * the prompt as another tool name and the run exited in two seconds having done nothing, with the
+ * error on stderr — which the caller was discarding. No flag ordering is safe across four CLIs.
+ */
+export declare function driveWith(driver: DriverSpec, req: DriveRequest, cwd: string): DriveReport;
+/** Everything that is not Claude Code reports prose, so the report IS its output. */
+export declare function readPlainOutput(out: string): DriveReport;

package/dist/setup/drive-agent.js

@@ -0,0 +1,171 @@
+/**
+ * Asking a child agent to drive the app, and reading what it says back.
+ *
+ * The drive needs a model, and the model does not need to be the caller. A client reads its MCP
+ * server list once at startup and cannot reload it, so an agent that has just run `init` does not
+ * yet have the reticle_* tools — which is why the hand-driven procedure asks for a restart, and why
+ * three runs in five ended there having shown the user nothing. A child process started after init
+ * reads the list init just wrote. No restart, no lost context, no waiting on a human.
+ *
+ * Two details here are not stylistic, and both cost a real run to learn.
+ */
+import { spawnSync } from 'node:child_process';
+import { ASSERTED, readAssertionsGrade } from './drive-plan.js';
+/** Ten minutes. Long, because the drive is a model working, and bounded, because it can wedge. */
+export const DRIVE_TIMEOUT_MS = 10 * 60_000;
+/** Only the Reticle surface, unless the capabilities file has to be finished first. */
+const RETICLE_TOOLS = 'mcp__reticle';
+const CAPABILITY_TOOLS = 'mcp__reticle,Read,Edit,Write';
+/**
+ * Findings are the point, not the verdict.
+ *
+ * A green verdict demonstrates the mechanism. What people remember is Reticle telling them
+ * something they did not know — measured on a real app, a drive's own assertion passed and Reticle
+ * overruled it on a 504 fired inside the action window, which the drive then reported rather than
+ * explaining away. That only happens if the drive is asked for it: asked for a verdict alone, it
+ * returns a verdict alone, and everything else the page did goes unmentioned.
+ */
+/**
+ * The task LEADS.
+ *
+ * Measured: with the situation first and a capabilities dump in the middle, a model answered "I
+ * don't see an actual task or request from you yet" and drove nothing — one turn, no verdict, and
+ * setup reported success. Context goes after the ask, never before it.
+ */
+export function buildDrivePrompt(req) {
+    const task = undefined === req.flow ? 'drive one user flow' : `drive THIS flow — ${req.flow}`;
+    const capabilities = undefined === req.unfinishedCapabilitiesFile
+        ? ''
+        : `\n\nFIRST: this session reports hasCapabilities:false, so ${req.unfinishedCapabilitiesFile} was scaffolded and never finished. Register whatever the app's state is readable through, and list the testids your flow touches. EDIT ONLY THAT FILE. This is somebody's repository, not a scratch copy: if the app is broken in a way that blocks the drive (a build error, a missing asset, an auth wall), say so and stop. That is a finding worth having and it is theirs to fix.`;
+    const throttled = req.tabThrottled
+        ? '\n\nNOTE: this tab is hidden or throttled, so timers and rAF are clamped. If an action seems to land on a page that never advances, that is why — say so rather than reporting `unknown` as if the app were at fault.'
+        : '';
+    return (`TASK: ${task} in this running app and produce a verdict. Do it now; do not ask questions, there is nobody to answer.\n\n` +
+        `The app is at ${req.url} and Reticle session ${req.sessionId} is connected to it.${capabilities}${throttled}\n\n` +
+        'In as few calls as you can: ONE reticle_snapshot({mode:"interactive"}) for the whole flow, ' +
+        'reticle_act_sequence for every fill and intermediate click in one call, then ONE ' +
+        'reticle_act_and_wait({ref,action,until}) — that is the call that produces the verdict, and ' +
+        '`until` names the expected consequence BEFORE the action fires. Then reticle_state() once. ' +
+        'Wrap it in reticle_record start/stop and reticle_flow_save.\n\n' +
+        `Then CHECK the grade reticle_flow_save returns. Anything other than \`${ASSERTED}\` means the ` +
+        'flow only ACTS: it will pass even when the feature is broken, and this setup replays that flow ' +
+        'on every later run, so an unasserted flow becomes a permanent green. If it is weaker, record ' +
+        'again with an `until` that names a consequence the action CHANGES.\n\n' +
+        'Then, whatever the verdict says: call reticle_observe ONCE and report anything the app did that ' +
+        'its owner would want to know. A console error, a failed or slow request, an unhandled ' +
+        'rejection, a state that did not update, a request fired twice. Give the `file:line` wherever ' +
+        'you have it. A flow that passed with a 500 behind it is not a clean app, and this is the part ' +
+        'they cannot see for themselves — it is the most useful thing you will produce, so do not skip ' +
+        'it because the verdict was green.\n\n' +
+        'Report in this order: FINDINGS first (or "nothing else worth reporting" if the page really was ' +
+        'clean), then the flow name, the verdict, and assertions.grade. A verdict of "unknown" or ' +
+        '"no-fault" is NOT a pass — say so plainly rather than weakening the check until it passes.');
+}
+/**
+ * NDJSON, one event per line.
+ *
+ * `--output-format json` emits nothing until the run completes, so a drive killed at the timeout
+ * left no trace of what it had been doing — measured four times on one app, every one reporting
+ * "the drive produced no output". Streaming turns that into evidence, because spawnSync hands back
+ * the stdout it collected before killing the child.
+ */
+export function readDriveOutput(out) {
+    const events = [];
+    for (const line of String(out).split('\n')) {
+        if ('' === line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if ('object' === typeof parsed && null !== parsed)
+                events.push(parsed);
+        }
+        catch {
+            /* a truncated final line is what a killed run looks like */
+        }
+    }
+    const finished = [...events].reverse().find((e) => undefined !== e['total_cost_usd']);
+    if (undefined !== finished) {
+        const text = 'string' === typeof finished['result'] ? finished['result'] : '';
+        return {
+            text,
+            ...(undefined === readAssertionsGrade(text) ? {} : { grade: readAssertionsGrade(text) }),
+            ...('number' === typeof finished['num_turns'] ? { turns: finished['num_turns'] } : {}),
+            ...('number' === typeof finished['total_cost_usd']
+                ? { costUsd: finished['total_cost_usd'] }
+                : {}),
+        };
+    }
+    return { text: '', incomplete: describeUnfinished(events) };
+}
+/** Where a killed run had got to, from the last thing it did. */
+function describeUnfinished(events) {
+    for (const event of [...events].reverse()) {
+        if ('assistant' !== event['type'])
+            continue;
+        const message = event['message'];
+        const content = 'object' === typeof message && null !== message
+            ? message.content
+            : undefined;
+        if (!Array.isArray(content))
+            continue;
+        for (const part of content) {
+            if ('object' !== typeof part || null === part)
+                continue;
+            const p = part;
+            if ('tool_use' === p.type && 'string' === typeof p.name)
+                return `it was calling \`${p.name}\``;
+            if ('text' === p.type && 'string' === typeof p.text)
+                return `the last thing it said was: ${p.text.slice(0, 300)}`;
+        }
+    }
+    return 'it produced no events at all';
+}
+/**
+ * The prompt goes on STDIN.
+ *
+ * `--allowedTools` is variadic: with the prompt passed positionally after it, the flag swallowed
+ * the prompt as another tool name and the run exited in two seconds having done nothing, with the
+ * error on stderr — which the caller was discarding. No flag ordering is safe across four CLIs.
+ */
+export function driveWith(driver, req, cwd) {
+    const tools = undefined === req.unfinishedCapabilitiesFile ? RETICLE_TOOLS : CAPABILITY_TOOLS;
+    const prompt = buildDrivePrompt(req);
+    const args = driver.argv({
+        tools,
+        budgetUsd: req.budgetUsd,
+        model: req.model,
+        prompt,
+    });
+    const child = spawnSync(driver.bin, args, {
+        cwd,
+        encoding: 'utf8',
+        timeout: DRIVE_TIMEOUT_MS,
+        maxBuffer: 64 * 1024 * 1024,
+        // Only for the drivers that read it. Passing stdin to one that takes the prompt as an argument
+        // is harmless, but passing it as an argument to one that reads stdin is not: `--allowedTools`
+        // is variadic and swallowed a positional prompt, and the run exited in two seconds having done
+        // nothing at all.
+        ...('stdin' === driver.promptVia ? { input: prompt } : {}),
+    });
+    const stdout = child.stdout ?? '';
+    const report = driver.streamsNdjson ? readDriveOutput(stdout) : readPlainOutput(stdout);
+    if ('' !== report.text || undefined !== report.incomplete)
+        return report;
+    const stderr = String(child.stderr ?? '')
+        .trim()
+        .split('\n')
+        .slice(-3)
+        .join(' ');
+    return {
+        text: '',
+        incomplete: '' === stderr ? 'it produced no output at all' : stderr.slice(0, 300),
+    };
+}
+/** Everything that is not Claude Code reports prose, so the report IS its output. */
+export function readPlainOutput(out) {
+    const text = String(out).trim();
+    if ('' === text)
+        return { text: '', incomplete: 'it produced no output at all' };
+    const grade = readAssertionsGrade(text);
+    return { text, ...(undefined === grade ? {} : { grade }) };
+}

package/dist/setup/drive-plan.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Who drives the app, and whether what they left behind is worth keeping.
+ *
+ * The drive is the only part of setup that needs a model, and the only part that can succeed
+ * expensively and leave something worthless. Both of those are decisions, so both live here where
+ * they can be tested without spending anything.
+ */
+/** What a driver needs to build its own invocation. */
+export interface DriveInvocation {
+    /** The tools the drive may use, comma-separated, in Claude Code's spelling. */
+    readonly tools: string;
+    readonly budgetUsd: number;
+    readonly model: string | undefined;
+    /** Passed as an argument only by drivers whose promptVia is 'arg'. */
+    readonly prompt: string;
+}
+/**
+ * An agent CLI that can be asked to drive, in preference order.
+ *
+ * Each carries its OWN argv, because they share nothing. A table that lists four drivers and builds
+ * one CLI's flags for all of them does not support four drivers: it supports one and fails the
+ * others with an unknown-flag error, which is what this looked like before.
+ */
+export interface DriverSpec {
+    readonly id: string;
+    readonly bin: string;
+    /** How its prompt is delivered. Gemini and Codex take it as an argument; the rest read stdin. */
+    readonly promptVia: 'stdin' | 'arg';
+    /** Its own flags, in its own spelling. */
+    readonly argv: (invocation: DriveInvocation) => string[];
+    /** NDJSON, for the one CLI that streams it. Everything else reports prose. */
+    readonly streamsNdjson: boolean;
+    /** True where the invocation is documented but has not been watched driving a real app here. */
+    readonly unverified?: boolean;
+}
+export declare const DRIVERS: readonly DriverSpec[];
+/**
+ * The first driver that is present AND runs.
+ *
+ * The second half is the one that has bitten: a CLI can be on PATH and broken — a half-installed
+ * codex whose vendor binary is missing exits non-zero on every invocation — and driving with one of
+ * those produces an empty session that looks exactly like success.
+ */
+export declare function chooseDriver(drivers: readonly DriverSpec[], probe: (bin: string) => {
+    readonly present: boolean;
+    readonly runs: boolean;
+}): DriverSpec | null;
+/** The grade `reticle_flow_save` reported, read out of the drive's own prose. */
+export declare function readAssertionsGrade(text: string | undefined): string | undefined;
+/** The only grade that makes a saved flow worth replaying. */
+export declare const ASSERTED = "asserted";
+export interface EscalationInput {
+    readonly escalationEnabled: boolean;
+    /** Set only when a faster model was chosen, since escalation means retrying without it. */
+    readonly fasterModel: string | undefined;
+    readonly flowSaved: boolean;
+    readonly grade: string | undefined;
+}
+/**
+ * Whether to re-record with the stronger model.
+ *
+ * Measured: a faster model reaches the same `verified: "yes"` about three times quicker and leaves
+ * an `assertion-free` or `presence-only` flow in three runs out of four. Such a flow only ACTS, so
+ * it passes even when the feature is broken — and setup replays saved flows on every later run,
+ * which turns one weak recording into a permanent green. Presenting that as a trade for the user to
+ * choose is worse than spending a second drive on it.
+ */
+export declare function shouldEscalate(input: EscalationInput): boolean;

package/dist/setup/drive-plan.js

@@ -0,0 +1,130 @@
+/**
+ * Who drives the app, and whether what they left behind is worth keeping.
+ *
+ * The drive is the only part of setup that needs a model, and the only part that can succeed
+ * expensively and leave something worthless. Both of those are decisions, so both live here where
+ * they can be tested without spending anything.
+ */
+export const DRIVERS = [
+    {
+        id: 'claude',
+        bin: 'claude',
+        promptVia: 'stdin',
+        streamsNdjson: true,
+        argv: ({ tools, budgetUsd, model }) => [
+            '-p',
+            '--permission-mode',
+            'acceptEdits',
+            '--allowedTools',
+            tools,
+            ...(undefined === model ? [] : ['--model', model]),
+            '--max-budget-usd',
+            String(budgetUsd),
+            // stream-json, not json: `json` emits nothing until the run completes, so a drive killed at
+            // the timeout left no trace of where it had got to.
+            '--output-format',
+            'stream-json',
+            '--verbose',
+        ],
+    },
+    {
+        id: 'codex',
+        bin: 'codex',
+        // `codex exec` is its headless form and takes the prompt positionally.
+        promptVia: 'arg',
+        streamsNdjson: false,
+        unverified: true,
+        argv: ({ prompt, model }) => [
+            'exec',
+            ...(undefined === model ? [] : ['--model', model]),
+            prompt,
+        ],
+    },
+    {
+        id: 'opencode',
+        bin: 'opencode',
+        // `opencode run [message..]`, verified against its own --help on this machine.
+        promptVia: 'arg',
+        streamsNdjson: false,
+        unverified: true,
+        argv: ({ prompt, model }) => [
+            'run',
+            ...(undefined === model ? [] : ['--model', model]),
+            prompt,
+        ],
+    },
+    {
+        id: 'cursor-agent',
+        bin: 'cursor-agent',
+        promptVia: 'arg',
+        streamsNdjson: false,
+        unverified: true,
+        argv: ({ prompt, model }) => [
+            '-p',
+            ...(undefined === model ? [] : ['--model', model]),
+            '--output-format',
+            'text',
+            prompt,
+        ],
+    },
+    {
+        id: 'gemini',
+        bin: 'gemini',
+        // Gemini takes its prompt as the value of -p, and gates MCP servers by name.
+        promptVia: 'arg',
+        streamsNdjson: false,
+        unverified: true,
+        argv: ({ prompt, model }) => [
+            '-p',
+            prompt,
+            ...(undefined === model ? [] : ['--model', model]),
+            '--allowed-mcp-server-names',
+            'reticle',
+            '--output-format',
+            'text',
+        ],
+    },
+];
+/**
+ * The first driver that is present AND runs.
+ *
+ * The second half is the one that has bitten: a CLI can be on PATH and broken — a half-installed
+ * codex whose vendor binary is missing exits non-zero on every invocation — and driving with one of
+ * those produces an empty session that looks exactly like success.
+ */
+export function chooseDriver(drivers, probe) {
+    for (const d of drivers) {
+        const { present, runs } = probe(d.bin);
+        if (present && runs)
+            return d;
+    }
+    return null;
+}
+/** The grade `reticle_flow_save` reported, read out of the drive's own prose. */
+export function readAssertionsGrade(text) {
+    const source = text ?? '';
+    return (/assertions?\.?grade\W+`?([a-z-]+)/i.exec(source)?.[1] ??
+        /grade\W+`?([a-z-]+)/i.exec(source)?.[1]);
+}
+/** The only grade that makes a saved flow worth replaying. */
+export const ASSERTED = 'asserted';
+/**
+ * Whether to re-record with the stronger model.
+ *
+ * Measured: a faster model reaches the same `verified: "yes"` about three times quicker and leaves
+ * an `assertion-free` or `presence-only` flow in three runs out of four. Such a flow only ACTS, so
+ * it passes even when the feature is broken — and setup replays saved flows on every later run,
+ * which turns one weak recording into a permanent green. Presenting that as a trade for the user to
+ * choose is worse than spending a second drive on it.
+ */
+export function shouldEscalate(input) {
+    if (!input.escalationEnabled)
+        return false;
+    if (undefined === input.fasterModel)
+        return false;
+    if (!input.flowSaved)
+        return false;
+    if (undefined === input.grade)
+        return false;
+    return ASSERTED !== input.grade;
+}

package/dist/setup/ensure-daemon.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Making sure something is listening before the app is asked to dial it.
+ *
+ * The setup phases wait for the page to appear as a session, which cannot happen unless a daemon
+ * holds the bridge port. Nothing in `init` started one. On a developer machine that is invisible,
+ * because an editor running `reticle mcp` has had a daemon up for hours; on a machine installing
+ * Reticle for the first time, which is every machine this command exists for, there is nothing to
+ * dial and setup ends with "the SDK is in the page and never dialled the bridge" — the SDK being
+ * blamed for the absence of the thing it was dialling.
+ *
+ * Idempotent by construction: an alive daemon for this project is adopted, and one belonging to
+ * somebody else is refused rather than stolen, which is the same rule `reticle mcp` follows.
+ */
+export interface EnsureDaemonDeps {
+    readonly usable: (port: number) => Promise<boolean>;
+    readonly spawn: (port: number) => boolean;
+    readonly waitReady: (port: number) => Promise<unknown>;
+    readonly scriptPath: string | undefined;
+}
+export declare const EnsureDaemon: {
+    /** Something usable was already there. */
+    readonly ADOPTED: "adopted";
+    readonly STARTED: "started";
+    /** Could not be started, and the caller has to say so rather than blame the page. */
+    readonly UNAVAILABLE: "unavailable";
+};
+export type EnsureDaemon = (typeof EnsureDaemon)[keyof typeof EnsureDaemon];
+export declare function ensureDaemon(port: number, deps: EnsureDaemonDeps): Promise<EnsureDaemon>;
+export declare function nodeEnsureDaemonDeps(): EnsureDaemonDeps;