@reticlehq/server 3.6.0 → 3.7.0

package/dist/command/setup/bringup/ensure-daemon.js

@@ -24,7 +24,7 @@ import { readDaemonRegistry } from '../../daemon/daemon-resolve.js';
 import { LOOPBACK_HOST, STATUS_HOLD_MS } from '@reticlehq/core';
 import { probePresence, presenceIsUsable } from '../../daemon/binding/port-presence.js';
 import { probeDaemon, waitForDaemonBind } from '../../../surface/mcp/mcp-proxy.js';
-import { daemonSpawnArgs } from '../../cli/daemon-start-options.js';
+import { daemonSpawnArgs, headlessByDefault } from '../../cli/daemon-start-options.js';
 import { fetchStatus, summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { runKill } from '../../cli/cli-kill.js';
 export const EnsureDaemon = {
@@ -154,7 +154,14 @@ export function nodeEnsureDaemonDeps(skewed) {
             const scriptPath = process.argv[1];
             if (undefined === scriptPath)
                 return false;
-            const started = spawnDaemon(process.execPath, scriptPath, daemonSpawnArgs({ port, headless: true, http: false }), port);
+            const started = spawnDaemon(process.execPath, scriptPath, 
+            // The daemon init starts is the one the agent attaches to and drives through, so it follows
+            // the same rule as every other: shown on a desktop, hidden in CI or with no display.
+            daemonSpawnArgs({
+                port,
+                headless: headlessByDefault(process.env, process.platform),
+                http: false,
+            }), port);
             // For a log or a pipe. On a terminal it was a JSON line in the middle of `init`'s output, read
             // by a person, about a step the next lines already report in words.
             if (true !== process.stderr.isTTY)

package/dist/command/setup/init/agent-restart.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether the agent that ran `init` has to restart before it can use what `init` set up.
+ *
+ * An agent client reads its MCP server list when it STARTS and never re-reads it. So the session
+ * that ran `init` has the `reticle_*` tools only if Reticle was registered before it started, and
+ * nothing a running session does can add them: there is no server entry in it to reconnect. The
+ * honest answer is a restart, said plainly, once `init` can tell it is needed.
+ *
+ * Two ways to tell. This run registered the server (it cannot be in any open session), or `init`
+ * runs inside an agent and the daemon has no agent attached, which is what an agent with the tools
+ * always has. Pure: the facts come in, the sentence comes out.
+ */
+export interface RestartFacts {
+    /** `init` was spawned by a coding agent (Claude Code, Codex), not typed by a person. */
+    readonly insideAgent: boolean;
+    /** This run registered the MCP server, so no open session has it. */
+    readonly newlyRegistered: boolean;
+    /** MCP clients attached to the daemon on this port; undefined when the daemon could not be asked. */
+    readonly attached: number | undefined;
+}
+export declare function restartNotice(facts: RestartFacts): string | undefined;
+/** How many agents' MCP clients the daemon's `/status` lists, or undefined for no answer. */
+export declare function attachedAgents(status: unknown): number | undefined;

package/dist/command/setup/init/agent-restart.js

@@ -0,0 +1,28 @@
+/**
+ * Whether the agent that ran `init` has to restart before it can use what `init` set up.
+ *
+ * An agent client reads its MCP server list when it STARTS and never re-reads it. So the session
+ * that ran `init` has the `reticle_*` tools only if Reticle was registered before it started, and
+ * nothing a running session does can add them: there is no server entry in it to reconnect. The
+ * honest answer is a restart, said plainly, once `init` can tell it is needed.
+ *
+ * Two ways to tell. This run registered the server (it cannot be in any open session), or `init`
+ * runs inside an agent and the daemon has no agent attached, which is what an agent with the tools
+ * always has. Pure: the facts come in, the sentence comes out.
+ */
+const RESTART_NOW = 'Restart your coding agent now: this session started before Reticle was registered with it, so ' +
+    'the `reticle_*` tools are not in it, and an agent loads its tools only when it starts. ' +
+    '`npx @reticlehq/server init --relaunch` prints the exact resume command for Claude Code and ' +
+    'Codex. Once per machine.';
+export function restartNotice(facts) {
+    if (facts.newlyRegistered)
+        return RESTART_NOW;
+    return facts.insideAgent && 0 === facts.attached ? RESTART_NOW : undefined;
+}
+/** How many agents' MCP clients the daemon's `/status` lists, or undefined for no answer. */
+export function attachedAgents(status) {
+    if ('object' !== typeof status || null === status)
+        return undefined;
+    const peers = status.mcpPeers;
+    return Array.isArray(peers) ? peers.length : 0;
+}

package/dist/command/setup/init/init-port.d.ts

@@ -1,3 +1,10 @@
+/**
+ * The port a project asks for when the default is somebody else's: its own, from its id (or its
+ * directory, before it has one), the same on every run. Every project used to ask for the default
+ * plus one, so with the first one's daemon not yet running every later project was written the same
+ * port and shared it. Taken ports are still skipped by the caller's `pickPort`.
+ */
+export declare function projectPortFor(seed: string): number;
 /**
  * `RETICLE_PORT`, when it names a port. The one reader of it for the CLI, `init` included.
  *
@@ -14,6 +21,8 @@ export declare function portForInit(explicit: number | undefined, configured: nu
     pickPort: (preferred: number) => Promise<number>;
     /** The daemon on `port` was started from this project's directory or one above it. */
     daemonStartedHere?: (port: number) => boolean;
-}): Promise<number | undefined>;
+}, 
+/** The project's directory: the port's seed when the project has no id yet. */
+dir?: string): Promise<number | undefined>;
 /** Is `dir` the same directory as `cwd`, or an ancestor of it? */
 export declare function isSameOrAbove(dir: string, cwd: string): boolean;

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

@@ -11,6 +11,23 @@
 import { relative, isAbsolute } from 'node:path';
 import { RETICLE_DEFAULT_PORT, ReticleEnv } from '@reticlehq/core';
 const MAX_PORT = 65_535;
+/** Ports a project moved off the default may get: above it, and below the 5000s dev servers use. */
+const PROJECT_PORT_FIRST = RETICLE_DEFAULT_PORT + 1;
+const PROJECT_PORT_SPAN = 599;
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+/**
+ * The port a project asks for when the default is somebody else's: its own, from its id (or its
+ * directory, before it has one), the same on every run. Every project used to ask for the default
+ * plus one, so with the first one's daemon not yet running every later project was written the same
+ * port and shared it. Taken ports are still skipped by the caller's `pickPort`.
+ */
+export function projectPortFor(seed) {
+    let hash = FNV_OFFSET;
+    for (let i = 0; i < seed.length; i++)
+        hash = Math.imul(hash ^ seed.charCodeAt(i), FNV_PRIME);
+    return PROJECT_PORT_FIRST + ((hash >>> 0) % PROJECT_PORT_SPAN);
+}
 /**
  * `RETICLE_PORT`, when it names a port. The one reader of it for the CLI, `init` included.
  *
@@ -26,7 +43,9 @@ export function portFromEnv(env) {
     const port = Number(raw);
     return 0 < port && port <= MAX_PORT ? port : undefined;
 }
-export async function portForInit(explicit, configured, projectId, deps) {
+export async function portForInit(explicit, configured, projectId, deps, 
+/** The project's directory: the port's seed when the project has no id yet. */
+dir) {
     if (explicit !== undefined)
         return explicit;
     if (configured !== undefined)
@@ -45,7 +64,8 @@ export async function portForInit(explicit, configured, projectId, deps) {
     const holders = await deps.daemonProjects(RETICLE_DEFAULT_PORT);
     if (1 !== holders.length || holders[0] === projectId)
         return undefined;
-    return deps.pickPort(RETICLE_DEFAULT_PORT + 1);
+    const seed = projectId ?? dir;
+    return deps.pickPort(seed === undefined ? PROJECT_PORT_FIRST : projectPortFor(seed));
 }
 /** Is `dir` the same directory as `cwd`, or an ancestor of it? */
 export function isSameOrAbove(dir, cwd) {

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

@@ -6,6 +6,7 @@
  * every command harder to read.
  */
 import { type InitResult } from '@reticlehq/init';
+import { type FirstFlowPort } from '../setup-command.js';
 /**
  * Does the served document name the SDK, so its absence means a stale dev server?
  *
@@ -22,7 +23,8 @@ interface InitRuntimeArgs {
     readonly dryRun: boolean;
     readonly filesOnly?: boolean | undefined;
     readonly json?: boolean | undefined;
-    readonly drive?: boolean | undefined;
+    /** `--no-first-run` sets it false: connect, and stop without the coverage summary. */
+    readonly firstRun?: boolean | undefined;
     readonly open?: boolean | undefined;
     readonly agents?: boolean | undefined;
     /**
@@ -41,9 +43,17 @@ interface InitRuntimeArgs {
     /** Restart the calling client so IT gets the tools — see relaunch.ts. */
     readonly relaunch?: boolean | undefined;
     readonly licenseKey?: string | undefined;
+    /**
+     * Init is the first half of a longer command (`reticle connect`): a setup that did not finish
+     * sets a failing exit code and returns, so the command can still sign in and link. Exiting here
+     * ended connect before it signed in, and nothing said to run it again.
+     */
+    readonly keepGoing?: boolean | undefined;
 }
 interface RuntimePrintIo {
     readonly print: (line: string) => void;
 }
-export declare function continueAfterInit(parsed: InitRuntimeArgs, result: InitResult, io: RuntimePrintIo, cwd: string): Promise<void>;
+export declare function continueAfterInit(parsed: InitRuntimeArgs, result: InitResult, io: RuntimePrintIo, cwd: string, 
+/** init's ending once the connection is proved: coverage and the agent prompt. See `FirstFlowPort`. */
+firstFlow?: FirstFlowPort): Promise<void>;
 export {};

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

@@ -11,18 +11,22 @@ import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { FEEDBACK_HINT, Framework, InitFailure } from '@reticlehq/init';
 import { confirmInstall, nodeConfirmDeps } from '../terminal/confirm.js';
 import { writeLicenseKey } from '../license-key.js';
-import { registerOtherAgents, runSetupCommand } from '../setup-command.js';
-import { bridgeOccupied } from '../bringup/bridge-port.js';
+import { registerOtherAgents, runSetupCommand, } from '../setup-command.js';
+import { bridgeOccupied, freePortAfter } from '../bringup/bridge-port.js';
 import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../../portal/bridge/pairing-token.js';
 import { relaunchDecision } from '../bringup/relaunch.js';
+import { attachedAgents, restartNotice } from './agent-restart.js';
 import { claudeTranscriptExists, codexSessionFor } from '../terminal/transcripts.js';
-import { probePresence } from '../../daemon/binding/port-presence.js';
+import { PortPresence, probePresence } from '../../daemon/binding/port-presence.js';
 import { probeDaemon } from '../../../surface/mcp/proxy/proxy-daemon-probe.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { collectEnv, DEFAULT_PHASE_TIMEOUT_MS } from '../setup-options.js';
 import { staticPageDevCommand } from '../bringup/static-page-server.js';
 import { SetupPhase } from '../run-setup.js';
 import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
+/** Claude Code marks every process it spawns with this variable set to this value. */
+const CLAUDE_CODE_ENV = 'CLAUDECODE';
+const CLAUDE_CODE_MARKER = '1';
 /** How often the runtime phases look again: fast enough not to be the wait, slow enough to be free. */
 const POLL_MS = 250;
 /**
@@ -76,8 +80,16 @@ function printRelaunch(parsed, io, cwd) {
     }).message);
     io.print('');
 }
-export async function continueAfterInit(parsed, result, io, cwd) {
+export async function continueAfterInit(parsed, result, io, cwd, 
+/** init's ending once the connection is proved: coverage and the agent prompt. See `FirstFlowPort`. */
+firstFlow) {
     const port = parsed.port ?? RETICLE_DEFAULT_PORT;
+    const stop = () => {
+        if (true === parsed.keepGoing)
+            process.exitCode = 1;
+        else
+            process.exit(1);
+    };
     // Real installs persist the key whichever way setup ends. A preview must leave .env and
     // .gitignore untouched, just as it leaves project wiring and agent configuration untouched.
     if (!parsed.dryRun && undefined !== parsed.licenseKey) {
@@ -105,7 +117,7 @@ export async function continueAfterInit(parsed, result, io, cwd) {
             if (true === parsed.json)
                 process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
             if (!result.ok)
-                process.exit(1);
+                stop();
         });
     }
     // From here on init left the ask to us, so it is the last thing on every exit below.
@@ -114,17 +126,31 @@ export async function continueAfterInit(parsed, result, io, cwd) {
             io.print('');
         io.print(FEEDBACK_HINT);
     };
+    // `init` deferred its outcome to this phase, so every exit below reports it, and only once: the
+    // success path, a failure, a throw and an interrupt can each reach here, and two rows for one run
+    // would double the funnel this event exists to measure.
+    let outcomeReported = false;
+    const reportOnce = (init) => {
+        if (outcomeReported)
+            return;
+        outcomeReported = true;
+        reportInitOutcome(init);
+    };
     const context = result.context;
     if (context === undefined) {
-        // Nothing was established, so there is nothing to run against. init has already said why.
+        // Nothing was established, so there is nothing to run against. init has already said why, and
+        // the outcome it deferred (a failed dependency install, usually) is reported here or nowhere.
+        if (result.outcome !== undefined)
+            reportOnce(result.outcome);
         ask();
         if (true === parsed.json)
             process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-        process.exit(1);
+        stop();
+        return;
     }
     const reportFailure = (reason) => {
         if (result.outcome !== undefined) {
-            reportInitOutcome({ ...result.outcome, ok: false, reason });
+            reportOnce({ ...result.outcome, ok: false, reason });
         }
     };
     // A PENDING connect step is not a reason to skip the runtime phase, and treating it as one made
@@ -142,10 +168,13 @@ export async function continueAfterInit(parsed, result, io, cwd) {
     // 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 }).catch((error) => {
+    const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).catch((error) => {
         reportFailure(InitFailure.RUNTIME_ERROR);
         throw error;
-    }), port);
+    });
+    const refusal = bridgeOccupied(presence, port, PortPresence.FOREIGN === presence
+        ? await freePortAfter(port, (p) => probeDaemon(p))
+        : undefined);
     if (refusal !== undefined) {
         reportFailure(InitFailure.BRIDGE_OCCUPIED);
         io.print(refusal);
@@ -153,8 +182,12 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         if (true === parsed.json) {
             process.stdout.write(`${JSON.stringify({ ok: false, reason: InitFailure.BRIDGE_OCCUPIED }, null, 2)}\n`);
         }
-        process.exit(1);
+        stop();
+        return;
     }
+    // A Ctrl-C during the wait ends the process with no `finally`, so the outcome is reported from the
+    // signal itself. The send is detached, so it survives the exit that follows.
+    const releaseInterrupt = reportOnInterrupt(() => reportFailure(InitFailure.INTERRUPTED));
     return runSetupCommand({
         appDir: context.appDir,
         invokedAt: cwd,
@@ -164,6 +197,9 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         pairingToken: readOrCreatePairingTokenSync(defaultPairingTokenDir()),
         env: collectEnv(parsed.env ?? []),
         openBrowser: false !== parsed.open,
+        firstRun: false !== parsed.firstRun,
+        json: true === parsed.json,
+        firstFlow,
         registerAgents: wantsAgents(parsed),
         phaseTimeoutMs: undefined === parsed.timeoutSeconds
             ? DEFAULT_PHASE_TIMEOUT_MS
@@ -181,17 +217,19 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         // A plain page with no dev script gets Reticle's own static server, so the page is actually
         // served and the connect can be proved, instead of stopping at "start the app yourself".
         ...(() => {
-            const devCommand = context.devCommand ??
-                (undefined === parsed.url
-                    ? staticPageDevCommand({
-                        appDir: context.appDir,
-                        isStaticPage: Framework.HTML === context.framework,
-                    })
-                    : undefined);
-            return undefined === devCommand ? {} : { devCommand };
+            if (undefined !== context.devCommand)
+                return { devCommand: context.devCommand };
+            if (undefined !== parsed.url)
+                return {};
+            const devCommand = staticPageDevCommand({
+                appDir: context.appDir,
+                isStaticPage: Framework.HTML === context.framework,
+            });
+            return undefined === devCommand ? {} : { devCommand, devCommandIsStaticPage: true };
         })(),
         ...(undefined === parsed.url ? {} : { suppliedUrl: parsed.url }),
-    }, (line) => io.print(line)).then((outcome) => {
+    }, (line) => io.print(line))
+        .then(async (outcome) => {
         if (result.outcome !== undefined) {
             const init = {
                 ...result.outcome,
@@ -210,26 +248,28 @@ export async function continueAfterInit(parsed, result, io, cwd) {
                         ? InitFailure.DEV_SERVER
                         : InitFailure.APP_CONNECTION;
             }
-            reportInitOutcome(init);
+            reportOnce(init);
         }
         // 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);
+                stop();
             return;
         }
         io.print('');
         // The precondition for everything the closing asks for, printed on the path that could not say
-        // it. An agent client reads its MCP server list when it STARTS and never re-reads it, so on the
-        // run that first registers Reticle the `reticle_*` tools are not in the session that just asked
-        // for them -- and this path closes by telling that session to call `reticle_act_and_wait`.
-        // `restartHint` has said this for a long time and is printed only when init stops at the files.
-        if (true === result.mcpNewlyRegistered) {
-            io.print('Reticle was registered with your agent by this run, and an agent reads its tool list only ' +
-                'when it starts: the `reticle_*` tools are NOT in this session yet. Restart it first — ' +
-                '`npx @reticlehq/server init --relaunch` prints the exact resume command for Claude Code ' +
-                'and Codex. Once per machine.');
+        // it. An agent client reads its MCP server list when it STARTS and never re-reads it, so an
+        // agent that ran this without the `reticle_*` tools cannot do what the closing tells it to.
+        // See agent-restart.ts for the two ways that is known.
+        const restart = restartNotice({
+            insideAgent: CLAUDE_CODE_MARKER === process.env[CLAUDE_CODE_ENV] ||
+                undefined !== codexSessionFor(cwd),
+            newlyRegistered: true === result.mcpNewlyRegistered,
+            attached: attachedAgents(await fetchStatus(port)),
+        });
+        if (undefined !== restart) {
+            io.print(restart);
             io.print('');
         }
         if (outcome.ok && !outcome.flowSaved) {
@@ -245,11 +285,8 @@ export async function continueAfterInit(parsed, result, io, cwd) {
             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.');
+            io.print(`✓ setup complete — ${outcome.url ?? 'the app'} is instrumented and its first flow is ` +
+                'saved. The tab stays open; a linked project sends the flow and its run to your dashboard.');
             ask();
             return;
         }
@@ -259,9 +296,31 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         for (const [i, step] of outcome.fallback.entries())
             io.print(`   ${i + 1}. ${step}`);
         ask();
-        process.exit(1);
+        stop();
     }, (error) => {
         reportFailure(InitFailure.RUNTIME_ERROR);
         throw error;
+    })
+        .finally(releaseInterrupt);
+}
+const INTERRUPT_SIGNALS = ['SIGINT', 'SIGTERM'];
+/** 128 + the signal number, which is what a shell reports. */
+const INTERRUPT_EXIT_CODE = { SIGINT: 130, SIGTERM: 143 };
+/** Run `report` if the process is interrupted. Returns the disposer. */
+function reportOnInterrupt(report) {
+    const handlers = INTERRUPT_SIGNALS.map((signal) => {
+        const handler = () => {
+            report();
+            // Before setup installs its own handler ours may be the only one, and a listener present
+            // means Node no longer exits on the signal by itself: without this, Ctrl-C would be ignored.
+            if (1 === process.listenerCount(signal))
+                process.exit(INTERRUPT_EXIT_CODE[signal]);
+        };
+        process.on(signal, handler);
+        return { signal, handler };
     });
+    return () => {
+        for (const { signal, handler } of handlers)
+            process.off(signal, handler);
+    };
 }

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

@@ -53,6 +53,8 @@ export declare class OwnedDevServer {
     handOver(url?: string): void;
     stop(): void;
 }
+/** Run a command and return what it printed, or '' if it failed to finish within `timeoutMs`. */
+export declare function run(file: string, args: string[], timeoutMs?: number): string;
 /**
  * Fetch the page and say what came back.
  *

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

@@ -63,7 +63,13 @@ export class OwnedDevServer {
         this.child = spawn(process.execPath, [LOG_CAP_SCRIPT, log, String(DEV_SERVER_LOG_CAP_BYTES), command], {
             cwd,
             // Its own process group, so stopping it stops what it started rather than only the wrapper.
-            detached: !WINDOWS,
+            // Detached on Windows too: there libuv puts every non-detached child in a job object that
+            // kills it when this process exits. The supervisor died with `init`, the server it fed lost
+            // its pipe reader, and its next log line was an EPIPE: every Windows install cell whose
+            // server logs per request (Next, Astro) or on an edit (CRA, Angular) failed that way.
+            detached: true,
+            // Detached on Windows means no console; this keeps one from opening as a visible window.
+            windowsHide: true,
             // Nothing of ours: the supervisor holds the server's pipes, and init holds none of its.
             stdio: 'ignore',
             // Reticle already provides the detached supervisor. Astro's agent auto-backgrounding
@@ -169,8 +175,21 @@ export class OwnedDevServer {
         this.child = undefined;
     }
 }
-function run(file, args) {
-    const r = spawnSync(file, args, { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+/**
+ * How long one process-listing command may take. `init` calls these on every dev-server poll, and
+ * spawnSync blocks the event loop: with no bound, one stalled WMI query on a Windows install cell
+ * froze `init` silently for nine and a half minutes, until the gate killed it.
+ */
+const RUN_TIMEOUT_MS = 15_000;
+/** Run a command and return what it printed, or '' if it failed to finish within `timeoutMs`. */
+export function run(file, args, timeoutMs = RUN_TIMEOUT_MS) {
+    const r = spawnSync(file, args, {
+        encoding: 'utf8',
+        maxBuffer: 8 * 1024 * 1024,
+        timeout: timeoutMs,
+    });
+    if (undefined !== r.error)
+        return '';
     return r.stdout ?? '';
 }
 /**
@@ -183,13 +202,22 @@ function run(file, args) {
  * `init` then waits out the full quiet window and reports "the dev server stopped producing output
  * without ever serving a page" about a Vite server that was serving perfectly the whole time.
  *
- * The fallback prints the same two-integers-per-line shape, so `parseWmicProcesses` reads either
- * without knowing which produced it. Tried in this order because `wmic` is an order of magnitude
- * faster to start than PowerShell, and on a machine that still has it nothing needs to change.
+ * The fallback prints the same `CreationDate ParentProcessId ProcessId` shape (UTC, in WMI's
+ * datetime format), so `parseWmicProcesses` reads either without knowing which produced it. The
+ * creation time is not decoration: Windows keeps a dead parent's pid as ParentProcessId and reuses
+ * pids, and without it the tree walk adopted the runner's sshd and reported port 22 as the dev
+ * server. A process with no creation time (System) prints the old two-column row.
+ *
+ * Tried in this order because `wmic` is an order of magnitude faster to start than PowerShell, and
+ * on a machine that still has it nothing needs to change.
  */
-const POWERSHELL_PAIRS = 'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ParentProcessId) $($_.ProcessId)" }';
+const POWERSHELL_PAIRS = 'Get-CimInstance Win32_Process | ForEach-Object { ' +
+    '$c = $_.CreationDate; ' +
+    "$t = if ($c) { $c.ToUniversalTime().ToString('yyyyMMddHHmmss.ffffff', " +
+    "[Globalization.CultureInfo]::InvariantCulture) + '+000' } else { '' }; " +
+    '"$t $($_.ParentProcessId) $($_.ProcessId)".Trim() }';
 function windowsProcessPairs() {
-    const fromWmic = parseWmicProcesses(run('wmic', ['process', 'get', 'ParentProcessId,ProcessId']));
+    const fromWmic = parseWmicProcesses(run('wmic', ['process', 'get', 'CreationDate,ParentProcessId,ProcessId']));
     if (0 < fromWmic.length)
         return fromWmic;
     return parseWmicProcesses(run('powershell', ['-NoProfile', '-NonInteractive', '-Command', POWERSHELL_PAIRS]));

package/dist/command/setup/probe/existing-app.d.ts

@@ -10,3 +10,15 @@ export declare function urlOfExistingApp(entries: readonly DevServerEntry[], sco
     projectId?: string | undefined;
     root?: string | undefined;
 }): string | undefined;
+/**
+ * The url of a window of THIS project already connected to the daemon, if one is.
+ *
+ * A desktop app with a packaged renderer announces no dev server, so the registry above cannot see
+ * it, and setup started the app again beside the running one. On macOS a build signed differently
+ * from the installed app is a different app to the keychain, so every start asked for the password
+ * again. Scoped to the project the page reported, like the registry: never a sibling's window.
+ */
+export declare function connectedAppUrl(sessions: readonly {
+    readonly url?: string;
+    readonly projectId?: string;
+}[], projectId: string | undefined): string | undefined;

package/dist/command/setup/probe/existing-app.js

@@ -11,3 +11,17 @@ export function urlOfExistingApp(entries, scope) {
     const first = mine[0];
     return first === undefined ? undefined : first.url;
 }
+/**
+ * The url of a window of THIS project already connected to the daemon, if one is.
+ *
+ * A desktop app with a packaged renderer announces no dev server, so the registry above cannot see
+ * it, and setup started the app again beside the running one. On macOS a build signed differently
+ * from the installed app is a different app to the keychain, so every start asked for the password
+ * again. Scoped to the project the page reported, like the registry: never a sibling's window.
+ */
+export function connectedAppUrl(sessions, projectId) {
+    if (projectId === undefined)
+        return undefined;
+    const mine = sessions.find((s) => s.projectId === projectId && 0 < (s.url ?? '').length);
+    return mine?.url;
+}

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

@@ -35,7 +35,7 @@ export function remainingSteps(p) {
             'what produce a verdict. Or hand the whole drive to Reticle with `reticle_verify { action: ' +
             '"explore", persona: "<who does what>" }`, which records what it drove so later runs replay ' +
             'with no model in the loop; that route runs on the Reticle platform and needs a linked ' +
-            'project (`reticle connect`); every plan, Free included, has monthly Harness credits.');
+            'project (`reticle connect`); a new account gets 10 free credits to try it.');
     }
     // Whether anything is actually outstanding, read BEFORE the docs pointer is added -- that line is
     // an offer, not a task, and a run with nothing left still gets it.

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

@@ -2,12 +2,8 @@
  * The half of setup that happens after the files are written.
  *
  * `init` wires a project; this gets the app running with the SDK inside it and proves a session
- * connected. That is where ONBOARDING ends — the first run, which proves a flow, is a separate
- * stage and a separate command.
- *
- * It does NOT drive a flow. `reticle_verify { action: "explore" }` does that, with a model inside
- * the daemon that already holds the tools — so no client restart is needed and no second CLI has to
- * exist on the machine.
+ * connected. That is where ONBOARDING ends. Then init says what Reticle sees and hands the first
+ * flow to the coding agent (`try-command.ts`'s `initFirstFlow`); nothing in init drives.
  *
  * Every effect is injected. That is not ceremony: the sequence has five phases, each with its own
  * way of going wrong, and the alternative to injecting them is a test that boots a real dev server
@@ -16,6 +12,20 @@
 import { type CandidateSession } from './session-pick.js';
 import { type PageProbe } from './probe/page-probe.js';
 import { AppShape } from './desktop-shape.js';
+/**
+ * Said before Reticle starts its own static server for a plain page, while it can still be acted
+ * on: the page may already be served by something with an API behind it, and only the person
+ * running init knows that (#1426).
+ */
+export declare const STATIC_PAGE_URL_HINT: string;
+/** Whose server the success line names, so a session on Reticle's own is never mistaken for the app. */
+export declare const ServerStartedBy: {
+    readonly CALLER: "you passed its url";
+    readonly ALREADY_RUNNING: "it was already running";
+    readonly RETICLE_STATIC: "Reticle started this static server";
+    readonly SETUP: "setup started the dev server";
+};
+export type ServerStartedBy = (typeof ServerStartedBy)[keyof typeof ServerStartedBy];
 export declare const SetupPhase: {
     readonly DEV_SERVER: "dev-server";
     readonly CONNECT: "connect";
@@ -29,11 +39,14 @@ export interface SetupOutcome {
     readonly url?: string | undefined;
     readonly sessionId?: string | undefined;
     /**
-     * Always false here now, and kept because the callers that report progress still read it.
-     *
-     * Onboarding does not drive, so it cannot save a flow. The first run is what saves one.
+     * Always false: init never drives, and the coding agent proves the first flow after it.
      */
     readonly flowSaved: boolean;
+    /**
+     * The session was a Reticle-owned headless browser, now closed: there is no tab of the person's
+     * own to drive a first flow in.
+     */
+    readonly leased?: boolean;
     /** What the caller should do next, when this did not finish. */
     readonly fallback: string[];
     readonly notes: string[];
@@ -125,6 +138,13 @@ export interface SetupInput {
     /** This project's id, so a live tab of it can be told from another app's on the same url. */
     readonly projectId?: string | undefined;
     readonly devCommand?: string | undefined;
+    /**
+     * `devCommand` is Reticle's own static server, not the project's. The page may already be served
+     * by something else (python, php, a Node server with an API), and only the person running init
+     * can say so — with --url — so they are told before :5500 starts, and the success line says
+     * whose server it is (#1426).
+     */
+    readonly devCommandIsStaticPage?: boolean | undefined;
     /** The app is already served here, so nothing is started. */
     readonly suppliedUrl?: string | undefined;
     /**