@reticlehq/server 2.12.0 → 2.13.1

package/dist/setup/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/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-runtime.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 '../init/run.js';
+/** Just enough of the parsed command to decide and run. */
+export 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;
+}
+export interface RuntimePrintIo {
+    readonly print: (line: string) => void;
+}
+/**
+ * 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.
+ */
+export declare function continueAfterInit(parsed: InitRuntimeArgs, result: InitResult, io: RuntimePrintIo, cwd: string): Promise<void>;

package/dist/setup/init-runtime.js

@@ -0,0 +1,160 @@
+/**
+ * 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 '../init/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.
+ */
+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);
+    }
+    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.
+    // What a restart should do, decided and printed. 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.
+    if (true === parsed.relaunch) {
+        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('');
+    }
+    // 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);
+    });
+}

package/dist/setup/interrupt.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Take the dev server with us when setup is interrupted.
+ *
+ * `setup` starts a dev server the user did not start — detached, in its own process group — and
+ * stops it in a `finally`. A `finally` does not run on SIGINT: the process is terminated. So Ctrl-C
+ * during setup left that server running forever, holding a port nobody could account for, and the
+ * next run's port probe then found a stranger on it.
+ *
+ * It hid behind an earlier bug. `init` used to exit before the dev server was ever started whenever
+ * instrumentation needed a manual step, so the orphan check found nothing and passed for the wrong
+ * reason. Letting the runtime phase run is what exposed this.
+ */
+/** The parts of `process` this needs, so the behaviour is testable without signalling anything. */
+export interface SignalTarget {
+    on(signal: 'SIGINT' | 'SIGTERM', handler: () => void): void;
+    off(signal: 'SIGINT' | 'SIGTERM', handler: () => void): void;
+    exit(code: number): void;
+}
+/**
+ * Run `stop` if this process is interrupted, then leave with the signal's own code.
+ *
+ * Returns a disposer, and callers must use it: `init` keeps running after setup, and a handler left
+ * behind would tear down a server it no longer owns.
+ */
+export declare function stopOnInterrupt(stop: () => void, target: SignalTarget): () => void;

package/dist/setup/interrupt.js

@@ -0,0 +1,40 @@
+/**
+ * Take the dev server with us when setup is interrupted.
+ *
+ * `setup` starts a dev server the user did not start — detached, in its own process group — and
+ * stops it in a `finally`. A `finally` does not run on SIGINT: the process is terminated. So Ctrl-C
+ * during setup left that server running forever, holding a port nobody could account for, and the
+ * next run's port probe then found a stranger on it.
+ *
+ * It hid behind an earlier bug. `init` used to exit before the dev server was ever started whenever
+ * instrumentation needed a manual step, so the orphan check found nothing and passed for the wrong
+ * reason. Letting the runtime phase run is what exposed this.
+ */
+/** 128 + the signal number, which is what a shell reports — so a caller can tell Ctrl-C from a failure. */
+const EXIT_CODE = { SIGINT: 130, SIGTERM: 143 };
+/**
+ * Run `stop` if this process is interrupted, then leave with the signal's own code.
+ *
+ * Returns a disposer, and callers must use it: `init` keeps running after setup, and a handler left
+ * behind would tear down a server it no longer owns.
+ */
+export function stopOnInterrupt(stop, target) {
+    // Once only. `stop` is not idempotent — it kills a process GROUP — and on a recycled pid a second
+    // kill is somebody else's process.
+    let done = false;
+    const handlers = ['SIGINT', 'SIGTERM'].map((signal) => {
+        const handler = () => {
+            if (!done) {
+                done = true;
+                stop();
+            }
+            target.exit(EXIT_CODE[signal]);
+        };
+        target.on(signal, handler);
+        return { signal, handler };
+    });
+    return () => {
+        for (const { signal, handler } of handlers)
+            target.off(signal, handler);
+    };
+}

package/dist/setup/license-key.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Writing a license key where the CLI will find it, without leaking it.
+ *
+ * The instructions used to ask an agent to do this by hand in three steps: append to `.env`, check
+ * `.gitignore`, confirm. Every one of those is deterministic, and the second is the one that costs
+ * something when skipped — a license key committed to git is a leaked credential, and it stays
+ * leaked after it is deleted.
+ *
+ * The key is never printed, never returned, and never put in a result object. The only thing said
+ * out loud is that a key was written.
+ */
+export interface LicenseIo {
+    readonly exists: (path: string) => boolean;
+    readonly readFile: (path: string) => string;
+    readonly writeFile: (path: string, contents: string) => void;
+}
+export declare const LicenseWrite: {
+    readonly WRITTEN: "written";
+    readonly ALREADY: "already";
+    readonly REPLACED: "replaced";
+};
+export type LicenseWrite = (typeof LicenseWrite)[keyof typeof LicenseWrite];
+export interface LicenseResult {
+    readonly action: LicenseWrite;
+    /** True when `.gitignore` had to be changed so the key cannot be committed. */
+    readonly gitignoreUpdated: boolean;
+    /** Safe to print. Never contains the key. */
+    readonly message: string;
+}
+/** Whether `.gitignore` already covers `.env`, allowing for the forms people actually write. */
+export declare function gitignoreCoversEnv(contents: string): boolean;
+/**
+ * Put the key in `.env`, and make sure `.env` cannot be committed.
+ *
+ * An existing assignment is REPLACED rather than appended to: two `RETICLE_LICENSE_KEY` lines is a
+ * file where the answer depends on which one the parser reads last, and nobody should have to know
+ * which that is.
+ */
+export declare function writeLicenseKey(dir: string, key: string, io: LicenseIo): LicenseResult;

package/dist/setup/license-key.js

@@ -0,0 +1,72 @@
+/**
+ * Writing a license key where the CLI will find it, without leaking it.
+ *
+ * The instructions used to ask an agent to do this by hand in three steps: append to `.env`, check
+ * `.gitignore`, confirm. Every one of those is deterministic, and the second is the one that costs
+ * something when skipped — a license key committed to git is a leaked credential, and it stays
+ * leaked after it is deleted.
+ *
+ * The key is never printed, never returned, and never put in a result object. The only thing said
+ * out loud is that a key was written.
+ */
+const ENV_FILE = '.env';
+const GITIGNORE = '.gitignore';
+const ENV_VAR = 'RETICLE_LICENSE_KEY';
+export const LicenseWrite = {
+    WRITTEN: 'written',
+    ALREADY: 'already',
+    REPLACED: 'replaced',
+};
+const joinPath = (dir, file) => `${dir.replace(/\/$/, '')}/${file}`;
+/** Whether `.gitignore` already covers `.env`, allowing for the forms people actually write. */
+export function gitignoreCoversEnv(contents) {
+    return contents
+        .split('\n')
+        .map((l) => l.trim())
+        .some((l) => ENV_FILE === l || '.env*' === l || '*.env' === l || '/.env' === l);
+}
+/**
+ * Put the key in `.env`, and make sure `.env` cannot be committed.
+ *
+ * An existing assignment is REPLACED rather than appended to: two `RETICLE_LICENSE_KEY` lines is a
+ * file where the answer depends on which one the parser reads last, and nobody should have to know
+ * which that is.
+ */
+export function writeLicenseKey(dir, key, io) {
+    const envPath = joinPath(dir, ENV_FILE);
+    const existing = io.exists(envPath) ? io.readFile(envPath) : '';
+    const lines = '' === existing ? [] : existing.split('\n');
+    const at = lines.findIndex((l) => l.trimStart().startsWith(`${ENV_VAR}=`));
+    const already = -1 !== at && lines[at]?.trim() === `${ENV_VAR}=${key}`;
+    let action = LicenseWrite.WRITTEN;
+    if (already)
+        action = LicenseWrite.ALREADY;
+    else if (-1 !== at) {
+        lines[at] = `${ENV_VAR}=${key}`;
+        action = LicenseWrite.REPLACED;
+    }
+    else {
+        if (0 < lines.length && '' !== lines[lines.length - 1])
+            lines.push('');
+        lines.push(`${ENV_VAR}=${key}`, '');
+    }
+    if (LicenseWrite.ALREADY !== action)
+        io.writeFile(envPath, lines.join('\n'));
+    // The order matters: a key in git is leaked whether or not the file is later removed.
+    const ignorePath = joinPath(dir, GITIGNORE);
+    const ignore = io.exists(ignorePath) ? io.readFile(ignorePath) : '';
+    let gitignoreUpdated = false;
+    if (!gitignoreCoversEnv(ignore)) {
+        const next = '' === ignore ? `${ENV_FILE}\n` : `${ignore.replace(/\n*$/, '\n')}${ENV_FILE}\n`;
+        io.writeFile(ignorePath, next);
+        gitignoreUpdated = true;
+    }
+    const wrote = LicenseWrite.ALREADY === action
+        ? `license key already in ${ENV_FILE}`
+        : `license key written to ${ENV_FILE}`;
+    return {
+        action,
+        gitignoreUpdated,
+        message: gitignoreUpdated ? `${wrote}, and ${ENV_FILE} added to ${GITIGNORE}` : wrote,
+    };
+}

package/dist/setup/listeners.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Which ports a process tree is listening on, parsed from the tools that can answer that.
+ *
+ * Kept separate from the commands that produce the text so the Windows behaviour is testable from
+ * any machine. That is not a stylistic preference: port discovery on Windows returned nothing at
+ * all until this was extracted, so a dev server that prints no parseable URL was undiscoverable
+ * there — and `react-scripts` prints no parseable URL outside a tty, which makes it the majority
+ * platform's most common React setup.
+ */
+/** One LISTENING socket and the process that owns it. */
+export interface Listener {
+    readonly port: number;
+    readonly pid: number;
+}
+/** `lsof -a -p <pids> -iTCP -sTCP:LISTEN -P -n`, NAME column only. */
+export declare function parseLsofPorts(out: string): number[];
+/**
+ * `netstat -ano` on Windows.
+ *
+ * The port is whatever follows the LAST colon: `[::]:3000` has three of them, so splitting on ':'
+ * and taking index 1 reads every IPv6 row as port 0 and silently drops half the table.
+ */
+export declare function parseNetstatListeners(out: string): Listener[];
+/** One (pid, parent) pair, as `wmic process get ParentProcessId,ProcessId` prints them. */
+export interface ProcessPair {
+    readonly pid: number;
+    readonly ppid: number;
+}
+export declare function parseWmicProcesses(out: string): ProcessPair[];
+/**
+ * `root` and everything descended from it.
+ *
+ * The dev server is almost never the process we spawned: `npm run dev` starts a shell, which starts
+ * node, which binds the port. Matching only the pid we hold finds nothing, and nothing is
+ * indistinguishable from "no server".
+ */
+export declare function descendants(pairs: readonly ProcessPair[], root: number): number[];

package/dist/setup/listeners.js

@@ -0,0 +1,85 @@
+/**
+ * Which ports a process tree is listening on, parsed from the tools that can answer that.
+ *
+ * Kept separate from the commands that produce the text so the Windows behaviour is testable from
+ * any machine. That is not a stylistic preference: port discovery on Windows returned nothing at
+ * all until this was extracted, so a dev server that prints no parseable URL was undiscoverable
+ * there — and `react-scripts` prints no parseable URL outside a tty, which makes it the majority
+ * platform's most common React setup.
+ */
+/** `lsof -a -p <pids> -iTCP -sTCP:LISTEN -P -n`, NAME column only. */
+export function parseLsofPorts(out) {
+    const ports = new Set();
+    for (const m of String(out).matchAll(/:(\d+)\s*$/gm))
+        ports.add(Number(m[1]));
+    return [...ports];
+}
+const NETSTAT_PROTO = 'TCP';
+const NETSTAT_STATE = 'LISTENING';
+const NETSTAT_MIN_COLUMNS = 5;
+/**
+ * `netstat -ano` on Windows.
+ *
+ * The port is whatever follows the LAST colon: `[::]:3000` has three of them, so splitting on ':'
+ * and taking index 1 reads every IPv6 row as port 0 and silently drops half the table.
+ */
+export function parseNetstatListeners(out) {
+    const rows = [];
+    for (const line of String(out).split(/\r?\n/)) {
+        const f = line.trim().split(/\s+/);
+        if (f.length < NETSTAT_MIN_COLUMNS)
+            continue;
+        if (f[0]?.toUpperCase() !== NETSTAT_PROTO || f[3]?.toUpperCase() !== NETSTAT_STATE)
+            continue;
+        const local = f[1] ?? '';
+        const port = Number(local.slice(local.lastIndexOf(':') + 1));
+        const pid = Number(f[4]);
+        if (Number.isInteger(port) && port > 0 && Number.isInteger(pid))
+            rows.push({ port, pid });
+    }
+    return rows;
+}
+export function parseWmicProcesses(out) {
+    const pairs = [];
+    for (const line of String(out).split(/\r?\n/)) {
+        const f = line.trim().split(/\s+/);
+        if (f.length !== 2)
+            continue;
+        const ppid = Number(f[0]);
+        const pid = Number(f[1]);
+        if (Number.isInteger(pid) && Number.isInteger(ppid))
+            pairs.push({ pid, ppid });
+    }
+    return pairs;
+}
+/**
+ * `root` and everything descended from it.
+ *
+ * The dev server is almost never the process we spawned: `npm run dev` starts a shell, which starts
+ * node, which binds the port. Matching only the pid we hold finds nothing, and nothing is
+ * indistinguishable from "no server".
+ */
+export function descendants(pairs, root) {
+    const byParent = new Map();
+    for (const { pid, ppid } of pairs) {
+        const kids = byParent.get(ppid);
+        if (kids === undefined)
+            byParent.set(ppid, [pid]);
+        else
+            kids.push(pid);
+    }
+    const found = new Set([root]);
+    const queue = [root];
+    while (queue.length > 0) {
+        const next = queue.shift();
+        if (next === undefined)
+            continue;
+        for (const child of byParent.get(next) ?? []) {
+            if (found.has(child))
+                continue;
+            found.add(child);
+            queue.push(child);
+        }
+    }
+    return [...found];
+}

package/dist/setup/node-effects.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The real world, bound to the injected shape `runSetupPhases` expects.
+ *
+ * Everything here is a thin binding to something that already exists — `openInBrowser`,
+ * `fetchStatus`, the driver table — with one exception: the dev server. Nothing else in the package
+ * owns a spawned process, and owning one properly is most of this file.
+ *
+ * The promise this makes about that process: setup leaves it running on success, because an
+ * instrumented app the user can watch IS the deliverable, and stops it on every other ending. A
+ * server nobody started, holding a port nobody can account for, surviving the terminal that spawned
+ * it, is the failure this file exists to avoid — measured, an interrupted run used to leave one
+ * listening indefinitely.
+ */
+import type { CandidateSession } from './session-pick.js';
+import type { PageProbe } from './page-probe.js';
+/** The dev server this process started, and the only one it will ever stop. */
+export declare class OwnedDevServer {
+    private child;
+    private buffer;
+    private lastOutputAt;
+    private handedOver;
+    start(command: string, cwd: string, env: Readonly<Record<string, string>>): void;
+    /** The process group leader, for a caller that has to clean up what it handed over. */
+    pid(): number | undefined;
+    output(): string;
+    exited(): boolean;
+    quietForMs(): number;
+    /** Ports anything in this server's process tree is listening on. */
+    listeningPorts(): number[];
+    /** Hand the running server to the user. After this, `stop()` does nothing. */
+    /**
+     * Leave the server running and stop holding it.
+     *
+     * `unref` on the child is NOT enough: its stdout and stderr are pipes owned by this process, and
+     * an open pipe keeps the event loop alive on its own. So `init` printed "setup complete" and then
+     * hung until something killed it, turning a successful run into a non-zero exit — which is
+     * exactly what the install gate reported, on a run whose every other assertion passed.
+     *
+     * The streams are unref'd rather than destroyed: the server is still writing to them, and
+     * destroying the read end of a live pipe risks an EPIPE in somebody else's dev server.
+     */
+    handOver(): void;
+    stop(): void;
+}
+/**
+ * Fetch the page and say what came back.
+ *
+ * A refused certificate is reported separately because the server ANSWERED: a self-signed dev cert
+ * is an ordinary local setup, and calling it "nothing is listening" sends somebody to start a
+ * server that is already running.
+ */
+export declare function probePage(url: string): Promise<PageProbe>;
+/** Sessions the daemon is holding, in the shape the picker reads. */
+export declare function listSessions(port: number): Promise<CandidateSession[]>;
+/** Whether this project has a saved flow, wherever the project keeps one. */
+export declare function flowsSaved(roots: readonly string[]): boolean;
+/** On PATH at all. The separate question of whether it RUNS is asked by chooseDriver. */
+export declare function binaryExists(bin: string): boolean;
+/** Whether a directory looks like a project setup has already wired. */
+export declare function alreadyWired(dir: string): boolean;