@reticlehq/server 2.8.0 → 2.10.0

package/dist/session/no-session-diagnosis.js

@@ -19,6 +19,9 @@
  * the hot resolve() path and this stays unit-testable.
  */
 import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
+import { STALL_AFTER_MS } from '../telemetry/instrumentation-stall.js';
+/** The one framework whose most likely cause differs from every other framework's. */
+const NUXT = 'nuxt';
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session
  * recovery: a message that already carries its own next action must not be handed a second, more
@@ -40,6 +43,21 @@ const RETRY = SELF_RECOVERING_MARKER;
  * Only offered when the app is known to carry the SDK: leasing an uninstrumented app just burns a
  * browser and comes back `ready:false`.
  */
+/**
+ * The no-shell path, for the branches where a BLIND lease would be wrong.
+ *
+ * A lease opens a URL, so offering one while nothing is listening is offering to open nothing —
+ * which is why these branches deliberately withheld it, and a test pins that. But withholding it
+ * left an agent with no CLI holding no path at all: reported from Windows, where the MCP server was
+ * registered and every tool advertised while no `reticle` binary existed on disk, so every remedy
+ * offered was a shell command that could not be run.
+ *
+ * The resolution is the ORDER, not the offer. Get the URL first — which these branches already tell
+ * the reader to do — and then the lease is the way to open it without a shell.
+ */
+const URL_THEN_LEASE = 'Once you have that URL, open it with reticle_lease {action:"acquire", url} rather than a shell ' +
+    'command — it needs no CLI on PATH (reach it with reticle_run {tool:"reticle_lease"} if it is ' +
+    'not advertised directly).';
 const SELF_SERVE = 'You do not have to wait for the human: reticle_lease {action:"acquire", url} opens a browser ' +
     'Reticle drives itself, and returns a sessionId you can use immediately (reach it with ' +
     'reticle_run {tool:"reticle_lease"} if it is not advertised directly; release it when you finish).';
@@ -66,9 +84,82 @@ const SELF_SERVE = 'You do not have to wait for the human: reticle_lease {action
  */
 const NON_LOCALHOST_GATE = 'One more cause that leaves every other check healthy: if the app is served on anything other ' +
     'than localhost (a hosts-file alias, a LAN IP, a tunnel), the SDK refuses to connect unless it ' +
-    'is given `allowNonLocalhost: true` — the refusal is page-side, so nothing here can see it. ' +
-    "Check the browser console for that message and pass the flag in the app's reticle.connect().";
+    'is given `allowNonLocalhost: true` AND a pairing token — the flag alone is NOT sufficient off ' +
+    'localhost, which cost one reporter their whole setup until they read our compiled SDK by hand. ' +
+    'The token is the one in `~/.reticle/pairing-token`, passed as `token` to the same connect(). ' +
+    'The refusal is page-side, so nothing here can see it: check the browser console for that ' +
+    "message and pass both in the app's reticle.connect().";
+/**
+ * The causes that actually occurred in the field, for an app that is wired and still silent.
+ *
+ * Every one of these is indistinguishable from "no SDK installed" from every surface an agent can
+ * reach, and the old message modelled none of them — it modelled a missing SDK and a wrong port, and
+ * across a batch of reports on four apps the port was right every time. An agent that is told the
+ * wrong differential does not merely waste calls: several of these reports end with the agent
+ * telling its human that Reticle was not set up, on an app that was correctly wired.
+ */
+const REAL_CAUSES = 'Causes that produce exactly this and are NOT a port problem, in the order they actually occur: ' +
+    '(a) the SDK is in the bundle but `connect()` is never reached — a dev-mode guard or a missing ' +
+    'runtime-config value returning early, which emits nothing at all, so grep the app for the ' +
+    'connect call and confirm it runs; (b) the dev server was started BEFORE the Reticle plugin was ' +
+    'added, so it is not in the bundle at all — restart the dev server, do not rely on HMR; ' +
+    '(c) a peer dependency is missing, typically `@reticlehq/react` in a non-React app, so the ' +
+    "dynamic import fails silently; (d) this daemon's working directory is not the project, so it is " +
+    'scoped to the wrong app entirely — check the directory named above is really where your app ' +
+    'lives.';
+/** Nuxt's most likely cause is (b), and Nuxt is the framework where it is nearly certain. */
+const NUXT_STALE_BUNDLE = 'This project is Nuxt: the most likely cause by a distance is a dev server that predates the ' +
+    'Reticle plugin. Nuxt does NOT register a newly added plugin on HMR, so the running bundle ' +
+    'carries no SDK however correct the config is — STOP and restart `nuxt dev`, then reload the ' +
+    'page, before investigating anything else.';
+/**
+ * The lead when durable state proves this project has connected on this port before.
+ *
+ * The daemon used to contradict itself inside one response: `reticle_sessions` said a session HAD
+ * connected earlier "so the wiring is correct", and a lease seconds later said the usual cause was a
+ * port mismatch. It already held the evidence against its own hint.
+ */
+const RESTARTED_LEAD = 'no browser session connected. This daemon has served none since it started, but it is a NEW ' +
+    'process — an app for this project HAS connected on this port before, which is recorded ' +
+    'durably. So the wiring is correct and the port is correct: what is failing now is the SDK ' +
+    'reaching initialise on the page. Re-running the install is the wrong move here: it cannot help ' +
+    'on a project that has demonstrably connected, and it can overwrite a working config.';
 const SCANNED_PORTS = [...DEV_SERVER_PORTS].join(', ');
+/**
+ * How to say "open the app" to an agent that may have no `reticle` binary.
+ *
+ * These strings are read by an AGENT that is already blocked, and they used to name a bare
+ * `reticle open <url>`. Reticle registers its MCP server as `npx @reticlehq/server mcp`, so the
+ * ordinary install puts NOTHING on PATH — the binary those messages assume is missing on most
+ * machines that ever read them.
+ *
+ * Reported from Windows, where a half-failed plugin install left the MCP server registered and all
+ * the tools advertised while no CLI existed on disk. The agent followed the remediation, found no
+ * `reticle`, tried `npx @reticlehq/reticle` (a package that does not exist and 404s), and had no
+ * path forward at all. The remedy has to be a command that works from a bare npm environment.
+ *
+ * Init-time messages keep the short form on purpose: there, the reader is already running the CLI.
+ */
+const OPEN_CMD = '`npx @reticlehq/server open <url>`';
+const OPEN_CMD_BARE = '`npx @reticlehq/server open`';
+const INIT_CMD = '`npx @reticlehq/server init`';
+/**
+ * The one sentence that stops the scan lying about a server that is running.
+ *
+ * A port that accepted a connection and then said nothing is evidence FOR the app being up, not
+ * against it, and it has to be read before the "nothing is listening" sentence rather than after —
+ * the reader acts on the first claim.
+ */
+function slowListenerClause(facts) {
+    const slow = facts.slowListeners ?? [];
+    if (0 === slow.length)
+        return '';
+    const ports = slow.join(', ');
+    const subject = 1 === slow.length ? `Port ${ports} ACCEPTED` : `Ports ${ports} ACCEPTED`;
+    return (`${subject} a connection but did not answer in time, which is what a server-rendered dev ` +
+        'server compiling its first route looks like — so something IS running there and you should ' +
+        'open it rather than start it. Setting that aside: ');
+}
 /**
  * The commonest first-run state there is, and until #320 the message named it nowhere.
  *
@@ -78,7 +169,7 @@ const SCANNED_PORTS = [...DEV_SERVER_PORTS].join(', ');
  * discovering that one `reticle open` fixed it instantly.
  */
 const OPEN_THE_APP = 'Reticle only ever sees a page that is LOADED, so the commonest cause by a distance is that no ' +
-    "browser has opened the app yet: run `reticle open <url>` with the app's own URL (or ask the " +
+    `browser has opened the app yet: run ${OPEN_CMD} with the app's own URL (or ask the ` +
     'human to open it).';
 /**
  * What a machine-wide port scan can and cannot say.
@@ -114,6 +205,70 @@ function portMismatchClause(facts) {
         ` Either restart the daemon on ${String(configured)}, or update \`.reticle.json\` to` +
         ` ${String(facts.port)} and restart the dev server so the app picks it up.`);
 }
+/**
+ * The tail every "the app is wired and silent" branch ends with, ranked.
+ *
+ * One place, because the ranking is the whole fix: a hint that lists "no server", "no SDK" and
+ * "no tab" at equal weight is a hint the reader has to rank itself, with strictly less evidence
+ * than the daemon has.
+ */
+function rankedCauses(facts) {
+    const nuxt = facts.framework?.toLowerCase() === NUXT ? `${NUXT_STALE_BUNDLE} ` : '';
+    return (`${nuxt}${REAL_CAUSES} If none of those, the app may be dialling a different daemon than this ` +
+        `one (on ${String(facts.port)}): check the app's reticle port matches ` +
+        `${String(facts.port)}.${portMismatchClause(facts)} ${NON_LOCALHOST_GATE}`);
+}
+/**
+ * The scope answer, when the config was somewhere else all along.
+ *
+ * This OUTRANKS every "you may have no SDK" sentence in this file, because it is positive evidence:
+ * a `.reticle.json` in `apps/web` means that app has been through `init` whatever the daemon's own
+ * directory looks like. Naming the directories rather than adopting one is deliberate — several
+ * configs means several projects, and choosing silently is how an agent gets a confident verdict
+ * about an app it never touched.
+ */
+function configsElsewhereClause(facts) {
+    const configs = facts.configsElsewhere ?? [];
+    if (0 === configs.length)
+        return '';
+    const named = configs
+        .map((c) => (c.projectId === undefined ? c.directory : `${c.directory} ('${c.projectId}')`))
+        .join(', ');
+    return (`A \`.reticle.json\` WAS found outside this daemon's directory: ${named}. So the app is wired ` +
+        'and this is a SCOPE problem, not an install problem — this daemon was started somewhere that ' +
+        'is not the project, which is the normal outcome when an editor launches it from your home ' +
+        "directory. Restart the daemon from the app's directory (or point it there) rather than " +
+        'installing anything.');
+}
+/** Where we looked, when we found nothing. An absence nobody can check is not evidence. */
+function searchedClause(facts) {
+    const searched = facts.searchedDirectories ?? [];
+    if (0 === searched.length)
+        return '';
+    if ((facts.configsElsewhere ?? []).length > 0)
+        return '';
+    return ` I looked in: ${searched.join(', ')}. If your app is not in that list, that is the answer — this daemon is standing somewhere else.`;
+}
+/**
+ * A leading sentence when the daemon has been up long enough that no app is coming.
+ *
+ * Only fires for a WIRED project (initialized) that has NEVER connected and is past the
+ * threshold. An unwired project already names the install gap as its primary cause; adding a time
+ * sentence there would double-blame.
+ */
+function stallClause(facts) {
+    const { daemonUpMs, initialized, everConnected } = facts;
+    if (everConnected)
+        return '';
+    if (!initialized)
+        return '';
+    if (daemonUpMs === undefined || daemonUpMs < STALL_AFTER_MS)
+        return '';
+    const minutes = Math.round(daemonUpMs / 60_000);
+    return (`This daemon has been running for ${String(minutes)} minutes and no app has connected. ` +
+        'The most likely cause is that the dev server was not restarted after adding the Reticle ' +
+        'plugin, so the running bundle carries no SDK. Restart the dev server first. ');
+}
 export function diagnoseNoSession(facts) {
     const { everConnected, initialized, listening, port } = facts;
     // Named when known: a claim about a missing file is a claim about ONE directory.
@@ -133,11 +288,30 @@ export function diagnoseNoSession(facts) {
                 'that a lease you were using aged out; a lease is a headless context, not a human tab, and ' +
                 'it takes its cookies with it (so an authenticated app needs signing in again). Re-acquire ' +
                 'with reticle_lease {action:"acquire", url} and carry on. If you were driving a human tab ' +
-                `instead, it went away — reopen it or run \`reticle open\`. ${RETRY}`);
+                `instead, it went away — reopen it or run ${OPEN_CMD_BARE}. ${RETRY}`);
         }
         return ('no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
             'is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen ' +
-            `the app (or run \`reticle open\`), or reload the tab. ${SELF_SERVE} ${RETRY}`);
+            `the app (or run ${OPEN_CMD_BARE}), or reload the tab. ${SELF_SERVE} ${RETRY}`);
+    }
+    // Ranked ahead of every "we have never seen one" branch below, because it is the one fact that
+    // OUTRANKS them: those branches all reason from an absence, and this reasons from a recorded
+    // connection. It is also the branch that stops the daemon contradicting itself — a hint that the
+    // wiring is unproven, printed by a daemon holding proof that it is.
+    if (true === facts.previouslyConnected) {
+        const listeners = 0 === listening.length
+            ? `${unattributedListeners(listening)} If the dev server is not running, start it first ` +
+                '(the command is in `next_action`).'
+            : unattributedListeners(listening);
+        return `${RESTARTED_LEAD} ${OPEN_THE_APP} ${listeners} ${rankedCauses(facts)} ${SELF_SERVE} ${RETRY}`;
+    }
+    // A config found elsewhere outranks every "you may have no SDK" branch below: those reason from
+    // an absence in ONE directory, and this is a file we read in another. Ranked here so the reader is
+    // never sent through an install on a project that has demonstrably been installed.
+    if (!initialized && (facts.configsElsewhere ?? []).length > 0) {
+        return ('no browser session connected, and this daemon has never seen one. ' +
+            `${configsElsewhereClause(facts)} ${unattributedListeners(listening)} ${OPEN_THE_APP} ` +
+            `${rankedCauses(facts)} ${SELF_SERVE} ${RETRY}`);
     }
     if (0 === listening.length) {
         // Lead with the stronger EVIDENCE, and do not overstate what it is.
@@ -156,20 +330,25 @@ export function diagnoseNoSession(facts) {
         // is expected rather than diagnostic.
         if (!initialized) {
             return ('no browser session connected. Two things to weigh, and neither of them is proof. ' +
-                `(1) Nothing is listening on the ports Reticle scans (${SCANNED_PORTS}), so the dev server ` +
-                'may not be running — ask the human to start it (`npm run dev`). That scan is narrow ' +
+                `(1) ${slowListenerClause(facts)}Nothing is listening on the ports Reticle scans (${SCANNED_PORTS}), so the dev server ` +
+                'may not be running — START IT YOURSELF, in the background, using the command in ' +
+                "`next_action` (it is read from this project's own scripts; if there is none, that field " +
+                'says so and you should ask rather than guess). Tell the human in one line that it is ' +
+                'running. That scan is narrow ' +
                 'though: a server on any other port is invisible to it, so if the app IS running, ask for ' +
-                'its URL rather than assuming it is down, and open it with `reticle open <url>`. ' +
+                `its URL rather than assuming it is down, and open it with ${OPEN_CMD}. ` +
                 `(2) There is no \`.reticle.json\` in ${where}. That is the ` +
-                "file `reticle init` writes, so the app may carry no Reticle SDK — but check the app's " +
+                `file ${INIT_CMD} writes, so the app may carry no Reticle SDK — but check the app's ` +
                 'OWN directory before re-running `init`: in a monorepo the daemon often runs at the root ' +
                 'while the app lives in a subdirectory, and an app wired by the Vite or Babel plugin ' +
-                `carries the SDK without that file at all. ${RETRY}`);
+                `carries the SDK without that file at all.${searchedClause(facts)} ${URL_THEN_LEASE} ${RETRY}`);
         }
-        return (`no browser session connected, and this daemon has never seen one. ${OPEN_THE_APP} ` +
+        return (`${stallClause(facts)}no browser session connected, and this daemon has never seen one. ${OPEN_THE_APP} ` +
             'Nothing is listening on the ports Reticle scans ' +
             `(${SCANNED_PORTS}) either, and the most common reason for that is a dev server that is not ` +
-            'running: ask the human to start it (`npm run dev`), then open the app in a browser. ' +
+            'running: start it yourself in the background with the command in `next_action` — it is read ' +
+            "from this project's own scripts, and says so rather than guessing when there is none — tell " +
+            'the human in one line that it is running, then open the app in a browser. ' +
             // The caveat is here rather than omitted because the scan is NARROW, and the old sentence
             // spent its confidence as though an empty result were proof of absence. Reported twice: a
             // scripted drive of 2.5.0 asserted the app was not running while it served 200 on :7699, and
@@ -180,7 +359,7 @@ export function diagnoseNoSession(facts) {
             // Deliberately NOT offering reticle_lease here, and a test pins that: a lease opens a URL, and
             // if nothing is listening there is nothing at any URL to open. Asking for the real one is the
             // only move that can recover the :7699 case.
-            'the app IS running, ask the human for its URL rather than assuming it is down. ' +
+            `the app IS running, ask the human for its URL rather than assuming it is down. ${URL_THEN_LEASE} ` +
             // Reachable only for a project that HAS been through `init` — the uninstrumented case is
             // answered above, leading with that certainty instead of behind this scan's guess.
             `${RETRY}`);
@@ -188,17 +367,15 @@ export function diagnoseNoSession(facts) {
     if (!initialized) {
         return ('no browser session connected, and this daemon has never seen one. ' +
             `What was actually checked: there is no \`.reticle.json\` in ${where}. That is the file ` +
-            '`reticle init` writes, so the app may carry no Reticle SDK — but it is not proof, and the ' +
+            `${INIT_CMD} writes, so the app may carry no Reticle SDK — but it is not proof, and the ` +
             'same absence is expected in a monorepo whose daemon runs at the root while the app lives in ' +
             "a subdirectory, or in an app wired by the Vite or Babel plugin. Check the app's OWN " +
-            'directory: if it has no config, run `reticle init` there and restart the dev server; if it ' +
-            'has one, the app is wired and simply has no page open — `reticle open <url>`. ' +
-            `${unattributedListeners(listening)} ${RETRY}`);
+            `directory: if it has no config, run ${INIT_CMD} there and restart the dev server; if it ` +
+            `has one, the app is wired and simply has no page open — ${OPEN_CMD}. ` +
+            `${unattributedListeners(listening)}${searchedClause(facts)} ${RETRY}`);
     }
-    return ('no browser session connected, and this daemon has never seen one for this project, which is ' +
+    return (`${stallClause(facts)}no browser session connected, and this daemon has never seen one for this project, which is ` +
         `wired for Reticle. ${OPEN_THE_APP} ${unattributedListeners(listening)} ` +
-        'If the page IS open and still does not appear, the app is either serving a build made before ' +
-        `the wiring landed or dialling a different daemon than this one (on ${String(port)}): restart ` +
-        "the dev server, hard-reload the page, and check that the app's reticle port matches " +
-        `${String(port)}.${portMismatchClause(facts)} ${NON_LOCALHOST_GATE} ${SELF_SERVE} ${RETRY}`);
+        'If the page IS open and still does not appear, the app is wired and the SDK is not reaching ' +
+        `this daemon (on ${String(port)}). ${rankedCauses(facts)} ${SELF_SERVE} ${RETRY}`);
 }

package/dist/session/no-session-next-action.d.ts

@@ -0,0 +1,46 @@
+/**
+ * "No browser session connected", as something an agent can RUN.
+ *
+ * The prose diagnosis next door is good and it is prose: the agent has to read four hedged sentences
+ * and decide which of them is about its situation. This is the same decision, decided here, as one
+ * value plus one literal command — so the branch happens in the daemon, which has the evidence,
+ * rather than in the agent, which does not.
+ *
+ * The rule that outranks helpfulness: never invent a command. If the project has no dev script, this
+ * says there is none. A command that does not exist sends the agent chasing a phantom error in its
+ * own repo.
+ *
+ * Pure. The facts arrive from the watch; nothing here touches the disk or the clock.
+ */
+import { NoSessionAction } from '@reticlehq/core';
+import type { DevCommand } from './dev-command.js';
+/** The executable half of the no-session payload. */
+export interface NoSessionNextAction {
+    action: NoSessionAction;
+    /** The literal command to run. Absent whenever it could not be sourced without guessing. */
+    command?: string;
+    /** The port this action is about — where the app is, or where the dev script will put it. */
+    port?: number;
+    /** One sentence: why this is the action, and — when there is no command — why there is none. */
+    reason: string;
+}
+interface NextActionFacts {
+    everConnected: boolean;
+    initialized: boolean;
+    listening: readonly number[];
+    dev: DevCommand | undefined;
+    /**
+     * An app for this project has connected on this port before, from durable state.
+     *
+     * Outranks `initialized`, which is only ever "is there a `.reticle.json` in the ONE directory this
+     * daemon stands in". In a monorepo, or under an editor that starts the MCP server from the user's
+     * home, that answer is no for projects that are wired and have connected — and the action handed
+     * back was `reticle init`, which is the one action that cannot help and can overwrite the config
+     * that works.
+     */
+    previouslyConnected?: boolean;
+}
+export declare function nextActionFor(facts: NextActionFacts): NoSessionNextAction;
+/** The same action as one sentence, for the prose message the human reads. */
+export declare function renderNextAction(next: NoSessionNextAction): string;
+export {};

package/dist/session/no-session-next-action.js

@@ -0,0 +1,85 @@
+/**
+ * "No browser session connected", as something an agent can RUN.
+ *
+ * The prose diagnosis next door is good and it is prose: the agent has to read four hedged sentences
+ * and decide which of them is about its situation. This is the same decision, decided here, as one
+ * value plus one literal command — so the branch happens in the daemon, which has the evidence,
+ * rather than in the agent, which does not.
+ *
+ * The rule that outranks helpfulness: never invent a command. If the project has no dev script, this
+ * says there is none. A command that does not exist sends the agent chasing a phantom error in its
+ * own repo.
+ *
+ * Pure. The facts arrive from the watch; nothing here touches the disk or the clock.
+ */
+import { NoSessionAction } from '@reticlehq/core';
+/** `reticle init`, the only command here that is Reticle's own and so cannot be wrong. */
+const INIT_COMMAND = 'reticle init';
+const OPEN_COMMAND = 'reticle open';
+const LOCALHOST = 'http://localhost';
+export function nextActionFor(facts) {
+    if (facts.everConnected) {
+        return {
+            action: NoSessionAction.REOPEN_APP,
+            reason: 'a session was connected to this daemon earlier, so the wiring is correct — the tab was ' +
+                'closed, reloaded, or the lease aged out. Reopen the app, or take one you own with ' +
+                'reticle_lease {action:"acquire", url}.',
+        };
+    }
+    if (0 === facts.listening.length) {
+        const dev = facts.dev;
+        if (dev === undefined) {
+            return {
+                action: NoSessionAction.START_DEV_SERVER,
+                reason: 'nothing is listening on the ports Reticle scans, so the app is probably not running — ' +
+                    'but this project declares no dev script (no `dev`, `develop` or `start` in its ' +
+                    'package.json), so there is no command to hand you. Ask the human how their app is ' +
+                    'started, and for the URL it serves on.',
+            };
+        }
+        return {
+            action: NoSessionAction.START_DEV_SERVER,
+            command: dev.command,
+            ...(dev.port === undefined ? {} : { port: dev.port }),
+            reason: 'nothing is listening on the ports Reticle scans, so the app is not running. This is the ' +
+                `project's own \`${dev.script}\` script — run it in the background, tell the human it is ` +
+                'running, then call reticle_sessions again.',
+        };
+    }
+    // Something IS up. Whatever else is true, do NOT hand back a start command: a second dev server on
+    // a second port is the exact confusion the probe exists to prevent.
+    const ports = facts.listening.join(', ');
+    const only = 1 === facts.listening.length ? facts.listening[0] : undefined;
+    if (!facts.initialized && true !== facts.previouslyConnected) {
+        return {
+            action: NoSessionAction.RUN_INIT,
+            command: INIT_COMMAND,
+            ...(only === undefined ? {} : { port: only }),
+            reason: `something is listening (${ports}) but no \`.reticle.json\` was found, so the app may ` +
+                "carry no Reticle SDK. Run this in the APP's own directory — in a monorepo that is not " +
+                'where this daemon stands — then restart the dev server.',
+        };
+    }
+    if (only === undefined) {
+        return {
+            action: NoSessionAction.OPEN_APP,
+            reason: `this project is wired and no page is open. Several ports are listening (${ports}) and ` +
+                'none of them can be attributed to this project, so open the one the human names: ' +
+                `\`${OPEN_COMMAND} <url>\`.`,
+        };
+    }
+    return {
+        action: NoSessionAction.OPEN_APP,
+        command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`,
+        port: only,
+        reason: 'this project is wired and a dev server is listening — Reticle only ever sees a page a ' +
+            'browser has LOADED, and nothing has loaded one.',
+    };
+}
+/** The same action as one sentence, for the prose message the human reads. */
+export function renderNextAction(next) {
+    const command = next.command;
+    return command === undefined
+        ? `NEXT ACTION: ${next.reason}`
+        : `NEXT ACTION: run \`${command}\` — ${next.reason}`;
+}

package/dist/session/no-session-watch.d.ts

@@ -10,6 +10,42 @@
  * daemon that outlives the agent by hours has no business scanning ports it does not need.
  */
 import type { SessionManager } from './session-manager.js';
+interface NoSessionWatchOptions {
+    sessions: SessionManager;
+    port: number;
+    /** Whether this project has been through `reticle init` (a projectId is stamped in .reticle.json). */
+    initialized: boolean;
+    /** Where that was decided — this daemon's working directory unless a caller says otherwise. */
+    directory?: string;
+    probe?: () => Promise<number[]>;
+    /**
+     * How many pooled leases have aged out, if a pool exists. Injected as a reader rather than the
+     * pool itself: the diagnosis needs one number, and taking the whole pool would tie the session
+     * layer to the browser layer for it.
+     */
+    reapedLeases?: () => number;
+    /**
+     * Opens a URL in a browser Reticle owns, and resolves once it is open.
+     *
+     * The daemon passes the POOL's acquire — the same path `reticle_lease` takes — rather than
+     * `reticle drive`. Deliberate: the pool runs inside this process and binds nothing, so it needs no
+     * port arbitration, while `reticle drive` starts a second daemon that fights this one for the port.
+     * Omitted on a daemon with no pool, and auto-attach is then simply off.
+     */
+    attach?: (url: string) => Promise<unknown>;
+    /**
+     * Where the durable "an app has connected here before" bit lives. The daemon's state home unless
+     * a test says otherwise.
+     */
+    stateDir?: string;
+}
+/**
+ * Start the watch. Returns a stop function; the timer is unref'd so it never holds the daemon up.
+ *
+ * Exported for the test that pins the after-boot config read below — the daemon itself starts this
+ * through `wireSessionScope`.
+ */
+export declare function startNoSessionWatch(options: NoSessionWatchOptions): () => void;
 /**
  * The daemon's whole session-scoping decision in one call: scope auto-selection to the active
  * project, and keep the no-session diagnosis fresh. Both derive from the same one fact — whether
@@ -18,4 +54,7 @@ import type { SessionManager } from './session-manager.js';
  */
 export declare function wireSessionScope(sessions: SessionManager, activeProjectId: string | undefined, port: number, 
 /** Reader for the pool's aged-out-lease count; omitted when this daemon runs no pool. */
-reapedLeases?: () => number): () => void;
+reapedLeases?: () => number, 
+/** Opens a URL in a Reticle-owned browser (the pool). Omitted ⇒ auto-attach is off. */
+attach?: (url: string) => Promise<unknown>): () => void;
+export {};