@reticlehq/server 2.13.0 → 2.14.0

package/dist/cli/adhoc-verdict.js

@@ -0,0 +1,115 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { LOOPBACK_HOST, MCP_SSE_PATH } from '@reticlehq/core';
+import { TOKEN_QUERY_PARAM } from '../bridge/token-auth.js';
+import { ReticleTool } from '../tools/tool-names.js';
+/** `verified` is the only field that decides the exit code. Everything else is for the reader. */
+const PROVED = 'yes';
+function endpointFor(port, token) {
+    const url = new URL(`http://${LOOPBACK_HOST}:${String(port)}${MCP_SSE_PATH}`);
+    if (token !== undefined && token.length > 0)
+        url.searchParams.set(TOKEN_QUERY_PARAM, token);
+    return url;
+}
+async function connectOverSse(endpoint) {
+    const client = new Client({ name: 'reticle-cli', version: '1' }, { capabilities: {} });
+    await client.connect(new SSEClientTransport(endpoint));
+    return {
+        call: async (name, args) => await client.callTool({ name, arguments: args }),
+        close: async () => {
+            await client.close();
+        },
+    };
+}
+/** The verdict object an MCP tool result carries, or undefined when the shape is not one. */
+function verdictOf(result) {
+    const structured = result?.structuredContent;
+    if ('object' === typeof structured && null !== structured) {
+        return structured;
+    }
+    return undefined;
+}
+/**
+ * The tool's own words when it refused, rather than the envelope carrying them.
+ *
+ * A refusal from these tools is the most useful text they produce — it names the cause and the next
+ * action — and printing the MCP result object around it buries that in JSON escaping. The reader is
+ * at a terminal; give them the sentence.
+ */
+function refusalText(result) {
+    const r = result;
+    if (true !== r?.isError || !Array.isArray(r.content))
+        return undefined;
+    const text = r.content
+        .map((part) => part.text)
+        .filter((t) => 'string' === typeof t)
+        .join('\n');
+    if (0 === text.length)
+        return undefined;
+    // The tools answer with a JSON envelope whose `error` is the sentence; unwrap when it is one.
+    try {
+        const parsed = JSON.parse(text);
+        const inner = parsed?.error;
+        return 'string' === typeof inner ? inner : text;
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Navigate (optionally) and assert, against the daemon already on this port.
+ *
+ * Exit code 0 ONLY for `verified: "yes"`. `unknown` exits non-zero on purpose: it means Reticle could
+ * not tell what happened, and a CI step that treats "could not tell" as success is the false green
+ * this whole product exists to prevent.
+ */
+export async function runAdhocVerdict(options) {
+    const connect = options.connect ?? connectOverSse;
+    let caller;
+    try {
+        caller = await connect(endpointFor(options.port, options.token));
+    }
+    catch (error) {
+        return {
+            code: 1,
+            lines: [
+                `could not reach the daemon on port ${String(options.port)}: ${error instanceof Error ? error.message : String(error)}`,
+                'It answers `reticle status`; if that works and this does not, the daemon is older than this CLI.',
+            ],
+        };
+    }
+    try {
+        if (options.url !== undefined && options.url.length > 0) {
+            await caller.call(ReticleTool.NAVIGATE, { url: options.url });
+        }
+        const result = await caller.call(ReticleTool.ASSERT, { predicate: options.predicate });
+        const refusal = refusalText(result);
+        if (refusal !== undefined) {
+            return { code: 1, lines: [`verified: unknown`, refusal] };
+        }
+        const verdict = verdictOf(result);
+        // Narrowed rather than stringified: these arrive as `unknown` off a record, and a verdict field
+        // that is accidentally an object must not print as `[object Object]` in the one line a reader
+        // acts on.
+        const asText = (value) => 'string' === typeof value ? value : undefined;
+        const verified = asText(verdict?.['verified']);
+        const reason = asText(verdict?.['verifiedReason']) ?? asText(verdict?.['failureReason']);
+        const lines = [
+            `verified: ${verified ?? 'unknown'}`,
+            ...(reason === undefined ? [] : [`reason: ${reason}`]),
+            JSON.stringify(verdict ?? result, null, 2),
+        ];
+        return { code: PROVED === verified ? 0 : 1, lines };
+    }
+    catch (error) {
+        return {
+            code: 1,
+            lines: [
+                `the verdict could not be taken: ${error instanceof Error ? error.message : String(error)}`,
+            ],
+        };
+    }
+    finally {
+        await caller.close().catch(() => undefined);
+    }
+}

package/dist/cli/chromium-hint.d.ts

@@ -34,14 +34,28 @@ export interface ChromiumProbe {
     browsersRoot?: string | undefined;
     /** Chromium revisions actually sitting in that root, wanted or not. */
     installedRevisions?: readonly string[] | undefined;
+    /**
+     * The `node_modules` roots this process would resolve `playwright` from, nearest first.
+     *
+     * Only meaningful when playwright is ABSENT, and it is the evidence that branch was missing. The
+     * daemon usually runs from npx or a global install, so it resolves from its OWN location and not
+     * from the user's project — a reporter installed the right playwright in two project directories
+     * and kept reading "not installed", with no way to see that neither was ever searched.
+     */
+    searchedPaths?: readonly string[] | undefined;
 }
+/** The install command, pinned when we know what to pin to. */
+export declare function chromiumInstallCommand(playwrightVersion?: string): string;
 /**
- * The install command, pinned when we know what to pin to.
+ * The install-deps command, pinned the same way `chromiumInstallCommand` is.
  *
- * Unpinned is still the right fallback: a wrong-revision download is a bad outcome, but no command
- * at all is a worse one.
+ * A missing OS shared library (e.g. `libnspr4.so`) is a different failure from a missing browser
+ * binary: the binary is already there, but Playwright's own host-requirement check refuses to launch
+ * it. `npx playwright install chromium` does nothing for that case — the fix is `install-deps`, and
+ * it needs the same pin for the same reason: unpinned, `npx` can resolve a different playwright than
+ * the one the daemon bundles.
  */
-export declare function chromiumInstallCommand(playwrightVersion?: string): string;
+export declare function chromiumInstallDepsCommand(playwrightVersion?: string): string;
 /**
  * Split a resolved executable path into the browsers root and the revision under it, or null.
  *

package/dist/cli/chromium-hint.js

@@ -33,14 +33,31 @@ const CHROMIUM_DIR = /^chromium-\d+$/;
 /** The same directory name as a path segment, on either separator, so Windows paths split too. */
 const CHROMIUM_SEGMENT = /[\\/](chromium-\d+)[\\/]/;
 /**
- * The install command, pinned when we know what to pin to.
+ * Pin an `npx playwright <subcommand>` invocation to the playwright the daemon actually bundles.
  *
  * Unpinned is still the right fallback: a wrong-revision download is a bad outcome, but no command
- * at all is a worse one.
+ * at all is a worse one. Shared by `chromiumInstallCommand` and `chromiumInstallDepsCommand`, which
+ * differ only in the subcommand they need pinned.
  */
-export function chromiumInstallCommand(playwrightVersion) {
+function pinnedPlaywrightCommand(subcommand, playwrightVersion) {
     const pin = playwrightVersion === undefined ? 'playwright' : `playwright@${playwrightVersion}`;
-    return `npx ${pin} install chromium`;
+    return `npx ${pin} ${subcommand}`;
+}
+/** The install command, pinned when we know what to pin to. */
+export function chromiumInstallCommand(playwrightVersion) {
+    return pinnedPlaywrightCommand('install chromium', playwrightVersion);
+}
+/**
+ * The install-deps command, pinned the same way `chromiumInstallCommand` is.
+ *
+ * A missing OS shared library (e.g. `libnspr4.so`) is a different failure from a missing browser
+ * binary: the binary is already there, but Playwright's own host-requirement check refuses to launch
+ * it. `npx playwright install chromium` does nothing for that case — the fix is `install-deps`, and
+ * it needs the same pin for the same reason: unpinned, `npx` can resolve a different playwright than
+ * the one the daemon bundles.
+ */
+export function chromiumInstallDepsCommand(playwrightVersion) {
+    return pinnedPlaywrightCommand('install-deps chromium', playwrightVersion);
 }
 /**
  * Split a resolved executable path into the browsers root and the revision under it, or null.
@@ -79,6 +96,7 @@ function installedRevisions(root) {
  * in, which is why the probe never reads `PLAYWRIGHT_BROWSERS_PATH` itself.
  */
 export async function probeChromium() {
+    const searched = playwrightResolutionRoots();
     try {
         const { chromium } = await import('playwright');
         const executablePath = chromium.executablePath();
@@ -98,7 +116,32 @@ export async function probeChromium() {
     }
     catch {
         // Playwright itself is absent — a different problem from a missing browser, and the hint says so.
-        return { exists: false };
+        // The roots are gathered HERE rather than in the hint so the hint stays pure: this is the only
+        // place that knows which module did the resolving.
+        return { exists: false, ...(0 === searched.length ? {} : { searchedPaths: searched }) };
+    }
+}
+/**
+ * Where `import('playwright')` would look from HERE — the roots that EXIST, nearest first.
+ *
+ * The existence filter is the part that makes this evidence rather than noise. Node's ancestor chain
+ * runs to the filesystem root and its nearest entries are usually directories nobody ever created:
+ * measured from the built daemon, the two nearest are `dist/cli/node_modules` and `dist/node_modules`,
+ * and the informative one — the daemon's own `node_modules` — is third. Printing the first two
+ * unfiltered would name two paths the reader cannot check and hide the one they can.
+ *
+ * Capped after filtering, because the point is to show whether this process searched where the
+ * reader installed, not to dump the chain.
+ */
+const MAX_SEARCHED_ROOTS = 2;
+function playwrightResolutionRoots() {
+    try {
+        const roots = createRequire(import.meta.url).resolve.paths('playwright') ?? [];
+        return roots.filter((root) => existsSync(root)).slice(0, MAX_SEARCHED_ROOTS);
+    }
+    catch {
+        // An environment that cannot enumerate its own resolution paths still gets the bare verdict.
+        return [];
     }
 }
 /** The bundled playwright's version, or undefined if it cannot be read (the hint then goes unpinned). */
@@ -128,7 +171,12 @@ export function chromiumHint(probe) {
     }
     const command = chromiumInstallCommand(probe.playwrightVersion);
     if (probe.executablePath === undefined) {
-        return `✗ the playwright package is not installed; run: ${command}`;
+        // Same rule as the missing-browser line below: a verdict with nowhere to check it against reads
+        // as a broken check. The roots say whether this process even searched the directory the reader
+        // installed into — which for a daemon run from npx or a global install it usually did not.
+        const searched = probe.searchedPaths ?? [];
+        const where = 0 === searched.length ? '' : ` — looked in ${searched.join(', ')}`;
+        return `✗ the playwright package is not installed${where}; run: ${command}`;
     }
     const present = probe.installedRevisions ?? [];
     if (present.length > 0 && probe.wantedRevision !== undefined) {

package/dist/cli/cli-doctor.js

@@ -13,8 +13,7 @@ import { captureLookup, describeForeignHolder, findPortHolder } from './port-hol
 import { chromiumHint, probeChromium } from './chromium-hint.js';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
-import { diagnoseDesktop, isDesktopProject } from '../init/desktop-doctor.js';
-import { diagnoseWebCsp } from '../init/csp-doctor.js';
+import { diagnoseDesktop, isDesktopProject, diagnoseWebCsp } from '@reticlehq/init';
 import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectId, readProjectPort, } from './cli-port.js';
 import { DoctorRow, doctorRow } from './doctor-rows.js';
 import { attachState, describeAttachState } from '../mcp/attach-memory.js';

package/dist/cli/cli-flow-commands.d.ts

@@ -5,12 +5,26 @@
  * opens first. These five functions form one cohesive group: they all read the flow store and report on
  * verification state, and none of them touch daemon lifecycle, which is what the rest of cli.ts does.
  */
+import { type ChangedFiles } from '../flows/git-changed.js';
 import { type FileSystemPort } from '../project/fs-port.js';
 import { type NamedFlow } from '../flows/flow-sources.js';
 /** Load the {name, steps} of every saved flow for the active project. */
 /** Explicit files plus, when --since is given, the git-changed files since that ref. */
-export declare function resolveChangedFiles(files: string[], since: string | undefined): Promise<string[]>;
-export declare function loadNamedFlows(fs: FileSystemPort, reticleRoot: string): Promise<NamedFlow[]>;
+/**
+ * `cwd` is the tree to diff, and it is a PARAMETER because the two callers do not share one. From a
+ * terminal `process.cwd()` is the project; inside a globally-registered daemon it is `/` or `$HOME`,
+ * where `git diff` answers about the wrong repository or about none.
+ */
+export declare function resolveChangedFiles(files: string[], since: string | undefined, cwd: string): Promise<ChangedFiles>;
+/**
+ * `projectId` is a PARAMETER for the same reason `reticleRoot` already is: the two together are one
+ * address, and reading half of it from a global made them disagree. Resolved through `sessionRoot`
+ * the root named the session's project while `readProjectId(process.cwd())` named the daemon's —
+ * and a daemon started outside a project has none, so the list came back EMPTY. `affected` renders
+ * that as "no saved flows exist yet" and `verify_change` as nothing covering the change: a
+ * confident negative about somebody else's project, which is worse than an error.
+ */
+export declare function loadNamedFlows(fs: FileSystemPort, reticleRoot: string, projectId: string | undefined): Promise<NamedFlow[]>;
 /**
  * `reticle watch [url]` — on every save, report which saved flows must re-verify (the affected set).
  * Environment-side (costs the agent nothing per turn); the buddy loop. This v1 detects + reports on

package/dist/cli/cli-flow-commands.js

@@ -27,13 +27,31 @@ import { watch } from 'node:fs';
 import { log } from '../log.js';
 /** Load the {name, steps} of every saved flow for the active project. */
 /** Explicit files plus, when --since is given, the git-changed files since that ref. */
-export async function resolveChangedFiles(files, since) {
+/**
+ * `cwd` is the tree to diff, and it is a PARAMETER because the two callers do not share one. From a
+ * terminal `process.cwd()` is the project; inside a globally-registered daemon it is `/` or `$HOME`,
+ * where `git diff` answers about the wrong repository or about none.
+ */
+export async function resolveChangedFiles(files, since, cwd) {
+    // No ref means no question was asked of git, which is not a failure to answer one.
     if (since === undefined)
-        return files;
-    return [...new Set([...files, ...(await changedFilesSince(since, process.cwd()))])];
+        return { files, failed: false };
+    const changed = await changedFilesSince(since, cwd);
+    return {
+        files: [...new Set([...files, ...changed.files])],
+        failed: changed.failed,
+        ...(changed.reason === undefined ? {} : { reason: changed.reason }),
+    };
 }
-export async function loadNamedFlows(fs, reticleRoot) {
-    const projectId = readProjectId(process.cwd());
+/**
+ * `projectId` is a PARAMETER for the same reason `reticleRoot` already is: the two together are one
+ * address, and reading half of it from a global made them disagree. Resolved through `sessionRoot`
+ * the root named the session's project while `readProjectId(process.cwd())` named the daemon's —
+ * and a daemon started outside a project has none, so the list came back EMPTY. `affected` renders
+ * that as "no saved flows exist yet" and `verify_change` as nothing covering the change: a
+ * confident negative about somebody else's project, which is worse than an error.
+ */
+export async function loadNamedFlows(fs, reticleRoot, projectId) {
     const store = new FlowStore(fs, reticleRoot, { now: () => Date.now() });
     const flows = [];
     for (const name of await store.list(projectId)) {
@@ -88,7 +106,7 @@ export function handleWatch() {
             setTimeout(fn, ms).unref();
         },
         onFlush: (files) => {
-            void loadNamedFlows(fs, reticleRoot)
+            void loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()))
                 .then(async (flows) => {
                 const result = affectedSavedFlows(flows, files);
                 if (result.affected.length > 0) {
@@ -105,7 +123,7 @@ export function handleWatch() {
     });
     log('reticle_watch_started', { cwd: process.cwd() });
     // Print the ambient line once at startup so the human sees where they stand before touching anything.
-    void loadNamedFlows(fs, reticleRoot)
+    void loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()))
         .then((flows) => emitBuddyStatus(fs, reticleRoot, flows, []))
         .catch(() => undefined);
     watch(process.cwd(), { recursive: true }, (_event, filename) => {
@@ -151,8 +169,9 @@ hook = false) {
     try {
         const fs = createNodeFileSystem();
         const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
-        const changed = await resolveChangedFiles(files, since);
-        const allFlows = await loadNamedFlows(fs, reticleRoot);
+        // Same deliberate degradation as the gate: a terminal caller sees git's own error anyway.
+        const changed = (await resolveChangedFiles(files, since, process.cwd())).files;
+        const allFlows = await loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()));
         const affected = affectedSavedFlows(allFlows, changed).affected;
         const latest = await new RunStore(fs, reticleRoot).latest();
         const passing = (latest?.flows ?? [])

package/dist/cli/cli-parse-feedback.js

@@ -5,7 +5,7 @@
  * is the one command whose arguments are free text, so it is the only place in the grammar where
  * "everything that is not a flag" is a rule with edge cases rather than a one-liner.
  */
-import { FeedbackKind } from '@reticlehq/core';
+import { FeedbackKind } from '@reticlehq/core/telemetry';
 /** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
 export const RATING_FLAG = '--rating';
 export const BUG_FLAG = '--bug';

package/dist/cli/cli-parse.d.ts

@@ -13,7 +13,7 @@ export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
  * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
  * the usage block rather than being a footnote somewhere else.
  */
-export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]\n                [--flow \"<what to drive>\"] [--env KEY=VALUE]... [--files-only]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --flow names the journey worth proving, in your own words. Only you know\n                which one matters, and naming it is the difference between a drive that\n                finishes and one that spends its budget looking for something to do\n                --env is what the app needs to reach a usable state: the key from\n                .env.example, the mock backend, the variable that skips an auth wall.\n                Repeatable, and a value may contain spaces and equals signs\n                --files-only writes the files and stops, which is what init did before it\n                learned to boot the app and prove the install works\n                --license writes the key to .env and keeps .env out of git\n                --json puts the result on stdout, so an agent reads one object\n                --no-drive / --no-open / --no-agents / --url / --timeout / --drive-model\n                are the runtime dials: CI, a headless box, or an app you already run\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N]\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>] [--session-id <id>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle; runs/flows recorded on the dashboard):\n  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]\n                                                       (browser device flow by default; --email mails a code)\n  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push | sync [--watch]                        (one sync cycle: send the difference, collect decisions)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
+export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]\n                [--flow \"<what to drive>\"] [--env KEY=VALUE]... [--files-only]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --flow names the journey worth proving, in your own words. Only you know\n                which one matters, and naming it is the difference between a drive that\n                finishes and one that spends its budget looking for something to do\n                --env is what the app needs to reach a usable state: the key from\n                .env.example, the mock backend, the variable that skips an auth wall.\n                Repeatable, and a value may contain spaces and equals signs\n                --files-only writes the files and stops, which is what init did before it\n                learned to boot the app and prove the install works\n                --relaunch prints the exact command that restarts THIS conversation with\n                the tools loaded, so the restart is not a chore handed to a human. It\n                refuses when the session id has no transcript behind it, because\n                --resume on an empty id opens a blank conversation that looks like\n                success. Works with --files-only\n                --license writes the key to .env and keeps .env out of git\n                --json puts the result on stdout, so an agent reads one object\n                --no-drive / --no-open / --no-agents / --url / --timeout / --drive-model\n                are the runtime dials: CI, a headless box, or an app you already run\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N]\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>] [--session-id <id>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n                [--expect '<json predicate>']            (one verdict, no saved flows needed \u2014 asks\n                the daemon that is already running, so nothing is bound and nothing is stopped. This\n                is the path when your client never loaded the reticle_* tools. exit 0 ONLY on\n                verified:\"yes\" \u2014 \"unknown\" is not a pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle; runs/flows recorded on the dashboard):\n  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]\n                                                       (browser device flow by default; --email mails a code)\n  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push | sync [--watch]                        (one sync cycle: send the difference, collect decisions)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";
@@ -128,6 +128,7 @@ export type CliResult = {
     timeoutMs?: number;
     storageState?: string;
     sessionId?: string;
+    expect?: unknown;
 } | {
     kind: 'affected';
     files: string[];

package/dist/cli/cli-parse.js

@@ -28,6 +28,11 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
                 Repeatable, and a value may contain spaces and equals signs
                 --files-only writes the files and stops, which is what init did before it
                 learned to boot the app and prove the install works
+                --relaunch prints the exact command that restarts THIS conversation with
+                the tools loaded, so the restart is not a chore handed to a human. It
+                refuses when the session id has no transcript behind it, because
+                --resume on an empty id opens a blank conversation that looks like
+                success. Works with --files-only
                 --license writes the key to .env and keeps .env out of git
                 --json puts the result on stdout, so an agent reads one object
                 --no-drive / --no-open / --no-agents / --url / --timeout / --drive-model
@@ -43,6 +48,10 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
   reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)
   reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
   reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>] [--session-id <id>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
+                [--expect '<json predicate>']            (one verdict, no saved flows needed — asks
+                the daemon that is already running, so nothing is bound and nothing is stopped. This
+                is the path when your client never loaded the reticle_* tools. exit 0 ONLY on
+                verified:"yes" — "unknown" is not a pass)
   reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
   reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)
   reticle watch [url]                                  (on save, report which saved flows must re-verify)
@@ -233,6 +242,15 @@ export const HTTP_PORT_FLAG = '--http-port';
 export const HTTP_TOKEN_FLAG = '--http-token';
 const TIMEOUT_FLAG = '--timeout';
 const STORAGE_STATE_FLAG = '--storage-state';
+/**
+ * A predicate for a flow-free, one-shot verdict against the daemon that is already running.
+ *
+ * The dead end this removes: a client that never loaded the `reticle_*` tools had no path to a
+ * verdict at all. `verify` refused because the daemon owned the port — the normal state after a
+ * working install — the other verdict paths need saved flows a first-install project does not have,
+ * and stopping the daemon cuts the agent's own MCP link.
+ */
+const EXPECT_FLAG = '--expect';
 const SESSION_ID_FLAG = '--session-id';
 const unknownArgument = (arg) => ({
     kind: 'error',
@@ -380,6 +398,7 @@ function parseVerifySuffix(args, defaultPort) {
     let timeoutMs;
     let storageState;
     let sessionId;
+    let expect;
     let port = defaultPort;
     let i = 0;
     while (i < args.length) {
@@ -423,6 +442,23 @@ function parseVerifySuffix(args, defaultPort) {
                 return missingValue(SESSION_ID_FLAG);
             sessionId = v;
         }
+        else if (arg === EXPECT_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined)
+                return missingValue(EXPECT_FLAG);
+            try {
+                expect = JSON.parse(v);
+            }
+            catch {
+                // Named as a JSON problem rather than an unknown argument: the value IS the predicate, and
+                // "unknown argument" would send the reader looking at the flag instead of at their quoting.
+                return {
+                    kind: 'error',
+                    message: `${EXPECT_FLAG} needs a JSON predicate; could not parse: ${v}`,
+                };
+            }
+        }
         else if (arg.startsWith('--')) {
             return unknownArgument(arg);
         }
@@ -441,6 +477,7 @@ function parseVerifySuffix(args, defaultPort) {
         url,
         headless,
         port,
+        ...(expect !== undefined ? { expect } : {}),
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         ...(storageState !== undefined ? { storageState } : {}),
         ...(sessionId !== undefined ? { sessionId } : {}),
@@ -778,6 +815,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 ...(r.timeoutMs !== undefined ? { timeoutMs: r.timeoutMs } : {}),
                 ...(r.storageState !== undefined ? { storageState: r.storageState } : {}),
                 ...(r.sessionId !== undefined ? { sessionId: r.sessionId } : {}),
+                ...(r.expect !== undefined ? { expect: r.expect } : {}),
             };
         }
         case CAPSULES_COMMAND:

package/dist/cli/cli-port.d.ts

@@ -23,20 +23,12 @@ export declare const RETICLE_CONFIG_BASENAME = ".reticle.json";
  */
 export declare function findProjectConfig(cwd: string): Record<string, unknown> | undefined;
 /**
- * Ports that belong to a DEV SERVER, not to Reticle's bridge. Next defaults to 3000, Vite to 5173,
- * Astro to 4321, and so on.
- *
- * `.reticle.json`'s `port` is the bridge — the daemon ↔ SDK channel, default 4400 — and it has
- * nothing to do with the port the app is served on. Setting it to the dev-server port makes the
- * daemon try to bind the port the app already holds; what the user sees is either a bind failure or
- * a daemon that never connects, neither of which mentions the actual mistake. The old setup skill
- * asked "what port does your dev server run on?" a few lines before showing this field, which is how
- * the confusion got manufactured in the first place.
+ * The dev-server port heuristics live in `@reticlehq/init` — `existing-config.ts` is what diagnoses
+ * a `.reticle.json` whose `port` is the app's own dev-server port, and the scaffolder may not import
+ * the daemon. Re-exported here so the runtime readers (the dev-server probe, the no-session
+ * diagnosis, and `cli.ts`) are unchanged.
  */
-export declare const DEV_SERVER_PORTS: ReadonlySet<number>;
-export declare function isLikelyDevServerPort(port: number): boolean;
-/** The warning printed when a project pins the bridge to something that looks like its dev server. */
-export declare function devServerPortWarning(port: number): string;
+export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning } from '@reticlehq/init';
 /**
  * Read the port stored in the project's .reticle.json (written by `reticle init`).
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.

package/dist/cli/cli-port.js

@@ -53,45 +53,12 @@ export function findProjectConfig(cwd) {
     return undefined;
 }
 /**
- * Ports that belong to a DEV SERVER, not to Reticle's bridge. Next defaults to 3000, Vite to 5173,
- * Astro to 4321, and so on.
- *
- * `.reticle.json`'s `port` is the bridge — the daemon ↔ SDK channel, default 4400 — and it has
- * nothing to do with the port the app is served on. Setting it to the dev-server port makes the
- * daemon try to bind the port the app already holds; what the user sees is either a bind failure or
- * a daemon that never connects, neither of which mentions the actual mistake. The old setup skill
- * asked "what port does your dev server run on?" a few lines before showing this field, which is how
- * the confusion got manufactured in the first place.
+ * The dev-server port heuristics live in `@reticlehq/init` — `existing-config.ts` is what diagnoses
+ * a `.reticle.json` whose `port` is the app's own dev-server port, and the scaffolder may not import
+ * the daemon. Re-exported here so the runtime readers (the dev-server probe, the no-session
+ * diagnosis, and `cli.ts`) are unchanged.
  */
-export const DEV_SERVER_PORTS = new Set([
-    3000,
-    3001,
-    4200,
-    4321,
-    5000,
-    5173,
-    5174,
-    8000,
-    8080,
-    8100,
-    9000,
-    // Added after the scan reported "nothing is listening" at people whose app was plainly running.
-    // A narrow list is not just unhelpful, it is CONFIDENTLY wrong — the message states absence as a
-    // fact — so the defaults of the frameworks agents actually meet belong in it.
-    1420, // Tauri
-    3100, // Next, second instance
-    4173, // vite preview
-    5175, // Vite, third instance
-    7860, // Gradio
-    8501, // Streamlit
-]);
-export function isLikelyDevServerPort(port) {
-    return DEV_SERVER_PORTS.has(port);
-}
-/** The warning printed when a project pins the bridge to something that looks like its dev server. */
-export function devServerPortWarning(port) {
-    return `[reticle] .reticle.json sets "port": ${port}, which is a common DEV-SERVER port. That field is the Reticle BRIDGE port (default 4400), not the port your app is served on — they must be different, or the daemon fights your dev server for it. Remove "port" unless you are running several apps at once.`;
-}
+export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning } from '@reticlehq/init';
 /**
  * Read the port stored in the project's .reticle.json (written by `reticle init`).
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.

package/dist/cli/cli-update-commands.js

@@ -8,14 +8,12 @@
 import { checkForUpdate } from '../update/update-checker.js';
 import { updateTarget } from '../update/update-nudge.js';
 import { applyUpdate, rollback } from '../update/updater.js';
-import { refreshAgentRules } from '../init/refresh-rules.js';
+import { refreshAgentRules, detectPackageManager, buildNodeIo, SILENT_HOST } from '@reticlehq/init';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { log } from '../log.js';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { reticleDepsOf, sdkSyncCommand } from '../update/sdk-sync.js';
-import { detectPackageManager } from '../init/detect.js';
-import { buildNodeIo } from '../init/node-io.js';
 /**
  * Bring the SDK in the CURRENT project to the version being installed.
  *
@@ -34,7 +32,9 @@ function syncProjectSdk(target) {
         return; // not an app directory
     }
     const packages = reticleDepsOf(manifest);
-    const io = buildNodeIo(cwd);
+    // Nothing to trace and nothing to report: this reads the manifest and runs one package-manager
+    // command. It never enters `runInit`, so there is no init outcome for a host to carry.
+    const io = buildNodeIo(cwd, SILENT_HOST);
     const pm = detectPackageManager(new Set(io.rootFiles()), new Set(io.listDirs('node_modules')));
     const cmd = sdkSyncCommand(pm, packages, target);
     if (null === cmd) {