@reticlehq/server 2.14.0 → 3.2.0

package/dist/setup/drive-agent.js

@@ -1,171 +0,0 @@
-/**
- * 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. */
-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

@@ -1,69 +0,0 @@
-/**
- * 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. */
-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";
-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;
-export {};

package/dist/setup/drive-plan.js

@@ -1,130 +0,0 @@
-/**
- * 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.js

@@ -1,58 +0,0 @@
-/**
- * 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.
- */
-import { log } from '../log.js';
-import { spawnDaemon } from '../daemon/daemon.js';
-import { probePresence, presenceIsUsable } from '../daemon/port-presence.js';
-import { waitForDaemon, probeDaemon } from '../mcp/mcp-proxy.js';
-import { daemonSpawnArgs } from '../cli/daemon-start-options.js';
-import { fetchStatus } from '../cli/cli-launch.js';
-export const EnsureDaemon = {
-    /** Something usable was already there. */
-    ADOPTED: 'adopted',
-    STARTED: 'started',
-    /** Could not be started, and the caller has to say so rather than blame the page. */
-    UNAVAILABLE: 'unavailable',
-};
-export async function ensureDaemon(port, deps) {
-    if (await deps.usable(port))
-        return EnsureDaemon.ADOPTED;
-    if (undefined === deps.scriptPath)
-        return EnsureDaemon.UNAVAILABLE;
-    if (!deps.spawn(port))
-        return EnsureDaemon.UNAVAILABLE;
-    try {
-        // Readiness means the port ACCEPTS, not that a child was spawned: a readiness signal that
-        // precedes readiness is worse than none, because what waits on it stops waiting too early.
-        await deps.waitReady(port);
-    }
-    catch {
-        return EnsureDaemon.UNAVAILABLE;
-    }
-    return (await deps.usable(port)) ? EnsureDaemon.STARTED : EnsureDaemon.UNAVAILABLE;
-}
-export function nodeEnsureDaemonDeps() {
-    return {
-        usable: async (port) => presenceIsUsable(await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus })),
-        spawn: (port) => {
-            const scriptPath = process.argv[1];
-            if (undefined === scriptPath)
-                return false;
-            const started = spawnDaemon(process.execPath, scriptPath, daemonSpawnArgs({ port, headless: true, http: false }), port);
-            log('reticle_setup_daemon_started', { port, started });
-            return started;
-        },
-        waitReady: (port) => waitForDaemon(port),
-        scriptPath: process.argv[1],
-    };
-}

package/dist/setup/init-host.js

@@ -1,26 +0,0 @@
-import { spanSync } from '../trace.js';
-import { reportInitOutcome } from '../telemetry/init-telemetry.js';
-import { defaultPairingTokenDir, readOrCreatePairingTokenSync } from '../bridge/pairing-token.js';
-import { declaredInstallSource } from '../telemetry/install-source.js';
-export function serverInitHost() {
-    return {
-        span(name, fields, fn) {
-            return spanSync(name, fields, fn);
-        },
-        reportOutcome(outcome) {
-            reportInitOutcome(outcome);
-        },
-        /**
-         * Minted here if nothing has written it yet. `init` used to READ the file and return empty when
-         * the daemon had never started; the CDN snippet inlined that empty value permanently, and
-         * regenerating the token made the pasted literal stale. Same mint as the daemon
-         * (`readOrCreatePairingToken`), and it honours `RETICLE_PAIRING_TOKEN_DIR`.
-         */
-        pairingToken() {
-            return readOrCreatePairingTokenSync(defaultPairingTokenDir()) ?? '';
-        },
-        installSource() {
-            return declaredInstallSource();
-        },
-    };
-}

package/dist/setup/init-runtime.d.ts

@@ -1,41 +0,0 @@
-/**
- * What `init` does after the files are written, and how it decides whether to.
- *
- * Lives here rather than in cli.ts because it is a cohesive unit with its own reasons, and because
- * cli.ts is a dispatcher: a command that grew a second half should not make the file that routes
- * every command harder to read.
- */
-import type { InitResult } from '@reticlehq/init';
-/** Just enough of the parsed command to decide and run. */
-interface InitRuntimeArgs {
-    readonly port: number | undefined;
-    readonly dryRun: boolean;
-    readonly filesOnly?: boolean | undefined;
-    readonly json?: boolean | undefined;
-    readonly drive?: boolean | undefined;
-    readonly open?: boolean | undefined;
-    readonly agents?: boolean | undefined;
-    /**
-     * `--no-mcp`. It governs agent registration too, and pre-approval with it.
-     *
-     * The flag's own help says it skips MORE than the server registration, "because all three only
-     * make sense once the tools are reachable" — and a pre-approval rule for a server the machine was
-     * told not to register is the clearest case of that. It went unread when the registration moved
-     * here, so a run that asked us to leave the machine's config alone wrote to four files in the
-     * user's home. The install gate caught it, because the gate runs with --no-mcp.
-     */
-    readonly mcp?: boolean | undefined;
-    readonly flow?: string | undefined;
-    readonly env?: string[] | undefined;
-    readonly url?: string | undefined;
-    readonly timeoutSeconds?: number | undefined;
-    /** Restart the calling client so IT gets the tools — see relaunch.ts. */
-    readonly relaunch?: boolean | undefined;
-    readonly driveModel?: string | undefined;
-    readonly licenseKey?: string | undefined;
-}
-interface RuntimePrintIo {
-    readonly print: (line: string) => void;
-}
-export declare function continueAfterInit(parsed: InitRuntimeArgs, result: InitResult, io: RuntimePrintIo, cwd: string): Promise<void>;
-export {};

package/dist/setup/init-runtime.js

@@ -1,167 +0,0 @@
-/**
- * What `init` does after the files are written, and how it decides whether to.
- *
- * Lives here rather than in cli.ts because it is a cohesive unit with its own reasons, and because
- * cli.ts is a dispatcher: a command that grew a second half should not make the file that routes
- * every command harder to read.
- */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
-import { confirmInstall, nodeConfirmDeps } from './confirm.js';
-import { writeLicenseKey } from './license-key.js';
-import { registerOtherAgents, runSetupCommand } from './setup-command.js';
-import { bridgeOccupied } from './bridge-port.js';
-import { relaunchDecision } from './relaunch.js';
-import { claudeTranscriptExists, codexSessionFor } from './transcripts.js';
-import { probePresence } from '../daemon/port-presence.js';
-import { probeDaemon } from '../mcp/proxy-daemon-probe.js';
-import { fetchStatus } from '../cli/cli-launch.js';
-import { collectEnv, DEFAULT_DRIVE_BUDGET_USD, DEFAULT_PHASE_TIMEOUT_MS } from './setup-options.js';
-/** How often the runtime phases look again: fast enough not to be the wait, slow enough to be free. */
-const POLL_MS = 250;
-/** Registration is global MCP wiring, so both flags that disown it are read here. */
-function wantsAgents(parsed) {
-    return false !== parsed.agents && false !== parsed.mcp;
-}
-const licenseIo = {
-    exists: (path) => existsSync(path),
-    readFile: (path) => readFileSync(path, 'utf8'),
-    writeFile: (path, contents) => writeFileSync(path, contents),
-};
-/**
- * Carry on from a finished `init`, or stop where it used to.
- *
- * `--files-only` is what init did before it learned to boot the app, and a dry run is a preview:
- * both keep the old ending. Everyone else gets the rest, because writing files was never the same
- * thing as an install working.
- */
-function printRelaunch(parsed, io, cwd) {
-    if (true !== parsed.relaunch)
-        return;
-    io.print(relaunchDecision({
-        ...(undefined === process.env['CLAUDE_CODE_SESSION_ID']
-            ? {}
-            : { claudeSessionId: process.env['CLAUDE_CODE_SESSION_ID'] }),
-        ...(undefined === codexSessionFor(cwd) ? {} : { codexSessionId: codexSessionFor(cwd) }),
-        transcriptExists: claudeTranscriptExists,
-        cwd,
-    }).message);
-    io.print('');
-}
-export async function continueAfterInit(parsed, result, io, cwd) {
-    const port = parsed.port ?? RETICLE_DEFAULT_PORT;
-    // Before anything else: the key belongs in .env whichever way this run ends, and the CLI folds a
-    // project-local .env into the environment on every invocation.
-    if (undefined !== parsed.licenseKey) {
-        const written = writeLicenseKey(cwd, parsed.licenseKey, licenseIo);
-        io.print(written.message);
-    }
-    // Decided and printed before the `--files-only` return, not after it. The restart question is
-    // asked by whoever just installed, and `--files-only` is the mode an agent uses when the app is
-    // ALREADY running — so the one route that most needs the answer was the one route that could not
-    // reach it, and `--relaunch --files-only` accepted the flag and silently did nothing with it.
-    //
-    // Never performed: opening a terminal is not something a one-shot command should do behind a
-    // flag, and the half worth having is the refusal — `--resume` on an id with no transcript opens
-    // an EMPTY conversation that looks exactly like it worked. See relaunch.ts.
-    printRelaunch(parsed, io, cwd);
-    if (true === parsed.filesOnly || parsed.dryRun) {
-        // Registration and pre-approval still run here, and this is the ONLY route an existing user
-        // has: nothing reaches back into a machine that installed Reticle a version ago, so the
-        // upgrade path is re-running init, and the light form of init has to be enough to carry it.
-        // A dry run writes nothing anywhere, including here.
-        if (true === parsed.filesOnly && wantsAgents(parsed))
-            registerOtherAgents(io.print);
-        return confirmInstall(result, io, nodeConfirmDeps(port)).then(() => {
-            if (!result.ok)
-                process.exit(1);
-        });
-    }
-    const context = result.context;
-    if (context === undefined) {
-        // Nothing was established, so there is nothing to run against. init has already said why.
-        process.exit(1);
-    }
-    // A PENDING connect step is not a reason to skip the runtime phase, and treating it as one made
-    // `init` stop with "paste this snippet" while never looking at the app.
-    //
-    // `result.ok` is exactly `!connectPending`, so every project whose instrumentation needs a manual
-    // step — a plain-HTML app, anything with no recognised build config — exited here. The user was
-    // told to do something by hand and told nothing about whether their server was even up, whether
-    // the snippet had landed, or which url was checked. The runtime phase answers all three, and its
-    // answers are the actionable ones: "nothing is serving http://…", "the SDK is NOT in the page".
-    //
-    // The run still ends non-zero: the phase returns `ok: false` when no session appears, and a
-    // session appearing means the manual step WAS done and the app really did connect — which is a
-    // green worth reporting, not one to suppress.
-    // Before the connect wait, never after: a bridge held by a stranger makes a session impossible,
-    // so going ahead spends the entire budget and then reports what reads as an instrumentation
-    // problem — the one place that is fine. See bridge-port.ts.
-    const refusal = bridgeOccupied(await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }), port);
-    if (refusal !== undefined) {
-        io.print(refusal);
-        process.exit(1);
-    }
-    return runSetupCommand({
-        appDir: context.appDir,
-        invokedAt: cwd,
-        bridgePort: port,
-        env: collectEnv(parsed.env ?? []),
-        openBrowser: false !== parsed.open,
-        drive: false !== parsed.drive,
-        registerAgents: wantsAgents(parsed),
-        escalateWeakFlow: true,
-        driveBudgetUsd: DEFAULT_DRIVE_BUDGET_USD,
-        phaseTimeoutMs: undefined === parsed.timeoutSeconds
-            ? DEFAULT_PHASE_TIMEOUT_MS
-            : parsed.timeoutSeconds * 1000,
-        // Only when the caller actually said so — see connectBudgetMs. Omitted, the shape's policy
-        // keeps deciding, so nobody who passed nothing waits less than they used to.
-        ...(undefined === parsed.timeoutSeconds
-            ? {}
-            : { connectBudgetMs: parsed.timeoutSeconds * 1000 }),
-        pollMs: POLL_MS,
-        ...(undefined === context.devCommand ? {} : { devCommand: context.devCommand }),
-        ...(undefined === parsed.flow ? {} : { flow: parsed.flow }),
-        ...(undefined === parsed.url ? {} : { suppliedUrl: parsed.url }),
-        ...(undefined === parsed.driveModel ? {} : { driveModel: parsed.driveModel }),
-    }, (line) => io.print(line)).then((outcome) => {
-        // One object, so an agent reads a result instead of interpreting a report.
-        if (true === parsed.json) {
-            process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
-            if (!outcome.ok)
-                process.exit(1);
-            return;
-        }
-        io.print('');
-        // The drive's own account, whether it ended well or not. Discarding it left a run that reached
-        // the drive, produced something, and told the reader nothing about what it found.
-        if (undefined !== outcome.verdict && '' !== outcome.verdict) {
-            io.print(outcome.verdict);
-            io.print('');
-        }
-        if (outcome.ok && !outcome.flowSaved) {
-            // Success, and no flow. Saying "a flow was driven" here would replace a wrong exit code with
-            // a wrong sentence, which is the worse of the two: the exit code is read by CI and the
-            // sentence is read by a person deciding whether their app is verified. It is not.
-            io.print(`✓ ${outcome.url ?? 'the app'} is instrumented and connected — but NOT verified.`);
-            for (const [i, step] of outcome.fallback.entries())
-                io.print(`   ${String(i + 1)}. ${step}`);
-            return;
-        }
-        if (outcome.ok) {
-            io.print(`✓ setup complete — ${outcome.url ?? 'the app'} is instrumented and a flow was driven.`);
-            // A passing flow shows the mechanism working. What the run SAW is the part nobody can get for
-            // themselves, and it deserves a line of its own rather than a paragraph that gets skimmed.
-            io.print('  Read the FINDINGS above before moving on: a flow can pass with a failed request or a ' +
-                'console error behind it, and that is the app, not the check.');
-            return;
-        }
-        // A run that produced no verdict did not succeed, and the exit code is the one place a caller
-        // reads that without parsing anything.
-        io.print('⚠ setup did not finish. To carry on from here:');
-        for (const [i, step] of outcome.fallback.entries())
-            io.print(`   ${i + 1}. ${step}`);
-        process.exit(1);
-    });
-}