@reticlehq/server 2.11.0 → 2.13.0

package/dist/setup/auto-approve.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Removing the Accept button, for the tools Reticle owns and nothing else.
+ *
+ * A drive that stops on a per-call approval dialog is not automated, and the dialog is per CALL:
+ * a single verification run makes dozens, so a human sits there clicking through a loop that was
+ * supposed to run without them. Every client below documents a way to pre-approve a named server,
+ * and this writes exactly that rule, at install time, in the client's own spelling.
+ *
+ * Two limits, both deliberate:
+ *
+ * 1. ONLY `reticle` is allowed. Not `mcp(*)`, not a global auto-run switch. Reticle's tools drive
+ *    the user's own dev server on their own machine, which is what makes pre-approving them
+ *    defensible; the same edit made globally would hand the same pass to every other MCP server
+ *    they ever install, including ones that reach the network. Their approval gate is not ours to
+ *    dismantle, only ours to step out of.
+ * 2. Nothing is written for an agent that is not installed. An absent agent has no Accept button to
+ *    remove, and the file would be litter — Cursor's especially, since that one TAKES OVER from an
+ *    allowlist we cannot read.
+ *
+ * Codex is absent by design: its approval policy is global (`approval_policy`), so there is no
+ * reticle-shaped rule to write, and its config is TOML, which this repo never rewrites. Its
+ * headless form, `codex exec`, does not prompt at all — which is the form the drive uses.
+ */
+import { type PlatformPaths } from './agent-configs.js';
+import type { AgentWriterIo } from './agent-writer.js';
+/** A documented way to pre-approve one MCP server, in one client's own spelling. */
+export interface ApprovalGrant {
+    readonly id: string;
+    readonly name: string;
+    /** Home-relative, per platform. */
+    readonly paths: PlatformPaths;
+    /** Present if ANY of these exist. An agent that is not installed is not configured. */
+    readonly markers: readonly PlatformPaths[];
+    /** The rule, in the client's words, for the plan output. */
+    readonly rule: string;
+    /** Adds our rule to a parsed config, leaving everything else exactly as it was. */
+    readonly grant: (current: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * True where creating this file supersedes an in-app allowlist we cannot read, so the user has to
+     * be told rather than have their other servers quietly start prompting again.
+     */
+    readonly supersedesInApp?: boolean;
+}
+export declare const APPROVAL_GRANTS: readonly ApprovalGrant[];
+export declare const ApprovalOutcome: {
+    readonly GRANTED: "granted";
+    readonly ALREADY: "already";
+    readonly ABSENT: "absent";
+    /** Deliberately left for an explicit run, because doing it unattended costs the user something. */
+    readonly DEFERRED: "deferred";
+    readonly FAILED: "failed";
+};
+export type ApprovalOutcome = (typeof ApprovalOutcome)[keyof typeof ApprovalOutcome];
+export interface ApprovalResult {
+    readonly id: string;
+    readonly name: string;
+    readonly file: string;
+    readonly outcome: ApprovalOutcome;
+    readonly rule: string;
+    /** Set where the user has to be told something the write alone does not say. */
+    readonly warn?: string;
+}
+export interface ApprovalWhere {
+    readonly home: string;
+    readonly platform: keyof PlatformPaths;
+}
+export interface ApprovalOptions {
+    /**
+     * Refuse any grant that would CREATE a file superseding an allowlist we cannot read.
+     *
+     * Set on the unattended path. Writing Cursor's permissions.json for the first time takes over
+     * from what the user approved inside the app, which is a fair trade when they just ran a command
+     * and can read the line saying so, and not a fair trade at all when a version bump did it behind
+     * them: their OTHER MCP servers would start prompting again and nothing would connect that to us.
+     * Merging into a file they already own stays safe either way.
+     */
+    readonly onlyIfNoSupersede?: boolean;
+}
+/**
+ * Pre-approve Reticle's tools everywhere the machine has an agent that would otherwise ask.
+ *
+ * A client that cannot be written is reported, never thrown: one unwritable settings file is not a
+ * reason to leave the other three prompting.
+ */
+export declare function grantAutoApproval(io: AgentWriterIo, where: ApprovalWhere, grants?: readonly ApprovalGrant[], options?: ApprovalOptions): ApprovalResult[];

package/dist/setup/auto-approve.js

@@ -0,0 +1,150 @@
+/**
+ * Removing the Accept button, for the tools Reticle owns and nothing else.
+ *
+ * A drive that stops on a per-call approval dialog is not automated, and the dialog is per CALL:
+ * a single verification run makes dozens, so a human sits there clicking through a loop that was
+ * supposed to run without them. Every client below documents a way to pre-approve a named server,
+ * and this writes exactly that rule, at install time, in the client's own spelling.
+ *
+ * Two limits, both deliberate:
+ *
+ * 1. ONLY `reticle` is allowed. Not `mcp(*)`, not a global auto-run switch. Reticle's tools drive
+ *    the user's own dev server on their own machine, which is what makes pre-approving them
+ *    defensible; the same edit made globally would hand the same pass to every other MCP server
+ *    they ever install, including ones that reach the network. Their approval gate is not ours to
+ *    dismantle, only ours to step out of.
+ * 2. Nothing is written for an agent that is not installed. An absent agent has no Accept button to
+ *    remove, and the file would be litter — Cursor's especially, since that one TAKES OVER from an
+ *    allowlist we cannot read.
+ *
+ * Codex is absent by design: its approval policy is global (`approval_policy`), so there is no
+ * reticle-shaped rule to write, and its config is TOML, which this repo never rewrites. Its
+ * headless form, `codex exec`, does not prompt at all — which is the form the drive uses.
+ */
+import { joinFor } from './agent-configs.js';
+const RETICLE_KEY = 'reticle';
+const INDENT = 2;
+const home = (path) => ({ darwin: path, linux: path, win32: path });
+/** Append to a nested array, without duplicating and without disturbing what is already in it. */
+function addToList(current, outer, key, value) {
+    const scope = null === outer
+        ? current
+        : 'object' === typeof current[outer] && null !== current[outer]
+            ? { ...current[outer] }
+            : {};
+    const list = Array.isArray(scope[key]) ? scope[key] : [];
+    if (list.includes(value))
+        return current;
+    const next = { ...scope, [key]: [...list, value] };
+    return null === outer ? next : { ...current, [outer]: next };
+}
+export const APPROVAL_GRANTS = [
+    {
+        id: 'claude-code',
+        name: 'Claude Code',
+        paths: home('.claude/settings.json'),
+        markers: [home('.claude')],
+        rule: 'permissions.allow += "mcp__reticle"',
+        grant: (c) => addToList(c, 'permissions', 'allow', 'mcp__reticle'),
+    },
+    {
+        id: 'cursor',
+        name: 'Cursor',
+        paths: home('.cursor/permissions.json'),
+        markers: [home('.cursor')],
+        rule: 'mcpAllowlist += "reticle:*"',
+        // Documented: "when a key appears in permissions.json, it fully replaces the in-app allowlist
+        // for that type". Merging keeps everything already in the FILE; it cannot restore what was only
+        // ever clicked in the UI, so the user is told.
+        supersedesInApp: true,
+        grant: (c) => addToList(c, null, 'mcpAllowlist', `${RETICLE_KEY}:*`),
+    },
+    {
+        id: 'antigravity',
+        name: 'Antigravity',
+        paths: home('.gemini/antigravity-cli/settings.json'),
+        markers: [
+            {
+                darwin: 'Library/Application Support/Antigravity',
+                linux: '.config/Antigravity',
+                win32: 'AppData/Roaming/Antigravity',
+            },
+            home('.gemini/antigravity-cli'),
+        ],
+        rule: 'permissions.allow += "mcp(reticle/*)"',
+        grant: (c) => addToList(c, 'permissions', 'allow', `mcp(${RETICLE_KEY}/*)`),
+    },
+    {
+        id: 'gemini-cli',
+        name: 'Gemini CLI',
+        paths: home('.gemini/settings.json'),
+        markers: [home('.gemini')],
+        rule: 'mcpServers.reticle.trust = true',
+        // Gemini has no allowlist: trust is a property of the server entry itself, so this reaches into
+        // the entry init already wrote rather than adding a rule beside it.
+        grant: (c) => {
+            const servers = 'object' === typeof c['mcpServers'] && null !== c['mcpServers']
+                ? { ...c['mcpServers'] }
+                : {};
+            const entry = 'object' === typeof servers[RETICLE_KEY] && null !== servers[RETICLE_KEY]
+                ? servers[RETICLE_KEY]
+                : {};
+            return { ...c, mcpServers: { ...servers, [RETICLE_KEY]: { ...entry, trust: true } } };
+        },
+    },
+];
+export const ApprovalOutcome = {
+    GRANTED: 'granted',
+    ALREADY: 'already',
+    ABSENT: 'absent',
+    /** Deliberately left for an explicit run, because doing it unattended costs the user something. */
+    DEFERRED: 'deferred',
+    FAILED: 'failed',
+};
+/**
+ * Pre-approve Reticle's tools everywhere the machine has an agent that would otherwise ask.
+ *
+ * A client that cannot be written is reported, never thrown: one unwritable settings file is not a
+ * reason to leave the other three prompting.
+ */
+export function grantAutoApproval(io, where, grants = APPROVAL_GRANTS, options = {}) {
+    const join = joinFor(where.platform);
+    return grants.map((grant) => {
+        const file = join(where.home, grant.paths[where.platform]);
+        const base = { id: grant.id, name: grant.name, file, rule: grant.rule };
+        const installed = grant.markers.some((m) => io.exists(join(where.home, m[where.platform])));
+        if (!installed)
+            return { ...base, outcome: ApprovalOutcome.ABSENT };
+        try {
+            const existed = io.exists(file);
+            if (true === options.onlyIfNoSupersede && true === grant.supersedesInApp && !existed) {
+                return {
+                    ...base,
+                    outcome: ApprovalOutcome.DEFERRED,
+                    warn: `creating ${file} would supersede what you approved inside ${grant.name}, which is not something to do unannounced. Run: npx @reticlehq/server init --files-only`,
+                };
+            }
+            // A settings file we cannot parse is left exactly as it is. Reformatting somebody's config to
+            // add one line is a worse outcome than one dialog they have to click.
+            const current = existed
+                ? JSON.parse(io.readFile(file))
+                : {};
+            const next = grant.grant(current);
+            if (next === current)
+                return { ...base, outcome: ApprovalOutcome.ALREADY };
+            io.mkdirp(file.slice(0, Math.max(0, file.lastIndexOf('/'))));
+            io.writeFile(file, `${JSON.stringify(next, null, INDENT)}\n`);
+            const warn = true === grant.supersedesInApp && !existed
+                ? `${file} now governs which MCP tools run without asking; anything you had approved inside ${grant.name} itself will ask again until it is listed here too`
+                : undefined;
+            return { ...base, outcome: ApprovalOutcome.GRANTED, ...(undefined === warn ? {} : { warn }) };
+        }
+        catch (err) {
+            return {
+                ...base,
+                outcome: ApprovalOutcome.FAILED,
+                warn: String(err?.message ?? err).slice(0, 120),
+            };
+        }
+    });
+}

package/dist/setup/bridge-port.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The bridge port, checked before the connect wait.
+ *
+ * The bridge is the channel between the daemon and the SDK in the page. While something else holds
+ * that port no session can ever appear, however correct the instrumentation is — so a run that goes
+ * ahead spends its entire connect budget and then reports what looks like a wiring problem, sending
+ * the reader to the one place that is fine.
+ *
+ * `serve` refuses a held port too, in prose written for somebody starting a daemon. This is the same
+ * fact told to somebody installing, and it has to say what the bridge IS: that sentence is what
+ * makes "no session appeared" mean something.
+ */
+import { PortPresence } from '../daemon/port-presence.js';
+/** The refusal to print, or undefined when the port is usable. */
+export declare function bridgeOccupied(presence: PortPresence, port: number): string | undefined;

package/dist/setup/bridge-port.js

@@ -0,0 +1,24 @@
+/**
+ * The bridge port, checked before the connect wait.
+ *
+ * The bridge is the channel between the daemon and the SDK in the page. While something else holds
+ * that port no session can ever appear, however correct the instrumentation is — so a run that goes
+ * ahead spends its entire connect budget and then reports what looks like a wiring problem, sending
+ * the reader to the one place that is fine.
+ *
+ * `serve` refuses a held port too, in prose written for somebody starting a daemon. This is the same
+ * fact told to somebody installing, and it has to say what the bridge IS: that sentence is what
+ * makes "no session appeared" mean something.
+ */
+import { PortPresence } from '../daemon/port-presence.js';
+/** The refusal to print, or undefined when the port is usable. */
+export function bridgeOccupied(presence, port) {
+    // DAEMON is the ordinary case — that is the daemon init is about to use. FREE is fine too: one
+    // gets started. Only a stranger is fatal.
+    if (PortPresence.FOREIGN !== presence)
+        return undefined;
+    return (`port ${String(port)} is held by something that is not a Reticle daemon. That is the bridge — ` +
+        'the channel between the daemon and the SDK in your page — so no session can ever appear while ' +
+        'it is occupied, however correct the wiring is. Free it, or re-run with --port <n> and set the ' +
+        'same port in .reticle.json.');
+}

package/dist/setup/desktop-shape.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 declare const AppShape: {
+    readonly WEB: "web";
+    readonly ELECTRON: "electron";
+    readonly TAURI: "tauri";
+};
+export type AppShape = (typeof AppShape)[keyof typeof AppShape];
+export declare const isDesktop: (shape: AppShape) => boolean;
+/** Files and dependencies that name the shell, read through an injected reader. */
+export interface ShapeEvidence {
+    /** `src-tauri/tauri.conf.json` exists. */
+    readonly hasTauriConf: boolean;
+    /** `electron` is a dependency or devDependency. */
+    readonly hasElectronDep: boolean;
+}
+/**
+ * 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 declare function readShape(evidence: ShapeEvidence): AppShape;
+export declare function isDesktopOrigin(url: string): boolean;
+/**
+ * How the phases should behave for this shape.
+ *
+ * Returned as data rather than branched at each call site, so the differences are visible in one
+ * place and testable without a desktop runtime.
+ */
+export interface ShapePolicy {
+    /** Open a browser at the url. False for desktop: the app window is already the client. */
+    readonly openBrowser: boolean;
+    /** Require an HTTP response before looking for a session. */
+    readonly requireHttpReady: boolean;
+    /** How long the app gets to produce a session, which for Tauri includes a Rust build. */
+    readonly connectBudgetMs: number;
+    /** Said out loud, because a desktop run looks stuck if nobody explains the wait. */
+    readonly note: string | undefined;
+}
+export declare function policyFor(shape: AppShape): ShapePolicy;

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;