@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/setup/agent-writer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Carrying out an agent-config plan.
+ *
+ * The plan decides; this writes. Kept apart because the deciding is where the judgement is — which
+ * paths are evidenced, which formats are safe to touch — and it is worth testing against a pretend
+ * filesystem rather than a real one.
+ *
+ * One rule governs everything here: only our key is ever written. The rest of somebody's config is
+ * copied through untouched, and a file we cannot parse is left exactly as it is. A config file is
+ * not ours, and the cost of being wrong about that is not a failed install but a broken editor.
+ */
+import { AgentAction, type AgentPlanStep, type PlatformPaths } from './agent-configs.js';
+/** The filesystem, injected so the writer is testable without one. */
+export interface AgentWriterIo {
+    readonly exists: (path: string) => boolean;
+    readonly readFile: (path: string) => string;
+    readonly writeFile: (path: string, contents: string) => void;
+    readonly mkdirp: (dir: string) => void;
+}
+interface AgentWriteResult {
+    readonly id: string;
+    readonly name: string;
+    readonly file: string;
+    /** What actually happened, which is not always what was planned. */
+    readonly action: AgentAction | 'created' | 'merged';
+    readonly why: string;
+}
+/**
+ * Write what the plan says to write, and nothing else.
+ *
+ * A step that fails becomes a `manual` result rather than an exception: one unwritable config on a
+ * machine with a dozen agents is not a reason to abandon the other eleven, and the user needs to be
+ * told which one to do by hand.
+ */
+export declare function applyAgentPlan(plan: readonly AgentPlanStep[], io: AgentWriterIo): AgentWriteResult[];
+/** The `/reticle` instruction, for agents that load skills from a directory. */
+export declare const RETICLE_SKILL = "---\nname: reticle\ndescription: Verify a change against the running app, from inside it, before calling it done.\n---\n\nReticle exposes the running app to you as `reticle_*` MCP tools. Look, act, observe, assert.\n\nOnly `reticle_act_and_wait` and `reticle_assert` produce a verdict. Everything else moves or\nreads the app and proves nothing, so a drive that ends without one of those has no result however\nmany tools it used.\n\n`verified: \"unknown\"` is not a pass: it means Reticle could not tell what happened.\n`verified: \"no-fault\"` is not a pass either, because nothing was declared to prove. Never weaken a\ncheck to make it pass.\n\nThe cheapest path that answers the question:\n\n- \"did my edit break anything?\" -> `reticle_verify { action: \"change\", files: [...] }`\n- \"does this known journey still work?\" -> `reticle_verify { action: \"flows\", names: [\"...\"] }`\n- \"does this new behaviour work?\" -> `reticle_act { steps: [...] }` for the setup, then ONE `reticle_act_and_wait`\n- \"nothing is recorded yet\" -> `reticle_verify { action: \"explore\", persona: \"<who does what>\" }`, which\n  drives the app and SAVES what it drove, so the next run replays with no model in the loop\n";
+interface SkillWriteResult {
+    readonly id: string;
+    readonly file: string;
+}
+/**
+ * Write the skill for agents that have somewhere to put it, and only where they are installed.
+ *
+ * Scaffolding a skills tree for software somebody does not have is litter, and unlike a config file
+ * it is not even inert: it is a directory that appears in their home for no reason they can trace.
+ */
+export declare function applyAgentSkills(io: AgentWriterIo, where: {
+    readonly home: string;
+    readonly platform: keyof PlatformPaths;
+}): SkillWriteResult[];
+export {};

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

@@ -0,0 +1,116 @@
+/**
+ * Carrying out an agent-config plan.
+ *
+ * The plan decides; this writes. Kept apart because the deciding is where the judgement is — which
+ * paths are evidenced, which formats are safe to touch — and it is worth testing against a pretend
+ * filesystem rather than a real one.
+ *
+ * One rule governs everything here: only our key is ever written. The rest of somebody's config is
+ * copied through untouched, and a file we cannot parse is left exactly as it is. A config file is
+ * not ours, and the cost of being wrong about that is not a failed install but a broken editor.
+ */
+import { AgentAction, AGENT_CLIENTS, joinFor, parentOf, } from './agent-configs.js';
+/** Two spaces, because that is what every one of these files already uses. */
+const INDENT = 2;
+const RETICLE_KEY = 'reticle';
+/** A fresh Continue config. YAML is only ever created, never edited. */
+const CONTINUE_YAML = 'mcpServers:\n  - name: reticle\n    type: stdio\n    command: npx\n    args: ["@reticlehq/server", "mcp"]\n';
+/**
+ * Write what the plan says to write, and nothing else.
+ *
+ * A step that fails becomes a `manual` result rather than an exception: one unwritable config on a
+ * machine with a dozen agents is not a reason to abandon the other eleven, and the user needs to be
+ * told which one to do by hand.
+ */
+export function applyAgentPlan(plan, io) {
+    return plan.map((step) => {
+        const base = { id: step.id, name: step.name, file: step.file, why: step.why };
+        if (AgentAction.SKIP === step.action ||
+            AgentAction.ALREADY === step.action ||
+            AgentAction.MANUAL === step.action) {
+            return { ...base, action: step.action };
+        }
+        try {
+            io.mkdirp(parentOf(step.file));
+            if (AgentAction.CREATE_YAML === step.action) {
+                io.writeFile(step.file, CONTINUE_YAML);
+                return { ...base, action: 'created' };
+            }
+            const key = step.key;
+            if (undefined === key || undefined === step.entry) {
+                return {
+                    ...base,
+                    action: AgentAction.MANUAL,
+                    why: 'the plan named no key or entry to write',
+                };
+            }
+            // Only our key. Everything else in the file is read and written back untouched.
+            const current = AgentAction.MERGE === step.action
+                ? JSON.parse(io.readFile(step.file))
+                : {};
+            const bucket = current[key];
+            const servers = 'object' === typeof bucket && null !== bucket ? bucket : {};
+            const next = { ...current, [key]: { ...servers, [RETICLE_KEY]: step.entry } };
+            io.writeFile(step.file, `${JSON.stringify(next, null, INDENT)}\n`);
+            return { ...base, action: AgentAction.MERGE === step.action ? 'merged' : 'created' };
+        }
+        catch (err) {
+            return {
+                ...base,
+                action: AgentAction.MANUAL,
+                why: `could not write it (${String(err?.message ?? err).slice(0, 120)})`,
+            };
+        }
+    });
+}
+/** The `/reticle` instruction, for agents that load skills from a directory. */
+export const RETICLE_SKILL = `---
+name: reticle
+description: Verify a change against the running app, from inside it, before calling it done.
+---
+
+Reticle exposes the running app to you as \`reticle_*\` MCP tools. Look, act, observe, assert.
+
+Only \`reticle_act_and_wait\` and \`reticle_assert\` produce a verdict. Everything else moves or
+reads the app and proves nothing, so a drive that ends without one of those has no result however
+many tools it used.
+
+\`verified: "unknown"\` is not a pass: it means Reticle could not tell what happened.
+\`verified: "no-fault"\` is not a pass either, because nothing was declared to prove. Never weaken a
+check to make it pass.
+
+The cheapest path that answers the question:
+
+- "did my edit break anything?" -> \`reticle_verify { action: "change", files: [...] }\`
+- "does this known journey still work?" -> \`reticle_verify { action: "flows", names: ["..."] }\`
+- "does this new behaviour work?" -> \`reticle_act { steps: [...] }\` for the setup, then ONE \`reticle_act_and_wait\`
+- "nothing is recorded yet" -> \`reticle_verify { action: "explore", persona: "<who does what>" }\`, which
+  drives the app and SAVES what it drove, so the next run replays with no model in the loop
+`;
+/**
+ * Write the skill for agents that have somewhere to put it, and only where they are installed.
+ *
+ * Scaffolding a skills tree for software somebody does not have is litter, and unlike a config file
+ * it is not even inert: it is a directory that appears in their home for no reason they can trace.
+ */
+export function applyAgentSkills(io, where) {
+    const written = [];
+    const join = joinFor(where.platform);
+    for (const client of AGENT_CLIENTS) {
+        const dir = client.skillDir;
+        if (undefined === dir)
+            continue;
+        if (!io.exists(join(where.home, client.marker[where.platform])))
+            continue;
+        try {
+            const target = join(where.home, dir);
+            io.mkdirp(target);
+            io.writeFile(join(target, 'SKILL.md'), RETICLE_SKILL);
+            written.push({ id: client.id, file: join(target, 'SKILL.md') });
+        }
+        catch {
+            /* an unwritable home directory is not a reason to fail an install */
+        }
+    }
+    return written;
+}

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

@@ -0,0 +1,153 @@
+/**
+ * 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 CREATED where the file itself takes over settings we cannot read — Cursor's
+ *    permissions.json supersedes its in-app allowlist and pins the run mode to Allowlist, so a user
+ *    who ran everything without asking loses that and cannot switch back while the file exists.
+ *    Merging into one they already have is fine; making one is not, so that case is DEFERRED with
+ *    the in-app step to take instead. Nothing is written at all for an agent that is not installed:
+ *    an absent agent has no Accept button to remove.
+ *
+ * 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, parentOf } 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" — and in practice it costs more than that. A non-empty mcpAllowlist also locks
+        // the run mode to Allowlist, so a user who had Run Everything ("YOLO") on loses it and cannot
+        // turn it back on while the file exists; Cursor has acknowledged that as their bug. Merging into
+        // a file the user already made is safe — they are already in Allowlist mode. Creating one is
+        // not, so we never do: see the DEFERRED branch below.
+        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) {
+    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 === grant.supersedesInApp && !existed) {
+                return {
+                    ...base,
+                    outcome: ApprovalOutcome.DEFERRED,
+                    warn: `left ${grant.name}'s approvals alone — creating ${file} would take over its in-app settings and pin the run mode to Allowlist. If ${grant.name} asks before every reticle tool call, add \`${RETICLE_KEY}:*\` under Settings → Agents → Approvals & Execution (nothing to do if you run everything already).`,
+                };
+            }
+            // 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(parentOf(file));
+            io.writeFile(file, `${JSON.stringify(next, null, INDENT)}\n`);
+            return { ...base, outcome: ApprovalOutcome.GRANTED };
+        }
+        catch (err) {
+            return {
+                ...base,
+                outcome: ApprovalOutcome.FAILED,
+                warn: String(err?.message ?? err).slice(0, 120),
+            };
+        }
+    });
+}

package/dist/command/setup/bringup/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/binding/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/command/setup/bringup/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/binding/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/command/setup/bringup/dev-server-wait.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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;
+    /**
+     * How long silence may mean "still starting" on THIS machine. Defaults to QUIET_MEANS_HUNG_MS.
+     *
+     * Passed in rather than read from the platform here, so this stays a pure decision and exactly one
+     * caller owns the platform check. 45s is generous on a laptop and tight on a cold Windows runner,
+     * where a first `npm run dev` optimises dependencies before Vite prints a line.
+     */
+    readonly quietMeansHungMs?: 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 portBusyMessage(output: string): string | undefined;
+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/command/setup/bringup/dev-server-wait.js

@@ -0,0 +1,83 @@
+/**
+ * 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 >= (facts.quietMeansHungMs ?? QUIET_MEANS_HUNG_MS)
+        ? WaitVerdict.HUNG
+        : WaitVerdict.WAITING;
+}
+/**
+ * CRA (and webpack) print a prompt rather than a URL when their default port is taken, then exit
+ * or hang waiting for a tty. Setup used to report only "exited without serving anything", which
+ * hid the port that was actually busy (#802).
+ */
+const CRA_PORT_BUSY = /Something is already running on port (\d+)/i;
+const NAMED_PORT_BUSY = /Port (\d+) is (?:already )?in use/i;
+const EADDRINUSE_PORT = /(?:EADDRINUSE|address already in use)[^\d]*(\d+)/i;
+export function portBusyMessage(output) {
+    const match = CRA_PORT_BUSY.exec(output) ?? NAMED_PORT_BUSY.exec(output) ?? EADDRINUSE_PORT.exec(output);
+    const port = match?.[1];
+    if (undefined === port)
+        return undefined;
+    return (`port ${port} is already in use — something else is serving there, so this launcher did not ` +
+        `bind. Pass --url http://localhost:${port} if that process is this app, or free the port and re-run.`);
+}
+/** 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/command/setup/bringup/ensure-daemon.js

@@ -0,0 +1,58 @@
+/**
+ * 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/binding/port-presence.js';
+import { waitForDaemon, probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
+import { daemonSpawnArgs } from '../../cli/daemon-start-options.js';
+import { fetchStatus } from '../../daemon/binding/daemon-status-probe.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/command/setup/init/init-host.js

@@ -0,0 +1,37 @@
+import { spanSync } from '../../../trace.js';
+import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
+import { reportOnboardingStep } from '../../../telemetry/onboarding-funnel.js';
+import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../../portal/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);
+        },
+        /**
+         * One funnel step, fire-and-forget.
+         *
+         * `void` rather than awaited on purpose: `init` is writing files, and a step report that can
+         * slow a write down — or fail one — is a metric changing what the product does, which the
+         * telemetry contract forbids outright.
+         */
+        reportStep(step) {
+            void reportOnboardingStep(step);
+        },
+        /**
+         * 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/command/setup/init/init-runtime.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 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 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 {};