@reticlehq/server 3.2.0 → 3.4.0

package/dist/command/cli.js

@@ -14,7 +14,10 @@ import { attachStatusFields } from '../surface/mcp/attach-memory.js';
 import { splitBrainFields, withNextAction } from './cli/status-fields.js';
 import { reticleStateHome } from './daemon/daemon.js';
 import { handleMcp } from './cli/mcp-command.js';
-import { resolveDaemonForProject } from './daemon/daemon-resolve.js';
+import { handleReport } from './cli/report-command.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';
@@ -48,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,
@@ -69,12 +91,13 @@ function handleInit(parsed) {
         // past a missing package manager, and could not honour that while never being told about it.
         ...(parsed.url === undefined ? {} : { url: parsed.url }),
         captureBodies: true === parsed.captureBodies,
+        hooks: true === parsed.hooks,
         // The outcome is reported by confirmInstall instead, once it knows whether an app connected —
         // `init` writing files was never the same thing as `init` working (#269).
         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.
@@ -522,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.
     //
@@ -547,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
@@ -571,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
@@ -581,7 +635,7 @@ export function main() {
             process.exit(1);
             break;
         case 'init':
-            handleInit(parsed);
+            void handleInit(parsed);
             break;
         case 'serve':
             handleServe(parsed);
@@ -667,7 +721,10 @@ 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);
             break;
         case 'watch':
             handleWatch();

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

@@ -1,2 +1,44 @@
-/** 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;
+    url: string;
+    projectId?: string;
+    throttled: boolean;
+    /**
+     * The tab is backgrounded. Reported by the daemon on every session; `false` on one too old to say,
+     * which reads as visible — the conservative answer, since it keeps the reuse this command has
+     * always done rather than opening a tab on a guess.
+     */
+    hidden: boolean;
+    stale: boolean;
+    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
+ * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
+ * degrades to "running, 0 sessions" instead of throwing.
+ */
+export declare function summarizeStatus(payload: unknown): {
+    sessionCount: number;
+    sessions: StatusSession[];
+    why?: string;
+    /** The same diagnosis without the differential, for a surface a person reads. */
+    whyLead?: string;
+};
+export {};

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);
@@ -46,3 +73,49 @@ export function fetchStatus(port) {
         });
     });
 }
+/**
+ * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
+ * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
+ * degrades to "running, 0 sessions" instead of throwing.
+ */
+export function summarizeStatus(payload) {
+    if (typeof payload !== 'object' || null === payload)
+        return { sessionCount: 0, sessions: [] };
+    const obj = payload;
+    // Carried through to the printed line: with no sessions this is the whole answer, and dropping it
+    // here would silently undo the reason it is on the wire.
+    const why = 'string' === typeof obj['why'] ? obj['why'] : undefined;
+    // Absent on a daemon older than this field, which is why every reader falls back to `why`.
+    const whyLead = 'string' === typeof obj['whyLead'] ? obj['whyLead'] : undefined;
+    const raw = Array.isArray(obj['sessions']) ? obj['sessions'] : [];
+    const sessions = raw
+        .map((s) => {
+        if (typeof s !== 'object' || null === s)
+            return null;
+        const r = s;
+        const sessionId = 'string' === typeof r['sessionId'] ? r['sessionId'] : '';
+        if ('' === sessionId)
+            return null;
+        return {
+            sessionId,
+            url: 'string' === typeof r['url'] ? r['url'] : '',
+            ...('string' === typeof r['projectId'] && 0 < r['projectId'].length
+                ? { projectId: r['projectId'] }
+                : {}),
+            throttled: true === r['throttled'],
+            hidden: true === r['hidden'],
+            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);
+    const sessionCount = 'number' === typeof obj['sessionCount'] ? obj['sessionCount'] : sessions.length;
+    return {
+        sessionCount,
+        sessions,
+        ...(why === undefined ? {} : { why }),
+        ...(whyLead === undefined ? {} : { whyLead }),
+    };
+}

package/dist/command/daemon/binding/port-presence.d.ts

@@ -65,7 +65,7 @@ export declare function probePresence(port: number, probes: {
  * these lets the sentence tell them apart when — and only when — the recorded pid for the port
  * matches the process actually holding it.
  */
-export interface PortHolder {
+interface PortHolder {
     /** The pid we recorded for this port, from the daemon pid file. `null` when there is none. */
     ourPid: number | null;
     /** The pid actually holding the port, when the caller could determine it. */

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/idle-shutdown.d.ts

@@ -1,4 +1,4 @@
-export interface IdleShutdownOptions {
+interface IdleShutdownOptions {
     /** True when nothing is using the daemon: no agent connected, no browser session, no pool lease. */
     isIdle: () => boolean;
     /** Clean teardown + process exit. Called at most once. */
@@ -52,3 +52,4 @@ export declare function resolveIdleCheckMs(raw: string | undefined): number;
  * broken.
  */
 export declare function resolveIdleShutdownMs(raw: string | undefined): number;
+export {};

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) };
+    }
+}

package/dist/command/setup/bringup/dev-server-files.d.ts

@@ -0,0 +1,68 @@
+/**
+ * What `init` leaves in the state home about a dev server it handed over: the log, its one rotated
+ * predecessor, and a record of where the server is.
+ *
+ * All keyed on the app directory, beside the daemon logs and so outside the project: no bundler
+ * watcher ever sees them change (a `.reticle/` write inside the app once put Vite into a continuous
+ * full-reload loop), and two projects never share a file.
+ */
+import { z } from 'zod';
+export declare function devServerLogName(cwd: string): string;
+/** Where a handed-over server is: enough to find it again and to prove it is still that server. */
+declare const HandedOverSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    url: z.ZodString;
+    appDir: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    pid: number;
+    appDir: string;
+}, {
+    url: string;
+    pid: number;
+    appDir: string;
+}>;
+export type HandedOver = z.infer<typeof HandedOverSchema>;
+/**
+ * Written when `init` leaves a server running, so the next `init` can attach to it.
+ *
+ * Only Vite announces itself (through its plugin). Re-running init while a Next or Angular server
+ * it had started was still up spawned a second `dev`, which failed with "port 3000 is already in use
+ * — something else is serving there" — the something being the server init itself had left.
+ */
+export declare function recordHandOver(dir: string, record: HandedOver): void;
+/**
+ * The url of the server `init` handed over for `appDir`, when that process is alive AND the url
+ * still answers — both, because a recycled pid proves nothing and a url answering proves only that
+ * SOMETHING is there. Undefined otherwise, and the caller starts one.
+ */
+export declare function handedOverUrl(dir: string, appDir: string, deps: {
+    alive: (pid: number) => boolean;
+    answers: (url: string) => Promise<boolean>;
+}): Promise<string | undefined>;
+/**
+ * Stop the server `init` handed over for `appDir`, and forget it. True when one was stopped.
+ *
+ * For a port move: Next reads the daemon url into `NEXT_PUBLIC_RETICLE_URL` once, when `next dev`
+ * starts, so attaching to the running server after `init --port <new>` left the page dialling the
+ * old port — which the same run had just stopped. Only a server this record proves init started is
+ * touched; one the user started is theirs to restart.
+ */
+export declare function stopHandedOver(dir: string, appDir: string, deps: {
+    alive: (pid: number) => boolean;
+    kill: (pid: number) => void;
+}): boolean;
+/**
+ * Remove what servers that are gone left behind: their logs, rotated logs and records.
+ *
+ * Every run wrote a log per project and nothing ever deleted one, so the state home kept a file for
+ * every app `init` had ever started. A record whose pid is dead takes its logs with it; a log with no
+ * record at all goes once it is old. `keep` is the app about to start, whose files are replaced
+ * anyway.
+ */
+export declare function sweepDeadDevServers(dir: string, deps: {
+    alive: (pid: number) => boolean;
+    now: number;
+    keep?: string;
+}): void;
+export {};