@reticlehq/server 2.10.0 → 2.12.0

package/dist/cli/cloud-cli.js

@@ -16,7 +16,7 @@ import { z } from 'zod';
 import { createNodeFileSystem } from '../project/fs-port.js';
 import { RunStore } from '../runs/run-store.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
-import { syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 const DEFAULT_URL = 'http://localhost:8890';
 const RETICLE_DIR = '.reticle';
 const SESSION_FILE = 'session.json';
@@ -77,9 +77,15 @@ const readSession = async () => {
 };
 const baseUrl = (session) => {
     const env = process.env['RETICLE_CLOUD_URL'];
-    return env !== undefined && env.length > 0
-        ? env.replace(/\/+$/, '')
-        : (session?.url ?? DEFAULT_URL);
+    if (env !== undefined && env.length > 0)
+        return env.replace(/\/+$/, '');
+    if (null !== session && session.url.length > 0)
+        return session.url;
+    // Falling back to the local dev default WITHOUT being told to: say so on stderr, so a fresh
+    // `reticle login` never silently dials localhost. Humans read the hint; agents parse stdout
+    // JSON and ignore stderr, so stdout stays machine-readable either way.
+    hint(`no RETICLE_CLOUD_URL set — dialling the local dev default ${DEFAULT_URL} (set it for a real deployment)`);
+    return DEFAULT_URL;
 };
 /** Bearer for a command: an explicit api key (agent) wins, else the human login token. */
 const bearer = (session) => {
@@ -101,7 +107,7 @@ const api = async (method, url, token, body) => {
     };
     if (body !== undefined)
         init.body = JSON.stringify(body);
-    const res = await fetch(url, init);
+    const res = await cloudFetch(url, init);
     const text = await res.text();
     let json = null;
     if (text.length > 0) {
@@ -438,7 +444,7 @@ const cmdPush = async () => {
         const read = await store.read(id);
         if (!read.ok)
             continue;
-        const res = await syncRunToCloud(read.run, cloud.config, (u, init) => fetch(u, init));
+        const res = await syncRunToCloud(read.run, cloud.config, cloudFetch);
         if (res.outcome === SyncOutcome.SYNCED)
             pushed += 1;
         else if (res.outcome === SyncOutcome.FAILED)

package/dist/cli/config-discovery.d.ts

@@ -19,7 +19,7 @@
  * silently is how an agent ends up with a confident verdict about an app it never touched. Callers
  * are handed the list and must name it.
  */
-export interface FoundConfig {
+interface FoundConfig {
     /** Absolute path to the `.reticle.json`. */
     path: string;
     /** The directory it configures — what a reader needs in order to act. */
@@ -33,3 +33,4 @@ export interface ConfigDiscovery {
     searched: string[];
 }
 export declare function discoverProjectConfigs(cwd: string): ConfigDiscovery;
+export {};

package/dist/cli/doctor-rows.d.ts

@@ -18,7 +18,8 @@
  * row added and never documented.
  *
  * NOT every row prints on every run. `version` prints only on skew, `port check` only on a
- * mismatch, `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
+ * mismatch, `sibling` only when a well-known Reticle port other than ours has a listener,
+ * `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
  * vocabulary is therefore "what this command can print", not "what one run printed" — a guard built
  * by scraping a single invocation would silently stop covering the conditional rows, which are
  * exactly the ones a reader is least likely to have seen before.
@@ -32,6 +33,7 @@ export declare const DoctorRow: {
     readonly SESSIONS: "sessions";
     readonly BRIDGE_PORT: "bridge port";
     readonly PORT_CHECK: "port check";
+    readonly SIBLING: "sibling";
     readonly DAEMON_LOG: "daemon log";
     readonly TRACING: "tracing";
     readonly DESKTOP: "desktop";

package/dist/cli/doctor-rows.js

@@ -18,7 +18,8 @@
  * row added and never documented.
  *
  * NOT every row prints on every run. `version` prints only on skew, `port check` only on a
- * mismatch, `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
+ * mismatch, `sibling` only when a well-known Reticle port other than ours has a listener,
+ * `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
  * vocabulary is therefore "what this command can print", not "what one run printed" — a guard built
  * by scraping a single invocation would silently stop covering the conditional rows, which are
  * exactly the ones a reader is least likely to have seen before.
@@ -32,6 +33,7 @@ export const DoctorRow = {
     SESSIONS: 'sessions',
     BRIDGE_PORT: 'bridge port',
     PORT_CHECK: 'port check',
+    SIBLING: 'sibling',
     DAEMON_LOG: 'daemon log',
     TRACING: 'tracing',
     DESKTOP: 'desktop',

package/dist/cli/gate-exit.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What `reticle gate` means by its exit code.
+ *
+ * Split out of the handler because two different readers depend on it and they want opposite
+ * things. CI wants any problem to be a failure. A Stop hook — the layer that makes verification
+ * unskippable — wants to block a real regression and NOT block a project that has simply not
+ * recorded a flow yet, which is every project on its first day.
+ *
+ * `NOTHING_TO_CHECK` stays non-zero deliberately. The gate exits non-zero over an empty suite
+ * because "nothing was checked" and "everything passed" are indistinguishable from the outside,
+ * and that reasoning does not stop being true just because a second caller appeared.
+ */
+export declare const GateExit: {
+    /** Affected flows were checked and hold. */
+    readonly PASS: 0;
+    /** Something is actually wrong: an affected flow with no passing artifact, a downgraded
+     * assertion, deleted coverage. A caller should stop here. */
+    readonly FAIL: 1;
+    /** The gate ran and had nothing to judge — no flows recorded. Non-zero, but not a regression. */
+    readonly NOTHING_TO_CHECK: 2;
+};

package/dist/cli/gate-exit.js

@@ -0,0 +1,21 @@
+/**
+ * What `reticle gate` means by its exit code.
+ *
+ * Split out of the handler because two different readers depend on it and they want opposite
+ * things. CI wants any problem to be a failure. A Stop hook — the layer that makes verification
+ * unskippable — wants to block a real regression and NOT block a project that has simply not
+ * recorded a flow yet, which is every project on its first day.
+ *
+ * `NOTHING_TO_CHECK` stays non-zero deliberately. The gate exits non-zero over an empty suite
+ * because "nothing was checked" and "everything passed" are indistinguishable from the outside,
+ * and that reasoning does not stop being true just because a second caller appeared.
+ */
+export const GateExit = {
+    /** Affected flows were checked and hold. */
+    PASS: 0,
+    /** Something is actually wrong: an affected flow with no passing artifact, a downgraded
+     * assertion, deleted coverage. A caller should stop here. */
+    FAIL: 1,
+    /** The gate ran and had nothing to judge — no flows recorded. Non-zero, but not a regression. */
+    NOTHING_TO_CHECK: 2,
+};

package/dist/cli/gate-hook-message.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a Stop hook shows the human when the gate blocks.
+ *
+ * A hook runs at the moment an agent says it is finished, and whatever it prints is the last thing
+ * anybody reads. The gate's normal output is one long JSON line built for CI to parse; pasted into
+ * a terminal at the end of a session it is a wall of names with no instruction attached.
+ *
+ * So the hook path gets prose. It has to answer three things in the order a person asks them: what
+ * is not verified, why that matters right now, and what to do about it — including how to proceed
+ * anyway, because a gate with no honest escape hatch gets disabled entirely and then protects
+ * nothing.
+ */
+/** Named so a reader of the hook output knows the flag is real and not a suggestion. */
+export declare const GATE_SKIP_ENV = "RETICLE_SKIP_GATE";
+export interface GateHookInput {
+    /** Flows the changed files touch that have no passing artifact. */
+    uncovered: readonly string[];
+    /** Flows held back as flaky — reported, never counted as a pass. */
+    quarantined: readonly string[];
+    /** Assertions that dropped from a real consequence to a fakeable one. */
+    downgraded: readonly string[];
+    /** Flows whose coverage was deleted while their files changed. */
+    deleted: readonly string[];
+}
+/**
+ * The message, or undefined when there is nothing to say.
+ *
+ * `NOTHING_TO_CHECK` returns undefined on purpose: a project that has not recorded a flow yet is
+ * every project on its first day, and blocking there would make the first experience of Reticle an
+ * agent that cannot stop. The gate still reports it — this decides only whether a HUMAN is
+ * interrupted.
+ */
+export declare function gateHookMessage(exit: number, input: GateHookInput): string | undefined;

package/dist/cli/gate-hook-message.js

@@ -0,0 +1,46 @@
+/**
+ * What a Stop hook shows the human when the gate blocks.
+ *
+ * A hook runs at the moment an agent says it is finished, and whatever it prints is the last thing
+ * anybody reads. The gate's normal output is one long JSON line built for CI to parse; pasted into
+ * a terminal at the end of a session it is a wall of names with no instruction attached.
+ *
+ * So the hook path gets prose. It has to answer three things in the order a person asks them: what
+ * is not verified, why that matters right now, and what to do about it — including how to proceed
+ * anyway, because a gate with no honest escape hatch gets disabled entirely and then protects
+ * nothing.
+ */
+import { GateExit } from './gate-exit.js';
+/** Named so a reader of the hook output knows the flag is real and not a suggestion. */
+export const GATE_SKIP_ENV = 'RETICLE_SKIP_GATE';
+const MAX_NAMED = 5;
+/** A short list, then a count — a hook that prints forty names is a hook people turn off. */
+function name(list) {
+    const shown = list.slice(0, MAX_NAMED).join(', ');
+    return list.length > MAX_NAMED ? `${shown} (+${String(list.length - MAX_NAMED)} more)` : shown;
+}
+/**
+ * The message, or undefined when there is nothing to say.
+ *
+ * `NOTHING_TO_CHECK` returns undefined on purpose: a project that has not recorded a flow yet is
+ * every project on its first day, and blocking there would make the first experience of Reticle an
+ * agent that cannot stop. The gate still reports it — this decides only whether a HUMAN is
+ * interrupted.
+ */
+export function gateHookMessage(exit, input) {
+    if (GateExit.FAIL !== exit)
+        return undefined;
+    const lines = ['Reticle: this change is not verified.'];
+    if (input.uncovered.length > 0)
+        lines.push(`  no passing run covers: ${name(input.uncovered)}`);
+    if (input.downgraded.length > 0)
+        lines.push(`  assertions weakened to something fakeable: ${name(input.downgraded)} — a check that cannot fail is not a check`);
+    if (input.deleted.length > 0)
+        lines.push(`  coverage deleted while its files changed: ${name(input.deleted)}`);
+    if (input.quarantined.length > 0)
+        lines.push(`  held back as flaky, so proving nothing: ${name(input.quarantined)}`);
+    lines.push('');
+    lines.push('  Replay them: npx @reticlehq/server verify <your app url>');
+    lines.push(`  Or proceed anyway: ${GATE_SKIP_ENV}=1 — it is recorded, not silent.`);
+    return lines.join('\n');
+}

package/dist/cli/mcp-command.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `reticle mcp` — the process an editor launches, and the one whose failure a user experiences as
+ * "the MCP server disconnected".
+ *
+ * Split out of `cli.ts` when that file passed the 1000-line backstop. It earns its own module rather
+ * than being an arbitrary slice: everything here is about ONE decision — which daemon this agent
+ * talks to for the rest of its life — and the port resolution at the top is the fix for agents on
+ * different projects silently sharing one daemon, one identity and one blast radius.
+ */
+/**
+ * MCP proxy mode: ensures the daemon is running, then bridges Claude Code's
+ * stdin/stdout to the daemon's SSE endpoint. This is the recommended way to
+ * configure Reticle in.mcp.json — users never need to manage the daemon manually.
+ *
+ * Pass --drive <url> to have the daemon launch its own Playwright browser at that
+ * URL. The agent then has full autonomous control without relying on the user's browser.
+ */
+export declare function handleMcp(opts: {
+    port: number;
+    driveUrl?: string;
+    headless: boolean;
+    http: boolean;
+    httpPort?: number;
+    httpToken?: string;
+}): Promise<void>;

package/dist/cli/mcp-command.js

@@ -0,0 +1,143 @@
+/**
+ * `reticle mcp` — the process an editor launches, and the one whose failure a user experiences as
+ * "the MCP server disconnected".
+ *
+ * Split out of `cli.ts` when that file passed the 1000-line backstop. It earns its own module rather
+ * than being an arbitrary slice: everything here is about ONE decision — which daemon this agent
+ * talks to for the rest of its life — and the port resolution at the top is the fix for agents on
+ * different projects silently sharing one daemon, one identity and one blast radius.
+ */
+import { log } from '../log.js';
+import { isAlive, spawnDaemon, reticleStateHome } from '../daemon/daemon.js';
+import { PortPresence, probePresence, presenceIsUsable, describePresence, } from '../daemon/port-presence.js';
+import { waitForDaemon, startMcpProxy, probeDaemon, proxyLog, setProxyLogPort, } from '../mcp/mcp-proxy.js';
+import { installProxyResilience } from '../daemon/daemon-resilience.js';
+import { readProjectId } from './cli-port.js';
+import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, } from './cli-parse.js';
+import { resolveMcpPort } from '../daemon/daemon-resolve.js';
+import { pickDaemonPortToBind } from '../daemon/free-port.js';
+import { fetchStatus } from './cli-launch.js';
+/**
+ * MCP proxy mode: ensures the daemon is running, then bridges Claude Code's
+ * stdin/stdout to the daemon's SSE endpoint. This is the recommended way to
+ * configure Reticle in.mcp.json — users never need to manage the daemon manually.
+ *
+ * Pass --drive <url> to have the daemon launch its own Playwright browser at that
+ * URL. The agent then has full autonomous control without relying on the user's browser.
+ */
+export async function handleMcp(opts) {
+    const { driveUrl, headless, http, httpPort, httpToken } = opts;
+    // Decided before anything else, because every line below is about ONE port and the wrong one means
+    // serving another project's daemon. `resolveMcpPort` prefers our own daemon wherever it moved to,
+    // takes the requested port when it is free or unclaimed, and relocates to an OS-assigned port
+    // rather than adopting a daemon that belongs to somebody else.
+    //
+    // Synchronous-looking on purpose: a probe is one loopback connect, and doing it here keeps the
+    // proxy's transport built around a single fixed number. Making the proxy chase a moving port would
+    // mean reworking the reconnect path, which is the one piece whose failure reads to a user as
+    // "the MCP server disappeared mid-session".
+    const port = await resolveMcpPort(opts.port, readProjectId(process.cwd()), reticleStateHome(), {
+        alive: isAlive,
+        daemonPresent: async (p) => presenceIsUsable(await probePresence(p, { tcpOpen: probeDaemon, status: fetchStatus })),
+        pickPort: (p) => pickDaemonPortToBind(p),
+    });
+    if (port !== opts.port) {
+        log('reticle_mcp_port_relocated', {
+            requested: opts.port,
+            port,
+            reason: 'the requested port serves a different project',
+        });
+    }
+    // The proxy IS the MCP server the editor launched. Nothing respawns it, so an uncaught throw here
+    // is what a user experiences as "the MCP server disconnected — open /mcp and reconnect". Log it,
+    // report it, keep serving: the reconnect and dormant paths already know how to rebuild the only
+    // state this process has. See installProxyResilience for why its rule inverts the daemon's.
+    // The proxy's crash handlers must write to the proxy's LOG FILE, not just stderr. The editor
+    // swallows stderr, so wiring these to `log` meant a crash was handled and then unrecorded — the
+    // failure a user reports as "it disconnected" left nothing behind to read.
+    setProxyLogPort(port);
+    installProxyResilience(process, proxyLog);
+    /**
+     * Make sure a daemon is on the port, spawning one if not.
+     *
+     * Called on first start AND on every reconnect. The proxy used to only retry the socket, so a
+     * daemon that exited — crashed, `reticle stop`, or self-shut-down as idle — meant the retries hit
+     * a dead port until the budget ran out and the agent's MCP server exited with it. Reticle simply
+     * disappeared mid-session with nothing said. Respawning here makes the reconnect self-healing.
+     */
+    const ensure = async () => {
+        // The same question every other surface asks. It used to be a bare TCP connect, so a stranger on
+        // the bridge port answered "a daemon is here" — the proxy connected, the stream ended, and each
+        // client request woke into the identical non-answer. Rejecting here is what puts the proxy
+        // dormant with a reason, instead of pretending the wake succeeded.
+        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        if (presenceIsUsable(presence))
+            return;
+        if (PortPresence.FREE !== presence)
+            throw new Error(describePresence(presence, port));
+        const scriptPath = process.argv[1];
+        if (scriptPath === undefined) {
+            log('reticle_mcp_no_script', {});
+            process.exit(1);
+        }
+        const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)];
+        if (driveUrl !== undefined) {
+            daemonArgs.push(DRIVE_FLAG, driveUrl);
+            if (!headless)
+                daemonArgs.push(HEADED_FLAG);
+        }
+        // Forward the HTTP-verify flags too (previously silently dropped for `reticle mcp`).
+        if (http) {
+            daemonArgs.push(HTTP_FLAG);
+            if (httpPort !== undefined)
+                daemonArgs.push(HTTP_PORT_FLAG, String(httpPort));
+            if (httpToken !== undefined)
+                daemonArgs.push(HTTP_TOKEN_FLAG, httpToken);
+        }
+        spawnDaemon(process.execPath, scriptPath, daemonArgs, port);
+        // Announce the daemon only once the PORT ACCEPTS. This line used to be written the instant the
+        // child was spawned, which on a Windows first bootstrap meant `reticle_mcp_daemon_started`
+        // followed about ten seconds later by `reticle_mcp_daemon_unavailable` and a first
+        // `reticle_sessions` that expired. A readiness signal that precedes readiness is worse than
+        // none: a client that believes it stops waiting for the thing that has not happened.
+        await waitForDaemon(port);
+        log('reticle_mcp_daemon_started', { port, ...(driveUrl !== undefined ? { driveUrl } : {}) });
+    };
+    // Start the proxy WHATEVER happened to the daemon.
+    //
+    // This used to exit(1) when `ensure` failed, which is the third way an MCP server disappears on a
+    // user: something else is holding the bridge port — a foreign daemon from another project, a
+    // half-dead process, a port a colleague's tool grabbed — the spawned daemon cannot bind, and the
+    // editor shows a server that failed to start. Nothing about that is unrecoverable: the proxy
+    // answers `initialize` itself, serves the cached catalog, and its wake path retries a daemon on
+    // every client request. Present-and-complaining beats absent, because absent needs a human.
+    // `void`: the chain handles its own failure and the process must not wait on it — the proxy is
+    // started from `finally` either way.
+    void ensure()
+        .catch((err) => {
+        log('reticle_mcp_daemon_unavailable', {
+            error: err instanceof Error ? err.message : String(err),
+            note: 'serving anyway — the next tool call will try to start a daemon again',
+        });
+    })
+        .finally(() => {
+        // Also `void`: the proxy runs for the life of the process and is never awaited by anyone.
+        //
+        // The `.catch` is load-bearing despite that. `startMcpProxy` rejects when its FIRST connect
+        // fails — which is precisely the case this block exists to tolerate, a daemon that is not
+        // there yet — and with nothing attached that reject became an unhandledRejection. Reported
+        // from a win32 user as a crash reading `connect ECONNREFUSED` with an EMPTY frame list,
+        // because the stack of a refused socket is entirely node internals and the privacy filter
+        // keeps only Reticle frames. So the one path we most want diagnosable arrived as an anonymous
+        // crash. The proxy itself is unaffected — it has already installed its stdin reader and goes
+        // on serving from cache, waking a daemon on the next request — which is exactly why this
+        // must be logged as the expected condition it is rather than reported as a defect.
+        void startMcpProxy(port, ensure).catch((err) => {
+            log('reticle_mcp_proxy_first_connect_failed', {
+                port,
+                error: err instanceof Error ? err.message : String(err),
+                note: 'serving from cache; the next client request will try to start a daemon',
+            });
+        });
+    });
+}

package/dist/cli/sibling-ports.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Well-known Reticle ports other than the one this daemon bound.
+ *
+ * The remaining half of #261: when the SDK dials 4460 and we listen on 4400, we cannot see the
+ * refused inbound — but we CAN notice that a well-known Reticle port other than ours has a
+ * listener. That is an observation, not a diagnosis. A neighbour's daemon, another project, or an
+ * unrelated process on 4460 all look identical from here, so the sentence that reports it must not
+ * conclude that it is the daemon this app wants. Maintainer constraint on the issue: report the
+ * observation without the conclusion.
+ */
+/**
+ * The port the bench fixture's SDK dials.
+ *
+ * Deliberate, and must not be "fixed" onto the default: `bench/harness/ports.mjs` documents a past
+ * incident caused by having more than one source of truth for it. It exists so a default daemon on
+ * 4400 and a bench run never collide. Doctor and the no-session diagnosis probe it as a sibling
+ * of 4400 for that reason — it is the port the original silent no-connect was on.
+ */
+export declare const RETICLE_BENCH_PORT = 4460;
+/** Ports a Reticle daemon is known to occupy. Probe every one except the port we ourselves bound. */
+export declare const WELL_KNOWN_RETICLE_PORTS: readonly number[];
+/** Well-known Reticle ports other than `boundPort`. Empty when we are the only well-known occupant. */
+export declare function siblingPorts(boundPort: number, known?: readonly number[]): readonly number[];
+/**
+ * One sentence for a listener on a sibling Reticle port. `undefined` when there is nothing to say.
+ *
+ * Wording is load-bearing: it names the observation and refuses the conclusion. A test pins that it
+ * does not claim the listener is the daemon this app wants, or that the SDK is dialling it.
+ */
+export declare function siblingListenerNote(boundPort: number, occupiedSiblings: readonly number[]): string | undefined;
+/**
+ * Which well-known siblings currently accept a TCP connection.
+ *
+ * Pure in the rule, impure at the edge: `isListening` is injected so this can be tested without a
+ * socket, and so a lying probe is a separate failure from a lying sentence.
+ */
+export declare function findOccupiedSiblings(boundPort: number, isListening: (port: number) => Promise<boolean>): Promise<readonly number[]>;

package/dist/cli/sibling-ports.js

@@ -0,0 +1,56 @@
+/**
+ * Well-known Reticle ports other than the one this daemon bound.
+ *
+ * The remaining half of #261: when the SDK dials 4460 and we listen on 4400, we cannot see the
+ * refused inbound — but we CAN notice that a well-known Reticle port other than ours has a
+ * listener. That is an observation, not a diagnosis. A neighbour's daemon, another project, or an
+ * unrelated process on 4460 all look identical from here, so the sentence that reports it must not
+ * conclude that it is the daemon this app wants. Maintainer constraint on the issue: report the
+ * observation without the conclusion.
+ */
+import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+/**
+ * The port the bench fixture's SDK dials.
+ *
+ * Deliberate, and must not be "fixed" onto the default: `bench/harness/ports.mjs` documents a past
+ * incident caused by having more than one source of truth for it. It exists so a default daemon on
+ * 4400 and a bench run never collide. Doctor and the no-session diagnosis probe it as a sibling
+ * of 4400 for that reason — it is the port the original silent no-connect was on.
+ */
+export const RETICLE_BENCH_PORT = 4460;
+/** Ports a Reticle daemon is known to occupy. Probe every one except the port we ourselves bound. */
+export const WELL_KNOWN_RETICLE_PORTS = [
+    RETICLE_DEFAULT_PORT,
+    RETICLE_BENCH_PORT,
+];
+/** Well-known Reticle ports other than `boundPort`. Empty when we are the only well-known occupant. */
+export function siblingPorts(boundPort, known = WELL_KNOWN_RETICLE_PORTS) {
+    return known.filter((port) => port !== boundPort);
+}
+/**
+ * One sentence for a listener on a sibling Reticle port. `undefined` when there is nothing to say.
+ *
+ * Wording is load-bearing: it names the observation and refuses the conclusion. A test pins that it
+ * does not claim the listener is the daemon this app wants, or that the SDK is dialling it.
+ */
+export function siblingListenerNote(boundPort, occupiedSiblings) {
+    if (0 === occupiedSiblings.length)
+        return undefined;
+    const listed = occupiedSiblings.map((port) => `:${String(port)}`).join(', ');
+    return (`something is listening on ${listed}, which this daemon is not` +
+        ` (this daemon is on :${String(boundPort)}); that may or may not be related.`);
+}
+/**
+ * Which well-known siblings currently accept a TCP connection.
+ *
+ * Pure in the rule, impure at the edge: `isListening` is injected so this can be tested without a
+ * socket, and so a lying probe is a separate failure from a lying sentence.
+ */
+export async function findOccupiedSiblings(boundPort, isListening) {
+    const occupied = [];
+    for (const port of siblingPorts(boundPort)) {
+        if (await isListening(port))
+            occupied.push(port);
+    }
+    return occupied;
+}