@reticlehq/server 3.4.0 → 3.6.0

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

@@ -13,12 +13,14 @@ import { basename, join } from 'node:path';
 import { z } from 'zod';
 import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
 import { CLOUD_LINK_FILE, resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
+import { memoryReadUrl, MemoryResponseScope, scopeMemoryResponse, scopeOfMemoryResponse, } from '../../memory/cloud/memory-scope.js';
 import { applyCredential, findCredential } from './auth/cloud-keystore.js';
 import { defaultProjectFor } from './project-name.js';
 import { RETICLE_CONFIG_BASENAME } from './ports/resolve/cli-port.js';
 import { normalizeUrl } from './auth/cloud-session.js';
 import { cmdLogin, cmdLogout } from './cloud-login.js';
 import { api, baseUrl, bearer, CREDENTIALS_FILE, emit, err, flags, hint, home, readJson, readSession, readSessionFor, RETICLE_DIR, } from './cloud-kit.js';
+import { syncRequest } from '../../memory/cloud/cloud-sync.js';
 import { describeSync, runSyncCycle } from '../../memory/cloud/sync-cycle.js';
 import { diskSink, diskSource, readCloudIssues, readCloudState } from '../../memory/cloud/sync-disk.js';
 /**
@@ -42,6 +44,7 @@ import { diskSink, diskSource, readCloudIssues, readCloudState } from '../../mem
  */
 const CLOUD_COMMANDS = new Set([
     'login',
+    'connect',
     'logout',
     'whoami',
     'link',
@@ -175,8 +178,11 @@ const cmdWhoami = async () => {
             verify: cloud.verify,
         },
     });
+    // Signed out, `link` refuses with "run reticle login first"; `connect` does both in one go.
     if (null === cloud.config)
-        hint('this repo is not attached — run `reticle link`');
+        hint(null === session
+            ? 'this repo is not attached — run `reticle connect` (signs in and links in one step)'
+            : 'this repo is not attached — run `reticle link`');
     return 0;
 };
 /** `reticle project ls` / `reticle project create <name>` — key- or session-authed. */
@@ -433,11 +439,68 @@ const cmdLink = async (argv) => {
      * before they install, which is a legitimate order to work in.
      */
     if (!(await createNodeFileSystem().exists(join(process.cwd(), RETICLE_CONFIG_BASENAME)))) {
-        hint(`no ${RETICLE_CONFIG_BASENAME} here, so this app announces no project — its runs will not be ` +
-            'attributed to this binding. Run `reticle init` in the app, then restart the dev server.');
+        hint(`no ${RETICLE_CONFIG_BASENAME} here: this app's runs reach this binding only while its dev ` +
+            'server runs with the Reticle build plugin, which announces it. Run `reticle init` in the app ' +
+            'to make the binding hold without it.');
     }
     return 0;
 };
+/**
+ * `reticle connect` finishes the cloud half of first-run setup in one invocation. The CLI entry
+ * initializes an unwired app before calling this verb. A saved login is checked against this exact
+ * host before reuse; an expired one opens the normal browser approval flow. Login does not auto-link
+ * here because this command links once, to the project the caller named, then sends local history.
+ */
+const cmdConnect = async (argv) => {
+    for (let i = 0; i < argv.length; i += 2) {
+        const flag = argv[i];
+        const value = argv[i + 1];
+        if ((flag !== '--project' && flag !== '--url') ||
+            value === undefined ||
+            0 === value.length ||
+            value.startsWith('--')) {
+            err('usage: reticle connect [--project <name|id>] [--url <cloud origin>]');
+            return 2;
+        }
+    }
+    if (!(await createNodeFileSystem().exists(join(process.cwd(), RETICLE_CONFIG_BASENAME)))) {
+        err('this app is not wired yet — run `reticle init` in its directory, then `reticle connect`');
+        return 2;
+    }
+    const f = flags(argv);
+    const url = baseUrl(null, f['url']);
+    if (undefined === apiKeyFrom(process.env)) {
+        const session = await readSessionFor(url);
+        let signedIn = false;
+        if (session !== null) {
+            try {
+                await api('GET', `${url}/v1/me`, session.token);
+                signedIn = true;
+            }
+            catch {
+                hint('saved sign-in needs renewal — opening browser approval');
+            }
+        }
+        if (!signedIn) {
+            const code = await cmdLogin(['--url', url], cmdLink, false);
+            if (code !== 0)
+                return code;
+        }
+    }
+    const linkArgs = [
+        '--url',
+        url,
+        ...(f['project'] === undefined ? [] : ['--project', f['project']]),
+    ];
+    const linked = await cmdLink(linkArgs);
+    if (linked !== 0)
+        return linked;
+    const pushed = await cmdPush();
+    if (pushed !== 0)
+        return pushed;
+    hint('Connected. Open your coding agent and ask it to verify one flow in your app.');
+    return 0;
+};
 /** `reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]`. */
 const cmdConfig = async (argv) => {
     const f = flags(argv);
@@ -508,10 +571,7 @@ const cmdSync = async (argv) => {
             sink: diskSink(reticleRoot),
             state: readCloudState(reticleRoot),
             now: () => Date.now(),
-            request: async (url, init) => {
-                const res = await fetch(url, init);
-                return { status: res.status, text: await res.text() };
-            },
+            request: (url, init) => syncRequest(url, init),
         });
         emit({
             ok: report.ok,
@@ -544,13 +604,25 @@ const cmdSync = async (argv) => {
 };
 /** `reticle push` — the name people already type. One cycle, same as `reticle sync`. */
 const cmdPush = async () => cmdSync([]);
-/** Resolve THIS repo's linked cloud (url + project-scoped key). Throws a friendly error if not attached. */
+/**
+ * The linked project: its cloud, and the ID the link declares. Throws a friendly error when not
+ * attached.
+ *
+ * The id rides along for `reticle memory`, whose entire job is "what does THIS project know" and
+ * which was asking with nothing but the API key. A key covers a workspace, not a repo, so on a
+ * workspace with two repos it could print a sibling's established knowledge under this project's
+ * heading with no way for the reader to tell. See `memory-scope.ts`.
+ *
+ * The other `repoCloud()` callers below still read with the key alone. That is not an oversight
+ * being papered over: this change is scoped to the memory read, and the rest each need their own
+ * look at what the platform filters on.
+ */
 const repoCloud = async () => {
     const fs = createNodeFileSystem();
     const cloud = await resolveProjectCloud(fs, join(process.cwd(), RETICLE_DIR), homedir(), process.env);
     if (null === cloud.config)
         throw new Error(cloud.reason ?? 'cloud not attached here: run `reticle link`, or set RETICLE_API_KEY');
-    return cloud.config;
+    return { ...cloud.config, projectId: cloud.projectId };
 };
 /** `reticle runs` — the linked project's recent run artifacts (the key scopes it server-side). */
 const cmdRuns = async () => {
@@ -622,15 +694,39 @@ const cmdIssues = async (argv) => {
  * whole corpus to answer one question is the cost the sharded store was built to avoid.
  */
 const cmdMemory = async (argv) => {
-    const { url, apiKey } = await repoCloud();
+    const { url, apiKey, projectId } = await repoCloud();
     const at = argv.indexOf('--subject');
     const subject = -1 === at ? undefined : argv[at + 1];
     if (-1 !== at && subject === undefined) {
         err('usage: reticle memory [--subject <name>]');
         return 2;
     }
-    const query = subject === undefined ? '' : `?subject=${encodeURIComponent(subject)}`;
-    emit(await api('GET', `${url}/v1/memory${query}`, apiKey));
+    // Scoped to the LINKED project, on the way out AND on the way back. Without the parameter
+    // this printed whatever the key covered; without checking the response it still would, for as long
+    // as the platform ignores a parameter it does not know yet — which is exactly the window this ships
+    // in. This is the command whose whole job is "what does THIS project know", so a sibling's answer
+    // arriving under this heading is the one output nobody can tell from a correct one.
+    //
+    // The check is on the ENVELOPE and it REFUSES rather than printing. Printing an empty list would
+    // report "this project knows nothing", which is a different fact from "this response could not be
+    // shown to be about this project" and the one a person is likelier to act on. Nothing goes to
+    // stdout in that case: a caller piping this into an agent gets an error on stderr and a non-zero
+    // exit, never a plausible-looking empty answer.
+    //
+    // The refusal is the PRINTER's own, not a second check here: `scopeMemoryResponse` answers
+    // `undefined` for anything it cannot show to be this project's, so there is no ordering a future
+    // edit can get wrong — the body it must not print is one it was never handed. The verdict is read
+    // only to say WHICH refusal this is.
+    const scope = { projectId, subject };
+    const body = await api('GET', memoryReadUrl(url, scope), apiKey);
+    const printable = scopeMemoryResponse(body, projectId);
+    if (printable === undefined) {
+        err(MemoryResponseScope.OTHER === scopeOfMemoryResponse(body, projectId)
+            ? `the server answered about a different project than this repo is linked to — refusing to print another project's knowledge as this one's. Check the link with \`reticle status\`.`
+            : `the server's response does not say which project it is about, so there is no way to tell whether this is this project's knowledge. Refusing to print it; check the link with \`reticle status\`.`);
+        return 1;
+    }
+    emit(printable);
     return 0;
 };
 /** `reticle regression` — the CI gate: broken flows vs before. Exit 3 if any regressed (pipeline-friendly). */
@@ -661,6 +757,8 @@ export const runCloudCommand = async (argv) => {
                 // The linker is passed in rather than imported by cloud-login: login ends by linking and
                 // link needs a session, so the cycle is broken at this one call site.
                 return await cmdLogin(rest, cmdLink);
+            case 'connect':
+                return await cmdConnect(rest);
             case 'logout':
                 return await cmdLogout(rest);
             case 'whoami':

package/dist/command/cli/cloud-login.d.ts

@@ -4,7 +4,7 @@ type Linker = (argv: readonly string[]) => Promise<number>;
  * `reticle login` — browser device flow by default; `--email <e>` (or a positional email) keeps the
  * headless two-step code path for CI/servers where opening a browser makes no sense.
  */
-export declare const cmdLogin: (argv: readonly string[], link: Linker) => Promise<number>;
+export declare const cmdLogin: (argv: readonly string[], link: Linker, autoLink?: boolean) => Promise<number>;
 /** `reticle logout` — forget the cached session token (per-project keys under credentials.json stay). */
 /**
  * `reticle logout` — sign out of ONE host, not of everywhere.
@@ -15,4 +15,12 @@ export declare const cmdLogin: (argv: readonly string[], link: Linker) => Promis
  * one you did not mean.
  */
 export declare const cmdLogout: (argv?: readonly string[]) => Promise<number>;
+/**
+ * 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 declare function hudSignIn(onSignedIn: () => void, start?: (open: (url: string) => void) => Promise<number>, opener?: (url: string) => void): () => void;
 export {};

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

@@ -48,7 +48,7 @@ const signedInEmail = async (url, token) => {
     }
 };
 /** Persist a session token under ~/.reticle and print the next step. Shared by both login paths. */
-const writeSession = async (url, token, orgName, orgId, project, link, email) => {
+const writeSession = async (url, token, orgName, orgId, project, link, email, autoLink = true) => {
     await mkdir(join(home(), SESSIONS_DIR), { recursive: true });
     // Who signed in, so a flow saved on this machine can say which person made it (FlowFile.author).
     const who = email ?? (await signedInEmail(url, token));
@@ -65,7 +65,8 @@ const writeSession = async (url, token, orgName, orgId, project, link, email) =>
     await writeFile(sessionPath(home(), url), body);
     await writeFile(join(home(), SESSION_FILE), body);
     emit({ loggedIn: orgName, session: join(home(), SESSION_FILE) });
-    await linkAfterLogin(url, project, link);
+    if (autoLink)
+        await linkAfterLogin(url, project, link);
 };
 /**
  * Finish the job when the shell is already standing in an unlinked Reticle project.
@@ -124,17 +125,17 @@ 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) => {
+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);
         const poll = DevicePollSchema.parse(await api('POST', `${url}/v1/auth/device/token`, null, { deviceCode: started.deviceCode }));
         if ('approved' === poll.status && poll.token !== undefined && poll.org !== undefined) {
-            await writeSession(url, poll.token, poll.org.name, poll.org.id, project, link);
+            await writeSession(url, poll.token, poll.org.name, poll.org.id, project, link, undefined, autoLink);
             return 0;
         }
         if ('pending' === poll.status) {
@@ -154,12 +155,12 @@ const cmdLoginDevice = async (explicitUrl, project, link) => {
  * `reticle login` — browser device flow by default; `--email <e>` (or a positional email) keeps the
  * headless two-step code path for CI/servers where opening a browser makes no sense.
  */
-export const cmdLogin = async (argv, link) => {
+export const cmdLogin = async (argv, link, autoLink = true) => {
     const f = flags(argv);
     const positional = argv[0] !== undefined && !argv[0].startsWith('--') ? argv[0] : undefined;
     const email = f['email'] ?? positional;
     if (email === undefined)
-        return cmdLoginDevice(f['url'], f['project'], link);
+        return cmdLoginDevice(f['url'], f['project'], link, autoLink);
     const org = f['org'];
     const url = baseUrl(null, f['url']);
     let code = f['code'];
@@ -177,7 +178,7 @@ export const cmdLogin = async (argv, link) => {
         code = requested.devCode;
     }
     const parsed = LoginSchema.parse(await api('POST', `${url}/v1/auth/login`, null, { email, code }));
-    await writeSession(url, parsed.token, parsed.org.name, parsed.org.id, f['project'], link, email);
+    await writeSession(url, parsed.token, parsed.org.name, parsed.org.id, f['project'], link, email, autoLink);
     return 0;
 };
 /** `reticle logout` — forget the cached session token (per-project keys under credentials.json stay). */
@@ -199,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.
  *