@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/setup/setup-command.js

@@ -0,0 +1,224 @@
+/**
+ * The wire: everything init established, plus the world, plus the phases.
+ *
+ * Kept apart from cli.ts so the assembly is readable in one place and so `handleInit` stays the
+ * three lines it was. The only decision here is which effects to hand over; the sequencing lives in
+ * run-setup.ts and the pieces it calls.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { planAgentConfigs } from './agent-configs.js';
+import { AppShape, readShape } from './desktop-shape.js';
+import { stopOnInterrupt } from './terminal/interrupt.js';
+import { stopOnCrash, crashSentence } from './terminal/crash.js';
+import { applyAgentPlan, applyAgentSkills } from './agent-writer.js';
+import { ApprovalOutcome, grantAutoApproval } from './auto-approve.js';
+import { agentIo } from './agent-io.js';
+import { EnsureDaemon, ensureDaemon, nodeEnsureDaemonDeps } from './bringup/ensure-daemon.js';
+import { openInBrowser } from '../cli/launch/cli-launch.js';
+import { readProjectId } from '../cli/ports/resolve/cli-port.js';
+import { reticleStateHome } from '../daemon/daemon.js';
+import { readDevServers } from '../daemon/dev-servers.js';
+import { urlOfExistingApp } from './probe/existing-app.js';
+import { listSessions, OwnedDevServer, probePage } from './node-effects.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { summarizeStatus } from '../cli/launch/cli-launch.js';
+import { runSetupPhases, } from './run-setup.js';
+import { noticeKey, readSaid, rememberSaid, unsaidNotices } from './agent-notice-memory.js';
+/**
+ * The dev server a crash should take with it, if one is running right now.
+ *
+ * A `let` rather than a parameter because the crash handler is installed at the CLI entry point —
+ * a bug of ours can fire in any phase, and the first attempt at this installed the handler inside
+ * the runtime phase, where it caught nothing in either environment I tried: init had already
+ * returned. Only this phase ever owns a detached server, so only this phase fills it in.
+ */
+let activeDevServerStop = null;
+/** Stop the dev server setup started, if it is still running. Safe to call when there is none. */
+export function stopRunningDevServer() {
+    activeDevServerStop?.();
+}
+/** Where a crash of our own leaves its trace. Never a stream — see terminal/crash.ts. */
+const CRASH_LOG_NAME = '.reticle-setup-crash.log';
+/**
+ * Catch our own faults for the whole process, and take the dev server with them.
+ *
+ * Here rather than in `cli/`, where it started: the handler it installs lives in `terminal/`, and
+ * `cli` is not allowed to reach that directory. `directory-reach` was right to refuse it — the
+ * installer stops the dev server THIS file owns, so this is where it belonged all along.
+ *
+ * Installed at the CLI entry rather than inside the phase below, because a fault can fire in any
+ * phase: the first attempt sat inside the runtime phase and caught nothing in two different
+ * environments, because init had already returned by the time the handler existed.
+ */
+export function installCrashGuard() {
+    return stopOnCrash(stopRunningDevServer, process, (message, stack) => {
+        const crashLog = join(process.cwd(), CRASH_LOG_NAME);
+        try {
+            writeFileSync(crashLog, stack);
+        }
+        catch {
+            /* an unwritable directory is not worth a second crash */
+        }
+        process.stderr.write(`${crashSentence(message, crashLog)}\n`);
+    });
+}
+/** `electron` in either dependency list, read the same way init's desktop doctor reads it. */
+function hasElectronDependency(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        if ('object' !== typeof pkg || null === pkg)
+            return false;
+        const p = pkg;
+        return undefined !== { ...p.dependencies, ...p.devDependencies }['electron'];
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Register with the agents `init` does not reach, and leave the skill where one loads skills from.
+ *
+ * init covers eight clients and only where it finds them installed, which leaves VS Code's USER
+ * scope unwritten — it exists on machines today, and init only ever writes the project-scope file,
+ * so a VS Code user has no tools outside the directory they ran init in.
+ */
+export function registerOtherAgents(print) {
+    const platform = process.platform;
+    const home = homedir();
+    const results = applyAgentPlan(planAgentConfigs({ home, platform, exists: agentIo.exists, readFile: agentIo.readFile }), agentIo);
+    const wrote = results.filter((r) => 'created' === r.action || 'merged' === r.action);
+    if (0 < wrote.length) {
+        print(`registered the MCP server with ${wrote.length} more agent(s): ${wrote.map((r) => r.name).join(', ')}`);
+    }
+    // A format we will not rewrite is somebody's to edit, so it has to be said rather than skipped --
+    // but said ONCE. Two commands call this function by design, so a `curl | sh` followed by
+    // `reticle init` printed the same two paragraphs twice in one sitting, and again on every re-run
+    // after that. See agent-notice-memory.ts: the stamp is keyed on the notice's own text, so a
+    // config that changes is reported again.
+    const stateHome = reticleStateHome();
+    const manual = results
+        .filter((r) => 'manual' === r.action)
+        .map((r) => ({ name: r.name, file: r.file, why: r.why }));
+    const fresh = unsaidNotices(readSaid(stateHome), manual);
+    for (const notice of fresh) {
+        print(`${notice.name}: ${notice.why} — add the reticle entry to ${notice.file} by hand.`);
+    }
+    rememberSaid(stateHome, fresh.map((n) => noticeKey(n)));
+    const skills = applyAgentSkills(agentIo, { home, platform });
+    if (0 < skills.length)
+        print(`wrote the /reticle skill for ${skills.length} agent(s)`);
+    // Registration alone still leaves an Accept dialog in front of every call, and a verification run
+    // makes dozens of them: the loop is only autonomous once the tools are pre-approved.
+    const approvals = grantAutoApproval(agentIo, { home, platform });
+    const granted = approvals.filter((a) => ApprovalOutcome.GRANTED === a.outcome);
+    if (0 < granted.length) {
+        print(`pre-approved the reticle tools in ${granted.map((a) => a.name).join(', ')} — no Accept prompt per call`);
+    }
+    for (const noted of approvals.filter((a) => undefined !== a.warn)) {
+        print(`${noted.name}: ${String(noted.warn)}`);
+    }
+}
+/**
+ * Run the phases against the real world.
+ *
+ * The dev server is stopped on every ending except success, where it is handed to the user: an
+ * instrumented app they can watch is the deliverable, and killing it would leave them with config
+ * files and a dead tab.
+ */
+export async function runSetupCommand(input, print) {
+    if (input.registerAgents)
+        registerOtherAgents(print);
+    // Before the app is booted, because the app's whole job from here is to dial this port. Without
+    // it the phases wait out their budget and then report the SDK as the thing that failed.
+    const daemon = await ensureDaemon(input.bridgePort, nodeEnsureDaemonDeps());
+    if (EnsureDaemon.UNAVAILABLE === daemon) {
+        print(`could not start the Reticle daemon on port ${String(input.bridgePort)}, so nothing is listening for the app to connect to. Run \`npx @reticlehq/server serve --port ${String(input.bridgePort)}\` and try again.`);
+    }
+    // Which shell this is decides three things the phases would otherwise get wrong: opening a
+    // browser (harmful for desktop, where the app's own window is the client), waiting for an HTTP
+    // port (a Tauri webview has none), and how long the app gets to appear (a cold `tauri dev` builds
+    // Rust first). The same evidence init's desktop doctor reads.
+    const shape = readShape({
+        hasTauriConf: existsSync(join(input.appDir, 'src-tauri', 'tauri.conf.json')),
+        hasElectronDep: hasElectronDependency(input.appDir),
+    });
+    if (AppShape.WEB !== shape)
+        print(`detected a ${shape} app`);
+    const server = new OwnedDevServer();
+    const effects = {
+        startDevServer: (command, cwd) => {
+            print(`starting: ${command}`);
+            server.start(command, cwd, input.env);
+            return Promise.resolve();
+        },
+        existingAppUrl: () => Promise.resolve(urlOfExistingApp(readDevServers(reticleStateHome()), {
+            projectId: readProjectId(input.appDir),
+            root: input.appDir,
+        })),
+        devServerOutput: () => server.output(),
+        devServerExited: () => server.exited(),
+        devServerQuietForMs: () => server.quietForMs(),
+        observedPorts: () => server.listeningPorts(),
+        probePage,
+        openBrowser: async (url) => {
+            const failure = await openInBrowser(url);
+            if (null !== failure) {
+                print(`could not open a browser (${failure}). Nothing was opened, and nothing else here will ` +
+                    // Three wordings have been wrong in a row, each naming a way out that does not exist on
+                    // the machine being spoken to. It said `reticle_run({ tool: "reticle_lease", ... })`:
+                    // the default surface advertises neither name and ships no hatch to reach the second.
+                    // It then said `reticle open <url>`, which asks the OS to launch the default browser --
+                    // the very thing that just failed -- so it returned the reader to the same wall.
+                    // This one names no command: the missing piece is a browser, and the honest sentence
+                    // says which url needs one rather than inventing a Reticle that can conjure it.
+                    `open one: this asks the OS for your default browser, and it is a machine with none — ` +
+                    `CI, a container, an SSH session, WSL with no host browser. Point any browser that can ` +
+                    `reach it at ${url}; the session appears within a second of the page loading.`);
+            }
+        },
+        listSessions: () => listSessions(input.bridgePort),
+        // `summarizeStatus` already narrows this payload for `reticle status`; reusing it here keeps one
+        // reader of the wire shape rather than two that can disagree about which key carries the reason.
+        // Both lengths, from the one read: the lead is printed to the person watching the install, the
+        // full differential is recorded for the agent reading `--json`. Returning only the lead here is
+        // what emptied the agent surface — see the note at the call site in `run-setup.ts`.
+        daemonWhy: async () => {
+            const status = summarizeStatus(await fetchStatus(input.bridgePort));
+            const full = status.why;
+            // A daemon too old to report the short one falls back to the long one, because saying the
+            // right thing at length beats saying nothing.
+            const lead = status.whyLead ?? full;
+            if (undefined === lead)
+                return undefined;
+            return undefined === full ? { lead } : { lead, full };
+        },
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        note: print,
+    };
+    // A `finally` does not run on SIGINT, and this phase owns a detached dev server — see interrupt.ts.
+    const releaseSignals = stopOnInterrupt(() => {
+        server.stop();
+    }, process);
+    // The crash handler lives at the CLI entry, because a bug of ours can fire in any phase — but
+    // only this one owns a detached dev server, so this is where it learns what to stop.
+    activeDevServerStop = () => {
+        server.stop();
+    };
+    try {
+        const outcome = await runSetupPhases({ ...input, shape }, effects);
+        // The app stays up only when there is something worth watching.
+        if (outcome.ok)
+            server.handOver();
+        return {
+            ...outcome,
+        };
+    }
+    finally {
+        releaseSignals();
+        activeDevServerStop = null;
+        server.stop();
+    }
+}

package/dist/command/setup/setup-install.d.ts

@@ -0,0 +1,18 @@
+import { type OnboardingStep } from '@reticlehq/core/telemetry';
+/**
+ * What the one-line installer did, reported by the half that can report.
+ *
+ * `install/install.sh` (and its PowerShell twin) measures three durations it alone can see — they span the time before this
+ * binary existed — and hands them over. Everything after that is decided here, because a `.sh` and
+ * a `.ps1` carrying the same logic drift the first time somebody fixes a bug in one of them. The
+ * shell's whole job is: is there a runtime, put the CLI on the machine, exec this.
+ *
+ * Pure over its inputs so the reporting is testable without installing anything.
+ */
+export interface InstallReport {
+    readonly runtimeSecs: number;
+    readonly installSecs: number;
+}
+export declare function reportInstallSteps(report: InstallReport, 
+/** Injected for the same reason as in setup-mcp: this directory does not own a telemetry client. */
+reportStep: (step: OnboardingStep) => void): void;

package/dist/command/setup/setup-install.js

@@ -0,0 +1,40 @@
+import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
+export function reportInstallSteps(report, 
+/** Injected for the same reason as in setup-mcp: this directory does not own a telemetry client. */
+reportStep) {
+    /*
+     * `script_started` carries no duration, and that is not an oversight.
+     *
+     * The script's own start has nothing to measure against — it IS the origin. An `elapsedMs: 0`
+     * would enter every average as a real zero and drag it toward a number nobody experienced;
+     * absent means NOT MEASURED, which is what this is.
+     */
+    reportStep({
+        phase: OnboardingPhase.INSTALL,
+        step: 'script_started',
+        status: OnboardingStepStatus.COMPLETED,
+    });
+    reportStep({
+        phase: OnboardingPhase.INSTALL,
+        step: 'runtime_ready',
+        status: OnboardingStepStatus.COMPLETED,
+        ...secs(report.runtimeSecs),
+    });
+    // Reaching here AT ALL means the CLI is installed and on PATH: the shell execs this binary by
+    // name, so anything that would have made `cli_installed` false already exited before we ran.
+    reportStep({
+        phase: OnboardingPhase.INSTALL,
+        step: 'cli_installed',
+        status: OnboardingStepStatus.COMPLETED,
+        ...secs(report.installSecs),
+    });
+}
+/**
+ * Seconds to milliseconds, or nothing.
+ *
+ * Zero is dropped rather than sent: the shell passes 0 when a step was too fast to measure at
+ * whole-second resolution, and a real 0ms install did not happen. Same rule as `script_started`.
+ */
+function secs(value) {
+    return value > 0 ? { elapsedMs: value * 1000 } : {};
+}

package/dist/command/setup/setup-mcp.d.ts

@@ -0,0 +1,57 @@
+import { McpClient } from '@reticlehq/init';
+import { type OnboardingStep } from '@reticlehq/core/telemetry';
+/**
+ * `reticle setup mcp` — register the MCP server with every coding agent on this machine.
+ *
+ * `init` wires one PROJECT. This registers the server for the USER, which is a different job and
+ * the one the installer needs: at install time there is no project yet, and telling somebody to go
+ * and find one before their agent has any tools is how a two-minute setup becomes an afternoon.
+ *
+ * It writes only into configs an agent ALREADY keeps — see `detectMcpClients` for why. Creating
+ * `~/.gemini` for somebody who does not use Gemini is not helpfulness, it is litter in a home
+ * directory, and it makes the next tool's detection wrong too.
+ */
+export interface SetupMcpIo {
+    exists(path: string): boolean;
+    readFile(path: string): string | null;
+    writeFile(path: string, contents: string): void;
+    homeDir(): string;
+    print(line: string): void;
+    /** Register with a client that owns its own registration (Claude Code). Returns whether it took. */
+    runCli(command: string, args: readonly string[]): boolean;
+    /**
+     * Report one funnel step. INJECTED, not imported.
+     *
+     * This directory decides what to register and where; it does not own a telemetry client. The
+     * reach guard refused the import and its advice was right — the same inversion teardown already
+     * uses, and it keeps this function testable without a wire.
+     */
+    reportStep(step: OnboardingStep): void;
+}
+export interface SetupMcpResult {
+    readonly detected: readonly string[];
+    readonly registered: readonly string[];
+    readonly alreadyThere: readonly string[];
+    /**
+     * Clients whose config this will NOT rewrite, and which therefore still need a human.
+     *
+     * Separate from `registered` because it used to be inside it. `mergeClientConfig` answers MANUAL
+     * for a format we decline to rewrite, and documents its `content` as byte-identical to the
+     * existing file in that case, so writing it is a no-op when the file exists and creates an EMPTY
+     * one when it does not. The loop below handled ALREADY and treated everything else as applied, so
+     * Codex CLI was reported `registered` while its `config.toml` gained nothing: a false success in
+     * the install path, and the user got no tools and no snippet either. Reproduced with an empty HOME
+     * and a pre-seeded `~/.codex/config.toml`; the file came back byte-identical both times.
+     */
+    readonly manual: readonly ManualClient[];
+}
+/** A client the caller has to tell somebody about, with the two facts they need to act. */
+export interface ManualClient {
+    readonly id: string;
+    readonly configPath: string;
+    readonly docs: string | undefined;
+}
+export declare function setupMcp(io: SetupMcpIo): SetupMcpResult;
+/** Everything this machine could be asked about, for the report when nothing was found. */
+export declare function knownClientLabels(): string[];
+export { McpClient };

package/dist/command/setup/setup-mcp.js

@@ -0,0 +1,92 @@
+import { McpClient, MCP_CLIENTS, claudeAddCommand, claudeAvailableProbe, claudeExistsProbe, detectMcpClients, mergeClientConfig, clientSpec, ClientMergeStatus, } from '@reticlehq/init';
+import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
+export function setupMcp(io) {
+    const detected = [];
+    const registered = [];
+    const alreadyThere = [];
+    const manual = [];
+    /*
+     * Claude Code first, because nothing else can find it.
+     *
+     * `detectMcpClients` reads config files and Claude Code keeps none — it owns its registration
+     * behind `claude mcp add`, which is why its spec is `ConfigScope.CLI`. `fileBackedClients()`
+     * filters CLI scope out by construction, so this used to be a `ConfigScope.CLI` branch INSIDE
+     * the loop below, over a list that can never contain a CLI client. It was unreachable, and the
+     * effect was that the one-line installer told anybody running Reticle's most common client
+     * "No coding agent config found" and left their agent with no tools.
+     *
+     * Its own CLI is the probe, and it is the honest one: a config file only says the client was
+     * installed once, while `claude --version` says it is here now. Absent, this registers nothing
+     * and claims nothing — the negative control in the test file.
+     */
+    const available = claudeAvailableProbe();
+    if (io.runCli(available.command, available.args)) {
+        detected.push(McpClient.CLAUDE_CODE);
+        const already = claudeExistsProbe();
+        if (io.runCli(already.command, already.args)) {
+            alreadyThere.push(McpClient.CLAUDE_CODE);
+        }
+        else {
+            const cmd = claudeAddCommand();
+            if (io.runCli(cmd.command, cmd.args))
+                registered.push(McpClient.CLAUDE_CODE);
+        }
+    }
+    for (const client of detectMcpClients(io)) {
+        detected.push(client.id);
+        const spec = clientSpec(client.id);
+        const merged = mergeClientConfig(spec, client.existing);
+        if (ClientMergeStatus.ALREADY === merged.status) {
+            alreadyThere.push(client.id);
+            continue;
+        }
+        // A format we decline to rewrite is not a registration. Writing `content` here would be a no-op
+        // on an existing file and would CREATE an empty one otherwise, and either way claiming success
+        // sends somebody to an agent that has no Reticle tools in it.
+        if (ClientMergeStatus.MANUAL === merged.status) {
+            manual.push({ id: client.id, configPath: client.configPath, docs: spec.docs });
+            continue;
+        }
+        io.writeFile(client.configPath, merged.content);
+        registered.push(client.id);
+    }
+    /*
+     * Both INSTALL steps, reported from the one place that knows the answer.
+     *
+     * `agents_detected` is COMPLETED even when the count is zero, and that is the point: "this
+     * machine has no coding agent we recognise" is a real and important answer, not a failure. A
+     * funnel that only records successful detections cannot show the agents Reticle does not serve.
+     */
+    io.reportStep({
+        phase: OnboardingPhase.INSTALL,
+        step: 'agents_detected',
+        status: OnboardingStepStatus.COMPLETED,
+    });
+    io.reportStep({
+        phase: OnboardingPhase.INSTALL,
+        step: 'mcp_registered',
+        /*
+         * SKIPPED when there was nothing to register with — not failed. Nothing went wrong; there was
+         * simply no agent here, and counting that as our failure would hide the ones that are.
+         *
+         * FAILED when every client we found needs a hand. That case used to fall through to COMPLETED,
+         * so the cohort with the tools registered NOWHERE was counted among the successful installs, and
+         * the one number that says "did this machine get Reticle" read yes for the people it read no
+         * for. Registering some and not others is still COMPLETED: the agent they are using may well be
+         * one that worked, and a partial win is not a failed step.
+         */
+        status: 0 === detected.length
+            ? OnboardingStepStatus.SKIPPED
+            : 0 === registered.length && alreadyThere.length > 0
+                ? OnboardingStepStatus.SKIPPED
+                : 0 === registered.length && 0 === alreadyThere.length && manual.length > 0
+                    ? OnboardingStepStatus.FAILED
+                    : OnboardingStepStatus.COMPLETED,
+    });
+    return { detected, registered, alreadyThere, manual };
+}
+/** Everything this machine could be asked about, for the report when nothing was found. */
+export function knownClientLabels() {
+    return MCP_CLIENTS.map((c) => c.label);
+}
+export { McpClient };

package/dist/command/setup/setup-options.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The contract between the agent and the script.
+ *
+ * Everything setup does is deterministic except for the handful of things that require reading a
+ * repository and a human's request and understanding both. Those are exactly what an agent is good
+ * at and code is not, so they arrive here as ARGUMENTS rather than as steps somebody walks through:
+ * the agent decides, the script executes, and neither does the other's job.
+ *
+ * What only an agent can know, and therefore what belongs in this type:
+ *
+ *   --app       which app in a monorepo the user meant. init can find the ones that are servable;
+ *               only the request says which of them is being worked on.
+ *   --env       what the app needs to get past its own front door. A key in .env.example, a mock
+ *               backend named in the README, the variable that skips an auth wall: all readable by
+ *               an agent, none inferable by a script. Without this a real app sits on a login
+ *               screen and there is no flow to drive at all.
+ *   --url       the app is already running here, so do not start anything. This is also the answer
+ *               when the project's own scripts do not name a dev command: start it yourself and say
+ *               where. There is no flag that overrides the dev command; --url replaces the need.
+ *
+ * Everything else on this type is an operator's dial, not an agent's judgement.
+ *
+ * `--flow` used to head that list -- which journey to prove. Onboarding stopped driving in 7e698fea
+ * and the flag was retired with it, so naming the journey belongs to the FIRST RUN now
+ * (`reticle_verify { action: "explore", persona: ... }`), not to this type.
+ */
+/** The bridge port. NOT the dev server's, and conflating them is a documented setup failure. */
+export declare const DEFAULT_BRIDGE_PORT = 4400;
+/** Per-phase budget. */
+export declare const DEFAULT_PHASE_TIMEOUT_MS = 120000;
+interface SetupOptions {
+    /** Which app in a monorepo. */
+    readonly app?: string | undefined;
+    /** Environment the app needs in order to reach a usable state. */
+    readonly env?: Readonly<Record<string, string>> | undefined;
+    /** The dev command, when the project's scripts do not say it plainly. */
+    readonly devCommand?: string | undefined;
+    /** The app is already served here. */
+    readonly url?: string | undefined;
+    readonly bridgePort: number;
+    readonly phaseTimeoutMs: number;
+    /** Register the MCP with the other coding agents on this machine. */
+    readonly registerAgents: boolean;
+    /** Open a browser. False for CI, a headless box, or a tab the user already has. */
+    readonly openBrowser: boolean;
+    /** Restart a dev server whose bundle predates the build-config edit. */
+    readonly restartStaleDevServer: boolean;
+    /** Write files and stop, which is what `init` did before it grew the runtime phases. */
+    readonly filesOnly: boolean;
+    /** A license key, written to .env and never echoed. */
+    readonly licenseKey?: string | undefined;
+}
+export declare const DEFAULT_SETUP_OPTIONS: SetupOptions;
+/** One `KEY=VALUE`, as an agent would pass it. Everything after the first `=` is the value. */
+export declare function parseEnvAssignment(pair: string): {
+    key: string;
+    value: string;
+} | null;
+/**
+ * Fold repeated `--env KEY=VALUE` into one map, ignoring what cannot be a variable.
+ *
+ * A malformed pair is dropped rather than guessed at: an agent that meant `--env` and typed
+ * something else should see its variable missing, not see setup invent one.
+ */
+export declare function collectEnv(pairs: readonly string[]): Record<string, string>;
+export {};

package/dist/command/setup/setup-options.js

@@ -0,0 +1,63 @@
+/**
+ * The contract between the agent and the script.
+ *
+ * Everything setup does is deterministic except for the handful of things that require reading a
+ * repository and a human's request and understanding both. Those are exactly what an agent is good
+ * at and code is not, so they arrive here as ARGUMENTS rather than as steps somebody walks through:
+ * the agent decides, the script executes, and neither does the other's job.
+ *
+ * What only an agent can know, and therefore what belongs in this type:
+ *
+ *   --app       which app in a monorepo the user meant. init can find the ones that are servable;
+ *               only the request says which of them is being worked on.
+ *   --env       what the app needs to get past its own front door. A key in .env.example, a mock
+ *               backend named in the README, the variable that skips an auth wall: all readable by
+ *               an agent, none inferable by a script. Without this a real app sits on a login
+ *               screen and there is no flow to drive at all.
+ *   --url       the app is already running here, so do not start anything. This is also the answer
+ *               when the project's own scripts do not name a dev command: start it yourself and say
+ *               where. There is no flag that overrides the dev command; --url replaces the need.
+ *
+ * Everything else on this type is an operator's dial, not an agent's judgement.
+ *
+ * `--flow` used to head that list -- which journey to prove. Onboarding stopped driving in 7e698fea
+ * and the flag was retired with it, so naming the journey belongs to the FIRST RUN now
+ * (`reticle_verify { action: "explore", persona: ... }`), not to this type.
+ */
+/** The bridge port. NOT the dev server's, and conflating them is a documented setup failure. */
+export const DEFAULT_BRIDGE_PORT = 4400;
+/** Per-phase budget. */
+export const DEFAULT_PHASE_TIMEOUT_MS = 120_000;
+export const DEFAULT_SETUP_OPTIONS = {
+    bridgePort: DEFAULT_BRIDGE_PORT,
+    phaseTimeoutMs: DEFAULT_PHASE_TIMEOUT_MS,
+    registerAgents: true,
+    openBrowser: true,
+    restartStaleDevServer: true,
+    filesOnly: false,
+};
+/** One `KEY=VALUE`, as an agent would pass it. Everything after the first `=` is the value. */
+export function parseEnvAssignment(pair) {
+    const at = pair.indexOf('=');
+    if (0 >= at)
+        return null;
+    const key = pair.slice(0, at).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+        return null;
+    return { key, value: pair.slice(at + 1) };
+}
+/**
+ * Fold repeated `--env KEY=VALUE` into one map, ignoring what cannot be a variable.
+ *
+ * A malformed pair is dropped rather than guessed at: an agent that meant `--env` and typed
+ * something else should see its variable missing, not see setup invent one.
+ */
+export function collectEnv(pairs) {
+    const env = {};
+    for (const pair of pairs) {
+        const parsed = parseEnvAssignment(pair);
+        if (null !== parsed)
+            env[parsed.key] = parsed.value;
+    }
+    return env;
+}