@reticlehq/server 3.5.0 → 3.7.0

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

@@ -84,8 +84,9 @@ 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
+- "nothing is recorded yet" -> drive the journey yourself with \`reticle_act_and_wait\` and an \`until\` on its
+  last step; it is saved as a flow, so the next run replays with no model in the loop. With a linked
+  project, \`reticle_verify { action: "explore", persona: "<who does what>" }\` drives it for you
 `;
 /**
  * Write the skill for agents that have somewhere to put it, and only where they are installed.

package/dist/command/setup/bringup/bridge-port.d.ts

@@ -12,4 +12,6 @@
  */
 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;
+export declare function bridgeOccupied(presence: PortPresence, port: number, freePort?: number): string | undefined;
+/** The first port after `port` that nothing answers on, or undefined within the scan. */
+export declare function freePortAfter(port: number, isOpen: (port: number) => Promise<boolean>): Promise<number | undefined>;

package/dist/command/setup/bringup/bridge-port.js

@@ -12,13 +12,23 @@
  */
 import { PortPresence } from '../../daemon/binding/port-presence.js';
 /** The refusal to print, or undefined when the port is usable. */
-export function bridgeOccupied(presence, port) {
+export function bridgeOccupied(presence, port, freePort) {
     // 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.');
+        'it is occupied, however correct the wiring is. Free it, or re-run on another port (init moves ' +
+        `the config and the page with it): reticle init --port ${freePort === undefined ? '<n>' : String(freePort)}`);
+}
+/** How many ports past the held one are tried before giving up on a suggestion. */
+const FREE_PORT_SCAN = 20;
+/** The first port after `port` that nothing answers on, or undefined within the scan. */
+export async function freePortAfter(port, isOpen) {
+    for (let candidate = port + 1; candidate <= port + FREE_PORT_SCAN; candidate++) {
+        if (!(await isOpen(candidate)))
+            return candidate;
+    }
+    return undefined;
 }

package/dist/command/setup/bringup/connect-lease.d.ts

@@ -9,6 +9,7 @@
 /** A lease this run opened, and the way to hand it back; or why it could not be opened. */
 type LeaseOutcome = {
     readonly sessionId: string;
+    readonly zeroInstall: boolean;
     readonly release: () => Promise<void>;
 } | {
     readonly failed: string;

package/dist/command/setup/bringup/connect-lease.js

@@ -25,6 +25,7 @@ export async function openLeaseFor(port, url, token) {
         }
         return {
             sessionId: got.leased,
+            zeroInstall: got.zeroInstall,
             release: async () => {
                 await releaseLease(caller, got.leased);
                 await close();

package/dist/command/setup/bringup/dev-server-log-cap.js

@@ -101,6 +101,8 @@ function main(argv) {
     const child = spawn(command, {
         shell: true,
         stdio: ['ignore', 'pipe', 'pipe'],
+        // This supervisor runs detached with no console on Windows, so the shell would open a window.
+        windowsHide: true,
         env: process.env,
     });
     child.stdout.on('data', (chunk) => log.write(chunk));

package/dist/command/setup/bringup/dev-server-wait.d.ts

@@ -59,6 +59,14 @@ export declare const WAIT_CEILING_MS: number;
  */
 export declare function judgeWait(facts: WaitFacts): WaitVerdict;
 export declare function portBusyMessage(output: string): string | undefined;
+/**
+ * The dev server died before serving: say so, and quote the end of what it printed.
+ *
+ * Without the tail the reason was invisible: a missing `vite` binary printed `vite: command not
+ * found` to its own log, setup said only "exited without serving anything", and its first remedy
+ * ("start the dev server yourself") failed the same way.
+ */
+export declare function devServerDiedMessage(output: string): string;
 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

package/dist/command/setup/bringup/dev-server-wait.js

@@ -61,6 +61,25 @@ export function portBusyMessage(output) {
     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.`);
 }
+/** How many of the dev server's last lines a failure quotes. Enough for a stack's first frames. */
+const DIED_TAIL_LINES = 6;
+/**
+ * The dev server died before serving: say so, and quote the end of what it printed.
+ *
+ * Without the tail the reason was invisible: a missing `vite` binary printed `vite: command not
+ * found` to its own log, setup said only "exited without serving anything", and its first remedy
+ * ("start the dev server yourself") failed the same way.
+ */
+export function devServerDiedMessage(output) {
+    const tail = output
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => 0 < line.trim().length)
+        .slice(-DIED_TAIL_LINES);
+    return 0 === tail.length
+        ? 'The dev server exited without serving anything, and printed nothing.'
+        : `The dev server exited without serving anything. The last it printed:\n${tail.map((line) => `    ${line}`).join('\n')}`;
+}
 /** 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) {

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.
  *
@@ -12,4 +19,10 @@ export declare function portForInit(explicit: number | undefined, configured: nu
     daemonProjects: (port: number) => Promise<readonly string[]>;
     daemonPresent: (port: number) => Promise<boolean>;
     pickPort: (preferred: number) => Promise<number>;
-}): Promise<number | undefined>;
+    /** The daemon on `port` was started from this project's directory or one above it. */
+    daemonStartedHere?: (port: number) => boolean;
+}, 
+/** 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

@@ -8,8 +8,26 @@
  *
  * Undefined means the default.
  */
+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.
  *
@@ -25,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)
@@ -34,11 +54,21 @@ export async function portForInit(explicit, configured, projectId, deps) {
     // config as a `port` nobody chose.
     if (!(await deps.daemonPresent(RETICLE_DEFAULT_PORT)))
         return undefined;
+    // Started here — by this project's own editor MCP, typically — so it is ours whatever project id
+    // it recorded. Moving off it strands that agent: an MCP resolves its port once, at startup.
+    if (true === deps.daemonStartedHere?.(RETICLE_DEFAULT_PORT))
+        return undefined;
     // The bridge's own rule: it refuses a page only when it has served exactly ONE other project. A
     // daemon serving nobody, several projects, or ours accepts this one. A project that has never
     // been through init has no id yet, so a single named holder is somebody else.
     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) {
+    const rel = relative(dir, cwd);
+    return '' === rel || (!rel.startsWith('..') && !isAbsolute(rel));
 }

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

@@ -6,13 +6,25 @@
  * 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?
+ *
+ * A Next App Router page names its client components in the flight data inlined into the HTML —
+ * `reticle-dev.tsx`, measured on Next 16 under Turbopack and webpack alike. Reported from a Next app
+ * whose dev server was already running before init: setup waited on a page that could never connect
+ * and said nothing, because Next was assumed to carry the SDK only in its bundle. The Pages Router
+ * names chunks, not modules, so it stays silent.
+ */
+export declare function htmlCarriesSdk(framework: string, exists: (path: string) => boolean): boolean;
 /** 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;
+    /** `--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;
     /**
@@ -31,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

@@ -6,22 +6,27 @@
  * every command harder to read.
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 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;
 /**
@@ -30,6 +35,22 @@ const POLL_MS = 250;
  * of the document can never see it. See `htmlCarriesSdk` in run-setup.ts.
  */
 const HTML_CARRIES_SDK = new Set([Framework.VITE, Framework.HTML]);
+/** The connect component `init` writes for a Next App Router project. */
+const NEXT_APP_CONNECT = ['app', 'src/app'].flatMap((d) => ['tsx', 'jsx', 'js'].map((ext) => `${d}/reticle-dev.${ext}`));
+/**
+ * Does the served document name the SDK, so its absence means a stale dev server?
+ *
+ * A Next App Router page names its client components in the flight data inlined into the HTML —
+ * `reticle-dev.tsx`, measured on Next 16 under Turbopack and webpack alike. Reported from a Next app
+ * whose dev server was already running before init: setup waited on a page that could never connect
+ * and said nothing, because Next was assumed to carry the SDK only in its bundle. The Pages Router
+ * names chunks, not modules, so it stays silent.
+ */
+export function htmlCarriesSdk(framework, exists) {
+    if (HTML_CARRIES_SDK.has(framework))
+        return true;
+    return Framework.NEXT === framework && NEXT_APP_CONNECT.some(exists);
+}
 /** Registration is global MCP wiring, so both flags that disown it are read here. */
 function wantsAgents(parsed) {
     return false !== parsed.agents && false !== parsed.mcp;
@@ -59,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) {
@@ -88,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.
@@ -97,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
@@ -125,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);
@@ -136,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,
@@ -147,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
@@ -160,21 +213,23 @@ export async function continueAfterInit(parsed, result, io, cwd) {
                 startupBudgetMs: parsed.timeoutSeconds * 1000,
             }),
         pollMs: POLL_MS,
-        htmlCarriesSdk: HTML_CARRIES_SDK.has(context.framework),
+        htmlCarriesSdk: htmlCarriesSdk(context.framework, (rel) => existsSync(join(context.appDir, rel))),
         // 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,
@@ -193,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) {
@@ -228,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;
         }
@@ -242,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.
  *