@reticlehq/server 3.8.2 → 3.10.0

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

@@ -1,14 +1,21 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
-import { claudeAddCommand, McpClient, probeCli, terminalWidth, wrapForTerminal, } from '@reticlehq/init';
+import { mcpLauncher } from '../setup/mcp-launcher.js';
+import { claudePluginInstalled, probeCli, terminalWidth, wrapForTerminal } from '@reticlehq/init';
 import { tutorialShownSteps } from './tutorial.js';
 import { setupMcp, knownClientLabels } from '../setup/setup-mcp.js';
 import { reportInstallSteps } from '../setup/setup-install.js';
 import { registerOtherAgents } from '../setup/setup-command.js';
+import { agentLines, agentRows, awaitedClients, claudeStateDir, connectionLines, installedAgentRows, waitForAgents, } from '../setup/agent-next-steps.js';
+import { connectedAgentClients } from '../../surface/mcp/peer/agents-connected.js';
+import { reticleStateHome } from '../daemon/daemon.js';
 /** How many coding agents on this machine have Reticle's tools after this run. */
-export function handleSetupMcp(reportStep, standalone = true) {
+export function handleSetupMcp(reportStep, standalone = true, 
+/** Wait for the agents to connect. The caller decides: a terminal, and not CI. */
+waitForConnect = false) {
     const io = {
+        launcher: mcpLauncher(),
         exists: (p) => existsSync(p),
         readFile: (p) => {
             try {
@@ -48,25 +55,12 @@ export function handleSetupMcp(reportStep, standalone = true) {
             : `No coding agent config found. Looked for: ${knownClientLabels().join(', ')}. Install one, then run \`reticle setup mcp\` again.`);
         return 0;
     }
-    for (const id of result.registered)
-        io.print(`  ✓ ${id}`);
-    for (const id of result.alreadyThere)
-        io.print(`  ✓ ${id} (already set up)`);
-    for (const id of result.failed) {
-        io.print(`  ⚠ ${id}: Reticle registration failed; this agent may not have the tools.`);
-        io.print(id === McpClient.CLAUDE_CODE
-            ? `    Run this command to see the error and retry: ${claudeAddCommand().display}`
-            : '    Check your agent config file permissions, then retry: reticle setup mcp');
+    const rows = agentRows(result, io.launcher);
+    for (const line of agentLines(rows)) {
+        io.print(line);
     }
-    if (result.failed.length > 0)
+    if (result.failed.length > 0) {
         process.exitCode = 1;
-    // Said, not skipped. These are the clients whose format we will not rewrite, and they used to be
-    // counted as registered: the line below is the difference between a user who adds four lines to
-    // one file and a user who believes they are set up and has no tools.
-    for (const client of result.manual) {
-        io.print(`  ⚠ ${client.id}: add the reticle entry to ${client.configPath} by hand`);
-        if (client.docs !== undefined)
-            io.print(`    see ${client.docs}`);
     }
     /*
      * The OTHER agents, which `init` already reaches and this did not.
@@ -90,10 +84,14 @@ export function handleSetupMcp(reportStep, standalone = true) {
     // closing's Next list, where it belongs with the other things to do, not between the stages.
     if (standalone) {
         io.print('');
-        io.print('Restart your agent for it to pick up the new server.');
         io.print('Then: cd <your project> && reticle init');
+        if (waitForConnect) {
+            void reportConnections(rows, (line) => {
+                io.print(line);
+            });
+        }
     }
-    return result.registered.length + result.alreadyThere.length;
+    return result.registered.length + result.alreadyThere.length + result.pluginActive.length;
 }
 /**
  * The one line the launchers read and strip: what they cannot know and the next steps depend on.
@@ -107,11 +105,18 @@ export const INSTALL_RESULT_PREFIX = 'RETICLE_INSTALL';
 const APP_MARKERS = ['package.json', 'index.html'];
 /** Whether the folder the installer ran in is an app: `init` runs here, or after a `cd`. */
 export const InstallAppHere = { HERE: 'here', NONE: 'none' };
+/**
+ * `wait=yes`: this CLI has `reticle setup wait-agents`, and an agent has Reticle to wait for. A
+ * launcher runs the wait only when it reads this, so a launcher served from main never runs a
+ * subcommand that an older CLI does not have.
+ */
+const INSTALL_WAIT = ' wait=yes';
 export function installResultLine(agents, cwd) {
     const app = APP_MARKERS.some((file) => existsSync(join(cwd, file)))
         ? InstallAppHere.HERE
         : InstallAppHere.NONE;
-    return `${INSTALL_RESULT_PREFIX} agents=${String(agents)} app=${app}`;
+    const wait = 0 < agents ? INSTALL_WAIT : '';
+    return `${INSTALL_RESULT_PREFIX} agents=${String(agents)} app=${app}${wait}`;
 }
 /**
  * `reticle setup install` — the Node half of the one-line installer.
@@ -132,7 +137,77 @@ export function handleSetupInstall(opts, reportStep) {
     // No closing here: the installer prints the next step and the agent prompt itself, right after
     // this returns, so what this prints is progress and nothing else. Those two blocks are what the
     // ONBOARD steps below now stand for: what Reticle is for, shown before anything is asked of anyone.
-    for (const step of tutorialShownSteps())
+    for (const step of tutorialShownSteps()) {
         reportStep(step);
+    }
     process.stdout.write(`${installResultLine(agents, process.cwd())}\n`);
 }
+/** How long to wait for an agent to connect. Short: the person may not restart now. */
+const CONNECT_WAIT_MS = 60_000;
+const CONNECT_POLL_MS = 1000;
+/** Wait only where a person watches: a terminal, and not CI. */
+export function shouldWaitForAgents(isTty, isCi) {
+    return true === isTty && !isCi;
+}
+const nodeWait = {
+    read: () => connectedAgentClients(reticleStateHome()),
+    clock: {
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => {
+            setTimeout(resolve, ms);
+        }),
+    },
+};
+/** Wait (bounded) for the registered agents to connect, then say which did and what is missing. */
+export async function reportConnections(rows, print, wait = nodeWait) {
+    const want = awaitedClients(rows);
+    if (0 === want.length) {
+        return;
+    }
+    print('');
+    print(`Waiting up to ${String(CONNECT_WAIT_MS / 1000)}s for your agents to connect. Press Ctrl+C to skip.`);
+    const seen = await waitForAgents(want, wait.read, wait.clock, CONNECT_WAIT_MS, CONNECT_POLL_MS);
+    for (const line of connectionLines(rows, seen)) {
+        print(line);
+    }
+}
+/**
+ * `reticle init`: the same block and wait as `reticle setup mcp`, after its restart notice. Print the
+ * "Your agents:" block now. Returns the wait, for the caller to run last: a no-op when
+ * nobody watches.
+ */
+export function agentsBlock(rows, print, interactive, wait = nodeWait) {
+    for (const line of agentLines(rows)) {
+        print(line);
+    }
+    return interactive ? () => reportConnections(rows, print, wait) : () => Promise.resolve();
+}
+/** The agents on this machine and whether Reticle is in each config. Read only. */
+export function readAgentRows(cwd) {
+    const io = {
+        exists: (p) => existsSync(p),
+        readFile: (p) => {
+            try {
+                return readFileSync(p, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        homeDir: () => homedir(),
+    };
+    return installedAgentRows(io, cwd, claudePluginInstalled(io), claudeStateDir(), mcpLauncher());
+}
+/**
+ * `reticle setup wait-agents`: the installer's last step. The installer sends `setup install` output
+ * to a file, so that run cannot wait; this one runs with the terminal attached. Waits only where a
+ * person watches.
+ */
+export async function handleSetupWaitAgents(interactive) {
+    if (!interactive) {
+        return;
+    }
+    await reportConnections(readAgentRows(process.cwd()), (line) => {
+        process.stdout.write(`${line}\n`);
+    });
+}

package/dist/command/cli/status/status-lines.d.ts

@@ -19,10 +19,12 @@ export declare const StatusLabel: {
     readonly DAEMON: "daemon";
     readonly SESSIONS: "sessions";
     readonly AGENT_LINK: "agent link";
+    readonly AGENTS: "agents";
     readonly ACCOUNT: "account";
     readonly NEXT: "next";
     readonly SPLIT_BRAIN: "split brain";
     readonly UPDATE: "update";
+    readonly LICENSE: "license";
 };
 export type StatusLabel = (typeof StatusLabel)[keyof typeof StatusLabel];
 /** The block to print on stdout, one string per line, heading first. */

package/dist/command/cli/status/status-lines.js

@@ -14,15 +14,18 @@
  * trusting it, and prints what it can recognise. A status that cannot be rendered must still be
  * logged, so nothing here may throw.
  */
+import { mcpConnectionHint } from '../answers/mcp-connection-hint.js';
 /** Every row label this block can print. The one spelling; nothing writes a label inline. */
 export const StatusLabel = {
     DAEMON: 'daemon',
     SESSIONS: 'sessions',
     AGENT_LINK: 'agent link',
+    AGENTS: 'agents',
     ACCOUNT: 'account',
     NEXT: 'next',
     SPLIT_BRAIN: 'split brain',
     UPDATE: 'update',
+    LICENSE: 'license',
 };
 const LABELS = Object.values(StatusLabel);
 /** The heading, so a reader can tell which command produced the block. */
@@ -49,11 +52,13 @@ function num(fields, key) {
 }
 function sessionViews(fields) {
     const raw = fields['sessions'];
-    if (!Array.isArray(raw))
+    if (!Array.isArray(raw)) {
         return [];
+    }
     return raw.flatMap((s) => {
-        if ('object' !== typeof s || null === s)
+        if ('object' !== typeof s || null === s) {
             return [];
+        }
         const r = s;
         // Each of these explains something a reader would otherwise call a bug: a throttled or hidden
         // tab answers slowly, a stale one answers about a page that has moved on, and an unresponsive
@@ -77,17 +82,22 @@ export function statusLines(fields) {
     lines.push(row(StatusLabel.DAEMON, running
         ? `${OK} running${at}${pid === undefined ? '' : ` (pid ${String(pid)})`}`
         : `${NOT_OK} not running${at}`));
+    if (running && port !== undefined) {
+        lines.push(continuation(mcpConnectionHint(port)));
+    }
     // What was actually ON the port, when the pid file said nothing useful. "A stranger holds this"
     // and "nothing is here" were the same output once, and the true sentence was said by nothing a
     // person sees — so the word belongs in the prose, not only in the event.
     const presence = str(fields, 'presence');
-    if (presence !== undefined)
+    if (presence !== undefined) {
         lines.push(continuation(`port presence: ${presence}`));
+    }
     // The refusal a FOREIGN port produces. It is the whole answer when it is present, so it rides the
     // daemon row rather than waiting for a `next` that is not built in that branch.
     const reason = str(fields, 'reason');
-    if (reason !== undefined)
+    if (reason !== undefined) {
         lines.push(continuation(reason));
+    }
     if (running) {
         const count = num(fields, 'sessionCount') ?? 0;
         lines.push(row(StatusLabel.SESSIONS, count > 0
@@ -99,8 +109,9 @@ export function statusLines(fields) {
         // The daemon's own explanation for an empty session list, which outranks anything this command
         // could infer — it is the one holding the connection.
         const why = str(fields, 'why');
-        if (why !== undefined)
+        if (why !== undefined) {
             lines.push(continuation(why));
+        }
     }
     // Who is signed in, and whether this repo is linked: what `whoami` used to answer. Only when the
     // caller looked, which is what the key being present means.
@@ -112,29 +123,33 @@ export function statusLines(fields) {
         // A key the platform refused at the last sync is the answer, not "not signed in": a member
         // removed from the workspace was told to connect while the key was set, and refused.
         const refused = str(fields, 'keyRefused');
-        lines.push(row(StatusLabel.ACCOUNT, refused !== undefined
-            ? `${NOT_OK} refused at the last sync: ${refused}`
-            : who === undefined
-                ? `${NOT_OK} not signed in`
-                : `${OK} signed in as ${who}`));
+        lines.push(row(StatusLabel.ACCOUNT, accountText(refused, who)));
         const apps = appLinks(fields['workspaceApps']);
-        if (project === undefined && 0 < apps.length)
-            for (const { app, project: linked } of apps)
+        if (project === undefined && 0 < apps.length) {
+            for (const { app, project: linked } of apps) {
                 lines.push(continuation(null === linked
                     ? `${app} is not linked: run \`reticle connect\` in ${app}`
                     : `${app} is linked to ${linked}`));
-        else
+            }
+        }
+        else {
             lines.push(continuation(project === undefined
                 ? 'this repo is not linked: run `reticle connect`'
                 : `this repo is linked to ${project}${workspace === undefined ? '' : ` in workspace "${workspace}"`}`));
+        }
     }
     const client = str(fields, 'mcpClient');
     if (client !== undefined) {
         // The state in words (`mcpClientSaid`), never the record's own name for it.
         lines.push(row(StatusLabel.AGENT_LINK, str(fields, 'mcpClientSaid') ?? client));
         const action = str(fields, 'mcpClientAction');
-        if (action !== undefined)
+        if (action !== undefined) {
             lines.push(continuation(action));
+        }
+    }
+    // Per agent: connected, or the step still missing. The installer prints the same lines.
+    for (const [i, line] of agentLinesOf(fields['agents']).entries()) {
+        lines.push(0 === i ? row(StatusLabel.AGENTS, line) : continuation(line));
     }
     for (const [label, key] of [
         [StatusLabel.NEXT, 'nextAction'],
@@ -142,18 +157,58 @@ export function statusLines(fields) {
         [StatusLabel.UPDATE, 'updateAvailable'],
     ]) {
         const value = str(fields, key);
-        if (value !== undefined)
+        if (value !== undefined) {
             lines.push(row(label, value));
+        }
+    }
+    const license = licenseText(fields['license']);
+    if (license !== undefined) {
+        lines.push(row(StatusLabel.LICENSE, license));
     }
     return lines;
 }
+/** License states with no key set. `--json` carries them; the block stays silent. */
+const NO_KEY_LICENSE = new Set(['missing', 'eval']);
+/** The license row, only when a key is set: active, expired or rejected. */
+function licenseText(value) {
+    if ('object' !== typeof value || null === value) {
+        return undefined;
+    }
+    const { status, detail } = value;
+    if ('string' !== typeof status || NO_KEY_LICENSE.has(status)) {
+        return undefined;
+    }
+    return 'string' === typeof detail ? `${status}: ${detail}` : status;
+}
+/** The account row: refused at the last sync, not signed in, or signed in. */
+function accountText(refused, who) {
+    if (refused !== undefined) {
+        return `${NOT_OK} refused at the last sync: ${refused}`;
+    }
+    return who === undefined ? `${NOT_OK} not signed in` : `${OK} signed in as ${who}`;
+}
+/** The `agents` field as lines, read defensively: it is the status object, not a typed value. */
+function agentLinesOf(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.flatMap((raw) => {
+        if ('object' !== typeof raw || null === raw) {
+            return [];
+        }
+        const { said } = raw;
+        return 'string' === typeof said ? [said] : [];
+    });
+}
 /** A workspace root's apps and their links, read defensively off the status fields. */
 function appLinks(value) {
-    if (!Array.isArray(value))
+    if (!Array.isArray(value)) {
         return [];
+    }
     return value.flatMap((raw) => {
-        if ('object' !== typeof raw || null === raw)
+        if ('object' !== typeof raw || null === raw) {
             return [];
+        }
         const { app, project } = raw;
         return 'string' === typeof app
             ? [{ app, project: 'string' === typeof project ? project : null }]

package/dist/command/cli/status-fields.d.ts

@@ -32,4 +32,8 @@ export declare function splitBrainFields(port: number, projectId: string | undef
  * transport lives on stdout), so `--json` must not go through it.
  */
 export declare function reportStatus(fields: Record<string, unknown>, json: boolean): void;
-export declare function handleStatus(port: number, json?: boolean): Promise<void>;
+/**
+ * `license` is what `reticle license` printed. The caller reads it, so this directory does not
+ * reach into the license feature.
+ */
+export declare function handleStatus(port: number, json?: boolean, license?: Record<string, unknown>): Promise<void>;

package/dist/command/cli/status-fields.js

@@ -5,10 +5,14 @@ import { hasAnyAppConnectedBefore, hasProjectConnectedBefore, } from '../../memo
 import { devServersForProject } from '@reticlehq/core';
 import { readDevServers } from '../daemon/dev-servers.js';
 import { attachStatusFields } from '../../surface/mcp/attach-memory.js';
+import { connectedAgentClients } from '../../surface/mcp/peer/agents-connected.js';
+import { agentStatuses } from '../setup/agent-next-steps.js';
+import { readAgentRows } from './setup-mcp-cli.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { availableUpdate } from '../update/update-nudge.js';
 import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
-import { PortPresence, probePresence, presenceIsUsable, describePresence, } from '../daemon/binding/port-presence.js';
+import { PortPresence, probePresence, presenceIsUsable, } from '../daemon/binding/port-presence.js';
+import { describePortState } from '../daemon/port-state.js';
 import { summarizeStatus } from './launch/cli-launch.js';
 import { readProjectId } from './ports/resolve/cli-port.js';
 import { accountStatusFields } from './cloud-cli.js';
@@ -35,7 +39,7 @@ export function withNextAction(facts) {
  */
 export function splitBrainFields(port, projectId) {
     const home = reticleStateHome();
-    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)));
+    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)), { projectId, home });
     const note = elsewhere ?? wrongDaemonNote(port, resolveDaemonForProject(projectId, home, isAlive));
     return note === undefined ? {} : { splitBrain: note };
 }
@@ -56,7 +60,21 @@ export function reportStatus(fields, json) {
     }
     process.stdout.write(`${statusLines(fields).join('\n')}\n`);
 }
-export async function handleStatus(port, json = false) {
+/**
+ * Each agent on this machine: connected, or the step still missing. The same lines the installer
+ * prints after its wait. Absent when no agent is on this machine.
+ */
+function agentStatusFields() {
+    const rows = readAgentRows(process.cwd());
+    return 0 === rows.length
+        ? {}
+        : { agents: agentStatuses(rows, connectedAgentClients(reticleStateHome())) };
+}
+/**
+ * `license` is what `reticle license` printed. The caller reads it, so this directory does not
+ * reach into the license feature.
+ */
+export async function handleStatus(port, json = false, license) {
     // A broken session file must not cost the reader the rest of the status.
     const account = await accountStatusFields().catch(() => ({}));
     // At a workspace root that is no app of its own, each app and its link: "not linked" named none.
@@ -66,7 +84,7 @@ export async function handleStatus(port, json = false) {
             workspaceApps: await workspaceAppLinks(process.cwd(), localLinkOf).catch(() => []),
         });
     }
-    const report = (fields) => reportStatus({ ...fields, ...account }, json);
+    const report = (fields) => reportStatus({ ...fields, ...account, ...(license === undefined ? {} : { license }) }, json);
     const pid = readPid(port);
     // Durable, so it survives the daemon idling out — which is the state `status` is most often run in.
     const projectId = readProjectId(process.cwd());
@@ -81,7 +99,7 @@ export async function handleStatus(port, json = false) {
     // The OTHER half of the install, and the half this command could not see. A host that registers
     // Reticle and never lists its tools looks exactly like an abandoned install from here — same idle
     // daemon, same zero sessions — and the user sees a tool that does nothing. See attach-memory.ts.
-    const client = attachStatusFields(reticleStateHome(), port);
+    const client = { ...attachStatusFields(reticleStateHome(), port), ...agentStatusFields() };
     // What the dev servers themselves said. The reason this command could previously only guess at
     // whether the app was running is that it had no way to see one; now the ones carrying Reticle
     // announce, and the advice below stops contradicting the terminal the reader is looking at.
@@ -103,7 +121,7 @@ export async function handleStatus(port, json = false) {
             port,
             running: false,
             presence,
-            ...(presence === PortPresence.FOREIGN ? { reason: describePresence(presence, port) } : {}),
+            ...(presence === PortPresence.FOREIGN ? { reason: describePortState(presence, port) } : {}),
             // `init` promises this command says why the app has not connected. Without it the answer was
             // `running: false` and nothing else, which reads as "Reticle is broken" for what is usually
             // just a daemon that has not been asked to do anything yet.

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

@@ -1,6 +1,11 @@
 import type { CloudConfig } from '../../memory/cloud/cloud-sync.js';
 import { type FreeDrive } from '../../features/harness/platform/platform-drives.js';
 export declare const MSG_SIGN_IN_FIRST = "Link this folder first: reticle connect. It signs you in if you are not, and it is free, no card.";
+/**
+ * The local path that needs no account and no MCP tools. An agent whose client had no reticle_*
+ * tools ran `try`, was told to sign in, and stopped with no verdict.
+ */
+export declare const MSG_LOCAL_CHECK: string;
 /** The whole drive, model turns and browser included, before the CLI stops waiting for it. */
 export declare const TRY_BUDGET_MS = 120000;
 /** Model turns in the one free drive. Bounds what it costs, not what it may find. */
@@ -43,6 +48,8 @@ export declare function summarizeTry(journeys: readonly TryJourney[]): string[];
 export declare function runTry(args: TryArgs, ports: TryPorts): Promise<number>;
 /** The journeys out of an explore report, or one journey graded from the drive when unplanned. */
 export declare function journeysOf(report: Record<string, unknown>, persona?: string): TryJourney[];
+/** A daemon serving `port`: the one already there, or one started now. Undefined when ready. */
+export declare function ensureTryDaemon(port: number): Promise<string | undefined>;
 /** What `try` borrows from the cloud commands, passed in so neither module imports the other. */
 export interface TryCloud {
     push: () => Promise<number>;

package/dist/command/cli/try-command.js

@@ -19,7 +19,8 @@ import { describeUnsynced, unsyncedRoots } from '../../memory/cloud/unsynced-roo
 import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
 import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../portal/bridge/pairing-token.js';
 import { spawnDaemon } from '../daemon/daemon.js';
-import { PortPresence, describePresence, presenceIsUsable, probePresence, } from '../daemon/binding/port-presence.js';
+import { PortPresence, presenceIsUsable, probePresence, } from '../daemon/binding/port-presence.js';
+import { describePortState } from '../daemon/port-state.js';
 import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
 import { probeDaemon, waitForDaemonBind } from '../../surface/mcp/mcp-proxy.js';
 import { readProjectPort } from './ports/resolve/cli-port.js';
@@ -28,6 +29,12 @@ import { seeRunLine } from '../../memory/project/sync-status.js';
 import { DAEMON_INNER_COMMAND, PORT_FLAG } from './cli-parse.js';
 import { acquireLease, connectOverSse, endpointFor, exploreToEnd, refusalText, releaseLease, verdictOf, } from './adhoc-verdict.js';
 export const MSG_SIGN_IN_FIRST = 'Link this folder first: reticle connect. It signs you in if you are not, and it is free, no card.';
+/**
+ * The local path that needs no account and no MCP tools. An agent whose client had no reticle_*
+ * tools ran `try`, was told to sign in, and stopped with no verdict.
+ */
+export const MSG_LOCAL_CHECK = 'To check one thing on this machine with no account and no MCP tools: ' +
+    `reticle verify <url> --expect '{"kind":"text","contains":"..."}'. Exit 0 means it held.`;
 const PERSONA_FLAG = '--persona';
 /** The whole drive, model turns and browser included, before the CLI stops waiting for it. */
 export const TRY_BUDGET_MS = 120_000;
@@ -89,6 +96,7 @@ export async function runTry(args, ports) {
     const cloud = await ports.linked();
     if (null === cloud) {
         ports.fail(MSG_SIGN_IN_FIRST);
+        ports.fail(MSG_LOCAL_CHECK);
         return EXIT_FAIL;
     }
     const grant = await ports.requestDrive(cloud);
@@ -165,13 +173,13 @@ function tryPort(cwd) {
     return readProjectPort(cwd) ?? RETICLE_DEFAULT_PORT;
 }
 /** A daemon serving `port`: the one already there, or one started now. Undefined when ready. */
-async function ensureTryDaemon(port) {
+export async function ensureTryDaemon(port) {
     const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
     if (presenceIsUsable(presence))
         return undefined;
     // A stranger on the port: a daemon spawned now could not bind, so say who holds it instead.
     if (PortPresence.FREE !== presence)
-        return describePresence(presence, port);
+        return describePortState(presence, port);
     const script = process.argv[1];
     if (script === undefined)
         return 'Cannot locate the reticle daemon script.';

package/dist/command/cli/two-builds/compare-command.d.ts

@@ -0,0 +1,48 @@
+import { type OpenedPage } from '../../../features/compare/behaviour-compare.js';
+import { type CompareUrls } from '../../../features/compare/behaviour-report.js';
+import { type StateIo } from '../../../features/compare/outside/state-sources.js';
+import { type ToolCaller } from '../daemon-link/daemon-client.js';
+/** The pairing token the daemon asks for, or undefined when there is none. */
+export declare function pairingToken(): string | undefined;
+/** One leased tab as the compare driver. Every call goes through `reticle_run` on that tab. */
+export declare function leasedPage(caller: ToolCaller, url: string, sessionId: string): OpenedPage;
+export interface CompareCommandOptions extends CompareUrls {
+    json: boolean;
+    port: number;
+    token?: string;
+    /** The caller's project `.reticle`, where the leased tabs write their runs. */
+    root?: string;
+    /** Injected so a test can use its own transport. */
+    connect?: (endpoint: URL) => Promise<ToolCaller>;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    fetchText?: (url: string) => Promise<string | undefined>;
+    /** `--report <file>`: also write the comparison as an HTML page there. */
+    report?: string;
+    /** Injected so a test can capture the report; the default writes the file. */
+    writeReport?: (path: string, html: string) => void;
+    /** The path of the declared state sources file (`--state`). */
+    state?: string;
+}
+export declare const MSG_REPORT_WRITTEN = "Report:";
+export declare const MSG_REPORT_FAILED = "Report not written:";
+/** State sources read on this machine: a shell, `docker exec`, `fetch` and the file system. */
+export declare const hostStateIo: StateIo;
+/** Compare the builds through the daemon on `port`. Returns the lines to print and the exit code. */
+export declare function runCompareCommand(options: CompareCommandOptions): Promise<{
+    code: number;
+    lines: string[];
+}>;
+/**
+ * The command. It needs a daemon, as an agent does: `ensureDaemon` attaches to the one on the port,
+ * or starts one. Nothing here stops a daemon, so an agent's MCP link stays up.
+ */
+export declare function handleCompare(parsed: CompareUrls & {
+    json: boolean;
+    port: number;
+    report?: string;
+    state?: string;
+}, ensureDaemon: (port: number) => Promise<void>, out: {
+    line: (text: string) => void;
+    exit: (code: number) => void;
+}): Promise<void>;