@reticlehq/server 3.8.2 → 3.9.0

package/dist/command/cli/first-verdict.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Bare `reticle` in a folder that Reticle has not wired: the first verdict, with no agent, no
+ * `init` and no model.
+ *
+ * It finds the app (the folder's own dev server, or the one dev server that runs on this computer),
+ * starts the dev server when it does not run, opens the page in a Reticle browser with the
+ * zero-install reader, and runs a smoke check that cannot guess: the page loads, no console error,
+ * no failed request, and each same-origin link opens. Then it prints the verdict and the next step.
+ *
+ * The decisions are here, behind `FirstVerdictPorts`, so each one is a unit test. The browser, the
+ * daemon and the dev server are in `first-verdict-node.ts`.
+ */
+import { type ReticleEvent } from '@reticlehq/core';
+import { OnboardingStop } from '@reticlehq/core/telemetry';
+/** Bare `reticle` runs the first verdict only with no arguments, in a folder with no Reticle config. */
+export declare function bareRunsFirstVerdict(argv: readonly string[], wired: boolean): boolean;
+export declare const AppChoice: {
+    /** Check this url. */
+    readonly USE: "use";
+    /** Start the folder's dev command, then check what it serves. */
+    readonly START: "start";
+    /** Nothing to check: say why. */
+    readonly NONE: "none";
+};
+export type AppDecision = {
+    action: typeof AppChoice.USE;
+    url: string;
+} | {
+    action: typeof AppChoice.START;
+} | {
+    action: typeof AppChoice.NONE;
+    lines: string[];
+    stop: OnboardingStop;
+};
+export declare const MSG_NO_APP: string[];
+/**
+ * Which app to check. In an app folder, only that app: a server on another port can be another
+ * app, and a verdict on the wrong app is worse than none. Outside one, the one server that runs.
+ */
+export declare function chooseApp(facts: {
+    /** The folder's dev command, when the folder holds a web app. */
+    devCommand?: {
+        port?: number;
+    };
+    /** The dev command pins a port, and that port serves a page now. */
+    pinnedServing: boolean;
+    /** Dev-server ports that serve a page now, outside Reticle's own. */
+    running: readonly number[];
+}): AppDecision;
+/** What one page did, read from its own document's events. */
+export interface PageFacts {
+    /** The url the check opened. */
+    url: string;
+    /** The page came back with Reticle connected, at the url asked for. */
+    arrived: boolean;
+    /** Where the page went instead, when it went somewhere else. */
+    landedOn?: string;
+    /** The HTTP status of the document, when the browser reported one. */
+    documentStatus?: number;
+    consoleErrors: string[];
+    failedRequests: string[];
+}
+/**
+ * The facts of the page now on screen. Events of an earlier document are left out: the check
+ * reloads each page, and what the old document did is not this page's fault.
+ */
+export declare function pageFactsOf(url: string, events: readonly ReticleEvent[], nav: {
+    arrived: boolean;
+    landedOn?: string;
+}): PageFacts;
+/** The most links one check opens. Each one is a page load. */
+export declare const MAX_LINKS_OPENED = 8;
+/**
+ * The same-origin pages the links on `pageUrl` lead to, once each, without the page itself and
+ * without a link that ends the session. `found` counts them all, so a capped list says so.
+ */
+export declare function linksToOpen(pageUrl: string, links: readonly {
+    name: string;
+    href: string;
+}[], max?: number): {
+    open: string[];
+    found: number;
+};
+/** What the smoke check saw: the start page, and each link it opened. */
+export interface SmokeFacts {
+    start: PageFacts;
+    links: PageFacts[];
+    /** Same-origin links found on the start page. More than `links` when the check opened fewer. */
+    linksFound: number;
+}
+export interface SmokeVerdict {
+    verified: 'yes' | 'no';
+    lines: string[];
+}
+/**
+ * The verdict. "yes" only when the start page loaded with no console error and no failed request,
+ * and every link it opened did the same. A page that sends a visitor to sign in is a verdict too:
+ * the check is "yes" up to there, and it says what it could not reach.
+ */
+export declare function judgeSmoke(facts: SmokeFacts): SmokeVerdict;
+/** The app to check, or why there is none. `release` stops a dev server this run started. */
+export type FoundApp = {
+    url: string;
+    release?: () => void;
+} | {
+    lines: string[];
+    stop: OnboardingStop;
+};
+export interface FirstVerdictPorts {
+    findApp: () => Promise<FoundApp>;
+    /** Open the page with the zero-install reader and collect the facts, or say why it could not. */
+    smoke: (url: string) => Promise<SmokeFacts | {
+        failed: string[];
+    }>;
+    out: (line: string) => void;
+    /** Record one onboarding stop. */
+    stop: (row: {
+        step: string;
+        stop: OnboardingStop;
+    }) => void;
+}
+export declare const MSG_NEXT_STEP: string[];
+/** Find the app, check it, print the verdict. Returns the exit code: 0 only for "verified: yes". */
+export declare function runFirstVerdict(ports: FirstVerdictPorts): Promise<number>;
+/** The `reason` on a stop this command records, so a reader can tell it from an `init` stop. */
+export declare const FIRST_VERDICT_REASON = "first_verdict";

package/dist/command/cli/first-verdict.js

@@ -0,0 +1,267 @@
+/**
+ * Bare `reticle` in a folder that Reticle has not wired: the first verdict, with no agent, no
+ * `init` and no model.
+ *
+ * It finds the app (the folder's own dev server, or the one dev server that runs on this computer),
+ * starts the dev server when it does not run, opens the page in a Reticle browser with the
+ * zero-install reader, and runs a smoke check that cannot guess: the page loads, no console error,
+ * no failed request, and each same-origin link opens. Then it prints the verdict and the next step.
+ *
+ * The decisions are here, behind `FirstVerdictPorts`, so each one is a unit test. The browser, the
+ * daemon and the dev server are in `first-verdict-node.ts`.
+ */
+import { CRAWL_DEFAULTS, EventType, NetInitiator } from '@reticlehq/core';
+import { OnboardingStop } from '@reticlehq/core/telemetry';
+import { isAuthPath } from '../../surface/tools/lease-seed.js';
+/** Bare `reticle` runs the first verdict only with no arguments, in a folder with no Reticle config. */
+export function bareRunsFirstVerdict(argv, wired) {
+    return 0 === argv.length && !wired;
+}
+const LOCALHOST = 'http://localhost';
+const localUrl = (port) => `${LOCALHOST}:${String(port)}`;
+export const AppChoice = {
+    /** Check this url. */
+    USE: 'use',
+    /** Start the folder's dev command, then check what it serves. */
+    START: 'start',
+    /** Nothing to check: say why. */
+    NONE: 'none',
+};
+export const MSG_NO_APP = [
+    'Reticle found no web app here, and no dev server that runs on this computer.',
+    'Run this command in the folder of your web app, or start its dev server first.',
+];
+/**
+ * Which app to check. In an app folder, only that app: a server on another port can be another
+ * app, and a verdict on the wrong app is worse than none. Outside one, the one server that runs.
+ */
+export function chooseApp(facts) {
+    if (facts.devCommand !== undefined) {
+        const pinned = facts.devCommand.port;
+        if (pinned !== undefined && facts.pinnedServing) {
+            return { action: AppChoice.USE, url: localUrl(pinned) };
+        }
+        return { action: AppChoice.START };
+    }
+    const [only, ...others] = facts.running;
+    if (only !== undefined && 0 === others.length) {
+        return { action: AppChoice.USE, url: localUrl(only) };
+    }
+    if (only !== undefined) {
+        return {
+            action: AppChoice.NONE,
+            stop: OnboardingStop.NO_WEB_APP,
+            lines: [
+                'Reticle found more than one dev server, so it did not choose one:',
+                ...facts.running.map((port) => `  ${localUrl(port)}`),
+                'Run this command in the folder of the app to check.',
+            ],
+        };
+    }
+    return { action: AppChoice.NONE, stop: OnboardingStop.NO_WEB_APP, lines: MSG_NO_APP };
+}
+const ABORTED = /abort/i;
+const text = (value) => 'string' === typeof value ? value : undefined;
+const num = (value) => ('number' === typeof value ? value : undefined);
+/** A request that failed: an error status, or no answer that the page did not cancel itself. */
+function failure(e) {
+    if (EventType.NET_REQUEST !== e.type || NetInitiator.DOCUMENT === e.data['initiator']) {
+        return undefined;
+    }
+    const where = `${text(e.data['method']) ?? 'GET'} ${text(e.data['url']) ?? ''}`;
+    const status = num(e.data['status']);
+    if (status !== undefined && status >= CRAWL_DEFAULTS.FAILED_STATUS) {
+        return `${where}: HTTP ${String(status)}`;
+    }
+    const error = text(e.data['error']);
+    if (0 === status && error !== undefined && !ABORTED.test(error)) {
+        return `${where}: ${error}`;
+    }
+    return undefined;
+}
+/**
+ * The facts of the page now on screen. Events of an earlier document are left out: the check
+ * reloads each page, and what the old document did is not this page's fault.
+ */
+export function pageFactsOf(url, events, nav) {
+    const loads = events.filter((e) => EventType.NET_REQUEST === e.type && NetInitiator.DOCUMENT === e.data['initiator']);
+    const load = loads.at(-1);
+    const documentId = load?.documentId ?? events.at(-1)?.documentId;
+    const current = events.filter((e) => documentId === undefined || e.documentId === undefined || e.documentId === documentId);
+    const documentStatus = num(load?.data['status']);
+    return {
+        url,
+        arrived: nav.arrived,
+        ...(nav.landedOn === undefined ? {} : { landedOn: nav.landedOn }),
+        ...(documentStatus === undefined ? {} : { documentStatus }),
+        consoleErrors: current
+            .filter((e) => EventType.CONSOLE_ERROR === e.type || EventType.ERROR_UNCAUGHT === e.type)
+            .map((e) => text(e.data['message']) ?? e.type),
+        failedRequests: current.flatMap((e) => {
+            const failed = failure(e);
+            return failed === undefined ? [] : [failed];
+        }),
+    };
+}
+/**
+ * A link that ends the signed-in session. Opening it would check the rest of the app signed out.
+ * ponytail: the same words the crawl leaves alone; `cli` does not reach `crawl`, so it is said here.
+ */
+const ENDS_SESSION = /\b(?:sign ?out|log ?out|sign ?off|log ?off)\b/i;
+/** The most links one check opens. Each one is a page load. */
+export const MAX_LINKS_OPENED = 8;
+const WEB_PROTOCOLS = new Set(['http:', 'https:']);
+/**
+ * The same-origin pages the links on `pageUrl` lead to, once each, without the page itself and
+ * without a link that ends the session. `found` counts them all, so a capped list says so.
+ */
+export function linksToOpen(pageUrl, links, max = MAX_LINKS_OPENED) {
+    const here = new URL(pageUrl);
+    const key = (u) => `${u.pathname.replace(/\/+$/, '')}${u.search}`;
+    const seen = new Set([key(here)]);
+    const pages = [];
+    for (const link of links) {
+        let target;
+        try {
+            target = new URL(link.href, here);
+        }
+        catch {
+            continue;
+        }
+        if (!WEB_PROTOCOLS.has(target.protocol) || target.origin !== here.origin) {
+            continue;
+        }
+        if (ENDS_SESSION.test(link.name) || ENDS_SESSION.test(target.pathname.replace(/[/-]/g, ' '))) {
+            continue;
+        }
+        if (seen.has(key(target))) {
+            continue;
+        }
+        seen.add(key(target));
+        target.hash = '';
+        pages.push(target.href);
+    }
+    return { open: pages.slice(0, max), found: pages.length };
+}
+const PASS = '  ✓';
+const FAIL = '  ✗';
+const NOTE = '  -';
+const pathOf = (url) => {
+    try {
+        const u = new URL(url);
+        return `${u.pathname}${u.search}`;
+    }
+    catch {
+        return url;
+    }
+};
+/** Why a page did not load, or undefined when it loaded. */
+function notLoaded(page) {
+    // A page that went somewhere else (a redirect to a dashboard, or to sign in) did open.
+    if (!page.arrived && page.landedOn === undefined) {
+        return 'it did not load, or Reticle could not connect to it';
+    }
+    if (page.documentStatus !== undefined && page.documentStatus >= CRAWL_DEFAULTS.FAILED_STATUS) {
+        return `the server answered HTTP ${String(page.documentStatus)}`;
+    }
+    return undefined;
+}
+/** The faults of one page, one line each. */
+function faultsOf(page, label) {
+    const missed = notLoaded(page);
+    return [
+        ...(missed === undefined ? [] : [`${FAIL} ${label} did not open: ${missed}.`]),
+        ...page.consoleErrors.map((message) => `${FAIL} Console error on ${label}: ${message}`),
+        ...page.failedRequests.map((request) => `${FAIL} Failed request on ${label}: ${request}`),
+    ];
+}
+/**
+ * The verdict. "yes" only when the start page loaded with no console error and no failed request,
+ * and every link it opened did the same. A page that sends a visitor to sign in is a verdict too:
+ * the check is "yes" up to there, and it says what it could not reach.
+ */
+export function judgeSmoke(facts) {
+    const start = facts.start;
+    const landed = start.landedOn === undefined ? undefined : new URL(start.landedOn);
+    const signIn = landed !== undefined && isAuthPath(landed.pathname) && !isAuthPath(new URL(start.url).pathname);
+    const faults = [
+        ...faultsOf(start, pathOf(start.url)),
+        ...facts.links.flatMap((link) => faultsOf(link, pathOf(link.url))),
+    ];
+    const lines = [];
+    if (signIn && landed !== undefined) {
+        lines.push(`${NOTE} The app sent the page to its sign-in page (${landed.pathname}). ` +
+            'Reticle verified up to here. It did not check the pages behind sign-in.');
+    }
+    const linksOk = facts.links.filter((link) => 0 === faultsOf(link, '').length).length;
+    if (0 === faults.length) {
+        lines.push(`${PASS} The page loads.`, `${PASS} No console error.`, `${PASS} No failed request.`);
+    }
+    lines.push(...faults);
+    if (0 === facts.linksFound) {
+        lines.push(`${NOTE} The page has no same-origin link, so no link was opened.`);
+    }
+    else {
+        lines.push(`${0 === faults.length ? PASS : NOTE} ${String(linksOk)} of ${String(facts.links.length)} ` +
+            `link(s) opened with no fault.`);
+    }
+    if (facts.links.length < facts.linksFound) {
+        lines.push(`${NOTE} Reticle opened ${String(facts.links.length)} of ${String(facts.linksFound)} ` +
+            'same-origin links. It did not check the others.');
+    }
+    const verified = 0 === faults.length ? 'yes' : 'no';
+    lines.push('yes' === verified
+        ? `verified: yes — the smoke check passed on ${start.url}`
+        : `verified: no — ${String(faults.length)} fault(s) on ${start.url}`);
+    return { verified, lines };
+}
+export const MSG_NEXT_STEP = [
+    'Next: connect your coding agent, so it can verify each change it makes:',
+    '  npx @reticlehq/server init',
+];
+const STEP_PROJECT_DETECTED = 'project_detected';
+const STEP_APP_CONNECTED = 'app_connected';
+const EXIT_OK = 0;
+const EXIT_FAIL = 1;
+/** Find the app, check it, print the verdict. Returns the exit code: 0 only for "verified: yes". */
+export async function runFirstVerdict(ports) {
+    const found = await ports.findApp();
+    if ('stop' in found) {
+        for (const line of found.lines) {
+            ports.out(line);
+        }
+        const step = OnboardingStop.NO_WEB_APP === found.stop ? STEP_PROJECT_DETECTED : STEP_APP_CONNECTED;
+        ports.stop({ step, stop: found.stop });
+        return EXIT_FAIL;
+    }
+    try {
+        ports.out(`Reticle is checking ${found.url}. It installs nothing in your app.`);
+        let facts;
+        try {
+            facts = await ports.smoke(found.url);
+        }
+        catch (error) {
+            facts = { failed: [error instanceof Error ? error.message : String(error)] };
+        }
+        if ('failed' in facts) {
+            for (const line of [
+                'verified: unknown — Reticle could not check the page:',
+                ...facts.failed,
+            ]) {
+                ports.out(line);
+            }
+            ports.stop({ step: STEP_APP_CONNECTED, stop: OnboardingStop.APP_NOT_CONNECTED });
+            return EXIT_FAIL;
+        }
+        const verdict = judgeSmoke(facts);
+        for (const line of [...verdict.lines, '', ...MSG_NEXT_STEP]) {
+            ports.out(line);
+        }
+        return 'yes' === verdict.verified ? EXIT_OK : EXIT_FAIL;
+    }
+    finally {
+        found.release?.();
+    }
+}
+/** The `reason` on a stop this command records, so a reader can tell it from an `init` stop. */
+export const FIRST_VERDICT_REASON = 'first_verdict';

package/dist/command/cli/launch/sdk-version-match.d.ts

@@ -1,8 +1,9 @@
 /**
  * Run the CLI whose major matches the SDK the project actually installed.
  *
- * The agent's MCP entry and every rule file `init` writes say `npx @reticlehq/server`, deliberately
- * unpinned (see `npxServerArgs` in init), which resolves the LATEST server — while the project's SDK
+ * Every rule file `init` writes says `npx @reticlehq/server`, unpinned, which resolves the LATEST
+ * server. The agent's MCP entry names one version or an installed copy (see `serverInvocation` in
+ * init), and that copy is a release older or newer than the SDK too — while the project's SDK
  * stays locked at whatever `init` installed. A project wired on the previous major therefore got a
  * daemon from the next one, and every verdict came back `version_skew`; a global install from an
  * older release shadows npx the same way in the other direction. Nothing the project could do fixed

package/dist/command/cli/launch/sdk-version-match.js

@@ -1,8 +1,9 @@
 /**
  * Run the CLI whose major matches the SDK the project actually installed.
  *
- * The agent's MCP entry and every rule file `init` writes say `npx @reticlehq/server`, deliberately
- * unpinned (see `npxServerArgs` in init), which resolves the LATEST server — while the project's SDK
+ * Every rule file `init` writes says `npx @reticlehq/server`, unpinned, which resolves the LATEST
+ * server. The agent's MCP entry names one version or an installed copy (see `serverInvocation` in
+ * init), and that copy is a release older or newer than the SDK too — while the project's SDK
  * stays locked at whatever `init` installed. A project wired on the previous major therefore got a
  * daemon from the next one, and every verdict came back `version_skew`; a global install from an
  * older release shadows npx the same way in the other direction. Nothing the project could do fixed

package/dist/command/cli/lifecycle/daemon-lifecycle.js

@@ -21,7 +21,8 @@ import { probeDaemon, waitForDaemonBind } from '../../../surface/mcp/mcp-proxy.j
 import { stateDirProblem } from '../../daemon/state-dir.js';
 import { readPid, isAlive, removePid, spawnDaemon, logPath, reticleStateHome, } from '../../daemon/daemon.js';
 import { readDaemonStartupCause } from '../../daemon/lifetime/startup-failure.js';
-import { PortPresence, probePresence, describePresence, } from '../../daemon/binding/port-presence.js';
+import { PortPresence, probePresence } from '../../daemon/binding/port-presence.js';
+import { describePortState } from '../../daemon/port-state.js';
 import { daemonSpawnArgs } from '../daemon-start-options.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { requestShutdown, runKill } from '../cli-kill.js';
@@ -82,9 +83,9 @@ async function serveWithHonestExit(parsed) {
         log('reticle_daemon_start_refused', {
             port: parsed.port,
             presence,
-            reason: describePresence(presence, parsed.port),
+            reason: describePortState(presence, parsed.port),
         });
-        process.stderr.write(`${describePresence(presence, parsed.port)}\n`);
+        process.stderr.write(`${describePortState(presence, parsed.port)}\n`);
         process.exit(1);
         return;
     }
@@ -107,7 +108,7 @@ async function serveWithHonestExit(parsed) {
         log('reticle_daemon_start_failed_parent', {
             port: parsed.port,
             presence: settled,
-            reason: describePresence(settled, parsed.port),
+            reason: describePortState(settled, parsed.port),
             log: logPath(parsed.port),
             stateDir: stateDirProblem(reticleStateHome()) === undefined ? 'writable' : 'unwritable',
             ...(startupCause === undefined ? {} : { cause: startupCause }),
@@ -119,7 +120,7 @@ async function serveWithHonestExit(parsed) {
         const dirProblem = stateDirProblem(reticleStateHome());
         process.stderr.write(dirProblem === undefined
             ? startupCause === undefined
-                ? `the daemon did not come up on :${String(parsed.port)} — ${describePresence(settled, parsed.port)}\n` +
+                ? `the daemon did not come up on :${String(parsed.port)} — ${describePortState(settled, parsed.port)}\n` +
                     `see ${logPath(parsed.port)}\n`
                 : `the daemon did not come up on :${String(parsed.port)}.\n${startupCause}\n` +
                     `see ${logPath(parsed.port)}\n`

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

@@ -9,14 +9,15 @@
  */
 import { log } from '../../log.js';
 import { isAlive, spawnDaemon, reticleStateHome } from '../daemon/daemon.js';
-import { PortPresence, probePresence, presenceIsUsable, describePresence, } from '../daemon/binding/port-presence.js';
+import { PortPresence, probePresence, presenceIsUsable, } from '../daemon/binding/port-presence.js';
+import { describePortState } from '../daemon/port-state.js';
 import { waitForDaemon, startMcpProxy, probeDaemon, proxyLog, setProxyLogPort, flushProxyExit, reportWakeRefused, } from '../../surface/mcp/mcp-proxy.js';
 import { installProxyResilience } from '../daemon/daemon-resilience.js';
 import { readProjectId, readProjectPort } from './ports/resolve/cli-port.js';
 import { resolveMcpPort, daemonProjectAt, relocationReason, } from '../daemon/daemon-resolve.js';
 import { daemonSpawnArgs } from './daemon-start-options.js';
 import { WakeAction, decideWake } from '../daemon/wake-decision.js';
-import { runKill } from './cli-kill.js';
+import { runKill, stopWedgedDaemon } from './cli-kill.js';
 import { pickDaemonPortToBind } from '../daemon/binding/free-port.js';
 import { fetchStatus, summarizeStatus } from '../daemon/binding/daemon-status-probe.js';
 import { isNewerVersion } from '../update/update-nudge.js';
@@ -117,6 +118,9 @@ export async function handleMcp(opts) {
             reason: relocationReason(opts.port, to, projectId, reticleStateHome(), isAlive),
         });
     };
+    // A Reticle daemon stuck on the requested port is stopped, not moved away from: the app's SDK
+    // dials this port, and a daemon on another one gets no page (#1937).
+    await stopWedgedDaemon(opts.port);
     // `let`: a wake that finds the port taken resolves again, and the proxy follows (#1651, #1652).
     let port = await resolvePort();
     if (port !== opts.port) {
@@ -151,7 +155,12 @@ export async function handleMcp(opts) {
         // the bridge port answered "a daemon is here" — the proxy connected, the stream ended, and each
         // client request woke into the identical non-answer. Rejecting here is what puts the proxy
         // dormant with a reason, instead of pretending the wake succeeded.
-        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        let presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        // A Reticle daemon that holds the port and does not answer: stop it and keep the port, as at
+        // boot. Relocating left the app dialling a port with no working daemon (#1937).
+        if (PortPresence.FOREIGN === presence && (await stopWedgedDaemon(port))) {
+            presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        }
         // Identity, not just presence. `resolveMcpPort` above already refuses to adopt a stranger's
         // daemon at boot; this is the same question asked on every WAKE, which is where it was missing.
         //
@@ -192,7 +201,7 @@ export async function handleMcp(opts) {
             throw new Error(PortPresence.DAEMON === presence
                 ? `the daemon on port ${String(port)} belongs to a different project, so this one will ` +
                     'not adopt it. Stop it, or start this project on its own port.'
-                : describePresence(presence, port));
+                : describePortState(presence, port));
         }
         const scriptPath = process.argv[1];
         if (scriptPath === undefined) {

package/dist/command/cli/ports/port-holder.d.ts

@@ -16,6 +16,8 @@
 export interface PortHolder {
     pid: number;
     command: string;
+    /** Its command line is a Reticle daemon's. Set only by `identifyPortHolder`. */
+    reticleDaemon?: boolean;
 }
 /**
  * Run a lookup and return its stdout, or null if it could not run.

package/dist/command/cli/ports/port-holder.js

@@ -111,14 +111,22 @@ ourPid) {
          */
         const ours = ourPid !== null && ourPid !== undefined
             ? ` Reticle's own records show pid ${String(ourPid)} for this port — if that process is ` +
-                'still around it is a wedged Reticle daemon, and `reticle stop` clears it.'
+                'still around it is a Reticle daemon that did not answer in time. It may be busy. If it ' +
+                'stays silent, `reticle stop` clears it.'
             : '';
         return `port ${String(port)} is held by a process Reticle could not identify — ${tail}${ours}`;
     }
+    if (true === holder.reticleDaemon && ourPid !== holder.pid) {
+        // Not the pid we recorded, so `reticle stop` cannot find it. `restart` finds the listener.
+        // It did not answer a short probe. A busy daemon does that too, and other agents can use it.
+        return (`port ${String(port)} is held by a Reticle daemon (pid ${String(holder.pid)}) that did not ` +
+            'answer in time. It may be busy. Run `reticle status` again in a few seconds. If it stays ' +
+            'silent, run `reticle restart`: it stops that process and starts a new daemon on this port.');
+    }
     if (ourPid !== null && ourPid !== undefined && ourPid === holder.pid) {
         return (`port ${String(port)} is held by YOUR Reticle daemon (pid ${String(holder.pid)}), and it is ` +
-            'not responding — running but wedged, so nothing can use it and nothing else can bind the ' +
-            'port. Stop it with `reticle stop`; the next tool call starts a fresh one.');
+            'not responding: it did not answer in time. It may be busy. Run `reticle status` again in a ' +
+            'few seconds. If it stays silent, run `reticle stop`; the next tool call starts a fresh one.');
     }
     return (`port ${String(port)} is held by pid ${String(holder.pid)} ("${holder.command}"), which is not ` +
         `a Reticle daemon — ${tail}`);

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

@@ -1,4 +1,5 @@
 import type { OnboardingStep } from '@reticlehq/core/telemetry';
+import { type AgentRow, type WaitClock } from '../setup/agent-next-steps.js';
 /**
  * The terminal half of `reticle setup mcp`.
  *
@@ -15,7 +16,9 @@ import type { OnboardingStep } from '@reticlehq/core/telemetry';
  */
 export type StepReporter = (step: OnboardingStep) => void;
 /** How many coding agents on this machine have Reticle's tools after this run. */
-export declare function handleSetupMcp(reportStep: StepReporter, standalone?: boolean): number;
+export declare function handleSetupMcp(reportStep: StepReporter, standalone?: boolean, 
+/** Wait for the agents to connect. The caller decides: a terminal, and not CI. */
+waitForConnect?: boolean): number;
 /**
  * The one line the launchers read and strip: what they cannot know and the next steps depend on.
  *
@@ -43,3 +46,26 @@ export declare function handleSetupInstall(opts: {
     installSecs: number;
     mcp: boolean;
 }, reportStep: StepReporter): void;
+/** Wait only where a person watches: a terminal, and not CI. */
+export declare function shouldWaitForAgents(isTty: boolean | undefined, isCi: boolean): boolean;
+/** What the wait reads, and the clock it runs on. Injected, so a test does not wait. */
+export interface ConnectionWait {
+    readonly read: () => ReadonlySet<string>;
+    readonly clock: WaitClock;
+}
+/** Wait (bounded) for the registered agents to connect, then say which did and what is missing. */
+export declare function reportConnections(rows: readonly AgentRow[], print: (line: string) => void, wait?: ConnectionWait): Promise<void>;
+/**
+ * `reticle init`: the same block and wait as `reticle setup mcp`, after its restart notice. Print the
+ * "Your agents:" block now. Returns the wait, for the caller to run last: a no-op when
+ * nobody watches.
+ */
+export declare function agentsBlock(rows: readonly AgentRow[], print: (line: string) => void, interactive: boolean, wait?: ConnectionWait): () => Promise<void>;
+/** The agents on this machine and whether Reticle is in each config. Read only. */
+export declare function readAgentRows(cwd: string): AgentRow[];
+/**
+ * `reticle setup wait-agents`: the installer's last step. The installer sends `setup install` output
+ * to a file, so that run cannot wait; this one runs with the terminal attached. Waits only where a
+ * person watches.
+ */
+export declare function handleSetupWaitAgents(interactive: boolean): Promise<void>;