@reticlehq/server 3.8.1 → 3.9.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,6 +19,7 @@ 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";

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

@@ -19,6 +19,7 @@ export const StatusLabel = {
     DAEMON: 'daemon',
     SESSIONS: 'sessions',
     AGENT_LINK: 'agent link',
+    AGENTS: 'agents',
     ACCOUNT: 'account',
     NEXT: 'next',
     SPLIT_BRAIN: 'split brain',
@@ -49,11 +50,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
@@ -81,13 +84,15 @@ export function statusLines(fields) {
     // 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 +104,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 +118,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 +152,41 @@ export function statusLines(fields) {
         [StatusLabel.UPDATE, 'updateAvailable'],
     ]) {
         const value = str(fields, key);
-        if (value !== undefined)
+        if (value !== undefined) {
             lines.push(row(label, value));
+        }
     }
     return lines;
 }
+/** 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.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';
@@ -56,6 +60,16 @@ export function reportStatus(fields, json) {
     }
     process.stdout.write(`${statusLines(fields).join('\n')}\n`);
 }
+/**
+ * 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())) };
+}
 export async function handleStatus(port, json = false) {
     // A broken session file must not cost the reader the rest of the status.
     const account = await accountStatusFields().catch(() => ({}));
@@ -81,7 +95,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 +117,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.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-import { PlatformLinkVia } from '@reticlehq/core/telemetry';
+import { OnboardingPhase, PlatformLinkVia } from '@reticlehq/core/telemetry';
 import { hudSignIn } from './cli/cloud-login.js';
-import { handleSetupMcp, handleSetupInstall } from './cli/setup-mcp-cli.js';
+import { agentsBlock, handleSetupMcp, handleSetupInstall, handleSetupWaitAgents, readAgentRows, shouldWaitForAgents, } from './cli/setup-mcp-cli.js';
 import { reportStepFromCli } from './cli-onboarding.js';
 import { pathToFileURL } from 'node:url';
 import { openFailureNote, openLaunchFailureNote } from './cli/answers/open-note.js';
+import { writeCiHint } from './cli/ci-hint.js';
+import { currentAutomationHint, isCiEnv } from '../telemetry/automation-hint.js';
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { installCrashGuard } from './setup/setup-command.js';
@@ -18,6 +20,7 @@ import { handleHook } from './cli/hook/hook-command.js';
 import { HOOK_COMMAND } from './cli/cli-parse.js';
 import { daemonProjectAt, readDaemonRegistry, resolveDaemonForProject, } from './daemon/daemon-resolve.js';
 import { pickDaemonPortToBind } from './daemon/binding/free-port.js';
+import { exitAfterClose } from './daemon/lifetime/daemon-exit.js';
 import { isSameOrAbove, portForInit, portFromEnv } from './setup/init/init-port.js';
 import { daemonStartOptions } from './cli/daemon-start-options.js';
 import { handleGate, loadNamedFlows, resolveChangedFiles } from './cli/cli-flow-commands.js';
@@ -34,7 +37,8 @@ import { cmdLink, connectInstalls, isCloudCommand, runCloudCommand } from './cli
 import { SERVER_VERSION } from './version/identity/server-version.js';
 import { log } from '../log.js';
 import { isAlive, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon/daemon.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 { waitForDaemon, probeDaemon } from '../surface/mcp/mcp-proxy.js';
 import { installDaemonResilience, recordExitReason, DaemonExitReason, } from './daemon/daemon-resilience.js';
 import { IdleShutdown, resolveIdleShutdownMs, resolveIdleCheckMs } from './daemon/idle-shutdown.js';
@@ -46,11 +50,15 @@ import { NAVIGATE_NO_SESSION_ID, navigateLeftTab, openCandidates } from './cli/o
 import { fetchStatus } from './daemon/binding/daemon-status-probe.js';
 import { handleDrive } from './cli/drive/drive-command.js';
 import { handleVerify } from './cli/cli-verify.js';
+import { FIRST_VERDICT_REASON, bareRunsFirstVerdict } from './cli/first-verdict.js';
+import { cmdFirstVerdict } from './cli/first-verdict-node.js';
+import { reportOnboardingStop } from '../telemetry/onboarding-funnel.js';
 import { runKill } from './cli/cli-kill.js';
 import { runInit, buildNodeIo, InitFailure } from '@reticlehq/init';
 import { continueAfterInit } from './setup/init/init-runtime.js';
 import { initFirstFlow } from './cli/try-command.js';
 import { handleDoctor } from './cli/cli-doctor.js';
+import { writeFirstUseWarnings } from './cli/first-use-checks.js';
 import { serverInitHost } from './setup/init/init-host.js';
 import { describeLicense } from '../features/license/license.js';
 import { isLikelyDevServerPort, devServerPortWarning, readProjectPort, readProjectId, workspacePortConflict, projectDirOf, } from './cli/ports/resolve/cli-port.js';
@@ -60,7 +68,7 @@ import { renderHelp } from './cli/cli-usage.js';
 import { RENAMED_COMMANDS, renamedCommandFor, renamedNote } from './cli/cli-parse-grammar.js';
 import { handleFeedback, handleTelemetry } from '../telemetry/feedback-cli.js';
 import { installDaemonTelemetry } from '../telemetry/daemon-telemetry.js';
-import { reportCliRun } from '../telemetry/cli-telemetry.js';
+import { reportCliRun, reportGateCompleted } from '../telemetry/cli-telemetry.js';
 // Re-exported so existing imports (and the CLI tests) keep resolving from '@/cli.js'.
 export { parseCliArgs, CLI_USAGE };
 /** Said when `connect` carries on past an init whose setup did not finish. */
@@ -94,6 +102,11 @@ async function handleInit(parsed) {
     // RETICLE_PORT counts as explicit, as it does for every other command: resolved once here, so the
     // port written into the project and the port the runtime phase binds are the same number.
     const explicit = parsed.port ?? portFromEnv(process.env);
+    // The bridge port matters only when init goes on to start the app.
+    const bridgePort = true === parsed.filesOnly || parsed.dryRun
+        ? undefined
+        : (explicit ?? readProjectPort(cwd) ?? RETICLE_DEFAULT_PORT);
+    await writeFirstUseWarnings(bridgePort);
     const port = await portForInit(explicit, readProjectPort(cwd), readProjectId(cwd), {
         // The registry names a daemon's owner; an older daemon that never registered is known by the
         // projects its connected pages announced.
@@ -134,7 +147,7 @@ async function handleInit(parsed) {
         deferOutcome: true,
         continuesToRuntime: true !== parsed.filesOnly && true !== parsed.dryRun,
     }, io);
-    await continueAfterInit({ ...parsed, port }, result, io, cwd, initFirstFlow);
+    await continueAfterInit({ ...parsed, port }, result, io, cwd, initFirstFlow, (print, mayWait) => agentsBlock(readAgentRows(cwd), print, mayWait && shouldWaitForAgents(process.stdout.isTTY, isCiEnv(process.env))));
     return result;
 }
 // `serve`, `stop` and `restart` live in `cli/lifecycle/daemon-lifecycle.ts`: one idea, and the
@@ -194,7 +207,7 @@ function ensureDaemon(port) {
         // success for a daemon that never bound" shape. Refuse instead, with the sentence `doctor`
         // says.
         if (PortPresence.FREE !== presence) {
-            throw new Error(describePresence(presence, port));
+            throw new Error(describePortState(presence, port));
         }
         const scriptPath = process.argv[1];
         if (scriptPath === undefined) {
@@ -212,6 +225,8 @@ function ensureDaemon(port) {
  */
 /** How long `reticle open` waits for the launched page to register before reporting on it. */
 const OPEN_SESSION_WAIT_MS = 8000;
+/** For the heartbeat's resident memory, in MB. */
+const BYTES_PER_MB = 1024 * 1024;
 /**
  * Poll until a NEW session shows up, or the wait runs out. Returns whether one did.
  *
@@ -375,24 +390,15 @@ function handleDaemonInner(parsed) {
             // to reach a socket that is still open.
             server.announceShutdown?.();
             // Awaited before the close/exit chain: `process.exit(0)` kills an in-flight POST, and this is
-            // the one event carrying the whole session. A failed send resolves anyway (emit swallows its
-            // own errors), so this can delay the exit by at most the send timeout, never prevent it.
-            void daemonTelemetry
-                // The reason rides out on the session summary, which is the only event that fires at this
-                // exact moment. The proxy emits the matching `mcp_connection_lost` and cannot know it —
-                // it sees a socket end and nothing more, which is how a scheduled idle exit came to make up
-                // the large majority of "outages". See SessionSummary.exit.
-                .shutdown(reason)
-                .then(() => server.close())
-                .then(() => {
+            // the one event carrying the whole session. The reason rides out on the session summary;
+            // the proxy sees only a socket end. See SessionSummary.exit. The summary and the close share
+            // one bound, so a close that never settles cannot keep this process on its port (#1937).
+            void exitAfterClose({
+                summary: () => daemonTelemetry.shutdown(reason),
+                close: () => server.close(),
+            }).then((code) => {
                 removePid(parsed.port);
-                process.exit(0);
-            })
-                .catch((err) => {
-                const message = err instanceof Error ? err.message : String(err);
-                log('reticle_daemon_close_error', { error: message });
-                removePid(parsed.port);
-                process.exit(1);
+                process.exit(code);
             });
         };
         // Wrapped rather than passed directly: a signal handler receives the signal name as its first
@@ -432,6 +438,7 @@ function handleDaemonInner(parsed) {
             facts: () => ({
                 sessions: server.bridge.sessions.count(),
                 served: everServedToolCall(),
+                rssMb: Math.round(process.memoryUsage().rss / BYTES_PER_MB),
             }),
         }).start();
     })
@@ -617,6 +624,17 @@ export function main() {
             void handleInit(parsed);
             break;
         case 'serve':
+            // Bare `reticle` in a folder Reticle has not wired: the first verdict, with no agent and no
+            // `init`. A wired project, and `reticle serve` itself, keep serving.
+            if (bareRunsFirstVerdict(argv, myProjectId !== undefined || projectPort !== undefined || portConflict !== undefined)) {
+                void cmdFirstVerdict(parsed.port, !parsed.headless, (row) => reportOnboardingStop({ phase: OnboardingPhase.FIRST_RUN, reason: FIRST_VERDICT_REASON, ...row }, { detach: true }))
+                    .then((code) => process.exit(code))
+                    .catch((cause) => {
+                    process.stderr.write(`reticle: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+                    process.exit(1);
+                });
+                break;
+            }
             handleServe(parsed);
             break;
         case 'stop':
@@ -655,17 +673,24 @@ export function main() {
             process.exit(1);
             break;
         case 'doctor':
-            void handleDoctor(parsed.port);
+            void handleDoctor(parsed.port, parsed.fix, reportStepFromCli);
             break;
         case 'setup-mcp':
-            handleSetupMcp(reportStepFromCli);
+            void writeFirstUseWarnings().then(() => {
+                handleSetupMcp(reportStepFromCli, true, shouldWaitForAgents(process.stdout.isTTY, isCiEnv(process.env)));
+            });
+            break;
+        case 'setup-wait-agents':
+            void handleSetupWaitAgents(shouldWaitForAgents(process.stdout.isTTY, isCiEnv(process.env)));
             break;
         case 'setup-install':
-            handleSetupInstall({
-                runtimeSecs: parsed.runtimeSecs,
-                installSecs: parsed.installSecs,
-                mcp: parsed.mcp,
-            }, reportStepFromCli);
+            void writeFirstUseWarnings().then(() => {
+                handleSetupInstall({
+                    runtimeSecs: parsed.runtimeSecs,
+                    installSecs: parsed.installSecs,
+                    mcp: parsed.mcp,
+                }, reportStepFromCli);
+            });
             break;
         case 'open':
             handleOpen(parsed.port, parsed.url, parsed.navigate);
@@ -674,13 +699,25 @@ export function main() {
             handleDrive(parsed, readProjectId(process.cwd()));
             break;
         case 'verify':
-            handleVerify(parsed);
+            void writeFirstUseWarnings().then(() => {
+                handleVerify(parsed, () => {
+                    writeCiHint({ automation: currentAutomationHint(process.env), machineOutput: false });
+                });
+            });
             break;
         case 'affected':
-            void handleAffected(parsed.files, parsed.since);
+            void handleAffected(parsed.files, parsed.since).then(() => {
+                writeCiHint({ automation: currentAutomationHint(process.env), machineOutput: false });
+            });
             break;
         case 'gate':
-            void handleGate(parsed.files, parsed.since, parsed.hook, parsed.acceptCoverage);
+            void handleGate(parsed.files, parsed.since, parsed.hook, parsed.acceptCoverage, reportGateCompleted).then(() => {
+                // A stop hook's output is read by the agent, so it is a machine output mode.
+                writeCiHint({
+                    automation: currentAutomationHint(process.env),
+                    machineOutput: true === parsed.hook,
+                });
+            });
             break;
         case 'report':
             void handleReport(parsed.session, parsed.hook);