@reticlehq/server 2.10.0 → 2.12.0

package/dist/runs/run-context.js

@@ -0,0 +1,158 @@
+import { EventType, JournalVerdictEffectSchema, RUN_ESTABLISHED_CAP, buildRunContext, } from '@reticlehq/core';
+/**
+ * The run, derived from the journal that is already there.
+ *
+ * `.reticle/sessions/<id>/` already holds an append-only causal ledger of every action dispatched
+ * and every event observed. The run is a FOLD over that, never a second store — the same argument
+ * that deleted `instrumentation_stalled` from this codebase applies without modification: two ways
+ * to compute one number is worse than one way, because the day they disagree the disagreement lands
+ * inside a verdict and a user finds it before we do. So nothing here writes: it reads the ledger and
+ * folds it, and if the fold is wrong the ledger is still the single authority.
+ *
+ * **One run per session, for now.** Nothing here assumes it: the fold is pure and takes its evidence
+ * as arguments, so a later multi-run or multi-agent model is a change of caller, not a rewrite. It
+ * is not built today because nobody has hit the case, and a coordination model invented ahead of its
+ * first user is a guess.
+ *
+ * Only what Reticle OBSERVED goes in. A settle outcome is an observation. A route change is an
+ * observation. A verdict a verification tool recorded is an observation. What the agent meant to do
+ * next is not, and never enters here.
+ */
+/**
+ * The one key the route is filed under.
+ *
+ * The subject of "the app is on /checkout" is the route itself, so a later route change SUPERSEDES
+ * rather than appends. Filing it per-path would accumulate every page ever visited, which is the
+ * token bomb the cap exists to prevent.
+ */
+const ROUTE_KEY = 'route';
+/** The conclusions this fold is allowed to state, as prose rather than transcript. */
+const Fact = {
+    route: (to) => `route is ${to}`,
+    settled: (verb) => `${verb} settled`,
+    unsettled: (verb) => `${verb} did not settle`,
+};
+/**
+ * The SUBJECT a journal action was about: the ref it spent, else the target it resolved from.
+ *
+ * Exported so the feature-use instrument files a re-fetch under the same key this fold establishes
+ * it under. A second copy of this rule there would be a second definition of "the same subject".
+ */
+export function subjectOf(action) {
+    const ref = action.args['ref'];
+    if ('string' === typeof ref && ref.length > 0)
+        return ref;
+    const target = action.args['target'];
+    if ('string' === typeof target && target.length > 0)
+        return target;
+    return undefined;
+}
+/** What the action did, in the caller's own vocabulary — 'click', 'fill', else the tool's name. */
+function verbOf(action) {
+    const named = action.args['action'];
+    return 'string' === typeof named && named.length > 0 ? named : action.tool;
+}
+/** The verdict a verification tool recorded on this action, if it recorded one. */
+function verdictOf(action) {
+    const parsed = JournalVerdictEffectSchema.safeParse(action.effect);
+    return parsed.success ? parsed.data : undefined;
+}
+/** Which document and edit epoch each action was observed under, read off its attributed events. */
+function scopeByAction(events) {
+    const out = new Map();
+    for (const event of events) {
+        if (event.actionId === undefined)
+            continue;
+        if (event.documentId === undefined && event.editEpoch === undefined)
+            continue;
+        const existing = out.get(event.actionId) ?? {};
+        out.set(event.actionId, {
+            doc: event.documentId ?? existing.doc,
+            epoch: event.editEpoch ?? existing.epoch,
+        });
+    }
+    return out;
+}
+/**
+ * Fold the journal into candidate facts, newest last.
+ *
+ * Only the last `RUN_ESTABLISHED_CAP` actions are read: anything older cannot survive the fold, so
+ * parsing it would be work done to throw away. An action with no observed settle outcome states
+ * nothing and is skipped — "we drove it and cannot say what happened" is not an established fact,
+ * and writing it down as one is how a memory starts lying.
+ */
+export function establishedFromJournal(actions, events) {
+    const scope = scopeByAction(events);
+    let route;
+    for (const event of events) {
+        if (EventType.ROUTE_CHANGE !== event.type)
+            continue;
+        const pathname = event.data['pathname'];
+        const to = 'string' === typeof pathname ? pathname : event.data['to'];
+        if ('string' !== typeof to)
+            continue;
+        route = { key: ROUTE_KEY, fact: Fact.route(to), doc: event.documentId, epoch: event.editEpoch };
+    }
+    const out = [];
+    for (const action of actions.slice(-RUN_ESTABLISHED_CAP)) {
+        const settled = action.settled;
+        if (undefined === settled)
+            continue;
+        const key = subjectOf(action);
+        if (undefined === key)
+            continue;
+        const verb = verbOf(action);
+        out.push({
+            key,
+            fact: settled ? Fact.settled(verb) : Fact.unsettled(verb),
+            // The source pointer the verdict already reported. Read off the ledger rather than looked up
+            // again: a second lookup could disagree with the one the agent was shown.
+            source: verdictOf(action)?.source,
+            ...(scope.get(action.actionId) ?? {}),
+        });
+    }
+    if (route !== undefined)
+        out.push(route);
+    return out;
+}
+/**
+ * What a verdict already settled, newest last.
+ *
+ * Both verdict tools write here. `reticle_act_and_wait` closes its attribution window with one;
+ * `reticle_assert` drives nothing, so it appends its record WITHOUT opening a window — same effect
+ * shape, so this fold reads one kind of verdict rather than two.
+ */
+export function provenFromJournal(actions, events) {
+    const scope = scopeByAction(events);
+    const out = [];
+    for (const action of actions.slice(-RUN_ESTABLISHED_CAP)) {
+        const verdict = verdictOf(action);
+        if (undefined === verdict)
+            continue;
+        out.push({
+            claim: verdict.claim,
+            verified: verdict.verified,
+            source: verdict.source,
+            ...(scope.get(action.actionId) ?? {}),
+        });
+    }
+    return out;
+}
+/**
+ * The context for one run.
+ *
+ * `step` is the journal's action count rather than a counter of its own, for the reason at the top
+ * of this file: a second counter is a second thing that can disagree with the ledger. The document
+ * and epoch are the session's own, so the staleness rule here is the same one every other verdict in
+ * this codebase is scoped by.
+ */
+export function runContextFor(input) {
+    return buildRunContext({
+        step: input.actions.length,
+        intents: input.intents,
+        established: establishedFromJournal(input.actions, input.events),
+        proven: provenFromJournal(input.actions, input.events),
+        currentDocumentId: input.currentDocumentId,
+        currentEditEpoch: input.currentEditEpoch,
+    });
+}

package/dist/runs/run-diff.d.ts

@@ -1,6 +1,6 @@
 import type { ReticleVerificationRun } from '@reticlehq/core';
 /** A per-flow change between two runs. Only flows with a meaningful change are reported. */
-export interface FlowDelta {
+interface FlowDelta {
     name: string;
     beforeMs: number;
     afterMs: number;
@@ -29,3 +29,4 @@ export interface RunDiff {
  * console diffs land once runs persist per-step detail.
  */
 export declare function diffRuns(before: ReticleVerificationRun, after: ReticleVerificationRun, noiseFloorPct?: number): RunDiff;
+export {};

package/dist/runs/run-tools.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { sessionRoot } from '../project/session-root.js';
 import { RunReadError } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asString } from '../tools/tools-helpers.js';
@@ -36,7 +37,7 @@ export const RUN_TOOLS = [
             error: z.string().optional(),
         },
         handler: async (deps, args) => {
-            const store = new RunStore(deps.fs, deps.reticleRoot);
+            const store = new RunStore(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
             // format:"diff" is a whole-history operation (two most-recent runs), not a single-run read.
             if ('diff' === asString(args['format'])) {
                 const pair = await store.latestTwo();

package/dist/runs/verification-sync.js

@@ -14,7 +14,7 @@ import { buildVerificationRun } from './build-verification-run.js';
 import { mapReplayToFlowResult } from './replay-mapping.js';
 import { defaultRunId } from './runner-port.js';
 import { RunStore } from './run-store.js';
-import { syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { log } from '../log.js';
 /** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
@@ -58,7 +58,7 @@ export async function persistAndSyncVerificationRun(deps, timed, projectId) {
     const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
     if (null === cloud.config || !cloud.policy.runs)
         return run.runId; // not attached / runs disabled → local only
-    const result = await syncRunToCloud(run, cloud.config, (url, init) => fetch(url, init));
+    const result = await syncRunToCloud(run, cloud.config, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-run-sync-failed', { runId: run.runId, status: result.status, error: result.error });
     }

package/dist/session/dev-server-probe.d.ts

@@ -69,13 +69,5 @@ export declare function probeDevServerStates(ports?: readonly number[], probe?:
     serving: number[];
     slow: number[];
 }>;
-/**
- * The strongest state either loopback family reports.
- *
- * Serving a document beats a bare connection beats nothing, so a server bound to only one family is
- * still seen at its best — the same "either, not both" rule `anyFamilyServes` follows, extended to
- * three states.
- */
-export declare function anyFamilyState(port: number, probe?: (port: number, host: string) => Promise<PortState>): Promise<PortState>;
 /** Every candidate port serving a document, in ascending order. Never rejects. */
 export declare function probeDevServers(ports?: readonly number[], probe?: (port: number) => Promise<boolean>): Promise<number[]>;

package/dist/session/dev-server-probe.js

@@ -132,7 +132,7 @@ export async function probeDevServerStates(ports = [...DEV_SERVER_PORTS], probe
  * still seen at its best — the same "either, not both" rule `anyFamilyServes` follows, extended to
  * three states.
  */
-export async function anyFamilyState(port, probe = probeState) {
+async function anyFamilyState(port, probe = probeState) {
     const answers = await Promise.all(PROBE_HOSTS.map((host) => probe(port, host).catch(() => PortState.CLOSED)));
     if (answers.includes(PortState.SERVES_DOCUMENT))
         return PortState.SERVES_DOCUMENT;

package/dist/session/last-act.d.ts

@@ -16,6 +16,12 @@
  */
 interface ActEffect {
     action?: string | undefined;
+    /**
+     * The ref the action dispatched against. Recorded so the verdict nudge can suggest a call about
+     * the element the agent actually touched, rather than a worked example from a document. Written
+     * on the SAME success path as `action`, so a refused act leaves neither.
+     */
+    ref?: string | undefined;
     /** DOM mutations inside the acted element's own subtree. Undefined means nobody measured. */
     mutatedWithin?: number | undefined;
 }
@@ -35,7 +41,7 @@ export declare class LastAct {
      * Marking only on the success path is what makes that unrepeatable: a failure mode added later
      * cannot forget to clean up state that was never written.
      */
-    markActed(cursor: number, action: string | undefined, mutatedWithin: number | undefined): void;
+    markActed(cursor: number, action: string | undefined, mutatedWithin: number | undefined, ref?: string): void;
     /**
      * A navigation — by URL or by reload — moves the floor without being an act.
      *

package/dist/session/last-act.js

@@ -18,9 +18,9 @@ export class LastAct {
      * Marking only on the success path is what makes that unrepeatable: a failure mode added later
      * cannot forget to clean up state that was never written.
      */
-    markActed(cursor, action, mutatedWithin) {
+    markActed(cursor, action, mutatedWithin, ref) {
         this.#cursor = cursor;
-        this.#effect = { action, mutatedWithin };
+        this.#effect = { action, mutatedWithin, ...(ref === undefined ? {} : { ref }) };
     }
     /**
      * A navigation — by URL or by reload — moves the floor without being an act.

package/dist/session/lease-availability.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Whether the self-serve escape hatch can actually be taken, said in the same breath as the offer.
+ *
+ * `reticle_lease` is what `status`, `doctor` and the no-session diagnosis all recommend when no tab
+ * is connected: it opens a browser Reticle drives itself, so the agent does not have to wait for a
+ * human. It is the right advice and it is the one thing that cannot work when Chromium is missing or
+ * sitting at a revision this Playwright will not use — and the command giving the advice is usually
+ * the command that just diagnosed exactly that.
+ *
+ * Reported from the field, verbatim in shape: `doctor` printed `chromium ✗ wrong revision — the
+ * bundled playwright wants chromium-1234; the cache holds chromium-1228`, and then offered the lease
+ * as the way out. The reporter followed it, and could not have succeeded.
+ *
+ * Two things this refuses to do:
+ *
+ * **It does not fire on an absent probe.** A probe that could not run is not evidence the browser is
+ * missing, and a caveat asserting otherwise would be the same overclaiming this file exists to stop.
+ *
+ * **It does not tell the agent to install the browser.** A ~150MB download on somebody else's
+ * machine is not an agent's call to make unprompted, so the message names the command and hands it
+ * to the human rather than implying the agent should just run it.
+ */
+/** What the caller learned about the browser. Gathered by the caller so this stays pure. */
+export interface LeaseBrowserState {
+    /** Does the executable this Playwright wants actually exist on disk? */
+    exists: boolean;
+    /** The install command, already pinned to the bundled Playwright by `chromium-hint`. */
+    installCommand?: string | undefined;
+    /** The revision this Playwright wants, when the path names one. */
+    wantedRevision?: string | undefined;
+    /** Chromium revisions actually present, wanted or not. */
+    installedRevisions?: readonly string[] | undefined;
+}
+/**
+ * The sentence to append to a lease recommendation, or undefined when the lease is fine.
+ *
+ * Undefined rather than an empty string on the healthy path: a caller composing a message should not
+ * have to filter blanks, and a healthy install must pay nothing at all for this check.
+ */
+export declare function leaseCaveat(state: LeaseBrowserState | undefined): string | undefined;

package/dist/session/lease-availability.js

@@ -0,0 +1,43 @@
+/**
+ * Whether the self-serve escape hatch can actually be taken, said in the same breath as the offer.
+ *
+ * `reticle_lease` is what `status`, `doctor` and the no-session diagnosis all recommend when no tab
+ * is connected: it opens a browser Reticle drives itself, so the agent does not have to wait for a
+ * human. It is the right advice and it is the one thing that cannot work when Chromium is missing or
+ * sitting at a revision this Playwright will not use — and the command giving the advice is usually
+ * the command that just diagnosed exactly that.
+ *
+ * Reported from the field, verbatim in shape: `doctor` printed `chromium ✗ wrong revision — the
+ * bundled playwright wants chromium-1234; the cache holds chromium-1228`, and then offered the lease
+ * as the way out. The reporter followed it, and could not have succeeded.
+ *
+ * Two things this refuses to do:
+ *
+ * **It does not fire on an absent probe.** A probe that could not run is not evidence the browser is
+ * missing, and a caveat asserting otherwise would be the same overclaiming this file exists to stop.
+ *
+ * **It does not tell the agent to install the browser.** A ~150MB download on somebody else's
+ * machine is not an agent's call to make unprompted, so the message names the command and hands it
+ * to the human rather than implying the agent should just run it.
+ */
+/**
+ * The sentence to append to a lease recommendation, or undefined when the lease is fine.
+ *
+ * Undefined rather than an empty string on the healthy path: a caller composing a message should not
+ * have to filter blanks, and a healthy install must pay nothing at all for this check.
+ */
+export function leaseCaveat(state) {
+    if (state === undefined || state.exists)
+        return undefined;
+    // Present-at-the-wrong-revision and absent-entirely have different fixes and different readings,
+    // and collapsing them is what made the reported loop unbreakable — "the check is broken" and
+    // "none of these count" look identical from a flat `missing`.
+    const installed = state.installedRevisions ?? [];
+    const mismatch = state.wantedRevision !== undefined && installed.length > 0
+        ? ` This Playwright wants ${state.wantedRevision} and the cache holds ${installed.join(', ')}, so the builds already on this machine will not be used.`
+        : '';
+    const command = state.installCommand === undefined ? '' : ` The fix is: ${state.installCommand}.`;
+    return ('NOTE — reticle_lease cannot run here: it drives a Reticle-owned Chromium and that browser is ' +
+        `not available.${mismatch}${command} That download is the human's call, not something to run ` +
+        'unprompted on their machine, so hand this back rather than treating the lease as a way forward.');
+}

package/dist/session/live-control-tools.js

@@ -3,12 +3,7 @@ import { noteEmptyRead } from '../tools/observed-nothing.js';
 import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, YIELD_WITHOUT_SESSION_NOTE, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
-import { asNumber, asString } from '../tools/tools-helpers.js';
-import { waitForReady, RETICLE_LOOP_GUIDE } from './session-readiness.js';
-import { recoveryFor } from '../tools/error-recovery.js';
-/** Default + ceiling for the readiness wait — keep it short so a truly-missing app fails fast. */
-const WAIT_READY_DEFAULT_MS = 5000;
-const WAIT_READY_MAX_MS = 30000;
+import { asString } from '../tools/tools-helpers.js';
 /**
  * Is this a turn ending with nothing attached, rather than a call about a specific tab?
  *
@@ -225,42 +220,6 @@ export const LIVE_CONTROL_TOOLS = [
             return Promise.resolve(out);
         },
     },
-    {
-        name: ReticleTool.WAIT_READY,
-        description: 'Block until the app is connected, then continue — call this once right after init so your ' +
-            'first real tool call does not lose the race with the SDK connecting its WebSocket. Returns as ' +
-            'soon as a session exists (no latency if one already does), or after `timeoutMs` with a ' +
-            'recovery hint if none appears.',
-        inputSchema: {
-            timeoutMs: z
-                .number()
-                .optional()
-                .describe('How long to wait for a session (ms). Default 5000, max 30000.'),
-        },
-        outputSchema: {
-            ready: z.boolean(),
-            sessionCount: z.number(),
-            loop: z.string().optional(),
-            recovery: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            const requested = asNumber(args['timeoutMs']) ?? WAIT_READY_DEFAULT_MS;
-            const timeoutMs = Math.max(0, Math.min(requested, WAIT_READY_MAX_MS));
-            const ready = await waitForReady({
-                count: () => deps.sessions.count(),
-                timeoutMs,
-                now: deps.now,
-                sleep: (ms) => new Promise((res) => setTimeout(res, ms)),
-            });
-            // The first response a fresh agent gets — carry the loop guide so it learns how to drive Reticle.
-            if (ready)
-                return { ready: true, sessionCount: deps.sessions.count(), loop: RETICLE_LOOP_GUIDE };
-            const recovery = recoveryFor('no browser session connected');
-            return recovery !== undefined
-                ? { ready: false, sessionCount: 0, recovery }
-                : { ready: false, sessionCount: 0 };
-        },
-    },
 ];
 /**
  * The single actionable next-move for a pending mark: point the agent at the source (or the element

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

@@ -18,6 +18,7 @@
  * Pure: everything it needs is passed in, so the probe that discovers listening ports stays out of
  * the hot resolve() path and this stays unit-testable.
  */
+import { type LeaseBrowserState } from './lease-availability.js';
 export interface NoSessionFacts {
     /** Whether ANY session has connected to this daemon since it booted. */
     everConnected: boolean;
@@ -36,6 +37,15 @@ export interface NoSessionFacts {
     slowListeners?: readonly number[];
     /** The port this daemon is on — half of the mismatch the old message asked about. */
     port: number;
+    /**
+     * What the caller knows about the Chromium a lease would drive.
+     *
+     * Every branch below offers `reticle_lease` as the way not to wait for a human. When that browser
+     * is missing or at a revision this Playwright will not use, the offer is the one thing that cannot
+     * help — and it was being made by the same output that had just diagnosed exactly that. Optional:
+     * absent means the caller did not probe, which is not evidence the browser is missing.
+     */
+    leaseBrowser?: LeaseBrowserState | undefined;
     /**
      * The directory `initialized` was decided in, named in the message when it is known.
      *
@@ -107,6 +117,16 @@ export interface NoSessionFacts {
      * install never finished" to the user-facing diagnosis rather than only to telemetry.
      */
     daemonUpMs?: number;
+    /**
+     * Well-known Reticle ports other than `port` that currently accept a connection.
+     *
+     * Remaining half of #261. We cannot see an SDK dialling a port we are not on, but we can see that
+     * a well-known Reticle port has a listener. That is an observation: somebody else's daemon, another
+     * project, and an unrelated process all look the same from here. The sentence that reports it
+     * names the ports and refuses the conclusion. Absent or empty means nothing else was listening,
+     * which is the common case and must not gain a paragraph.
+     */
+    siblingListeners?: readonly number[];
 }
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session

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

@@ -18,8 +18,10 @@
  * Pure: everything it needs is passed in, so the probe that discovers listening ports stays out of
  * the hot resolve() path and this stays unit-testable.
  */
+import { leaseCaveat } from './lease-availability.js';
 import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
-import { STALL_AFTER_MS } from '../telemetry/instrumentation-stall.js';
+import { siblingListenerNote } from '../cli/sibling-ports.js';
+import { STALL_AFTER_MS } from './stall-clock.js';
 /** The one framework whose most likely cause differs from every other framework's. */
 const NUXT = 'nuxt';
 /**
@@ -58,6 +60,17 @@ const RETRY = SELF_RECOVERING_MARKER;
 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).';
+/**
+ * The lease advice, with the reason it cannot be taken when that is the case.
+ *
+ * A function rather than a constant so the caveat cannot be forgotten at one of the six sites that
+ * offer the lease — which is exactly how the offer came to be made by the command that had already
+ * diagnosed the problem.
+ */
+function leaseAdvice(base, facts) {
+    const caveat = leaseCaveat(facts.leaseBrowser);
+    return caveat === undefined ? base : `${base} ${caveat}`;
+}
 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).';
@@ -205,6 +218,24 @@ 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.`);
 }
+/**
+ * A listener on a well-known Reticle port we did not bind. Observation, not a cause.
+ *
+ * Leading space so the caller can concatenate it unconditionally. Empty when there is nothing to
+ * say, including when the occupied sibling is already the configured-port mismatch — that sentence
+ * already named both numbers, and repeating 4460 as a second "cause" would overclaim.
+ */
+function siblingListenerClause(facts) {
+    const occupied = facts.siblingListeners ?? [];
+    if (0 === occupied.length)
+        return '';
+    const mismatch = facts.projectPort;
+    const extra = mismatch !== undefined && mismatch !== facts.port
+        ? occupied.filter((port) => port !== mismatch)
+        : occupied;
+    const note = siblingListenerNote(facts.port, extra);
+    return note === undefined ? '' : ` ${note}`;
+}
 /**
  * The tail every "the app is wired and silent" branch ends with, ranked.
  *
@@ -216,7 +247,7 @@ 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}`);
+        `${String(facts.port)}.${portMismatchClause(facts)}${siblingListenerClause(facts)} ${NON_LOCALHOST_GATE}`);
 }
 /**
  * The scope answer, when the config was somewhere else all along.
@@ -292,7 +323,7 @@ export function diagnoseNoSession(facts) {
         }
         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 ${OPEN_CMD_BARE}), or reload the tab. ${SELF_SERVE} ${RETRY}`);
+            `the app (or run ${OPEN_CMD_BARE}), or reload the tab. ${leaseAdvice(SELF_SERVE, facts)} ${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
@@ -303,7 +334,7 @@ export function diagnoseNoSession(facts) {
             ? `${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}`;
+        return `${RESTARTED_LEAD} ${OPEN_THE_APP} ${listeners} ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${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
@@ -311,7 +342,7 @@ export function diagnoseNoSession(facts) {
     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}`);
+            `${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
     }
     if (0 === listening.length) {
         // Lead with the stronger EVIDENCE, and do not overstate what it is.
@@ -341,7 +372,7 @@ export function diagnoseNoSession(facts) {
                 `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.${searchedClause(facts)} ${URL_THEN_LEASE} ${RETRY}`);
+                `carries the SDK without that file at all.${searchedClause(facts)}${siblingListenerClause(facts)} ${leaseAdvice(URL_THEN_LEASE, facts)} ${RETRY}`);
         }
         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 ' +
@@ -359,10 +390,8 @@ 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. ${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}`);
+            `the app IS running, ask the human for its URL rather than assuming it is down. ${leaseAdvice(URL_THEN_LEASE, facts)}` +
+            `${siblingListenerClause(facts)} ${RETRY}`);
     }
     if (!initialized) {
         return ('no browser session connected, and this daemon has never seen one. ' +
@@ -372,10 +401,10 @@ export function diagnoseNoSession(facts) {
             "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 ${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}`);
+            `${unattributedListeners(listening)}${searchedClause(facts)}${siblingListenerClause(facts)} ${RETRY}`);
     }
     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 wired and the SDK is not reaching ' +
-        `this daemon (on ${String(port)}). ${rankedCauses(facts)} ${SELF_SERVE} ${RETRY}`);
+        `this daemon (on ${String(port)}). ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
 }

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

@@ -29,6 +29,11 @@ interface NextActionFacts {
     initialized: boolean;
     listening: readonly number[];
     dev: DevCommand | undefined;
+    /** Configs found in other workspace directories: positive evidence of a scope mismatch. */
+    configsElsewhere?: readonly {
+        directory: string;
+        projectId?: string;
+    }[];
     /**
      * An app for this project has connected on this port before, from durable state.
      *

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

@@ -26,6 +26,25 @@ export function nextActionFor(facts) {
                 'reticle_lease {action:"acquire", url}.',
         };
     }
+    const configsElsewhere = facts.configsElsewhere ?? [];
+    if (!facts.initialized && configsElsewhere.length > 0) {
+        const named = configsElsewhere
+            .map((config) => config.projectId === undefined
+            ? config.directory
+            : `${config.directory} ('${config.projectId}')`)
+            .join(', ');
+        const projectIds = configsElsewhere.flatMap((config) => config.projectId === undefined ? [] : [config.projectId]);
+        const leaseAlternative = 0 === projectIds.length
+            ? ''
+            : ' Alternatively, acquire the app URL explicitly with reticle_lease ' +
+                '{action:"acquire", url, projectId} using the matching projectId above.';
+        return {
+            action: NoSessionAction.OPEN_APP,
+            reason: `a \`.reticle.json\` was found outside this daemon's directory: ${named}. This is a ` +
+                "scope problem, not an install problem. Restart the daemon from the app's directory (or " +
+                `point it there), then open the app.${leaseAlternative}`,
+        };
+    }
     if (0 === facts.listening.length) {
         const dev = facts.dev;
         if (dev === undefined) {
@@ -41,9 +60,22 @@ export function nextActionFor(facts) {
             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.',
+            // "Probably", to match the branch above it and the paragraph beside it.
+            //
+            // The same fact was stated at two confidence levels by one function: no dev script said the
+            // app was "probably not running", and THIS branch — the one that hands over a command to run
+            // — asserted it flatly. That is the branch where being wrong costs something, because the
+            // agent then starts a SECOND dev server on a second port, which the guard below calls the
+            // exact confusion this probe exists to prevent.
+            //
+            // It also contradicted its own payload: the prose beside it says the scan is narrow, that a
+            // server on any other port is invisible to it, and that a running app should be checked for
+            // rather than assumed away. Measured on a machine with three dev servers up on ports the scan
+            // does not cover, it reported the app was not running.
+            reason: 'nothing is listening on the ports Reticle scans, so the app is probably not running — ' +
+                'though that scan is narrow, so if it IS up on another port, ask for its URL instead of ' +
+                `starting a second one. 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