@reticlehq/server 3.5.0 → 3.6.0

package/dist/command/cli/cloud-login.js

@@ -125,11 +125,11 @@ const linkAfterLogin = async (url, project, link) => {
  * Browser device flow — the DEFAULT `reticle login` (like `gh auth login`): fetch a device + user code,
  * open the browser to approve, then poll until the user confirms. No email to type, no code to copy back.
  */
-const cmdLoginDevice = async (explicitUrl, project, link, autoLink) => {
+const cmdLoginDevice = async (explicitUrl, project, link, autoLink, open = openBrowser) => {
     const url = baseUrl(null, explicitUrl);
     const started = DeviceStartSchema.parse(await api('POST', `${url}/v1/auth/device/start`, null, {}));
     hint(`Opening ${started.verificationUri} — confirm this code in the browser: ${started.userCode}`);
-    openBrowser(started.verificationUriComplete);
+    open(started.verificationUriComplete);
     const intervalMs = Math.max(1, started.interval) * 1000;
     for (;;) {
         await sleep(intervalMs);
@@ -200,3 +200,37 @@ export const cmdLogout = async (argv = []) => {
     emit({ loggedOut: true, url });
     return 0;
 };
+/** The daemon signs in for the panel and links nothing: its working directory is not the user's app. */
+const NO_LINK = () => Promise.resolve(0);
+/**
+ * The panel's Sign in: the same browser approval `reticle login` opens, started by the daemon, which
+ * owns `~/.reticle`. One flow at a time, and a second press while it is pending reopens its approval
+ * page rather than doing nothing: somebody who closed that tab must be able to get it back.
+ * `onSignedIn` runs when the approval lands so every open panel can repaint. A failure stays in the
+ * daemon log: the panel copied `reticle login` as it was clicked, which is the way through.
+ */
+export function hudSignIn(onSignedIn, start = (open) => cmdLoginDevice(undefined, undefined, NO_LINK, false, open), opener = openBrowser) {
+    let running = false;
+    let pending;
+    return () => {
+        if (running) {
+            if (pending !== undefined)
+                opener(pending);
+            return;
+        }
+        running = true;
+        void start((url) => {
+            pending = url;
+            opener(url);
+        })
+            .then((code) => {
+            if (0 === code)
+                onSignedIn();
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            running = false;
+            pending = undefined;
+        });
+    };
+}

package/dist/command/cli/demo/demo-page.js

@@ -30,7 +30,7 @@
 import { fileURLToPath } from 'node:url';
 import { createServer } from 'node:http';
 import { dirname, join, relative, extname, sep } from 'node:path';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 /** Where the tour starts. Everything else on the page is reached from here. */
 const SDK_ENTRY = '@reticlehq/browser';
 /** The signal the demo app fires when it saves — the consequence the tour declares in advance. */
@@ -208,13 +208,21 @@ export function serveDemoPage(html, graph) {
                 continue;
             const file = join(mount.dir, path.slice(mount.prefix.length));
             // A request that climbed out of the mount is not served, whatever it points at.
-            if (!file.startsWith(mount.dir + sep) || !existsSync(file) || statSync(file).isDirectory()) {
+            if (!file.startsWith(mount.dir + sep))
+                break;
+            // One read, no prior exists/stat check: a missing file or a directory throws here, and there
+            // is no window between a check and the read for the path to change under it.
+            let body;
+            try {
+                body = readFileSync(file);
+            }
+            catch {
                 break;
             }
             res.writeHead(200, {
                 'content-type': '.js' === extname(file) ? JS_CONTENT_TYPE : 'application/octet-stream',
             });
-            res.end(readFileSync(file));
+            res.end(body);
             return;
         }
         res.writeHead(404);

package/dist/command/cli/doctor/browser/chromium-hint.d.ts

@@ -48,7 +48,45 @@ export interface ChromiumProbe {
      * `Microsoft Edge`) — see launch-chromium. Present only when `exists` is false and one was found.
      */
     fallback?: string | undefined;
+    /** `executablePath` came from RETICLE_CHROMIUM_PATH, so the bundled build is not in play at all. */
+    configured?: boolean | undefined;
+    /** Why that configured executable cannot be launched. Present only when `exists` is false. */
+    problem?: ChromiumPathProblem | undefined;
 }
+/** What stops the executable RETICLE_CHROMIUM_PATH names from being launched. */
+export declare const ChromiumPathProblem: {
+    readonly MISSING: "missing";
+    readonly NOT_A_FILE: "not-a-file";
+    readonly NOT_EXECUTABLE: "not-executable";
+};
+export type ChromiumPathProblem = (typeof ChromiumPathProblem)[keyof typeof ChromiumPathProblem];
+/**
+ * What stops the file at `path` from being launched, or undefined when nothing does.
+ *
+ * Existing is not enough: Playwright cannot start a directory or a file without the executable bit,
+ * and its error for that reads like a missing install. Windows has no executable bit, so only the
+ * file check applies there.
+ */
+export declare function chromiumPathProblem(path: string, platform: NodeJS.Platform): ChromiumPathProblem | undefined;
+/** The Chromium RETICLE_CHROMIUM_PATH names, or undefined when it is unset or blank. */
+export declare function configuredChromiumPath(env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * What the probes report when RETICLE_CHROMIUM_PATH is set, or undefined when it is not. The user
+ * named the browser, so the bundled revision, the installed channels and the browsers root say
+ * nothing about whether a launch will work. Only the named file does.
+ */
+export declare function configuredChromiumProbe(env: NodeJS.ProcessEnv, pathProblem: (path: string) => ChromiumPathProblem | undefined): ChromiumProbe | undefined;
+/**
+ * How every RETICLE_CHROMIUM_PATH refusal begins. Error recovery keys on it, so the variable's name
+ * is read as configuration rather than as a `reticle_*` tool the call got wrong.
+ */
+export declare const CHROMIUM_PATH_REFUSAL_PREFIX: string;
+/**
+ * A RETICLE_CHROMIUM_PATH that cannot be launched. Worded apart from the missing-browser hint on
+ * purpose: that one sends the reader to install Playwright's build, which does nothing for a path
+ * typed wrong.
+ */
+export declare function configuredChromiumRefusal(path: string, problem: ChromiumPathProblem): string;
 /** The install command, pinned when we know what to pin to. */
 export declare function chromiumInstallCommand(playwrightVersion?: string): string;
 /**
@@ -83,5 +121,13 @@ export declare function parseChromiumRevision(executablePath: string): {
 export declare function probeChromium(): Promise<ChromiumProbe>;
 /** The bundled playwright's version, or undefined if it cannot be read (the hint then goes unpinned). */
 export declare function bundledPlaywrightVersion(): string | undefined;
+/**
+ * Why the lease preflight refuses, or undefined when a launch can go ahead.
+ *
+ * "Chromium is not installed" is kept in the usual message because error-recovery routes it to the
+ * install fix. A RETICLE_CHROMIUM_PATH that cannot be launched is a wrong path, not a missing
+ * install, so it says only that and the install fix is never attached.
+ */
+export declare function chromiumPreflightRefusal(probe: ChromiumProbe): string | undefined;
 /** The doctor line for the Chromium check — verdict, what was probed, and how to satisfy it. */
 export declare function chromiumHint(probe: ChromiumProbe): string;

package/dist/command/cli/doctor/browser/chromium-hint.js

@@ -20,8 +20,86 @@
  * resolves, so `PLAYWRIGHT_BROWSERS_PATH` and every platform default are honoured by construction
  * rather than by a table of roots this file would have to keep in step with Playwright's.
  */
-import { existsSync, readdirSync } from 'node:fs';
+import { accessSync, constants as fsConstants, existsSync, readdirSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { ReticleEnv } from '@reticlehq/core';
+/** What stops the executable RETICLE_CHROMIUM_PATH names from being launched. */
+export const ChromiumPathProblem = {
+    MISSING: 'missing',
+    NOT_A_FILE: 'not-a-file',
+    NOT_EXECUTABLE: 'not-executable',
+};
+/**
+ * What stops the file at `path` from being launched, or undefined when nothing does.
+ *
+ * Existing is not enough: Playwright cannot start a directory or a file without the executable bit,
+ * and its error for that reads like a missing install. Windows has no executable bit, so only the
+ * file check applies there.
+ */
+export function chromiumPathProblem(path, platform) {
+    let isFile;
+    try {
+        isFile = statSync(path).isFile();
+    }
+    catch {
+        return ChromiumPathProblem.MISSING;
+    }
+    if (!isFile)
+        return ChromiumPathProblem.NOT_A_FILE;
+    if ('win32' === platform)
+        return undefined;
+    try {
+        accessSync(path, fsConstants.X_OK);
+        return undefined;
+    }
+    catch {
+        return ChromiumPathProblem.NOT_EXECUTABLE;
+    }
+}
+/** The Chromium RETICLE_CHROMIUM_PATH names, or undefined when it is unset or blank. */
+export function configuredChromiumPath(env) {
+    const path = env[ReticleEnv.CHROMIUM_PATH]?.trim();
+    return path === undefined || 0 === path.length ? undefined : path;
+}
+/**
+ * What the probes report when RETICLE_CHROMIUM_PATH is set, or undefined when it is not. The user
+ * named the browser, so the bundled revision, the installed channels and the browsers root say
+ * nothing about whether a launch will work. Only the named file does.
+ */
+export function configuredChromiumProbe(env, pathProblem) {
+    const path = configuredChromiumPath(env);
+    if (path === undefined)
+        return undefined;
+    const problem = pathProblem(path);
+    return {
+        executablePath: path,
+        exists: problem === undefined,
+        configured: true,
+        ...(problem === undefined ? {} : { problem }),
+    };
+}
+/**
+ * How every RETICLE_CHROMIUM_PATH refusal begins. Error recovery keys on it, so the variable's name
+ * is read as configuration rather than as a `reticle_*` tool the call got wrong.
+ */
+export const CHROMIUM_PATH_REFUSAL_PREFIX = `${ReticleEnv.CHROMIUM_PATH} points at `;
+/** What each problem reads as, after the path. */
+const CHROMIUM_PATH_PROBLEM_TEXT = {
+    [ChromiumPathProblem.MISSING]: 'which does not exist',
+    [ChromiumPathProblem.NOT_A_FILE]: 'which is not a file',
+    [ChromiumPathProblem.NOT_EXECUTABLE]: 'which is not executable',
+};
+const CHROMIUM_PATH_FIX = "fix the path, or unset it to use Playwright's own Chromium";
+/** The doctor verdict for a RETICLE_CHROMIUM_PATH that can be launched. */
+const CHROMIUM_PATH_IN_USE = (path) => `✓ using ${path} (${ReticleEnv.CHROMIUM_PATH})`;
+/**
+ * A RETICLE_CHROMIUM_PATH that cannot be launched. Worded apart from the missing-browser hint on
+ * purpose: that one sends the reader to install Playwright's build, which does nothing for a path
+ * typed wrong.
+ */
+export function configuredChromiumRefusal(path, problem) {
+    return `${CHROMIUM_PATH_REFUSAL_PREFIX}${path}, ${CHROMIUM_PATH_PROBLEM_TEXT[problem]}; ${CHROMIUM_PATH_FIX}`;
+}
 /**
  * A browsers-root entry that is a chromium build.
  *
@@ -160,8 +238,28 @@ export function bundledPlaywrightVersion() {
     }
     return undefined;
 }
+/**
+ * Why the lease preflight refuses, or undefined when a launch can go ahead.
+ *
+ * "Chromium is not installed" is kept in the usual message because error-recovery routes it to the
+ * install fix. A RETICLE_CHROMIUM_PATH that cannot be launched is a wrong path, not a missing
+ * install, so it says only that and the install fix is never attached.
+ */
+export function chromiumPreflightRefusal(probe) {
+    if (probe.exists)
+        return undefined;
+    if (true === probe.configured && probe.executablePath !== undefined) {
+        return configuredChromiumRefusal(probe.executablePath, probe.problem ?? ChromiumPathProblem.MISSING);
+    }
+    return `Chromium is not installed for Playwright — ${chromiumHint(probe)}`;
+}
 /** The doctor line for the Chromium check — verdict, what was probed, and how to satisfy it. */
 export function chromiumHint(probe) {
+    if (true === probe.configured && probe.executablePath !== undefined) {
+        return probe.exists
+            ? CHROMIUM_PATH_IN_USE(probe.executablePath)
+            : `✗ ${configuredChromiumRefusal(probe.executablePath, probe.problem ?? ChromiumPathProblem.MISSING)}`;
+    }
     if (probe.exists) {
         // Naming the revision on the happy line too: it is the number the mismatch line talks about, and
         // a reader comparing two machines has nothing to compare without it.

package/dist/command/cli/drive/drive-attach.d.ts

@@ -44,7 +44,7 @@ export declare function decideDriveMode(presence: PortPresence): DriveMode;
 /** A driveable session the daemon opened on our behalf. */
 interface DriveSession {
     sessionId: string;
-    /** Whether the tab's SDK actually registered — false ⇒ the app may not embed @reticlehq/core. */
+    /** Whether the tab's SDK actually registered — false ⇒ the app may not embed @reticlehq/browser. */
     ready: boolean;
     /** How long the session survives untouched. Absent from a daemon that does not report it. */
     expiresInMs?: number;
@@ -76,8 +76,33 @@ export declare function readAttachResponse(port: number, url: string, res: {
 }): DriveAttachResult;
 /** Ask the daemon on `port` to open a driveable browser at `url`. */
 export declare function requestDriveSession(port: number, url: string, post?: DrivePost): Promise<DriveAttachResult>;
+/** Which app the attached page says it is, beside the project this directory names. */
+export interface AttachedApp {
+    /** What the JSON line carries. Every value is printable, see `printable`. */
+    fields: {
+        /** The project the page reported when it connected. */
+        projectId?: string;
+        title?: string;
+        /** The `projectId` in this directory's `.reticle.json`, when there is one. */
+        expectedProjectId?: string;
+    };
+    /**
+     * The two project ids differ. Decided on the raw values, before either is made printable, so two
+     * ids that differ only in a control character still count as different.
+     */
+    mismatch: boolean;
+}
+/** Nothing known about the app, as for a page that never connected. */
+export declare const NO_ATTACHED_APP: AttachedApp;
+/**
+ * Pick the attached session out of a `/status` payload. Pure.
+ *
+ * The drive answer is a lease result, which carries no project: the page reports that itself when
+ * it connects, and `/status` is where it is already listed.
+ */
+export declare function attachedApp(status: unknown, sessionId: string, expectedProjectId: string | undefined): AttachedApp;
 /** The success line. Names the session, because that is the handle everything downstream needs. */
-export declare function describeAttached(port: number, url: string, session: DriveSession): string;
+export declare function describeAttached(port: number, url: string, session: DriveSession, app?: AttachedApp): string;
 /**
  * What an attach cannot honour: the window.
  *

package/dist/command/cli/drive/drive-attach.js

@@ -31,6 +31,7 @@
 import * as http from 'node:http';
 import { DRIVE_PATH, LOOPBACK_HOST } from '@reticlehq/core';
 import { PortPresence } from '../../daemon/binding/port-presence.js';
+import { summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
 /** What `drive` should do about the port, given what is on it. */
 export const DriveMode = {
     /** Nothing is listening: bind it and run the foreground engine. */
@@ -134,18 +135,84 @@ export async function requestDriveSession(port, url, post = postJson) {
     }
     return readAttachResponse(port, url, res);
 }
+/** Nothing known about the app, as for a page that never connected. */
+export const NO_ATTACHED_APP = { fields: {}, mismatch: false };
+/**
+ * Control characters, and the 0x80 to 0x9f range some terminals also obey. Built with
+ * `fromCharCode` to keep them out of a regex literal (no-control-regex).
+ */
+const TERMINAL_CONTROLS = new RegExp(`[${String.fromCharCode(0)}-${String.fromCharCode(0x1f)}${String.fromCharCode(0x7f)}-${String.fromCharCode(0x9f)}]`, 'g');
+/**
+ * A value safe to print. The project id and title come from the page, and the expected project id
+ * from a `.reticle.json` anyone can commit. All three are written straight to the terminal (and into
+ * the JSON line beside it), so they could otherwise move the cursor or retitle the window. Each
+ * control character becomes U+FFFD, so the reader can still see that something was there.
+ */
+function printable(value) {
+    return value.replace(TERMINAL_CONTROLS, '\uFFFD');
+}
+/**
+ * Pick the attached session out of a `/status` payload. Pure.
+ *
+ * The drive answer is a lease result, which carries no project: the page reports that itself when
+ * it connects, and `/status` is where it is already listed.
+ */
+export function attachedApp(status, sessionId, expectedProjectId) {
+    const row = summarizeStatus(status).sessions.find((s) => s.sessionId === sessionId);
+    return {
+        fields: {
+            ...(row?.projectId === undefined ? {} : { projectId: printable(row.projectId) }),
+            ...(row?.title === undefined ? {} : { title: printable(row.title) }),
+            ...(expectedProjectId === undefined
+                ? {}
+                : { expectedProjectId: printable(expectedProjectId) }),
+        },
+        // Only warned when both sides are known: a page with no project id proves nothing, and neither
+        // does a directory without a `.reticle.json`.
+        mismatch: row?.projectId !== undefined &&
+            expectedProjectId !== undefined &&
+            row.projectId !== expectedProjectId,
+    };
+}
+/** The fallback when the daemon sent no hint for a page that did not connect. */
+const MSG_NOT_READY_HINT = 'Check that the app embeds @reticlehq/browser.';
+/** How the attach line names the page's project. */
+const PROJECT_LABEL = (projectId) => `project ${JSON.stringify(projectId)}`;
+/** The page is a different project from the one this directory's `.reticle.json` names. */
+const MSG_PROJECT_MISMATCH = (url, expected, actual) => `Warning: this directory's .reticle.json is ${PROJECT_LABEL(expected)}, but the page at ${url} ` +
+    `is ${PROJECT_LABEL(actual)}, so another app is probably serving that port. Check which dev ` +
+    'server is on it before trusting anything this session reports.';
+/**
+ * The project and title, and a warning when this directory names a different project.
+ *
+ * In a monorepo the port you meant for one app is easily held by another, and the port, url and
+ * session id read the same either way.
+ */
+function describeApp(url, app) {
+    const { projectId, title, expectedProjectId } = app.fields;
+    const named = [
+        ...(projectId === undefined ? [] : [PROJECT_LABEL(projectId)]),
+        ...(title === undefined ? [] : [JSON.stringify(title)]),
+    ];
+    const label = 0 === named.length ? '' : ` (${named.join(', ')})`;
+    const warning = app.mismatch && projectId !== undefined && expectedProjectId !== undefined
+        ? ` ${MSG_PROJECT_MISMATCH(url, expectedProjectId, projectId)}`
+        : '';
+    return { label, warning };
+}
 /** The success line. Names the session, because that is the handle everything downstream needs. */
-export function describeAttached(port, url, session) {
+export function describeAttached(port, url, session, app = NO_ATTACHED_APP) {
     const life = session.expiresInMs === undefined
         ? ''
         : ` It is released after ${String(Math.round(session.expiresInMs / 1000))}s untouched; any ` +
             'tool call against it resets that.';
     if (!session.ready) {
         return (`the Reticle daemon on :${String(port)} opened ${url} as session ${session.sessionId}, but ` +
-            `the page did not connect to the bridge. ${session.hint ?? 'Check that the app embeds @reticlehq/core.'}`);
+            `the page did not connect to the bridge. ${session.hint ?? MSG_NOT_READY_HINT}`);
     }
-    return (`attached to the Reticle daemon on :${String(port)} — it is driving ${url} as session ` +
-        `${session.sessionId}, which every Reticle tool can address.${life}`);
+    const { label, warning } = describeApp(url, app);
+    return (`attached to the Reticle daemon on :${String(port)} — it is driving ${url}${label} as session ` +
+        `${session.sessionId}, which every Reticle tool can address.${life}${warning}`);
 }
 /**
  * What an attach cannot honour: the window.

package/dist/command/cli/drive/drive-command.d.ts

@@ -6,8 +6,9 @@
  * place. The pure parts (which mode, and every sentence a user reads) live next door in
  * drive-attach.ts, which is where the reasoning for attaching is written down.
  */
+/** `projectId` is the one in this directory's `.reticle.json`, read by the caller. */
 export declare function handleDrive(parsed: {
     port: number;
     driveUrl: string;
     headless: boolean;
-}): void;
+}, projectId?: string): void;

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

@@ -13,9 +13,10 @@ import { probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
 import { readPid } from '../../daemon/daemon.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { captureLookup, findPortHolder } from '../ports/port-holder.js';
-import { DriveMode, decideDriveMode, describeAttached, driveForeignHolder, driveHeadlessOnAttach, driveRaceLost, requestDriveSession, } from './drive-attach.js';
-export function handleDrive(parsed) {
-    void driveWithHonestConflict(parsed);
+import { DriveMode, NO_ATTACHED_APP, attachedApp, decideDriveMode, describeAttached, driveForeignHolder, driveHeadlessOnAttach, driveRaceLost, requestDriveSession, } from './drive-attach.js';
+/** `projectId` is the one in this directory's `.reticle.json`, read by the caller. */
+export function handleDrive(parsed, projectId) {
+    void driveWithHonestConflict(parsed, projectId);
 }
 /**
  * Decide who gets the port BEFORE binding it — and when the answer is "the daemon", ask it instead.
@@ -29,7 +30,7 @@ export function handleDrive(parsed) {
  * because the MCP proxy respawns a daemon into the gap. So a healthy daemon is now ATTACHED to —
  * see cli/drive/drive-attach.ts.
  */
-async function driveWithHonestConflict(parsed) {
+async function driveWithHonestConflict(parsed, projectId) {
     const presence = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
     const mode = decideDriveMode(presence);
     if (DriveMode.REFUSE === mode) {
@@ -43,7 +44,7 @@ async function driveWithHonestConflict(parsed) {
         return;
     }
     if (DriveMode.ATTACH === mode) {
-        await attachToRunningDaemon(parsed.port, parsed.driveUrl, parsed.headless);
+        await attachToRunningDaemon(parsed.port, parsed.driveUrl, parsed.headless, projectId);
         return;
     }
     // The probe cannot close the race: something can take the port between here and the bind, and the
@@ -81,7 +82,7 @@ async function driveWithHonestConflict(parsed) {
  * against it renews its lease), and a foreground hold here could only keep it alive by faking tool
  * calls at it.
  */
-async function attachToRunningDaemon(port, url, headless) {
+async function attachToRunningDaemon(port, url, headless, projectId) {
     const result = await requestDriveSession(port, url);
     if (!result.ok) {
         log('reticle_drive_attach_failed', { port, url, reason: result.reason });
@@ -89,13 +90,18 @@ async function attachToRunningDaemon(port, url, headless) {
         process.exit(1);
         return;
     }
+    // Only a page that connected has reported its project; one that never dialled in is not listed.
+    const app = result.session.ready
+        ? attachedApp(await fetchStatus(port), result.session.sessionId, projectId)
+        : NO_ATTACHED_APP;
     log('reticle_drive_attached', {
         port,
         url,
         sessionId: result.session.sessionId,
         ready: result.session.ready,
+        ...app.fields,
     });
-    process.stderr.write(`${describeAttached(port, url, result.session)}\n`);
+    process.stderr.write(`${describeAttached(port, url, result.session, app)}\n`);
     // The command's own default is headed, and this path cannot deliver that. Said out loud rather
     // than left for the user to discover by watching a window that never opens.
     if (!headless)

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

@@ -16,7 +16,7 @@
  */
 import { log } from '../../../log.js';
 import { RETICLE_VERIFY_DEFAULT_PORT } from '../../../index.js';
-import { verifyEndpointMismatch } from '../../../status-payload.js';
+import { strandedClientsNote, verifyEndpointMismatch } from '../../../status-payload.js';
 import { probeDaemon, waitForDaemonBind } from '../../../surface/mcp/mcp-proxy.js';
 import { stateDirProblem } from '../../daemon/state-dir.js';
 import { readPid, isAlive, removePid, spawnDaemon, logPath, reticleStateHome, } from '../../daemon/daemon.js';
@@ -168,6 +168,9 @@ export function handleStop(port, quiet) {
  * anything at all, and a single `ok: false` cannot tell them which happened.
  */
 export async function handleRestart(port, force) {
+    const stranded = strandedClientsNote(await fetchStatus(port));
+    if (stranded !== undefined)
+        process.stderr.write(`${stranded}\n`);
     const freed = await runKill(port, force);
     if (!freed) {
         log('reticle_restart_aborted', {

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

@@ -51,3 +51,13 @@ export declare function describeForeignHolder(port: number, holder: PortHolder |
 ourPid?: number | null): string;
 /** The lookup itself. `exec` is injected so the shelling out never runs in a unit test. */
 export declare function findPortHolder(port: number, exec: (command: string, args: readonly string[]) => string | null): PortHolder | null;
+/** The path in `lsof -a -p <pid> -d cwd -Fn` output, or null when it printed none. */
+export declare function parseProcessCwd(stdout: string): string | null;
+/**
+ * The working directory of whatever LISTENS on `port`, or null.
+ *
+ * How the daemon tells which checkout served a page when every git worktree declares the same
+ * projectId: the dev server runs inside exactly one of them. Null wherever `lsof` cannot answer —
+ * Windows, a slim container — and the caller then keeps the answer it had without this.
+ */
+export declare function findListenerCwd(port: number, exec: (command: string, args: readonly string[]) => string | null): string | null;

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

@@ -121,3 +121,27 @@ export function findPortHolder(port, exec) {
     const out = exec('lsof', ['-nP', `-iTCP:${String(port)}`, '-sTCP:LISTEN', '-F', 'pc']);
     return null === out ? null : parsePortHolder(out);
 }
+/** `lsof -Fn` emits the file name on its own line, prefixed `n`. */
+const NAME_FIELD = 'n';
+/** The path in `lsof -a -p <pid> -d cwd -Fn` output, or null when it printed none. */
+export function parseProcessCwd(stdout) {
+    for (const raw of stdout.split('\n')) {
+        if (raw.startsWith(NAME_FIELD) && raw.length > NAME_FIELD.length)
+            return raw.slice(1);
+    }
+    return null;
+}
+/**
+ * The working directory of whatever LISTENS on `port`, or null.
+ *
+ * How the daemon tells which checkout served a page when every git worktree declares the same
+ * projectId: the dev server runs inside exactly one of them. Null wherever `lsof` cannot answer —
+ * Windows, a slim container — and the caller then keeps the answer it had without this.
+ */
+export function findListenerCwd(port, exec) {
+    const holder = findPortHolder(port, exec);
+    if (null === holder)
+        return null;
+    const out = exec('lsof', ['-a', '-p', String(holder.pid), '-d', 'cwd', '-Fn']);
+    return null === out ? null : parseProcessCwd(out);
+}

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

@@ -35,14 +35,16 @@ export function handleSetupMcp(reportStep, standalone = true) {
     const result = setupMcp(io);
     if (0 === result.detected.length) {
         // Even with no file-backed client, the broader set may still have somewhere to write.
-        registerOtherAgents((line) => {
+        const preRegistered = registerOtherAgents((line) => {
             io.print(line);
         });
         // Named rather than a bare "none found". A person whose agent IS installed needs to know
         // whether we looked for it at all, and the list is the difference between "we did not find
-        // yours" and "we do not support yours".
-        io.print(`No coding agent config found. Looked for: ${knownClientLabels().join(', ')}.`);
-        io.print('Install one, then run `reticle setup mcp` again.');
+        // yours" and "we do not support yours". When the broader set was written, saying "none found"
+        // right under its tick read as a contradiction: those agents are pre-registered, not found.
+        io.print(0 < preRegistered
+            ? `None of ${knownClientLabels().join(', ')} is installed here yet. The agents above are pre-registered and have Reticle's tools once installed; install one of the others, then run \`reticle setup mcp\` again.`
+            : `No coding agent config found. Looked for: ${knownClientLabels().join(', ')}. Install one, then run \`reticle setup mcp\` again.`);
         return;
     }
     for (const id of result.registered)

package/dist/command/cli/tutorial.d.ts

@@ -84,8 +84,8 @@ export declare function tutorialNextSteps(audience: TutorialAudience, restartAge
  * on `process.stdout.isTTY` does not work: that is `undefined` through every pipe, so the tour never
  * prints. A heuristic that silently answers "nobody is watching" is worse than no heuristic.
  *
- * It ends with the tour's OWN closing, which already names `reticle init`. Adding a second "Next:"
- * under it would be the same instruction twice in ten lines.
+ * It ends with the tour's OWN closing. Installing changes no project: the app is wired the first time
+ * an agent uses Reticle in it (see first-run-wiring.ts).
  */
 export declare function installClosing(registered?: boolean): string;
 export declare function renderTutorial(audience: TutorialAudience): string;

package/dist/command/cli/tutorial.js

@@ -95,8 +95,8 @@ export function tutorialNextSteps(audience, restartAgent = false) {
     const lines = TutorialAudience.AGENT === audience
         ? [
             'Next:',
-            '  reticle init            # instrument the project in this directory',
-            '  reticle status          # confirms the app connected, or says why it has not',
+            '  reticle_session list    # the first call wires this project: Reticle runs init itself',
+            '                          # and names every file it changed — tell the user which',
             '  then run the four steps above against it, and report the verdict',
         ]
         : [
@@ -104,12 +104,9 @@ export function tutorialNextSteps(audience, restartAgent = false) {
             ...(restartAgent
                 ? ['  restart your agent                 # it loads new tools only when it starts']
                 : []),
-            '  cd <your project> && reticle init  # wire Reticle into the app',
-            '  npm run dev                        # then load it in a browser',
-            '  reticle status                     # confirms the app connected, or says why not',
             '',
             // One line: the terminal wraps it at the reader's width, not ours.
-            'Then ask your agent to drive one real flow and report the verdict. That is the install proving itself, and it is the agent’s job rather than a command you run.',
+            'Ask your agent to verify one real flow in your project. Nothing in your app changed at install: the first time the agent uses Reticle there, Reticle wires the app, starts it, and tells you which files it changed.',
         ];
     return lines.join('\n');
 }
@@ -120,8 +117,8 @@ export function tutorialNextSteps(audience, restartAgent = false) {
  * on `process.stdout.isTTY` does not work: that is `undefined` through every pipe, so the tour never
  * prints. A heuristic that silently answers "nobody is watching" is worse than no heuristic.
  *
- * It ends with the tour's OWN closing, which already names `reticle init`. Adding a second "Next:"
- * under it would be the same instruction twice in ten lines.
+ * It ends with the tour's OWN closing. Installing changes no project: the app is wired the first time
+ * an agent uses Reticle in it (see first-run-wiring.ts).
  */
 export function installClosing(registered = true) {
     // One line a step. The reasons are for `reticle tutorial`; right after an install they turned a
@@ -140,7 +137,7 @@ export function installClosing(registered = true) {
  * Reticle" points at a panel on screen; straight after an install there is none to point at.
  */
 const INSTALL_SAYS = {
-    connect: 'Once `reticle init` wires your app, a Reticle panel appears in it: your proof the SDK is connected.',
+    connect: 'The first time your agent uses Reticle in a project, it wires the app and a Reticle panel appears in it: your proof the SDK is connected.',
 };
 export function renderTutorial(audience) {
     const steps = tutorialScript(audience)

package/dist/command/cli.d.ts

@@ -2,5 +2,11 @@
 import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli/cli-parse.js';
+/**
+ * Report status to the terminal. `--json` writes one structured line to STDOUT so it can be piped
+ * into `jq`; the human-readable block goes to stdout too. `log()` stays on stderr (the MCP
+ * transport lives on stdout), so `--json` must not go through it.
+ */
+export declare function reportStatus(fields: Record<string, unknown>, json: boolean): void;
 export declare function handleStatus(port: number, json?: boolean): Promise<void>;
 export declare function main(): void;