@reticlehq/server 3.3.0 → 3.5.0

package/dist/command/cli/ports/resolve/cli-port.js

@@ -9,7 +9,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { SILENT_HOST, buildNodeIo, deriveProjectId, findWorkspaceApps, packageName, } from '@reticlehq/init';
+import { SILENT_HOST, buildNodeIo, deriveProjectId, findWorkspaceApps, isDesktopProject, packageName, } from '@reticlehq/init';
 import { asProjectId } from '@reticlehq/core';
 /** The project config `reticle init` writes. */
 export const RETICLE_CONFIG_BASENAME = '.reticle.json';
@@ -35,18 +35,15 @@ const MAX_CONFIG_SEARCH_DEPTH = 6;
  * Returns undefined when nothing is found, which keeps every caller's existing default intact.
  */
 export function findProjectConfig(cwd) {
+    const dir = findProjectConfigDir(cwd);
+    return dir === undefined ? undefined : readConfigAt(dir);
+}
+/** The directory holding the nearest `.reticle.json` at or above `cwd`, by the same walk. */
+function findProjectConfigDir(cwd) {
     let dir = resolve(cwd);
     for (let depth = 0; depth <= MAX_CONFIG_SEARCH_DEPTH; depth += 1) {
-        try {
-            const raw = readFileSync(`${dir}/${RETICLE_CONFIG_BASENAME}`, 'utf8');
-            const config = JSON.parse(raw);
-            if ('object' === typeof config && config !== null && !Array.isArray(config)) {
-                return config;
-            }
-        }
-        catch {
-            // Absent, unreadable, or not JSON at this level — keep walking.
-        }
+        if (readConfigAt(dir) !== undefined)
+            return dir;
         const parent = dirname(dir);
         if (parent === dir)
             break;
@@ -54,6 +51,48 @@ export function findProjectConfig(cwd) {
     }
     return undefined;
 }
+/**
+ * The directory of the project this invocation serves: where its `.reticle.json` is, else the one
+ * wired workspace app below a monorepo root, else `cwd` itself. What the CLI reads the installed SDK
+ * from, so it answers for the app the port above belongs to rather than for the directory it was
+ * started in.
+ */
+export function projectDirOf(cwd) {
+    const configDir = findProjectConfigDir(cwd);
+    if (configDir !== undefined)
+        return appPointedAtBy(configDir) ?? configDir;
+    const apps = workspaceAppPorts(cwd);
+    const only = 1 === apps.length ? apps[0] : undefined;
+    return only === undefined ? resolve(cwd) : join(resolve(cwd), only.app);
+}
+/**
+ * The one workspace app below `dir` whose own config names the project `dir`'s does, or undefined.
+ *
+ * `init` writes a copy of the app's `.reticle.json` at the root the agent runs from, so the root's
+ * config is a pointer to that app rather than a project of its own. The projectId is the link — no
+ * path is stored — and a root whose id no app shares, or several do, is its own project.
+ */
+function appPointedAtBy(dir) {
+    const id = readConfigAt(dir)?.['projectId'];
+    if ('string' !== typeof id || 0 === id.length)
+        return undefined;
+    const named = workspaceApps(dir).filter((app) => id === readConfigAt(join(dir, app))?.['projectId']);
+    const only = 1 === named.length ? named[0] : undefined;
+    return only === undefined ? undefined : join(dir, only);
+}
+/** The `.reticle.json` in exactly `dir` — no walk — or undefined when absent or not an object. */
+function readConfigAt(dir) {
+    try {
+        const config = JSON.parse(readFileSync(join(dir, RETICLE_CONFIG_BASENAME), 'utf8'));
+        if ('object' === typeof config && config !== null && !Array.isArray(config)) {
+            return config;
+        }
+    }
+    catch {
+        // Absent, unreadable, or not JSON at this level.
+    }
+    return undefined;
+}
 /**
  * The dev-server port heuristics live in `@reticlehq/init` — `existing-config.ts` is what diagnoses
  * a `.reticle.json` whose `port` is the app's own dev-server port, and the scaffolder may not import
@@ -61,15 +100,70 @@ export function findProjectConfig(cwd) {
  * diagnosis, and `cli.ts`) are unchanged.
  */
 export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning } from '@reticlehq/init';
+/** A config's `port`, when it is a usable TCP port. */
+function configPort(config) {
+    const p = config?.['port'];
+    if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
+        return p;
+    return undefined;
+}
 /**
  * Read the port stored in the project's .reticle.json (written by `reticle init`).
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.
+ *
+ * With no config at or above `cwd`, it looks DOWN, the same way `projectIdsAt` does. Running from a
+ * monorepo root whose app was wired in `apps/web` used to find nothing and fall back to the default
+ * port, so `status`, `mcp` and `verify` quietly talked to another project's daemon. One wired app
+ * below, or several that agree, give their port; several that disagree give none, and
+ * `workspacePortConflict` is what says so rather than letting the default win in silence.
  */
 export function readProjectPort(cwd) {
-    const p = findProjectConfig(cwd)?.['port'];
-    if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
-        return p;
-    return undefined;
+    const config = findProjectConfig(cwd);
+    if (config !== undefined)
+        return configPort(config);
+    const ports = new Set(workspaceAppPorts(cwd).map((a) => a.port));
+    return 1 === ports.size ? [...ports][0] : undefined;
+}
+/** Each workspace app under `cwd` whose own `.reticle.json` records a port. */
+function workspaceAppPorts(cwd) {
+    const found = [];
+    for (const app of workspaceApps(cwd)) {
+        // The app's OWN file only — walking up from an unwired sibling would reach the root, or past it.
+        const port = configPort(readConfigAt(join(cwd, app)));
+        if (port !== undefined)
+            found.push({ app, port });
+    }
+    return found;
+}
+/** init's workspace discovery under `cwd`, relative app directories; empty when `cwd` is no package. */
+function workspaceApps(cwd) {
+    // Only from a directory that is itself a package: a root with no package.json is not a workspace,
+    // and scanning, say, a home directory would adopt the port of whichever checkout happened to sit
+    // there.
+    if (packageNameAt(cwd) === undefined)
+        return [];
+    try {
+        return findWorkspaceApps(buildNodeIo(cwd, SILENT_HOST));
+    }
+    catch {
+        // Discovery touches the filesystem; an unreadable tree is simply no further evidence.
+        return [];
+    }
+}
+/**
+ * The sentence for a monorepo root whose wired apps name different ports, or undefined when there is
+ * nothing to choose between. `readProjectPort` refuses to pick one; this is what tells the person
+ * which ports exist and how to name the one they meant.
+ */
+export function workspacePortConflict(cwd) {
+    if (findProjectConfig(cwd) !== undefined)
+        return undefined;
+    const apps = workspaceAppPorts(cwd);
+    if (new Set(apps.map((a) => a.port)).size < 2)
+        return undefined;
+    const listed = apps.map((a) => `${a.app} (:${String(a.port)})`).join(', ');
+    return (`This workspace has more than one app wired for Reticle, on different ports: ${listed}. ` +
+        'Not guessing which one you meant — run the command from inside that app, or pass --port.');
 }
 /**
  * Read the stable projectId stored in the project's .reticle.json (written by `reticle init`). The daemon
@@ -142,6 +236,22 @@ export function readProjectFramework(cwd) {
         return framework;
     return undefined;
 }
+/**
+ * Whether the project this directory serves is a desktop shell (Electron, Tauri) — the same question
+ * `doctor` asks, answered from the same files. Read so the no-session guidance stops sending a
+ * desktop user to a browser URL.
+ */
+export function readProjectIsDesktop(cwd) {
+    const dir = projectDirOf(cwd);
+    return isDesktopProject((relative) => {
+        try {
+            return readFileSync(join(dir, relative), 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
 /**
  * Whether the durable causal journal is enabled. On by default (the journal IS the loop); off only via
  * explicit opt-out — `.reticle.json` `"journal": false`, or `RETICLE_JOURNAL` set to `0`/`false`. The env

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

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { probeCli } from '@reticlehq/init';
+import { claudeAddCommand, McpClient, probeCli, terminalWidth, wrapForTerminal, } from '@reticlehq/init';
 import { installClosing, tutorialShownSteps } from './tutorial.js';
 import { setupMcp, knownClientLabels } from '../setup/setup-mcp.js';
 import { reportInstallSteps } from '../setup/setup-install.js';
@@ -22,7 +22,7 @@ export function handleSetupMcp(reportStep, standalone = true) {
             writeFileSync(p, contents);
         },
         homeDir: () => homedir(),
-        print: (line) => process.stdout.write(`${line}\n`),
+        print: (line) => process.stdout.write(`${wrapForTerminal(line, terminalWidth())}\n`),
         reportStep,
         // `probeCli`, not a bare `execFileSync`: on Windows `claude` is a `.cmd` shim that cannot be
         // spawned without a shell, so the plain call threw ENOENT for every Windows user and the
@@ -46,16 +46,24 @@ export function handleSetupMcp(reportStep, standalone = true) {
         return;
     }
     for (const id of result.registered)
-        io.print(`  registered  ${id}`);
+        io.print(`  ✓ ${id}`);
     for (const id of result.alreadyThere)
-        io.print(`  already     ${id}`);
+        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');
+    }
+    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(`  BY HAND     ${client.id}: add the reticle entry to ${client.configPath}`);
+        io.print(`  ⚠ ${client.id}: add the reticle entry to ${client.configPath} by hand`);
         if (client.docs !== undefined)
-            io.print(`              see ${client.docs}`);
+            io.print(`    see ${client.docs}`);
     }
     /*
      * The OTHER agents, which `init` already reaches and this did not.
@@ -75,13 +83,13 @@ export function handleSetupMcp(reportStep, standalone = true) {
     });
     // Said on every run, attended or not: a registration only takes effect when the agent re-reads
     // its config, and an agent that was already open is the commonest reason "it did not work".
-    io.print('');
-    io.print('Restart your agent for it to pick up the new server.');
-    // Only when this IS the whole command. Inside the installer the tour follows, and its own closing
-    // already names `reticle init` — printing it here too put the same instruction twice, ten lines
-    // apart, with the tour sandwiched between them.
-    if (standalone)
+    // Only when this IS the whole command. Inside the installer the restart is the first line of the
+    // 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');
+    }
 }
 /**
  * `reticle setup install` — the Node half of the one-line installer.
@@ -100,7 +108,7 @@ export function handleSetupInstall(opts, reportStep) {
     }
     // Installation and onboarding are one script, so the tour prints here and is not gated on
     // anything — see installClosing for the heuristic this replaced and why it reached nobody.
-    process.stdout.write(`${installClosing()}\n`);
+    process.stdout.write(`${wrapForTerminal(installClosing(opts.mcp), terminalWidth())}\n`);
     // Shown, so the ONBOARD steps are a fact rather than a guess.
     for (const step of tutorialShownSteps())
         reportStep(step);

package/dist/command/cli/tutorial.d.ts

@@ -76,7 +76,7 @@ export declare function tutorialScript(audience: TutorialAudience): TutorialStep
  * Split from `renderTutorial` so the closing block is a value a caller can assert on, rather than a
  * string only findable by matching rendered prose.
  */
-export declare function tutorialNextSteps(audience: TutorialAudience): string;
+export declare function tutorialNextSteps(audience: TutorialAudience, restartAgent?: boolean): string;
 /**
  * What the installer prints when it has finished.
  *
@@ -87,7 +87,7 @@ export declare function tutorialNextSteps(audience: TutorialAudience): string;
  * It ends with the tour's OWN closing, which already names `reticle init`. Adding a second "Next:"
  * under it would be the same instruction twice in ten lines.
  */
-export declare function installClosing(): string;
+export declare function installClosing(registered?: boolean): string;
 export declare function renderTutorial(audience: TutorialAudience): string;
 export type DemoPlan = {
     ok: true;

package/dist/command/cli/tutorial.js

@@ -91,7 +91,7 @@ export function tutorialScript(audience) {
  * Split from `renderTutorial` so the closing block is a value a caller can assert on, rather than a
  * string only findable by matching rendered prose.
  */
-export function tutorialNextSteps(audience) {
+export function tutorialNextSteps(audience, restartAgent = false) {
     const lines = TutorialAudience.AGENT === audience
         ? [
             'Next:',
@@ -101,12 +101,15 @@ export function tutorialNextSteps(audience) {
         ]
         : [
             'Next:',
-            '  cd <your project> && reticle init   # wire Reticle into the app',
+            ...(restartAgent
+                ? ['  restart your agent                 # it loads new tools only when it starts']
+                : []),
+            '  cd <your project> && reticle init  # wire Reticle into the app',
             '  npm run dev                        # then load it in a browser',
             '  reticle status                     # confirms the app connected, or says why not',
             '',
-            'Then ask your agent to drive one real flow and report the verdict. That is the install',
-            'proving itself, and it is the agent’s job rather than a command you run.',
+            // One line: the terminal wraps it at the reader's width, not ours.
+            'Then ask your agent to drive one real flow and report the verdict. That is the install proving itself, and it is the agent’s job rather than a command you run.',
         ];
     return lines.join('\n');
 }
@@ -120,14 +123,25 @@ export function tutorialNextSteps(audience) {
  * It ends with the tour's OWN closing, which already names `reticle init`. Adding a second "Next:"
  * under it would be the same instruction twice in ten lines.
  */
-export function installClosing() {
+export function installClosing(registered = true) {
+    // One line a step. The reasons are for `reticle tutorial`; right after an install they turned a
+    // four-step idea into twenty-five lines of prose between the reader and the next command.
+    const steps = tutorialScript(TutorialAudience.HUMAN).map((step, index) => `  ${String(index + 1)}. ${INSTALL_SAYS[step.id] ?? step.say}`);
     return [
         '',
-        'Reticle is installed. Here is what it does, in four steps:',
+        '✓ Reticle is installed. How it works:',
+        ...steps,
         '',
-        renderTutorial(TutorialAudience.HUMAN),
+        tutorialNextSteps(TutorialAudience.HUMAN, registered),
     ].join('\n');
 }
+/**
+ * Tour steps reworded for a reader who has no app wired yet. The in-app tour's "That panel is
+ * Reticle" points at a panel on screen; straight after an install there is none to point at.
+ */
+const INSTALL_SAYS = {
+    connect: 'Once `reticle init` wires your app, a Reticle panel appears in it: your proof the SDK is connected.',
+};
 export function renderTutorial(audience) {
     const steps = tutorialScript(audience)
         .map((step, index) => {

package/dist/command/cli.js

@@ -15,7 +15,9 @@ import { splitBrainFields, withNextAction } from './cli/status-fields.js';
 import { reticleStateHome } from './daemon/daemon.js';
 import { handleMcp } from './cli/mcp-command.js';
 import { handleReport } from './cli/report-command.js';
-import { resolveDaemonForProject } from './daemon/daemon-resolve.js';
+import { daemonProjectAt, resolveDaemonForProject } from './daemon/daemon-resolve.js';
+import { pickDaemonPortToBind } from './daemon/binding/free-port.js';
+import { portForInit, portFromEnv } from './setup/init/init-port.js';
 import { daemonStartOptions } from './cli/daemon-start-options.js';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv, devServersForProject, } from '@reticlehq/core';
@@ -49,19 +51,38 @@ import { continueAfterInit } from './setup/init/init-runtime.js';
 import { handleDoctor } from './cli/cli-doctor.js';
 import { serverInitHost } from './setup/init/init-host.js';
 import { describeLicense } from '../features/license/license.js';
-import { isLikelyDevServerPort, devServerPortWarning, readProjectPort, readProjectId, } from './cli/ports/resolve/cli-port.js';
-import { DAEMON_INNER_COMMAND, PORT_FLAG, parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
+import { isLikelyDevServerPort, devServerPortWarning, readProjectPort, readProjectId, workspacePortConflict, projectDirOf, } from './cli/ports/resolve/cli-port.js';
+import { nodeSpawner, readTextFile, reexecAtVersion, versionMatchNote, versionToMatch, } from './cli/launch/sdk-version-match.js';
+import { DAEMON_INNER_COMMAND, PORT_FLAG, parseCliArgs, CLI_USAGE, dialsTheDaemon, } from './cli/cli-parse.js';
 import { handleFeedback, handleIdentify, handleTelemetry } from '../telemetry/feedback-cli.js';
 import { installDaemonTelemetry } from '../telemetry/daemon-telemetry.js';
 import { reportCliRun } from '../telemetry/cli-telemetry.js';
 // Re-exported so existing imports (and the CLI tests) keep resolving from '@/cli.js'.
 export { parseCliArgs, CLI_USAGE };
-function handleInit(parsed) {
+async function handleInit(parsed) {
     const cwd = process.cwd();
-    const io = buildNodeIo(cwd, serverInitHost());
+    // 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);
+    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.
+        daemonProjects: async (p) => {
+            const claimed = daemonProjectAt(p, reticleStateHome());
+            if (claimed !== undefined && claimed.length > 0)
+                return [claimed];
+            const { sessions } = summarizeStatus(await fetchStatus(p));
+            return [
+                ...new Set(sessions.flatMap((s) => (s.projectId === undefined ? [] : [s.projectId]))),
+            ];
+        },
+        daemonPresent: async (p) => presenceIsUsable(await probePresence(p, { tcpOpen: probeDaemon, status: fetchStatus })),
+        pickPort: (p) => pickDaemonPortToBind(p),
+    });
+    const io = buildNodeIo(cwd, serverInitHost(), { stderr: true === parsed.json });
     const result = runInit({
         cwd,
-        port: parsed.port,
+        port,
         mcp: parsed.mcp,
         dryRun: parsed.dryRun,
         install: parsed.install,
@@ -76,7 +97,7 @@ function handleInit(parsed) {
         deferOutcome: true,
         continuesToRuntime: true !== parsed.filesOnly && true !== parsed.dryRun,
     }, io);
-    void continueAfterInit(parsed, result, io, cwd);
+    await continueAfterInit({ ...parsed, port }, result, io, cwd);
 }
 // `serve`, `stop` and `restart` live in `cli/lifecycle/daemon-lifecycle.ts`: one idea, and the
 // largest group this file could give up without splitting something that belongs together.
@@ -524,6 +545,26 @@ export function main() {
     if (licenseKey !== undefined)
         process.env[LICENSE_KEY_ENV] = licenseKey;
     const argv = process.argv.slice(2);
+    // Before anything reports or writes: a CLI a major away from the project's SDK makes every verdict
+    // `version_skew`, and the unpinned `npx @reticlehq/server` every agent entry uses resolves the
+    // LATEST major whatever the project installed. Hand the same arguments to the matching release and
+    // step aside — it reports its own run. See cli/launch/sdk-version-match.ts.
+    const matchVersion = versionToMatch({
+        argv,
+        cliVersion: SERVER_VERSION,
+        env: process.env,
+        projectDir: projectDirOf(process.cwd()),
+        readFile: readTextFile,
+    });
+    if (matchVersion !== undefined) {
+        process.stderr.write(`${versionMatchNote(matchVersion, SERVER_VERSION)}\n`);
+        reexecAtVersion(matchVersion, argv, process.env, {
+            spawn: nodeSpawner,
+            exit: (code) => process.exit(code),
+            warn: (line) => process.stderr.write(`${line}\n`),
+        });
+        return;
+    }
     // Every invocation passes through here — the single chokepoint for the "how often is it used / how
     // many distinct machines + projects" metrics. Fire-and-forget: a metric must never delay or fail a run.
     //
@@ -546,17 +587,39 @@ export function main() {
             process.stdout.write(`${CLI_USAGE}\n`);
             return;
         }
+        if ('connect' === argv[0]) {
+            void (async () => {
+                // A fresh project gets the same install, dev-server handover and browser proof as `init`.
+                // Its failure exits non-zero before any cloud binding can claim this repo is ready.
+                if (readProjectId(process.cwd()) === undefined) {
+                    await handleInit({ port: undefined, mcp: true, dryRun: false, install: true });
+                }
+                return runCloudCommand(argv);
+            })()
+                .then((code) => process.exit(code))
+                .catch((cause) => {
+                process.stderr.write(`reticle connect: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+                process.exit(1);
+            });
+            return;
+        }
         void runCloudCommand(argv).then((code) => process.exit(code));
         return;
     }
-    const portEnv = process.env[ReticleEnv.PORT];
-    const envPort = portEnv !== undefined ? parseInt(portEnv, 10) : undefined;
+    const envPort = portFromEnv(process.env);
     const projectPort = readProjectPort(process.cwd());
     // Say so rather than letting the daemon fight the dev server for the port and fail with an
     // EADDRINUSE that mentions neither file nor cause.
     if (projectPort !== undefined && isLikelyDevServerPort(projectPort)) {
         process.stderr.write(`${devServerPortWarning(projectPort)}\n`);
     }
+    // A monorepo root whose wired apps disagree on a port: nothing is picked, and without this line the
+    // default below would be — another project's daemon, answered as if it were this one.
+    const portConflict = projectPort === undefined && envPort === undefined && !argv.includes(PORT_FLAG)
+        ? workspacePortConflict(process.cwd())
+        : undefined;
+    if (portConflict !== undefined)
+        process.stderr.write(`${portConflict}\n`);
     // Registry BEFORE the default, and after both explicit sources.
     //
     // This is the line that ends the split brain. Build plugins have always asked the registry which
@@ -573,6 +636,11 @@ export function main() {
     // Headed by default; hidden only where there is no display to be headed on. A run nobody can see
     // is a run nobody trusts, and every "did it actually do anything?" cost a human round-trip.
     const parsed = parseCliArgs(argv, defaultPort, process.env['CI'] !== undefined);
+    // The refusal the line above promised. Printing it and carrying on let the default port answer
+    // anyway, for whichever project's daemon owned it.
+    if (portConflict !== undefined && dialsTheDaemon(parsed)) {
+        process.exit(1);
+    }
     switch (parsed.kind) {
         case 'error':
             // Two audiences, two channels. The structured line is for logs and scripts; the plain text is
@@ -583,7 +651,7 @@ export function main() {
             process.exit(1);
             break;
         case 'init':
-            handleInit(parsed);
+            void handleInit(parsed);
             break;
         case 'serve':
             handleServe(parsed);
@@ -669,7 +737,7 @@ export function main() {
             void handleHunt(parsed.dir);
             break;
         case 'gate':
-            void handleGate(parsed.files, parsed.since, parsed.hook);
+            void handleGate(parsed.files, parsed.since, parsed.hook, parsed.acceptCoverage);
             break;
         case 'report':
             void handleReport(parsed.session, parsed.hook);

package/dist/command/daemon/binding/daemon-status-probe.d.ts

@@ -1,5 +1,15 @@
-/** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
-export declare function fetchStatus(port: number): Promise<unknown>;
+/**
+ * GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure —
+ * including a body that is not a Reticle daemon's, so every caller reads a stranger as absent and
+ * `probePresence` calls the port FOREIGN.
+ *
+ * `host` defaults to loopback, which is every caller's actual target — except `bootSession`
+ * (reticlehq/reticle#1165 review), whose Bridge can bind a non-default host via `RETICLE_HOST`.
+ * Hardcoding loopback here made that preflight check the wrong address.
+ */
+export declare function fetchStatus(port: number, host?: string, 
+/** Also tell the daemon a setup run is waiting on it, so it does not idle out mid-wait. */
+hold?: boolean): Promise<unknown>;
 /** One connected tab as `reticle status` reports it — the at-a-glance health line. */
 interface StatusSession {
     sessionId: string;
@@ -16,6 +26,8 @@ interface StatusSession {
     pendingMarks: number;
     /** The tab is attached and answering nothing — see Session.unresponsive. Absent on an older daemon. */
     unresponsive?: true;
+    /** Since the SDK last sent anything, heartbeats included. Absent on a body that did not say. */
+    lastSeenMs?: number;
 }
 /**
  * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the

package/dist/command/daemon/binding/daemon-status-probe.js

@@ -1,5 +1,6 @@
 import * as http from 'node:http';
-import { LOOPBACK_HOST, STATUS_PATH } from '@reticlehq/core';
+import { z } from 'zod';
+import { LOOPBACK_HOST, STATUS_HOLD_QUERY, STATUS_PATH } from '@reticlehq/core';
 import { loopbackAgent } from '../../../surface/loopback-agent.js';
 /**
  * The impure half of `probePresence`: ask the port whether a Reticle daemon is answering.
@@ -15,13 +16,38 @@ import { loopbackAgent } from '../../../surface/loopback-agent.js';
  */
 /** How long the daemon /status probe waits before giving up — a local loopback call is near-instant. */
 const STATUS_PROBE_TIMEOUT_MS = 1000;
-/** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
-export function fetchStatus(port) {
+/**
+ * The fields every Reticle daemon's `/status` has carried, which no stranger's is likely to.
+ *
+ * Any JSON used to count. An unrelated MCP server on the port init chose answered `/status` with its
+ * own body, was adopted as the daemon, the page's bridge dial got WebSocket 404s, and init blamed the
+ * dev server. `contract` is NOT required: a daemon from before it existed is still Reticle, and has
+ * to be recognised as one so init can replace it as skewed rather than call it a stranger.
+ */
+const ReticleStatusSchema = z
+    .object({
+    running: z.literal(true),
+    version: z.string().min(1),
+    sessions: z.array(z.unknown()),
+})
+    .passthrough();
+/**
+ * GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure —
+ * including a body that is not a Reticle daemon's, so every caller reads a stranger as absent and
+ * `probePresence` calls the port FOREIGN.
+ *
+ * `host` defaults to loopback, which is every caller's actual target — except `bootSession`
+ * (reticlehq/reticle#1165 review), whose Bridge can bind a non-default host via `RETICLE_HOST`.
+ * Hardcoding loopback here made that preflight check the wrong address.
+ */
+export function fetchStatus(port, host = LOOPBACK_HOST, 
+/** Also tell the daemon a setup run is waiting on it, so it does not idle out mid-wait. */
+hold = false) {
     return new Promise((resolve) => {
         const req = http.get({
-            host: LOOPBACK_HOST,
+            host,
             port,
-            path: STATUS_PATH,
+            path: hold ? `${STATUS_PATH}?${STATUS_HOLD_QUERY}=1` : STATUS_PATH,
             timeout: STATUS_PROBE_TIMEOUT_MS,
             // Shares the proxy's keep-alive agent: the proxy calls this on every reconnect, and a socket
             // per probe is the same churn the POST leg was fixed for.
@@ -32,7 +58,8 @@ export function fetchStatus(port) {
             res.on('data', (chunk) => (body += chunk));
             res.on('end', () => {
                 try {
-                    resolve(JSON.parse(body));
+                    const parsed = ReticleStatusSchema.safeParse(JSON.parse(body));
+                    resolve(parsed.success ? parsed.data : undefined);
                 }
                 catch {
                     resolve(undefined);
@@ -80,6 +107,7 @@ export function summarizeStatus(payload) {
             stale: true === r['stale'],
             pendingMarks: 'number' === typeof r['pendingMarks'] ? r['pendingMarks'] : 0,
             ...(true === r['unresponsive'] ? { unresponsive: true } : {}),
+            ...('number' === typeof r['lastSeenMs'] ? { lastSeenMs: r['lastSeenMs'] } : {}),
         };
     })
         .filter((s) => s !== null);

package/dist/command/daemon/daemon-resolve.d.ts

@@ -16,6 +16,15 @@
  * This module is the one answer both sides now use. It is pure and injectable: no process spawning,
  * no port binding, nothing that needs a real `~/.reticle` to test.
  */
+import { type DaemonRegistryEntry } from '@reticlehq/core/artifacts';
+/**
+ * Every well-formed registry entry in `home`.
+ *
+ * A corrupt or half-written entry is skipped rather than thrown on: the registry is written by other
+ * processes that can be killed mid-write, and one bad file must not make a machine's daemons
+ * undiscoverable. Validated through core's schema so a shape change cannot silently pass here.
+ */
+export declare function readDaemonRegistry(home: string): DaemonRegistryEntry[];
 /**
  * The port of the live daemon serving `projectId`, or undefined when this project has none.
  *

package/dist/command/daemon/daemon-resolve.js

@@ -26,7 +26,7 @@ import { DaemonRegistryEntrySchema, daemonRegistryPort, pickDaemonPort, } from '
  * processes that can be killed mid-write, and one bad file must not make a machine's daemons
  * undiscoverable. Validated through core's schema so a shape change cannot silently pass here.
  */
-function readDaemonRegistry(home) {
+export function readDaemonRegistry(home) {
     let files;
     try {
         files = readdirSync(home);

package/dist/command/daemon/lifetime/daemon-usefulness.d.ts

@@ -21,6 +21,12 @@
  */
 export declare function noteToolCall(): void;
 export declare function everServedToolCall(): boolean;
+/**
+ * How long one hold from a setup run keeps the daemon from idling out. `init` renews it on a timer
+ * well inside this window for as long as it runs, so a run that dies stops holding within it.
+ */
+export declare const SETUP_HOLD_MS = 60000;
+export declare function noteSetupHold(now: number): void;
 /** Tests only. */
 export declare function resetDaemonUsefulness(): void;
 interface UsefulnessFacts {
@@ -56,5 +62,5 @@ interface IdlePool {
  * clause the shutdown watcher could never fire on the many daemons that spawn in a directory with
  * no app and sit there for the length of an editor session.
  */
-export declare function buildIdlePredicate(agentConnected: () => boolean, sessions: IdleSessions, pool: IdlePool): () => boolean;
+export declare function buildIdlePredicate(agentConnected: () => boolean, sessions: IdleSessions, pool: IdlePool, now?: () => number): () => boolean;
 export {};