@reticlehq/server 3.3.0 → 3.4.0

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 { 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,16 @@ 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)`);
     // 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 +75,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 +100,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();
+    // 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());
     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.
     //
@@ -549,14 +590,20 @@ export function main() {
         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 +620,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 +635,7 @@ export function main() {
             process.exit(1);
             break;
         case 'init':
-            handleInit(parsed);
+            void handleInit(parsed);
             break;
         case 'serve':
             handleServe(parsed);
@@ -669,7 +721,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 {};

package/dist/command/daemon/lifetime/daemon-usefulness.js

@@ -19,6 +19,7 @@
  * anybody could lose. When it does shut down, the MCP proxy reconnects and `ensureDaemon` spawns a
  * fresh one on the next call, which is a path already exercised hundreds of times a day.
  */
+import { STATUS_HOLD_MS } from '@reticlehq/core';
 /** Set the first time any tool is dispatched through runTool — the chokepoint every path shares. */
 let servedToolCall = false;
 export function noteToolCall() {
@@ -27,9 +28,30 @@ export function noteToolCall() {
 export function everServedToolCall() {
     return servedToolCall;
 }
+/**
+ * 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 const SETUP_HOLD_MS = STATUS_HOLD_MS;
+/**
+ * When a setup run last said it is waiting on this daemon — see STATUS_HOLD_QUERY.
+ *
+ * `init` starts the daemon and can then wait on the app longer than the idle grace: a cold desktop
+ * build, a slow first compile. The daemon counted none of that as activity, idled out
+ * (`reticle_daemon_idle_exit`) while init was still waiting for the app to dial it, and the app came
+ * up to a closed port.
+ */
+let setupHeldAt;
+export function noteSetupHold(now) {
+    setupHeldAt = now;
+}
+function setupHolding(now) {
+    return undefined !== setupHeldAt && now - setupHeldAt < SETUP_HOLD_MS;
+}
 /** Tests only. */
 export function resetDaemonUsefulness() {
     servedToolCall = false;
+    setupHeldAt = undefined;
 }
 /**
  * True when the daemon has done nothing for anyone and has nothing to lose by exiting.
@@ -49,13 +71,14 @@ export function isUselessDaemon(facts) {
  * 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 function buildIdlePredicate(agentConnected, sessions, pool) {
-    return () => (!agentConnected() ||
-        isUselessDaemon({
-            servedToolCall: everServedToolCall(),
-            everConnected: sessions.everConnected(),
-            activeLeases: pool.activeCount(),
-        })) &&
+export function buildIdlePredicate(agentConnected, sessions, pool, now = () => Date.now()) {
+    return () => !setupHolding(now()) &&
+        (!agentConnected() ||
+            isUselessDaemon({
+                servedToolCall: everServedToolCall(),
+                everConnected: sessions.everConnected(),
+                activeLeases: pool.activeCount(),
+            })) &&
         0 === sessions.count() &&
         0 === pool.activeCount();
 }

package/dist/command/dev/stale-issue-guard.d.ts

@@ -8,10 +8,9 @@
  *
  * ## Why `fixed-pending-release` is an accepted answer
  *
- * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
- * ships. The label is what tells a contributor not to start, so the label — not the closure — is
- * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
- * when they close things, only to say so.
+ * Work that is already ON the release branch is legitimately still open; the issue closes when the
+ * version ships. The label is that fact. It is not a fact about an open pull request. Applying it
+ * there is what told contributors a fix had shipped when the pull request was still unmerged.
  *
  * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
  * below testable without a network or a repo.

package/dist/command/dev/stale-issue-guard.js

@@ -8,10 +8,9 @@
  *
  * ## Why `fixed-pending-release` is an accepted answer
  *
- * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
- * ships. The label is what tells a contributor not to start, so the label — not the closure — is
- * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
- * when they close things, only to say so.
+ * Work that is already ON the release branch is legitimately still open; the issue closes when the
+ * version ships. The label is that fact. It is not a fact about an open pull request. Applying it
+ * there is what told contributors a fix had shipped when the pull request was still unmerged.
  *
  * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
  * below testable without a network or a repo.
@@ -61,9 +60,10 @@ export function staleIssues(claimed, issues) {
 /** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
 export function staleIssueReport(stale) {
     const list = stale.map((n) => `#${String(n)}`).join(', ');
+    const pronoun = 1 === stale.length ? 'it' : 'them';
     return (`${list} ${1 === stale.length ? 'is' : 'are'} still OPEN, and a commit on this branch says it ` +
-        `closes ${1 === stale.length ? 'it' : 'them'}. Anyone browsing the tracker reads that as work ` +
-        `nobody has started. Close ${1 === stale.length ? 'it' : 'them'}, or label ` +
-        `${1 === stale.length ? 'it' : 'them'} \`${PENDING_RELEASE_LABEL}\` if the fix is waiting on a ` +
-        `release. This has cost three contributors an evening each; it is not bookkeeping.`);
+        `closes ${pronoun}. Anyone browsing the tracker reads that as work nobody has started. Close ` +
+        `${pronoun} when this merges. Do not apply \`${PENDING_RELEASE_LABEL}\` from an open pull ` +
+        `request: that label means the fix is already on the release branch and waiting for the version ` +
+        `to ship. Applying it earlier is what sent contributors away from work that was not merged.`);
 }

package/dist/command/setup/bringup/connect-lease.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The connect proof for a run with no system browser to lean on: `init --no-open`, CI, a container,
+ * an agent, or a launcher that failed.
+ *
+ * Opens the app in a lease on the daemon at `port`, over the MCP transport every daemon serves --
+ * the same route `reticle verify` takes, so there is no second browser stack and no second daemon
+ * fighting this one for the port.
+ */
+/** A lease this run opened, and the way to hand it back; or why it could not be opened. */
+type LeaseOutcome = {
+    readonly sessionId: string;
+    readonly release: () => Promise<void>;
+} | {
+    readonly failed: string;
+};
+export declare function openLeaseFor(port: number, url: string, token: string | undefined): Promise<LeaseOutcome>;
+export {};

package/dist/command/setup/bringup/connect-lease.js

@@ -0,0 +1,38 @@
+/**
+ * The connect proof for a run with no system browser to lean on: `init --no-open`, CI, a container,
+ * an agent, or a launcher that failed.
+ *
+ * Opens the app in a lease on the daemon at `port`, over the MCP transport every daemon serves --
+ * the same route `reticle verify` takes, so there is no second browser stack and no second daemon
+ * fighting this one for the port.
+ */
+import { acquireLease, connectOverSse, endpointFor, releaseLease, } from '../../cli/adhoc-verdict.js';
+const reason = (error) => (error instanceof Error ? error.message : String(error));
+export async function openLeaseFor(port, url, token) {
+    let caller;
+    try {
+        caller = await connectOverSse(endpointFor(port, token));
+    }
+    catch (error) {
+        return { failed: `could not reach the daemon on port ${String(port)}: ${reason(error)}` };
+    }
+    const close = () => caller.close().catch(() => undefined);
+    try {
+        const got = await acquireLease(caller, url);
+        if ('failed' in got) {
+            await close();
+            return { failed: got.failed.join(' ') };
+        }
+        return {
+            sessionId: got.leased,
+            release: async () => {
+                await releaseLease(caller, got.leased);
+                await close();
+            },
+        };
+    }
+    catch (error) {
+        await close();
+        return { failed: reason(error) };
+    }
+}