@reticlehq/server 3.5.0 → 3.6.0

package/dist/command/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
+import { hudSignIn } from './cli/cloud-login.js';
 import { handleSetupMcp, handleSetupInstall } from './cli/setup-mcp-cli.js';
 import { reportStepFromCli, reportTutorialShown } from './cli-onboarding.js';
 import { runDemoTour } from './cli/demo/demo-run.js';
 import { renderTutorial } from './cli/tutorial.js';
 import { pathToFileURL } from 'node:url';
-import { openFailureNote } from './cli/answers/open-note.js';
+import { openFailureNote, openLaunchFailureNote } from './cli/answers/open-note.js';
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { installCrashGuard } from './setup/setup-command.js';
@@ -15,9 +16,9 @@ import { splitBrainFields, withNextAction } from './cli/status-fields.js';
 import { reticleStateHome } from './daemon/daemon.js';
 import { handleMcp } from './cli/mcp-command.js';
 import { handleReport } from './cli/report-command.js';
-import { daemonProjectAt, resolveDaemonForProject } from './daemon/daemon-resolve.js';
+import { daemonProjectAt, readDaemonRegistry, resolveDaemonForProject, } from './daemon/daemon-resolve.js';
 import { pickDaemonPortToBind } from './daemon/binding/free-port.js';
-import { portForInit, portFromEnv } from './setup/init/init-port.js';
+import { isSameOrAbove, portForInit, portFromEnv } from './setup/init/init-port.js';
 import { daemonStartOptions } from './cli/daemon-start-options.js';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv, devServersForProject, } from '@reticlehq/core';
@@ -78,6 +79,10 @@ async function handleInit(parsed) {
         },
         daemonPresent: async (p) => presenceIsUsable(await probePresence(p, { tcpOpen: probeDaemon, status: fetchStatus })),
         pickPort: (p) => pickDaemonPortToBind(p),
+        daemonStartedHere: (p) => {
+            const started = readDaemonRegistry(reticleStateHome()).find((e) => e.port === p)?.cwd;
+            return started !== undefined && isSameOrAbove(started, cwd);
+        },
     });
     const io = buildNodeIo(cwd, serverInitHost(), { stderr: true === parsed.json });
     const result = runInit({
@@ -104,15 +109,18 @@ async function handleInit(parsed) {
 import { handleServe, handleStop, handleRestart } from './cli/lifecycle/daemon-lifecycle.js';
 import { statusLines } from './cli/status/status-lines.js';
 /**
- * Log the status event AND print it for a person.
- *
- * Both, not either: the JSON line is documented and is what a log is for, and the block is for
- * whoever is reading the terminal — which, once an agent is running the command, is somebody who
- * did not type it and cannot be assumed to parse it.
+ * 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.
  */
-function reportStatus(fields, json) {
+export function reportStatus(fields, json) {
     if (json) {
-        log('reticle_status', fields);
+        const line = JSON.stringify({
+            t: new Date().toISOString(),
+            event: 'reticle_status',
+            ...fields,
+        });
+        process.stdout.write(`${line}\n`);
         return;
     }
     process.stdout.write(`${statusLines(fields).join('\n')}\n`);
@@ -223,14 +231,13 @@ export async function handleStatus(port, json = false) {
         ...nudge,
     });
 }
-/** Print the running package version (resolved once in server-version.ts). */
+/**
+ * Print the running package version (resolved once in server-version.ts), and nothing else.
+ *
+ * Bare on stdout so `V=$(reticle version)` works. It also wrote a JSON event to stderr, which a
+ * terminal shows: the first thing a new user typed after installing answered with a log line.
+ */
 function handleVersion() {
-    log('reticle_version', { version: SERVER_VERSION });
-    // Also on stdout, bare, because every diagnostic here starts by asking which build is running and
-    // that answer has to be copyable. The event alone looked fine in a terminal -- stderr is on the
-    // screen too -- but `V=$(reticle version)` came back empty, which is exactly the shape somebody
-    // reaches for when writing an issue template or a CI check. The event stays; machine-readable
-    // events all go to stderr and that consistency is worth keeping.
     process.stdout.write(`${SERVER_VERSION}\n`);
 }
 /** `reticle license` — show enterprise activation resolved from the environment (offline; nothing leaves). */
@@ -395,9 +402,7 @@ function handleOpen(requestedPort, url) {
                 // Points at the OS handler, not at `reticle doctor`. Doctor's browser check is about
                 // Reticle's own Chromium, which this command never touches — the same misdirect the
                 // no-session note below spells out at length, left standing here for one more release.
-                recovery: 'Nothing was opened. This command asks the OS to open a url in your default browser ' +
-                    `(\`${openCommand(decision.url, process.platform).cmd}\` on this platform) and that ` +
-                    'failed, so the fix is on the OS side: open the url yourself, or set a default browser.',
+                recovery: openLaunchFailureNote(decision.url, openCommand(decision.url, process.platform).cmd),
             });
             process.exit(1);
             return;
@@ -431,7 +436,8 @@ function handleOpen(requestedPort, url) {
     });
 }
 function handleDaemonInner(parsed) {
-    const options = daemonStartOptions(parsed);
+    // The daemon the CLI starts is the one that can sign in for the panel: it owns ~/.reticle.
+    const options = { ...daemonStartOptions(parsed), hudSignIn };
     startDaemon(options)
         .then((server) => {
         log('reticle_daemon_ready', { port: parsed.port, pid: process.pid });
@@ -722,7 +728,7 @@ export function main() {
             handleOpen(parsed.port, parsed.url);
             break;
         case 'drive':
-            handleDrive(parsed);
+            handleDrive(parsed, readProjectId(process.cwd()));
             break;
         case 'verify':
             handleVerify(parsed);

package/dist/command/daemon/binding/daemon-status-probe.d.ts

@@ -15,6 +15,8 @@ interface StatusSession {
     sessionId: string;
     url: string;
     projectId?: string;
+    /** The page's own title. Absent when the page has none, or on a daemon too old to send it. */
+    title?: string;
     throttled: boolean;
     /**
      * The tab is backgrounded. Reported by the daemon on every session; `false` on one too old to say,

package/dist/command/daemon/binding/daemon-status-probe.js

@@ -102,6 +102,7 @@ export function summarizeStatus(payload) {
             ...('string' === typeof r['projectId'] && 0 < r['projectId'].length
                 ? { projectId: r['projectId'] }
                 : {}),
+            ...('string' === typeof r['title'] && 0 < r['title'].length ? { title: r['title'] } : {}),
             throttled: true === r['throttled'],
             hidden: true === r['hidden'],
             stale: true === r['stale'],

package/dist/command/daemon/daemon-resolve.d.ts

@@ -76,6 +76,20 @@ export declare function daemonProjectAt(port: number, home: string): string | un
  * Only LIVE daemons are named: a port a session used yesterday is history, not a split.
  */
 export declare function daemonsServingProjectElsewhere(projectId: string | undefined, myPort: number, home: string, alive: (pid: number) => boolean, connectedOn: (port: number) => boolean): readonly number[];
+/** Live daemons that serve a named project, on any port but `myPort`. */
+export declare function projectDaemonsElsewhere(myPort: number, home: string, alive: (pid: number) => boolean): {
+    port: number;
+    projectId: string;
+}[];
+/**
+ * The sentence for a daemon started outside any project while projects run their own daemons, or
+ * `undefined` when there are none. Its sessions are empty because the apps dial their own ports,
+ * and "check your scope" is not something an agent inside an editor can act on (#1240).
+ */
+export declare function projectlessNote(myPort: number, others: readonly {
+    port: number;
+    projectId: string;
+}[]): string | undefined;
 /**
  * The sentence for a split brain, or `undefined` when there is none.
  *

package/dist/command/daemon/daemon-resolve.js

@@ -19,6 +19,8 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DaemonRegistryEntrySchema, daemonRegistryPort, pickDaemonPort, } from '@reticlehq/core/artifacts';
+import { ReticleEnv } from '@reticlehq/core';
+const RETICLE_PORT_ENV = ReticleEnv.PORT;
 /**
  * Every well-formed registry entry in `home`.
  *
@@ -117,6 +119,30 @@ export function daemonsServingProjectElsewhere(projectId, myPort, home, alive, c
         .map((entry) => entry.port)
         .sort((a, b) => a - b);
 }
+/** Live daemons that serve a named project, on any port but `myPort`. */
+export function projectDaemonsElsewhere(myPort, home, alive) {
+    return readDaemonRegistry(home)
+        .filter((entry) => entry.port !== myPort && alive(entry.pid))
+        .flatMap((entry) => entry.projectId === undefined || 0 === entry.projectId.length
+        ? []
+        : [{ port: entry.port, projectId: entry.projectId }])
+        .sort((a, b) => a.port - b.port);
+}
+/**
+ * The sentence for a daemon started outside any project while projects run their own daemons, or
+ * `undefined` when there are none. Its sessions are empty because the apps dial their own ports,
+ * and "check your scope" is not something an agent inside an editor can act on (#1240).
+ */
+export function projectlessNote(myPort, others) {
+    const first = others[0];
+    if (first === undefined)
+        return undefined;
+    const listed = others.map((o) => `${o.projectId} on :${String(o.port)}`).join(', ');
+    return (`this daemon on :${String(myPort)} was started outside any project, and the projects on this ` +
+        `machine run their own daemons: ${listed}. Their apps connect there, not here. Point the MCP ` +
+        `server at one — set ${RETICLE_PORT_ENV}=${String(first.port)} in its config, or launch it from ` +
+        'that project directory.');
+}
 /**
  * The sentence for a split brain, or `undefined` when there is none.
  *
@@ -179,8 +205,13 @@ export async function resolveMcpPort(preferred, projectId, home, deps) {
     const mine = resolveDaemonForProject(projectId, home, deps.alive);
     if (mine !== undefined)
         return mine;
-    if (!(await deps.daemonPresent(preferred)))
-        return preferred;
+    if (!(await deps.daemonPresent(preferred))) {
+        // A caller outside any project (an editor's user-scope MCP, launched from $HOME) used to dial the
+        // default and never see the one project that had moved off it (#1240). With exactly one project
+        // daemon live, that is the one; with several, the no-session answer names them instead.
+        const projects = projectId === undefined ? projectDaemonsElsewhere(preferred, home, deps.alive) : [];
+        return 1 === projects.length ? (projects[0]?.port ?? preferred) : preferred;
+    }
     return adoptable(daemonProjectAt(preferred, home), projectId)
         ? preferred
         : deps.pickPort(preferred);

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

@@ -34,7 +34,7 @@ interface AgentWriteResult {
  */
 export declare function applyAgentPlan(plan: readonly AgentPlanStep[], io: AgentWriterIo): AgentWriteResult[];
 /** The `/reticle` instruction, for agents that load skills from a directory. */
-export declare const RETICLE_SKILL = "---\nname: reticle\ndescription: Verify a change against the running app, from inside it, before calling it done.\n---\n\nReticle exposes the running app to you as `reticle_*` MCP tools. Look, act, observe, assert.\n\nOnly `reticle_act_and_wait` and `reticle_assert` produce a verdict. Everything else moves or\nreads the app and proves nothing, so a drive that ends without one of those has no result however\nmany tools it used.\n\n`verified: \"unknown\"` is not a pass: it means Reticle could not tell what happened.\n`verified: \"no-fault\"` is not a pass either, because nothing was declared to prove. Never weaken a\ncheck to make it pass.\n\nThe cheapest path that answers the question:\n\n- \"did my edit break anything?\" -> `reticle_verify { action: \"change\", files: [...] }`\n- \"does this known journey still work?\" -> `reticle_verify { action: \"flows\", names: [\"...\"] }`\n- \"does this new behaviour work?\" -> `reticle_act { steps: [...] }` for the setup, then ONE `reticle_act_and_wait`\n- \"nothing is recorded yet\" -> `reticle_verify { action: \"explore\", persona: \"<who does what>\" }`, which\n  drives the app and SAVES what it drove, so the next run replays with no model in the loop\n";
+export declare const RETICLE_SKILL = "---\nname: reticle\ndescription: Verify a change against the running app, from inside it, before calling it done.\n---\n\nReticle exposes the running app to you as `reticle_*` MCP tools. Look, act, observe, assert.\n\nOnly `reticle_act_and_wait` and `reticle_assert` produce a verdict. Everything else moves or\nreads the app and proves nothing, so a drive that ends without one of those has no result however\nmany tools it used.\n\n`verified: \"unknown\"` is not a pass: it means Reticle could not tell what happened.\n`verified: \"no-fault\"` is not a pass either, because nothing was declared to prove. Never weaken a\ncheck to make it pass.\n\nThe cheapest path that answers the question:\n\n- \"did my edit break anything?\" -> `reticle_verify { action: \"change\", files: [...] }`\n- \"does this known journey still work?\" -> `reticle_verify { action: \"flows\", names: [\"...\"] }`\n- \"does this new behaviour work?\" -> `reticle_act { steps: [...] }` for the setup, then ONE `reticle_act_and_wait`\n- \"nothing is recorded yet\" -> drive the journey yourself with `reticle_act_and_wait` and an `until` on its\n  last step; it is saved as a flow, so the next run replays with no model in the loop. With a linked\n  project, `reticle_verify { action: \"explore\", persona: \"<who does what>\" }` drives it for you\n";
 interface SkillWriteResult {
     readonly id: string;
     readonly file: string;

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

@@ -84,8 +84,9 @@ The cheapest path that answers the question:
 - "did my edit break anything?" -> \`reticle_verify { action: "change", files: [...] }\`
 - "does this known journey still work?" -> \`reticle_verify { action: "flows", names: ["..."] }\`
 - "does this new behaviour work?" -> \`reticle_act { steps: [...] }\` for the setup, then ONE \`reticle_act_and_wait\`
-- "nothing is recorded yet" -> \`reticle_verify { action: "explore", persona: "<who does what>" }\`, which
-  drives the app and SAVES what it drove, so the next run replays with no model in the loop
+- "nothing is recorded yet" -> drive the journey yourself with \`reticle_act_and_wait\` and an \`until\` on its
+  last step; it is saved as a flow, so the next run replays with no model in the loop. With a linked
+  project, \`reticle_verify { action: "explore", persona: "<who does what>" }\` drives it for you
 `;
 /**
  * Write the skill for agents that have somewhere to put it, and only where they are installed.

package/dist/command/setup/bringup/connect-lease.d.ts

@@ -9,6 +9,7 @@
 /** A lease this run opened, and the way to hand it back; or why it could not be opened. */
 type LeaseOutcome = {
     readonly sessionId: string;
+    readonly zeroInstall: boolean;
     readonly release: () => Promise<void>;
 } | {
     readonly failed: string;

package/dist/command/setup/bringup/connect-lease.js

@@ -25,6 +25,7 @@ export async function openLeaseFor(port, url, token) {
         }
         return {
             sessionId: got.leased,
+            zeroInstall: got.zeroInstall,
             release: async () => {
                 await releaseLease(caller, got.leased);
                 await close();

package/dist/command/setup/bringup/dev-server-wait.d.ts

@@ -59,6 +59,14 @@ export declare const WAIT_CEILING_MS: number;
  */
 export declare function judgeWait(facts: WaitFacts): WaitVerdict;
 export declare function portBusyMessage(output: string): string | undefined;
+/**
+ * The dev server died before serving: say so, and quote the end of what it printed.
+ *
+ * Without the tail the reason was invisible: a missing `vite` binary printed `vite: command not
+ * found` to its own log, setup said only "exited without serving anything", and its first remedy
+ * ("start the dev server yourself") failed the same way.
+ */
+export declare function devServerDiedMessage(output: string): string;
 export declare function announcedUrl(output: string): string | undefined;
 /**
  * The url to watch: whatever the tool announced, else one composed from a port we OBSERVED our own

package/dist/command/setup/bringup/dev-server-wait.js

@@ -61,6 +61,25 @@ export function portBusyMessage(output) {
     return (`port ${port} is already in use — something else is serving there, so this launcher did not ` +
         `bind. Pass --url http://localhost:${port} if that process is this app, or free the port and re-run.`);
 }
+/** How many of the dev server's last lines a failure quotes. Enough for a stack's first frames. */
+const DIED_TAIL_LINES = 6;
+/**
+ * The dev server died before serving: say so, and quote the end of what it printed.
+ *
+ * Without the tail the reason was invisible: a missing `vite` binary printed `vite: command not
+ * found` to its own log, setup said only "exited without serving anything", and its first remedy
+ * ("start the dev server yourself") failed the same way.
+ */
+export function devServerDiedMessage(output) {
+    const tail = output
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => 0 < line.trim().length)
+        .slice(-DIED_TAIL_LINES);
+    return 0 === tail.length
+        ? 'The dev server exited without serving anything, and printed nothing.'
+        : `The dev server exited without serving anything. The last it printed:\n${tail.map((line) => `    ${line}`).join('\n')}`;
+}
 /** A url the dev server announced, if it has announced one. Never composed, only read. */
 const URL_IN_OUTPUT = /https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d+/;
 export function announcedUrl(output) {

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

@@ -12,4 +12,8 @@ export declare function portForInit(explicit: number | undefined, configured: nu
     daemonProjects: (port: number) => Promise<readonly string[]>;
     daemonPresent: (port: number) => Promise<boolean>;
     pickPort: (preferred: number) => Promise<number>;
+    /** The daemon on `port` was started from this project's directory or one above it. */
+    daemonStartedHere?: (port: number) => boolean;
 }): Promise<number | undefined>;
+/** Is `dir` the same directory as `cwd`, or an ancestor of it? */
+export declare function isSameOrAbove(dir: string, cwd: string): boolean;

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

@@ -8,6 +8,7 @@
  *
  * Undefined means the default.
  */
+import { relative, isAbsolute } from 'node:path';
 import { RETICLE_DEFAULT_PORT, ReticleEnv } from '@reticlehq/core';
 const MAX_PORT = 65_535;
 /**
@@ -34,6 +35,10 @@ export async function portForInit(explicit, configured, projectId, deps) {
     // config as a `port` nobody chose.
     if (!(await deps.daemonPresent(RETICLE_DEFAULT_PORT)))
         return undefined;
+    // Started here — by this project's own editor MCP, typically — so it is ours whatever project id
+    // it recorded. Moving off it strands that agent: an MCP resolves its port once, at startup.
+    if (true === deps.daemonStartedHere?.(RETICLE_DEFAULT_PORT))
+        return undefined;
     // The bridge's own rule: it refuses a page only when it has served exactly ONE other project. A
     // daemon serving nobody, several projects, or ours accepts this one. A project that has never
     // been through init has no id yet, so a single named holder is somebody else.
@@ -42,3 +47,8 @@ export async function portForInit(explicit, configured, projectId, deps) {
         return undefined;
     return deps.pickPort(RETICLE_DEFAULT_PORT + 1);
 }
+/** Is `dir` the same directory as `cwd`, or an ancestor of it? */
+export function isSameOrAbove(dir, cwd) {
+    const rel = relative(dir, cwd);
+    return '' === rel || (!rel.startsWith('..') && !isAbsolute(rel));
+}

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

@@ -6,6 +6,16 @@
  * every command harder to read.
  */
 import { type InitResult } from '@reticlehq/init';
+/**
+ * Does the served document name the SDK, so its absence means a stale dev server?
+ *
+ * A Next App Router page names its client components in the flight data inlined into the HTML —
+ * `reticle-dev.tsx`, measured on Next 16 under Turbopack and webpack alike. Reported from a Next app
+ * whose dev server was already running before init: setup waited on a page that could never connect
+ * and said nothing, because Next was assumed to carry the SDK only in its bundle. The Pages Router
+ * names chunks, not modules, so it stays silent.
+ */
+export declare function htmlCarriesSdk(framework: string, exists: (path: string) => boolean): boolean;
 /** Just enough of the parsed command to decide and run. */
 interface InitRuntimeArgs {
     readonly port: number | undefined;

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

@@ -6,6 +6,7 @@
  * every command harder to read.
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { FEEDBACK_HINT, Framework, InitFailure } from '@reticlehq/init';
 import { confirmInstall, nodeConfirmDeps } from '../terminal/confirm.js';
@@ -30,6 +31,22 @@ const POLL_MS = 250;
  * of the document can never see it. See `htmlCarriesSdk` in run-setup.ts.
  */
 const HTML_CARRIES_SDK = new Set([Framework.VITE, Framework.HTML]);
+/** The connect component `init` writes for a Next App Router project. */
+const NEXT_APP_CONNECT = ['app', 'src/app'].flatMap((d) => ['tsx', 'jsx', 'js'].map((ext) => `${d}/reticle-dev.${ext}`));
+/**
+ * Does the served document name the SDK, so its absence means a stale dev server?
+ *
+ * A Next App Router page names its client components in the flight data inlined into the HTML —
+ * `reticle-dev.tsx`, measured on Next 16 under Turbopack and webpack alike. Reported from a Next app
+ * whose dev server was already running before init: setup waited on a page that could never connect
+ * and said nothing, because Next was assumed to carry the SDK only in its bundle. The Pages Router
+ * names chunks, not modules, so it stays silent.
+ */
+export function htmlCarriesSdk(framework, exists) {
+    if (HTML_CARRIES_SDK.has(framework))
+        return true;
+    return Framework.NEXT === framework && NEXT_APP_CONNECT.some(exists);
+}
 /** Registration is global MCP wiring, so both flags that disown it are read here. */
 function wantsAgents(parsed) {
     return false !== parsed.agents && false !== parsed.mcp;
@@ -160,7 +177,7 @@ export async function continueAfterInit(parsed, result, io, cwd) {
                 startupBudgetMs: parsed.timeoutSeconds * 1000,
             }),
         pollMs: POLL_MS,
-        htmlCarriesSdk: HTML_CARRIES_SDK.has(context.framework),
+        htmlCarriesSdk: htmlCarriesSdk(context.framework, (rel) => existsSync(join(context.appDir, rel))),
         // A plain page with no dev script gets Reticle's own static server, so the page is actually
         // served and the connect can be proved, instead of stopping at "start the app yourself".
         ...(() => {

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

@@ -106,7 +106,8 @@ export class OwnedDevServer {
         catch {
             /* not written yet */
         }
-        return Date.now() - lastOutputAt;
+        // Filesystem timestamps can include a fractional millisecond beyond Date.now()'s integer.
+        return Math.max(0, Date.now() - lastOutputAt);
     }
     /** Ports anything in this server's process tree is listening on. */
     listeningPorts() {

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

@@ -34,7 +34,8 @@ export function remainingSteps(p) {
             '`reticle_*` tools, ending in `reticle_act_and_wait` or `reticle_assert` — those two are ' +
             'what produce a verdict. Or hand the whole drive to Reticle with `reticle_verify { action: ' +
             '"explore", persona: "<who does what>" }`, which records what it drove so later runs replay ' +
-            'with no model in the loop; that route needs ANTHROPIC_API_KEY.');
+            'with no model in the loop; that route runs on the Reticle platform and needs a linked ' +
+            'project (`reticle connect`); every plan, Free included, has monthly Harness credits.');
     }
     // Whether anything is actually outstanding, read BEFORE the docs pointer is added -- that line is
     // an offer, not a task, and a run with nothing left still gets it.

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

@@ -55,6 +55,11 @@ export interface DaemonReason {
 export interface OwnedBrowser {
     readonly sessionId: string;
     readonly release: () => Promise<void>;
+    /**
+     * The page never dialled in, so the lease injected Reticle's own reader. That session proves the
+     * reader, not this install, and must never end onboarding as "connected".
+     */
+    readonly zeroInstall?: boolean;
 }
 export interface SetupEffects {
     /** Start the dev server. Resolves once started; the caller owns stopping it. */

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

@@ -13,7 +13,7 @@
  * way of going wrong, and the alternative to injecting them is a test that boots a real dev server
  * and a real browser to find out what happens when neither works.
  */
-import { judgeWait, portBusyMessage, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict, } from './bringup/dev-server-wait.js';
+import { judgeWait, devServerDiedMessage, portBusyMessage, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict, } from './bringup/dev-server-wait.js';
 import { connectProgressLine, waitProgressLine } from './terminal/wait-progress.js';
 /**
  * Windows gets longer to say something before silence counts as a wedge.
@@ -177,18 +177,20 @@ export async function runSetupPhases(input, fx) {
                     break;
                 }
                 if (WaitVerdict.DEAD === verdict) {
-                    note(portBusyMessage(fx.devServerOutput()) ??
-                        'The dev server exited without serving anything.');
+                    note(portBusyMessage(fx.devServerOutput()) ?? devServerDiedMessage(fx.devServerOutput()));
                     return stop(input, SetupPhase.DEV_SERVER, {}, notes);
                 }
                 if (WaitVerdict.HUNG === verdict) {
                     // Says BOTH were checked. A server that prints nothing but IS listening is the CRA case and
                     // must not be failed, so a reader has to be able to tell "we looked at the log" from "we
                     // looked at the log AND the ports".
-                    note((input.startupBudgetMs !== undefined && fx.now() - startedAt >= input.startupBudgetMs
-                        ? `The dev server did not become ready within ${String(input.startupBudgetMs)}ms. `
-                        : undefined === watching
-                            ? 'The dev server neither printed a URL nor bound a port, so setup has nothing to open. '
+                    const within = input.startupBudgetMs !== undefined && fx.now() - startedAt >= input.startupBudgetMs
+                        ? ` within ${String(input.startupBudgetMs)}ms`
+                        : undefined;
+                    note((undefined === watching
+                        ? `The dev server neither printed a URL nor bound a port${within ?? ''}, so setup has nothing to open. `
+                        : undefined !== within
+                            ? `The dev server did not become ready${within}. `
                             : `The dev server stopped making progress before ${watching} became ready. `) +
                         'Check its log, increase --timeout for a slow build, or pass --url with the address it serves.');
                     return stop(input, SetupPhase.DEV_SERVER, {}, notes);
@@ -232,6 +234,23 @@ export async function runSetupPhases(input, fx) {
     // dialled the bridge" over a correct install. With a lease to fall back on it is entered too, and
     // only the system browser is skipped.
     const canLease = undefined !== fx.openLease;
+    const injected = new Set();
+    /**
+     * The lease to keep, or undefined. A lease whose page only connected through Reticle's injected
+     * reader is handed straight back and its session excluded: it would otherwise be picked below and
+     * report a plain server with no SDK as an instrumented app.
+     */
+    const keepLease = async (owned) => {
+        if ('failed' in owned) {
+            note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
+            return undefined;
+        }
+        if (true !== owned.zeroInstall)
+            return owned;
+        injected.add(owned.sessionId);
+        await releaseLease(owned);
+        return undefined;
+    };
     if (null === alreadyConnected && policy.openBrowser && (input.openBrowser || canLease)) {
         // SERVED is the precondition, not SDK_PRESENT: a url that answers nothing is the only state
         // where a window is certainly useless. Whether the SDK is in the served HTML is a DIFFERENT
@@ -260,14 +279,9 @@ export async function runSetupPhases(input, fx) {
             const launcherFailed = input.openBrowser ? await fx.openBrowser(url) : undefined;
             openedBrowser = input.openBrowser;
             if (undefined !== fx.openLease && (!input.openBrowser || undefined !== launcherFailed)) {
-                const owned = await fx.openLease(url);
-                if ('failed' in owned) {
-                    note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
-                }
-                else {
-                    lease = owned;
+                lease = await keepLease(await fx.openLease(url));
+                if (undefined !== lease)
                     openedBrowser = true;
-                }
             }
         }
     }
@@ -288,7 +302,8 @@ export async function runSetupPhases(input, fx) {
     while (null === session) {
         // On a desktop app, only the desktop window counts. AppShape and the runtime a page reports use
         // the same three names, so the shape IS the requirement — see session-pick.
-        session = pickSession(await fx.listSessions(), url, before, requiredRuntime);
+        const listedNow = (await fx.listSessions()).filter((s) => !injected.has(s.sessionId));
+        session = pickSession(listedNow, url, before, requiredRuntime);
         if (null !== session)
             break;
         if (deadline <= fx.now())
@@ -301,13 +316,7 @@ export async function runSetupPhases(input, fx) {
             !isDesktop(input.shape) &&
             fx.now() - waitStartedAt >= SYSTEM_BROWSER_GRACE_MS) {
             leaseFallbackTried = true;
-            const owned = await fx.openLease(url);
-            if ('failed' in owned) {
-                note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
-            }
-            else {
-                lease = owned;
-            }
+            lease = await keepLease(await fx.openLease(url));
             continue;
         }
         // Not in silence: a desktop run used to print one line and then nothing for ten minutes.
@@ -368,9 +377,8 @@ export async function runSetupPhases(input, fx) {
     // `<url>` stays a placeholder in this string on purpose: `guidance-commands-run` feeds every
     // command we print to the real parser, and an interpolated value reads there as a missing operand.
     // The live url is named in the sentence instead, where a reader needs it anyway.
-    // Both routes, because `explore` needs a model: without ANTHROPIC_API_KEY it answers "No model
-    // configured to drive the app". Naming only that one hands the reader a dead end on any machine
-    // without a key, which is the same defect this release spent its time removing everywhere else.
+    // Both routes, because `explore` runs on the platform: without a linked project it refuses.
+    // Naming only that one hands the reader a dead end on any machine without one.
     // A heading and a numbered list rather than one paragraph: a reader scans for what to do next.
     //
     // This was a single 524-character note, measured on a real first run: eighty-three words, no
@@ -390,8 +398,8 @@ export async function runSetupPhases(input, fx) {
     note('  1. Drive one flow and end it with `reticle_act_and_wait` or `reticle_assert`. Those two ' +
         'produce a verdict; nothing else does.');
     note('  2. Or hand over the whole drive: `reticle_verify { action: "explore", persona: "<who does ' +
-        'what>" }` records what it drove, so later runs replay with no model in the loop. Needs ' +
-        'ANTHROPIC_API_KEY.');
+        'what>" }` records what it drove, so later runs replay with no model in the loop. Runs on ' +
+        'the Reticle platform: needs a linked project (`reticle connect`); Free includes monthly Harness credits.');
     return {
         ok: true,
         reachedPhase: SetupPhase.CONNECT,

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

@@ -30,7 +30,8 @@ interface SetupCommandInput extends Omit<SetupInput, 'shape'> {
     /** The bridge's pairing token, for the MCP transport a connect-proof lease is opened over. */
     readonly pairingToken?: string | undefined;
 }
-export declare function registerOtherAgents(print: (line: string) => void): void;
+/** Returns how many agents it wrote a config for, so a caller does not then say "none found". */
+export declare function registerOtherAgents(print: (line: string) => void): number;
 type SetupCommandResult = SetupOutcome;
 export declare function runSetupCommand(input: SetupCommandInput, print: (line: string) => void): Promise<SetupCommandResult>;
 export {};

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

@@ -89,6 +89,7 @@ function hasElectronDependency(dir) {
  */
 /** `agent`, `agents`. */
 const agentWord = (n) => (1 === n ? 'agent' : 'agents');
+/** Returns how many agents it wrote a config for, so a caller does not then say "none found". */
 export function registerOtherAgents(print) {
     const platform = process.platform;
     const home = homedir();
@@ -124,6 +125,7 @@ export function registerOtherAgents(print) {
     for (const noted of approvals.filter((a) => undefined !== a.warn)) {
         print(`  ⚠ ${noted.name}: ${String(noted.warn)}`);
     }
+    return wrote.length;
 }
 /**
  * Run the phases against the real world.

package/dist/command/version/version-skew.js

@@ -22,6 +22,7 @@
  * the wire changes and stays put when internals do. Versions still ride along, because they are what
  * a human acts on.
  */
+import { RETIRED_WIRE_NAMES } from '@reticlehq/core';
 import { resolveSdkFix } from './sdk-fix.js';
 /** Which pair disagreed. Named so the nudge can report each independently. */
 export const SkewPair = {
@@ -38,13 +39,15 @@ export const SkewPair = {
  * is not a browser to do -- there is no touch equivalent of a console error. A peer speaking a name
  * we do not know was built against a contract this daemon does not have, and that is a genuine
  * mismatch: one of us is stale, and tools will behave in ways neither side reports.
+ *
+ * A name we RETIRED is not unknown: an older peer still lists it, and we never send it (#1343).
  */
 function namesWeDoNotKnow(peer, self) {
     const unknown = [
         ...peer.commands.filter((name) => !self.commands.includes(name)),
         ...peer.events.filter((name) => !self.events.includes(name)),
         ...peer.actions.filter((name) => !self.actions.includes(name)),
-    ];
+    ].filter((name) => !RETIRED_WIRE_NAMES.includes(name));
     return [...new Set(unknown)].sort();
 }
 function versionPhrase(peer, self) {
@@ -77,8 +80,14 @@ export function describeSkew(peer, self) {
         const unknown = namesWeDoNotKnow(peer.contractParts, self.contractParts);
         if (0 === unknown.length)
             return undefined;
+        // Direction comes from the versions when both are known. An older peer naming something we do
+        // not know has a name we removed without retiring it, not a newer contract.
+        const order = compareVersions(peer.version, self.version);
+        const why = order !== undefined && order < 0
+            ? 'though it is the older of the two — so this daemon dropped a name it still uses'
+            : 'so it was built against a newer contract than this one';
         return (`version skew: ${versionPhrase(peer, self)}, and ${peer.what} speaks names this daemon does ` +
-            `not know (${unknown.join(', ')}) — so it was built against a newer contract than this one. ` +
+            `not know (${unknown.join(', ')}) — ${why}. ` +
             `Tools will behave in ways neither side reports. ${peer.fix}`);
     }
     if (peer.contract === undefined) {