@reticlehq/server 3.3.0 → 3.5.0

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

@@ -14,7 +14,7 @@
  * and a real browser to find out what happens when neither works.
  */
 import { judgeWait, portBusyMessage, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict, } from './bringup/dev-server-wait.js';
-import { waitProgressLine } from './terminal/wait-progress.js';
+import { connectProgressLine, waitProgressLine } from './terminal/wait-progress.js';
 /**
  * Windows gets longer to say something before silence counts as a wedge.
  *
@@ -28,7 +28,7 @@ import { waitProgressLine } from './terminal/wait-progress.js';
  */
 const WINDOWS_QUIET_MEANS_HUNG_MS = 3 * 60_000;
 const WINDOWS_QUIET_MEANS_HUNG_MS_APPLIES = 'win32' === process.platform;
-import { pickSession } from './session-pick.js';
+import { liveSessionOfProject, pickSession } from './session-pick.js';
 import { readPage, describePage, findingBeforeOpen, PageFinding, } from './probe/page-probe.js';
 import { remainingSteps } from './remaining-steps.js';
 import { AppShape, isDesktop, policyFor } from './desktop-shape.js';
@@ -40,11 +40,27 @@ import { AppShape, isDesktop, policyFor } from './desktop-shape.js';
 const SDK_READY_WINDOW_MS = 15_000;
 /** The wait left when no browser was opened: only a tab that is ALREADY loaded can still appear. */
 const NO_BROWSER_GRACE_MS = 3_000;
+/**
+ * How long a system browser that SAID it opened gets to produce a session before init proves the
+ * connect in a Reticle-owned browser instead. A launcher's exit is not a window: macOS `open` against
+ * a default browser that does not answer exits 1 only after the launch check has already counted it
+ * as opened, and init then waited out its whole connect budget over a correct install.
+ */
+const SYSTEM_BROWSER_GRACE_MS = 15_000;
 export const SetupPhase = {
     DEV_SERVER: 'dev-server',
     CONNECT: 'connect',
     DONE: 'done',
 };
+/** Hand a lease back. Best-effort: a lease that already expired is already gone. */
+async function releaseLease(lease) {
+    try {
+        await lease?.release();
+    }
+    catch {
+        /* nothing to undo */
+    }
+}
 const asProgress = (input, o) => ({
     initDone: true,
     devServerUp: undefined !== o.url,
@@ -89,6 +105,10 @@ async function daemonWhy(fx) {
 export async function runSetupPhases(input, fx) {
     const notes = [];
     const note = (line) => {
+        // The page is probed before the browser opens and again after the wait, and an unchanged page
+        // gave the reader the same paragraph twice in a row.
+        if (notes.at(-1) === line)
+            return;
         notes.push(line);
         fx.note(line);
     };
@@ -139,6 +159,7 @@ export async function runSetupPhases(input, fx) {
                     serving,
                     quietForMs: fx.devServerQuietForMs(),
                     elapsedMs: fx.now() - startedAt,
+                    budgetMs: input.startupBudgetMs,
                     quietMeansHungMs: WINDOWS_QUIET_MEANS_HUNG_MS_APPLIES
                         ? WINDOWS_QUIET_MEANS_HUNG_MS
                         : QUIET_MEANS_HUNG_MS,
@@ -164,8 +185,12 @@ export async function runSetupPhases(input, fx) {
                     // Says BOTH were checked. A server that prints nothing but IS listening is the CRA case and
                     // must not be failed, so a reader has to be able to tell "we looked at the log" from "we
                     // looked at the log AND the ports".
-                    note('The dev server neither printed a URL nor bound a port, so setup has nothing to open. ' +
-                        'Check its log, or pass --url with the address it serves.');
+                    note((input.startupBudgetMs !== undefined && fx.now() - startedAt >= input.startupBudgetMs
+                        ? `The dev server did not become ready within ${String(input.startupBudgetMs)}ms. `
+                        : undefined === watching
+                            ? 'The dev server neither printed a URL nor bound a port, so setup has nothing to open. '
+                            : `The dev server stopped making progress before ${watching} became ready. `) +
+                        'Check its log, increase --timeout for a slow build, or pass --url with the address it serves.');
                     return stop(input, SetupPhase.DEV_SERVER, {}, notes);
                 }
                 await fx.sleep(input.pollMs);
@@ -181,9 +206,13 @@ export async function runSetupPhases(input, fx) {
     const requiredRuntime = isDesktop(input.shape) ? input.shape : undefined;
     // A tab already on this URL is the answer. Opening another is how three sessions appear.
     // `before` is empty so pickSession will take that tab rather than waiting for a new one.
+    //
+    // Not only when attached: a server init started itself (Next, Angular — nothing announces) has a
+    // url too, and a live tab of this project already on it is just as much the answer. Without this
+    // every re-run opened one more tab.
     const alreadyConnected = attachedToExisting
         ? pickSession(listed, url, new Set(), requiredRuntime)
-        : null;
+        : liveSessionOfProject(listed, url, input.projectId, requiredRuntime);
     const before = new Set(listed.map((s) => s.sessionId));
     // Do not put a window in front of somebody until the page behind it can actually do something.
     //
@@ -198,7 +227,12 @@ export async function runSetupPhases(input, fx) {
     // proof that nothing can ever dial in.
     const budgetMs = input.connectBudgetMs ?? Math.max(input.phaseTimeoutMs, policy.connectBudgetMs);
     let openedBrowser = false;
-    if (null === alreadyConnected && input.openBrowser && policy.openBrowser) {
+    let lease;
+    // `--no-open` used to skip this whole block, so nothing was opened and the run ended on "never
+    // dialled the bridge" over a correct install. With a lease to fall back on it is entered too, and
+    // only the system browser is skipped.
+    const canLease = undefined !== fx.openLease;
+    if (null === alreadyConnected && policy.openBrowser && (input.openBrowser || canLease)) {
         // SERVED is the precondition, not SDK_PRESENT: a url that answers nothing is the only state
         // where a window is certainly useless. Whether the SDK is in the served HTML is a DIFFERENT
         // question — Vite injects a marker, while Nuxt, React Router, Astro, SvelteKit and CRA deliver
@@ -209,7 +243,7 @@ export async function runSetupPhases(input, fx) {
         //
         // So presence decides only WHEN: open the moment it appears (the fast path for the frameworks
         // that inline it), otherwise once the short readiness window is out.
-        const finding = await findingBeforeOpen(() => fx.probePage(url), { now: () => fx.now(), sleep: (ms) => fx.sleep(ms) }, Math.min(SDK_READY_WINDOW_MS, budgetMs), input.pollMs);
+        const finding = await findingBeforeOpen(() => fx.probePage(url), { now: () => fx.now(), sleep: (ms) => fx.sleep(ms) }, Math.min(SDK_READY_WINDOW_MS, budgetMs), input.pollMs, input.htmlCarriesSdk);
         if (PageFinding.NOT_SERVED === finding || PageFinding.TLS_REFUSED === finding) {
             note(describePage(finding, url));
             note('Not opening a browser: nothing answered that url, so the window could only show an error ' +
@@ -218,12 +252,23 @@ export async function runSetupPhases(input, fx) {
         else {
             // Said BEFORE the window appears, so somebody watching a page that stays inert has already
             // been told which of the two it is.
-            if (PageFinding.SDK_MISSING === finding)
+            if (PageFinding.SDK_MISSING === finding && input.htmlCarriesSdk) {
                 note(describePage(finding, url));
+            }
             // `= true` means ATTEMPTED, which is the most that is knowable — see openBrowser above for
             // why the launcher's own exit code must not be read as "no window appeared".
-            await fx.openBrowser(url);
-            openedBrowser = true;
+            const launcherFailed = input.openBrowser ? await fx.openBrowser(url) : undefined;
+            openedBrowser = input.openBrowser;
+            if (undefined !== fx.openLease && (!input.openBrowser || undefined !== launcherFailed)) {
+                const owned = await fx.openLease(url);
+                if ('failed' in owned) {
+                    note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
+                }
+                else {
+                    lease = owned;
+                    openedBrowser = true;
+                }
+            }
         }
     }
     // Waiting the full budget for a session when nothing was opened to create one is dead time, and
@@ -237,6 +282,9 @@ export async function runSetupPhases(input, fx) {
             ? budgetMs
             : Math.min(NO_BROWSER_GRACE_MS, budgetMs));
     let session = alreadyConnected;
+    const waitStartedAt = fx.now();
+    let connectSpokeAtMs;
+    let leaseFallbackTried = false;
     while (null === session) {
         // On a desktop app, only the desktop window counts. AppShape and the runtime a page reports use
         // the same three names, so the shape IS the requirement — see session-pick.
@@ -245,6 +293,32 @@ export async function runSetupPhases(input, fx) {
             break;
         if (deadline <= fx.now())
             break;
+        if (!leaseFallbackTried &&
+            undefined === lease &&
+            undefined !== fx.openLease &&
+            openedBrowser &&
+            input.openBrowser &&
+            !isDesktop(input.shape) &&
+            fx.now() - waitStartedAt >= SYSTEM_BROWSER_GRACE_MS) {
+            leaseFallbackTried = true;
+            const owned = await fx.openLease(url);
+            if ('failed' in owned) {
+                note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
+            }
+            else {
+                lease = owned;
+            }
+            continue;
+        }
+        // Not in silence: a desktop run used to print one line and then nothing for ten minutes.
+        const waitedMs = fx.now() - waitStartedAt;
+        const progress = connectProgressLine(waitedMs, connectSpokeAtMs, deadline - waitStartedAt, policy.awaiting);
+        if (undefined !== progress) {
+            // To the person only: it is progress, not a finding, and in `notes` it would split the
+            // page description printed before and after this wait into two copies.
+            fx.note(progress);
+            connectSpokeAtMs = waitedMs;
+        }
         await fx.sleep(input.pollMs);
     }
     if (null === session) {
@@ -275,8 +349,13 @@ export async function runSetupPhases(input, fx) {
                 fx.note(why.lead);
                 notes.push(why.full ?? why.lead);
             }
-            note(describePage(readPage(await fx.probePage(url)), url));
+            const finding = readPage(await fx.probePage(url));
+            // Silent on a bundle-connect shape: its HTML never carries the SDK, so the absence says nothing.
+            if (PageFinding.SDK_MISSING !== finding || input.htmlCarriesSdk) {
+                note(describePage(finding, url, undefined !== why));
+            }
         }
+        await releaseLease(lease);
         return stop(input, SetupPhase.CONNECT, { url }, notes);
     }
     // ── connected, which is where ONBOARDING ends ────────────────────────────────────────────────
@@ -292,16 +371,25 @@ export async function runSetupPhases(input, fx) {
     // Both routes, because `explore` needs a model: without ANTHROPIC_API_KEY it answers "No model
     // configured to drive the app". Naming only that one hands the reader a dead end on any machine
     // without a key, which is the same defect this release spent its time removing everywhere else.
-    // Three short lines rather than one paragraph, and each says who it is for.
+    // A heading and a numbered list rather than one paragraph: a reader scans for what to do next.
     //
     // This was a single 524-character note, measured on a real first run: eighty-three words, no
     // break, naming `reticle_*` tools at a reader who had just typed `reticle init` in a terminal and
     // has no such tools to call. The facts were right and the shape made them unreadable, which on
     // the last line of onboarding is the same as not saying them.
-    note(`Connected. ${url} is instrumented. Onboarding is done; nothing is verified yet.`);
-    note('Agent: drive one flow and end it with `reticle_act_and_wait` or `reticle_assert`. Those two ' +
+    note(`✓ Connected. ${url} is instrumented. Onboarding is done; nothing is verified yet.`);
+    // Said, because "connected" otherwise reads as "your browser connected": the page that dialled
+    // was a headless one Reticle launched and has now closed, and nothing is open on this screen.
+    if (undefined !== lease && session.sessionId === lease.sessionId) {
+        note('The proof came from a Reticle-owned headless browser (now closed), not a window of yours — ' +
+            `open ${url} in your own browser to use the app.`);
+    }
+    await releaseLease(lease);
+    note('');
+    note('Next, prove one flow. Your agent does this:');
+    note('  1. Drive one flow and end it with `reticle_act_and_wait` or `reticle_assert`. Those two ' +
         'produce a verdict; nothing else does.');
-    note('Or hand over the whole drive: `reticle_verify { action: "explore", persona: "<who does ' +
+    note('  2. Or hand over the whole drive: `reticle_verify { action: "explore", persona: "<who does ' +
         'what>" }` records what it drove, so later runs replay with no model in the loop. Needs ' +
         'ANTHROPIC_API_KEY.');
     return {

package/dist/command/setup/session-pick.d.ts

@@ -21,7 +21,20 @@ export interface CandidateSession {
     readonly hasCapabilities?: boolean;
     /** Which shell answered. Absent on an SDK too old to report one — see requiredRuntime below. */
     readonly runtime?: string;
+    /** The project the page reported. Absent on an SDK too old to report one. */
+    readonly projectId?: string;
 }
+/**
+ * A tab of THIS project on `url` that is demonstrably alive right now, or null.
+ *
+ * Stricter than `pickSession`, because it decides whether to open a window at all: every init run
+ * opened another tab even when this project already had a live one on the url, and the pile-up then
+ * made every tool called without a sessionId fail with "multiple sessions connected". Reused only on
+ * positive evidence — the page names this project, is visible, and was heard from inside the
+ * daemon's staleness threshold — because reusing a dead tab is the worse mistake: nothing opens and
+ * nothing connects.
+ */
+export declare function liveSessionOfProject(sessions: readonly CandidateSession[], url: string, projectId: string | undefined, requiredRuntime?: string): CandidateSession | null;
 /**
  * The session to drive, or null when nothing on this url qualifies.
  *

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

@@ -10,9 +10,29 @@
  *   the oldest: a tab whose dev server died yesterday. The HUD then plays to a window nobody is
  *   watching, and the verdict describes a page the user cannot see.
  */
+import { SESSION_HEALTH } from '@reticlehq/core';
 /** Sorts a hidden tab after a visible one; among equals, the least stale first. */
 const isLive = (s) => true !== s.hidden && true !== s.throttled;
 const staleness = (s) => s.lastSeenMs ?? Number.POSITIVE_INFINITY;
+/**
+ * A tab of THIS project on `url` that is demonstrably alive right now, or null.
+ *
+ * Stricter than `pickSession`, because it decides whether to open a window at all: every init run
+ * opened another tab even when this project already had a live one on the url, and the pile-up then
+ * made every tool called without a sessionId fail with "multiple sessions connected". Reused only on
+ * positive evidence — the page names this project, is visible, and was heard from inside the
+ * daemon's staleness threshold — because reusing a dead tab is the worse mistake: nothing opens and
+ * nothing connects.
+ */
+export function liveSessionOfProject(sessions, url, projectId, requiredRuntime) {
+    if (undefined === projectId || 0 === projectId.length)
+        return null;
+    const mine = sessions.filter((s) => projectId === s.projectId &&
+        true !== s.hidden &&
+        undefined !== s.lastSeenMs &&
+        s.lastSeenMs <= SESSION_HEALTH.STALE_THRESHOLD_MS);
+    return pickSession(mine, url, new Set(), requiredRuntime);
+}
 /**
  * The session to drive, or null when nothing on this url qualifies.
  *

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

@@ -27,22 +27,10 @@ interface SetupCommandInput extends Omit<SetupInput, 'shape'> {
     readonly env: Readonly<Record<string, string>>;
     /** Register the MCP server with the coding agents init does not itself reach. */
     readonly registerAgents: boolean;
+    /** The bridge's pairing token, for the MCP transport a connect-proof lease is opened over. */
+    readonly pairingToken?: string | undefined;
 }
-/**
- * Register with the agents `init` does not reach, and leave the skill where one loads skills from.
- *
- * init covers eight clients and only where it finds them installed, which leaves VS Code's USER
- * scope unwritten — it exists on machines today, and init only ever writes the project-scope file,
- * so a VS Code user has no tools outside the directory they ran init in.
- */
 export declare function registerOtherAgents(print: (line: string) => void): void;
 type SetupCommandResult = SetupOutcome;
-/**
- * Run the phases against the real world.
- *
- * The dev server is stopped on every ending except success, where it is handed to the user: an
- * instrumented app they can watch is the deliverable, and killing it would leave them with config
- * files and a dead tab.
- */
 export declare function runSetupCommand(input: SetupCommandInput, print: (line: string) => void): Promise<SetupCommandResult>;
 export {};

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

@@ -9,22 +9,25 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { planAgentConfigs } from './agent-configs.js';
-import { AppShape, readShape } from './desktop-shape.js';
+import { AppShape, describeShape, readShape } from './desktop-shape.js';
 import { stopOnInterrupt } from './terminal/interrupt.js';
 import { stopOnCrash, crashSentence } from './terminal/crash.js';
 import { applyAgentPlan, applyAgentSkills } from './agent-writer.js';
 import { ApprovalOutcome, grantAutoApproval } from './auto-approve.js';
 import { agentIo } from './agent-io.js';
-import { EnsureDaemon, ensureDaemon, nodeEnsureDaemonDeps } from './bringup/ensure-daemon.js';
+import { EnsureDaemon, ensureDaemon, holdDaemon, nodeEnsureDaemonDeps, nodeRetireDeps, retireMovedDaemons, } from './bringup/ensure-daemon.js';
 import { openInBrowser } from '../cli/launch/cli-launch.js';
+import { openLeaseFor } from './bringup/connect-lease.js';
 import { readProjectId } from '../cli/ports/resolve/cli-port.js';
-import { reticleStateHome } from '../daemon/daemon.js';
+import { spawnSync } from 'node:child_process';
+import { isAlive, reticleStateHome } from '../daemon/daemon.js';
 import { readDevServers } from '../daemon/dev-servers.js';
 import { urlOfExistingApp } from './probe/existing-app.js';
+import { handedOverUrl, stopHandedOver } from './bringup/dev-server-files.js';
 import { listSessions, OwnedDevServer, probePage } from './node-effects.js';
 import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
-import { summarizeStatus } from '../cli/launch/cli-launch.js';
-import { runSetupPhases, } from './run-setup.js';
+import { daemonSkew, summarizeStatus } from '../cli/launch/cli-launch.js';
+import { runSetupPhases, SetupPhase, } from './run-setup.js';
 import { noticeKey, readSaid, rememberSaid, unsaidNotices } from './agent-notice-memory.js';
 /**
  * The dev server a crash should take with it, if one is running right now.
@@ -84,13 +87,15 @@ function hasElectronDependency(dir) {
  * scope unwritten — it exists on machines today, and init only ever writes the project-scope file,
  * so a VS Code user has no tools outside the directory they ran init in.
  */
+/** `agent`, `agents`. */
+const agentWord = (n) => (1 === n ? 'agent' : 'agents');
 export function registerOtherAgents(print) {
     const platform = process.platform;
     const home = homedir();
     const results = applyAgentPlan(planAgentConfigs({ home, platform, exists: agentIo.exists, readFile: agentIo.readFile }), agentIo);
     const wrote = results.filter((r) => 'created' === r.action || 'merged' === r.action);
     if (0 < wrote.length) {
-        print(`registered the MCP server with ${wrote.length} more agent(s): ${wrote.map((r) => r.name).join(', ')}`);
+        print(`  ✓ ${String(wrote.length)} more ${agentWord(wrote.length)}: ${wrote.map((r) => r.name).join(', ')}`);
     }
     // A format we will not rewrite is somebody's to edit, so it has to be said rather than skipped --
     // but said ONCE. Two commands call this function by design, so a `curl | sh` followed by
@@ -103,21 +108,21 @@ export function registerOtherAgents(print) {
         .map((r) => ({ name: r.name, file: r.file, why: r.why }));
     const fresh = unsaidNotices(readSaid(stateHome), manual);
     for (const notice of fresh) {
-        print(`${notice.name}: ${notice.why} — add the reticle entry to ${notice.file} by hand.`);
+        print(`  ⚠ ${notice.name}: ${notice.why} — add the reticle entry to ${notice.file} by hand.`);
     }
     rememberSaid(stateHome, fresh.map((n) => noticeKey(n)));
     const skills = applyAgentSkills(agentIo, { home, platform });
     if (0 < skills.length)
-        print(`wrote the /reticle skill for ${skills.length} agent(s)`);
+        print(`  ✓ the /reticle skill, for ${String(skills.length)} ${agentWord(skills.length)}`);
     // Registration alone still leaves an Accept dialog in front of every call, and a verification run
     // makes dozens of them: the loop is only autonomous once the tools are pre-approved.
     const approvals = grantAutoApproval(agentIo, { home, platform });
     const granted = approvals.filter((a) => ApprovalOutcome.GRANTED === a.outcome);
     if (0 < granted.length) {
-        print(`pre-approved the reticle tools in ${granted.map((a) => a.name).join(', ')} — no Accept prompt per call`);
+        print(`  ✓ tools pre-approved in ${granted.map((a) => a.name).join(', ')}, so no Accept prompt per call`);
     }
     for (const noted of approvals.filter((a) => undefined !== a.warn)) {
-        print(`${noted.name}: ${String(noted.warn)}`);
+        print(`  ⚠ ${noted.name}: ${String(noted.warn)}`);
     }
 }
 /**
@@ -127,13 +132,70 @@ export function registerOtherAgents(print) {
  * instrumented app they can watch is the deliverable, and killing it would leave them with config
  * files and a dead tab.
  */
+/** How long a stopped dev server gets to let go of its port before the new one is started. */
+const HANDED_OVER_EXIT_MS = 10_000;
+const HANDED_OVER_EXIT_POLL_MS = 100;
+/** Stop the server a previous init handed over for `appDir`, and wait (bounded) for it to exit. */
+async function restartHandedOverServer(appDir) {
+    let stoppedPid;
+    const stopped = stopHandedOver(reticleStateHome(), appDir, {
+        alive: isAlive,
+        kill: (pid) => {
+            stoppedPid = pid;
+            try {
+                // Its own process group (it was spawned detached), so what it started goes with it.
+                if ('win32' === process.platform) {
+                    spawnSync('taskkill', ['/PID', String(pid), '/T', '/F']);
+                }
+                else {
+                    process.kill(-pid, 'SIGTERM');
+                }
+            }
+            catch {
+                /* already gone */
+            }
+        },
+    });
+    const deadline = Date.now() + HANDED_OVER_EXIT_MS;
+    while (undefined !== stoppedPid && isAlive(stoppedPid) && Date.now() < deadline) {
+        await new Promise((done) => setTimeout(done, HANDED_OVER_EXIT_POLL_MS));
+    }
+    return stopped;
+}
 export async function runSetupCommand(input, print) {
     if (input.registerAgents)
         registerOtherAgents(print);
+    // A moved port first: this project's daemon on the OLD port would otherwise be the one the page
+    // finds and dials, while everything below waits on the new one.
+    const retired = await retireMovedDaemons(readProjectId(input.appDir), input.bridgePort, nodeRetireDeps());
+    for (const port of retired) {
+        print(`stopped this project's Reticle daemon on port ${String(port)}: the project now uses ` +
+            `${String(input.bridgePort)}, and the page would have kept dialling the old one.`);
+    }
+    // And the dev server a previous init left running, which may have read the old port once at
+    // startup (Next does) — so the attach below would keep a page dialling the daemon just stopped.
+    if (0 < retired.length && (await restartHandedOverServer(input.appDir))) {
+        print(`stopped the dev server a previous init started, so it restarts on port ${String(input.bridgePort)}.`);
+    }
     // Before the app is booted, because the app's whole job from here is to dial this port. Without
     // it the phases wait out their budget and then report the SDK as the thing that failed.
-    const daemon = await ensureDaemon(input.bridgePort, nodeEnsureDaemonDeps());
-    if (EnsureDaemon.UNAVAILABLE === daemon) {
+    const daemon = await ensureDaemon(input.bridgePort, nodeEnsureDaemonDeps((status) => undefined !== daemonSkew(status)));
+    if (undefined !== daemon.message)
+        print(daemon.message);
+    if (EnsureDaemon.SKEWED_IN_USE === daemon.state) {
+        // Stop here: every hello from the page would be refused, and waiting out the connect budget
+        // only to blame the page is the run this exists to prevent.
+        return {
+            ok: false,
+            reachedPhase: SetupPhase.DEV_SERVER,
+            flowSaved: false,
+            notes: undefined === daemon.message ? [] : [daemon.message],
+            fallback: [
+                `Once those sessions are done, free the port with \`npx @reticlehq/server kill --port ${String(input.bridgePort)}\` and re-run init.`,
+            ],
+        };
+    }
+    if (EnsureDaemon.UNAVAILABLE === daemon.state) {
         print(`could not start the Reticle daemon on port ${String(input.bridgePort)}, so nothing is listening for the app to connect to. Run \`npx @reticlehq/server serve --port ${String(input.bridgePort)}\` and try again.`);
     }
     // Which shell this is decides three things the phases would otherwise get wrong: opening a
@@ -145,7 +207,7 @@ export async function runSetupCommand(input, print) {
         hasElectronDep: hasElectronDependency(input.appDir),
     });
     if (AppShape.WEB !== shape)
-        print(`detected a ${shape} app`);
+        print(`detected ${describeShape(shape)}`);
     const server = new OwnedDevServer();
     const effects = {
         startDevServer: (command, cwd) => {
@@ -153,10 +215,16 @@ export async function runSetupCommand(input, print) {
             server.start(command, cwd, input.env);
             return Promise.resolve();
         },
-        existingAppUrl: () => Promise.resolve(urlOfExistingApp(readDevServers(reticleStateHome()), {
+        // The server the plugin announced (Vite), or failing that the one a previous init handed over
+        // and recorded — the only way to know a Next or Angular server on the port is this project's own.
+        existingAppUrl: async () => urlOfExistingApp(readDevServers(reticleStateHome()), {
             projectId: readProjectId(input.appDir),
             root: input.appDir,
-        })),
+        }) ??
+            (await handedOverUrl(reticleStateHome(), input.appDir, {
+                alive: isAlive,
+                answers: async (url) => (await probePage(url)).served,
+            })),
         devServerOutput: () => server.output(),
         devServerExited: () => server.exited(),
         devServerQuietForMs: () => server.quietForMs(),
@@ -164,20 +232,16 @@ export async function runSetupCommand(input, print) {
         probePage,
         openBrowser: async (url) => {
             const failure = await openInBrowser(url);
-            if (null !== failure) {
-                print(`could not open a browser (${failure}). Nothing was opened, and nothing else here will ` +
-                    // Three wordings have been wrong in a row, each naming a way out that does not exist on
-                    // the machine being spoken to. It said `reticle_run({ tool: "reticle_lease", ... })`:
-                    // the default surface advertises neither name and ships no hatch to reach the second.
-                    // It then said `reticle open <url>`, which asks the OS to launch the default browser --
-                    // the very thing that just failed -- so it returned the reader to the same wall.
-                    // This one names no command: the missing piece is a browser, and the honest sentence
-                    // says which url needs one rather than inventing a Reticle that can conjure it.
-                    `open one: this asks the OS for your default browser, and it is a machine with none — ` +
-                    `CI, a container, an SSH session, WSL with no host browser. Point any browser that can ` +
-                    `reach it at ${url}; the session appears within a second of the page loading.`);
-            }
+            if (null === failure)
+                return undefined;
+            // It used to end "nothing else here will open one", which stopped being true once a
+            // Reticle-owned browser could always launch: run-setup opens a lease on this failure, so the
+            // reader is told what happens next rather than sent to find a browser by hand.
+            print(`could not open a browser (${failure}), so the connect proof will come from a ` +
+                `Reticle-owned headless browser instead. To use the app yourself, point any browser at ${url}.`);
+            return failure;
         },
+        openLease: (url) => openLeaseFor(input.bridgePort, url, input.pairingToken),
         listSessions: () => listSessions(input.bridgePort),
         // `summarizeStatus` already narrows this payload for `reticle status`; reusing it here keeps one
         // reader of the wire shape rather than two that can disagree about which key carries the reason.
@@ -207,16 +271,26 @@ export async function runSetupCommand(input, print) {
     activeDevServerStop = () => {
         server.stop();
     };
+    // Hold the daemon for as long as this run waits on it. Its idle rule counted none of this as
+    // activity, and on a slow desktop build the daemon init had just started idled out mid-wait.
+    const releaseDaemon = holdDaemon(input.bridgePort);
     try {
-        const outcome = await runSetupPhases({ ...input, shape }, effects);
+        const outcome = await runSetupPhases({ ...input, shape, projectId: readProjectId(input.appDir) }, effects);
         // The app stays up only when there is something worth watching.
-        if (outcome.ok)
-            server.handOver();
+        if (outcome.ok) {
+            server.handOver(outcome.url);
+            // Its output is on a file now, not this terminal, so say where: a compile error that used to
+            // scroll past here is the first thing somebody will look for.
+            const log = server.logPath();
+            if (undefined !== log)
+                print(`The dev server keeps running; its output goes to ${log}`);
+        }
         return {
             ...outcome,
         };
     }
     finally {
+        releaseDaemon();
         releaseSignals();
         activeDevServerStop = null;
         server.stop();

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

@@ -32,6 +32,8 @@ export interface SetupMcpResult {
     readonly detected: readonly string[];
     readonly registered: readonly string[];
     readonly alreadyThere: readonly string[];
+    /** Automatic registration was attempted but failed. */
+    readonly failed: readonly string[];
     /**
      * Clients whose config this will NOT rewrite, and which therefore still need a human.
      *

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

@@ -1,9 +1,10 @@
-import { McpClient, MCP_CLIENTS, claudeAddCommand, claudeAvailableProbe, claudeExistsProbe, detectMcpClients, mergeClientConfig, clientSpec, ClientMergeStatus, } from '@reticlehq/init';
+import { McpClient, MCP_CLIENTS, claudeAddCommand, claudeAvailableProbe, claudeHasReticle, detectMcpClients, mergeClientConfig, clientSpec, ClientMergeStatus, } from '@reticlehq/init';
 import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
 export function setupMcp(io) {
     const detected = [];
     const registered = [];
     const alreadyThere = [];
+    const failed = [];
     const manual = [];
     /*
      * Claude Code first, because nothing else can find it.
@@ -22,14 +23,16 @@ export function setupMcp(io) {
     const available = claudeAvailableProbe();
     if (io.runCli(available.command, available.args)) {
         detected.push(McpClient.CLAUDE_CODE);
-        const already = claudeExistsProbe();
-        if (io.runCli(already.command, already.args)) {
+        // Read from Claude's config: `claude mcp get` health-checks by launching the server.
+        if (claudeHasReticle(io, undefined)) {
             alreadyThere.push(McpClient.CLAUDE_CODE);
         }
         else {
             const cmd = claudeAddCommand();
             if (io.runCli(cmd.command, cmd.args))
                 registered.push(McpClient.CLAUDE_CODE);
+            else
+                failed.push(McpClient.CLAUDE_CODE);
         }
     }
     for (const client of detectMcpClients(io)) {
@@ -47,8 +50,13 @@ export function setupMcp(io) {
             manual.push({ id: client.id, configPath: client.configPath, docs: spec.docs });
             continue;
         }
-        io.writeFile(client.configPath, merged.content);
-        registered.push(client.id);
+        try {
+            io.writeFile(client.configPath, merged.content);
+            registered.push(client.id);
+        }
+        catch {
+            failed.push(client.id);
+        }
     }
     /*
      * Both INSTALL steps, reported from the one place that knows the answer.
@@ -69,7 +77,8 @@ export function setupMcp(io) {
          * SKIPPED when there was nothing to register with — not failed. Nothing went wrong; there was
          * simply no agent here, and counting that as our failure would hide the ones that are.
          *
-         * FAILED when every client we found needs a hand. That case used to fall through to COMPLETED,
+         * FAILED when no detected client is usable, whether registration failed or needs a hand.
+         * That case used to fall through to COMPLETED,
          * so the cohort with the tools registered NOWHERE was counted among the successful installs, and
          * the one number that says "did this machine get Reticle" read yes for the people it read no
          * for. Registering some and not others is still COMPLETED: the agent they are using may well be
@@ -79,11 +88,11 @@ export function setupMcp(io) {
             ? OnboardingStepStatus.SKIPPED
             : 0 === registered.length && alreadyThere.length > 0
                 ? OnboardingStepStatus.SKIPPED
-                : 0 === registered.length && 0 === alreadyThere.length && manual.length > 0
+                : 0 === registered.length && 0 === alreadyThere.length
                     ? OnboardingStepStatus.FAILED
                     : OnboardingStepStatus.COMPLETED,
     });
-    return { detected, registered, alreadyThere, manual };
+    return { detected, registered, alreadyThere, failed, manual };
 }
 /** Everything this machine could be asked about, for the report when nothing was found. */
 export function knownClientLabels() {

package/dist/command/setup/terminal/wait-progress.d.ts

@@ -26,3 +26,11 @@ export declare const WAIT_PROGRESS_EVERY_MS = 15000;
  * without a line per poll burying the output it exists to explain.
  */
 export declare function waitProgressLine(elapsedMs: number, watching: string | undefined, lastSpokeAtMs: number | undefined): string | undefined;
+/**
+ * The same, for the wait on a session after the app is up.
+ *
+ * That wait was silent as well: a desktop init printed "Waiting for the app to launch and dial in."
+ * and then nothing for the whole of its budget. Naming what is awaited and how long remains is what
+ * lets somebody tell a slow start from a wedged one — and when to stop waiting themselves.
+ */
+export declare function connectProgressLine(elapsedMs: number, lastSpokeAtMs: number | undefined, budgetMs: number, awaiting: string): string | undefined;