@reticlehq/server 2.4.0 → 2.6.0

package/dist/cli/cli-update-commands.js

@@ -0,0 +1,93 @@
+/**
+ * The self-update command pair — `reticle update` and `reticle rollback`.
+ *
+ * Split out of cli.ts, which sits at the 600-line cap: these two are one cohesive unit (swap the
+ * installed version, restart) and the file they came from is the CLI's dispatch table, which grows
+ * for entirely different reasons.
+ */
+import { checkForUpdate } from '../update/update-checker.js';
+import { updateTarget } from '../update/update-nudge.js';
+import { applyUpdate, rollback } from '../update/updater.js';
+import { SERVER_VERSION } from '../version/server-version.js';
+import { log } from '../log.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { reticleDepsOf, sdkSyncCommand } from '../update/sdk-sync.js';
+import { detectPackageManager } from '../init/detect.js';
+import { buildNodeIo } from '../init/node-io.js';
+/**
+ * Bring the SDK in the CURRENT project to the version being installed.
+ *
+ * Best-effort and non-fatal on purpose: `reticle update` is run from wherever the human happens to
+ * be, which is often not an app at all. A directory with no manifest, or one that has none of our
+ * packages, simply has nothing to sync — that is a normal outcome, not a failure, and it must never
+ * stop the CLI half from happening.
+ */
+function syncProjectSdk(target) {
+    const cwd = process.cwd();
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return; // not an app directory
+    }
+    const packages = reticleDepsOf(manifest);
+    const io = buildNodeIo(cwd);
+    const pm = detectPackageManager(new Set(io.rootFiles()), new Set(io.listDirs('node_modules')));
+    const cmd = sdkSyncCommand(pm, packages, target);
+    if (null === cmd) {
+        log('reticle_update_sdk', { synced: false, reason: 'no @reticlehq packages in this project' });
+        return;
+    }
+    const ok = io.exec(cmd.command, cmd.args);
+    log('reticle_update_sdk', { synced: ok, packages, to: target, packageManager: pm });
+    if (!ok) {
+        log('reticle_update_sdk_failed', {
+            hint: `run \`${cmd.command} ${cmd.args.join(' ')}\` by hand, then restart the dev server`,
+        });
+    }
+}
+/** `reticle update` — install the latest server version, sync the app's SDK, and restart. */
+export async function handleUpdate() {
+    try {
+        const manifest = await checkForUpdate(SERVER_VERSION, () => Date.now());
+        // Direction, not inequality: the registry being DIFFERENT is not the registry being newer, and
+        // the old gate happily installed a downgrade — reported by a user. See updateTarget.
+        const target = updateTarget(manifest);
+        if (target === undefined) {
+            log('reticle_update', {
+                ok: false,
+                message: 'already on the latest version',
+                version: SERVER_VERSION,
+            });
+            return;
+        }
+        log('reticle_update', { ok: true, from: SERVER_VERSION, to: target });
+        // The app's SDK FIRST, then the CLI. `reticle update` used to swap only the CLI, so the command
+        // whose job is keeping an install current was itself a way to produce a version-skewed pair —
+        // and the skew message told people to run it to fix an outdated SDK, which it could not do.
+        //
+        // Before the CLI swap because `applyUpdate` never returns (it execs and exits). If this half
+        // fails the daemon is still the older one, which is the direction the HELLO check names clearly
+        // and a re-run fixes; the reverse would leave a new daemon talking to an old page.
+        syncProjectSdk(target);
+        await applyUpdate(target); // calls process.exit; Claude Code restarts
+    }
+    catch (error) {
+        log('reticle_update_failed', { error: error instanceof Error ? error.message : String(error) });
+        process.exitCode = 1;
+    }
+}
+/** `reticle rollback` — restore the previous server version and restart. */
+export async function handleRollback() {
+    try {
+        await rollback(); // calls process.exit
+    }
+    catch (error) {
+        log('reticle_rollback_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        process.exitCode = 1;
+    }
+}

package/dist/{cli-verify.js → cli/cli-verify.js}

@@ -12,18 +12,18 @@
 import { join, basename } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, } from '@reticlehq/core';
-import { start } from './index.js';
-import { resolveCloudConfig, syncRunToCloud, SyncOutcome } from './cloud/cloud-sync.js';
-import { ReticleRunner } from './runs/reticle-runner.js';
-import { createRunnerPort } from './runs/runner-port.js';
-import { RunStore } from './runs/run-store.js';
-import { renderRunReport } from './runs/render-report.js';
-import { BaselineStore } from './project/baselines.js';
-import { RecordingStore } from './flows/recordings.js';
-import { FlowStore } from './flows/flows.js';
-import { ProjectStore } from './project/project-store.js';
-import { AnnotationStore } from './flows/annotation-store.js';
-import { createNodeFileSystem } from './project/fs-port.js';
+import { start } from '../index.js';
+import { resolveCloudConfig, syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { ReticleRunner } from '../runs/reticle-runner.js';
+import { createRunnerPort } from '../runs/runner-port.js';
+import { RunStore } from '../runs/run-store.js';
+import { renderRunReport } from '../runs/render-report.js';
+import { BaselineStore } from '../project/baselines.js';
+import { RecordingStore } from '../flows/recordings.js';
+import { FlowStore } from '../flows/flows.js';
+import { ProjectStore } from '../project/project-store.js';
+import { AnnotationStore } from '../flows/annotation-store.js';
+import { createNodeFileSystem } from '../project/fs-port.js';
 const EXIT_PASS = 0;
 const EXIT_FAIL = 1;
 const DEFAULT_SESSION_TIMEOUT_MS = 15_000;
@@ -63,7 +63,7 @@ export async function runVerify(args, ports) {
             return;
         }
         const names = await conn.listFlows();
-        if (names.length === 0) {
+        if (0 === names.length) {
             ports.fail(MSG_NO_FLOWS);
             ports.exit(EXIT_FAIL);
             return;
@@ -89,7 +89,7 @@ export async function runVerify(args, ports) {
  */
 async function pushRunToCloud(run, ports) {
     const config = resolveCloudConfig(process.env);
-    if (config === null)
+    if (null === config)
         return;
     const result = await syncRunToCloud(run, config, (url, init) => fetch(url, init));
     if (result.outcome === SyncOutcome.SYNCED) {

package/dist/{cloud-cli.js → cli/cloud-cli.js}

@@ -7,15 +7,16 @@
  * is `<repo>/.reticle/cloud.json`. Auth for a command = `RETICLE_CLOUD_KEY` env (agent) OR the login token.
  */
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { NodePlatform } from '../platform.js';
 import { spawn } from 'node:child_process';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { createNodeFileSystem } from './project/fs-port.js';
-import { RunStore } from './runs/run-store.js';
-import { resolveProjectCloud } from './cloud/cloud-config.js';
-import { syncRunToCloud, SyncOutcome } from './cloud/cloud-sync.js';
+import { createNodeFileSystem } from '../project/fs-port.js';
+import { RunStore } from '../runs/run-store.js';
+import { resolveProjectCloud } from '../cloud/cloud-config.js';
+import { syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 const DEFAULT_URL = 'http://localhost:8890';
 const RETICLE_DIR = '.reticle';
 const SESSION_FILE = 'session.json';
@@ -162,8 +163,12 @@ const DevicePollSchema = z.object({
 });
 /** Best-effort open the approval page in the default browser; the printed URL is the headless fallback. */
 const openBrowser = (target) => {
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', target] : [target];
+    const cmd = NodePlatform.MACOS === process.platform
+        ? 'open'
+        : NodePlatform.WINDOWS === process.platform
+            ? 'cmd'
+            : 'xdg-open';
+    const args = NodePlatform.WINDOWS === process.platform ? ['/c', 'start', '', target] : [target];
     try {
         const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
         child.on('error', () => undefined);
@@ -193,18 +198,18 @@ const cmdLoginDevice = async () => {
     for (;;) {
         await sleep(intervalMs);
         const poll = DevicePollSchema.parse(await api('POST', `${url}/v1/auth/device/token`, null, { deviceCode: started.deviceCode }));
-        if (poll.status === 'approved' && poll.token !== undefined && poll.org !== undefined) {
+        if ('approved' === poll.status && poll.token !== undefined && poll.org !== undefined) {
             await writeSession(url, poll.token, poll.org.name);
             return 0;
         }
-        if (poll.status === 'pending') {
+        if ('pending' === poll.status) {
             if (Date.now() > started.expiresAt) {
                 err('device login expired — run `reticle login` again');
                 return 1;
             }
             continue;
         }
-        err(poll.status === 'denied'
+        err('denied' === poll.status
             ? 'device login was denied in the browser'
             : 'device login expired — run `reticle login` again');
         return 1;
@@ -264,7 +269,7 @@ const cmdWhoami = async () => {
             verify: cloud.verify,
         },
     });
-    if (cloud.config === null)
+    if (null === cloud.config)
         hint('this repo is not attached — run `reticle link`');
     return 0;
 };
@@ -273,18 +278,18 @@ const cmdProject = async (argv) => {
     const session = await readSession();
     const token = bearer(session);
     const url = baseUrl(session);
-    if (token === null) {
+    if (null === token) {
         err('run `reticle login` first, or set RETICLE_CLOUD_KEY');
         return 2;
     }
     const sub = argv[0];
-    if (sub === 'ls') {
+    if ('ls' === sub) {
         emit(await api('GET', `${url}/v1/projects`, token));
         return 0;
     }
-    if (sub === 'create') {
+    if ('create' === sub) {
         const name = argv.slice(1).join(' ').trim();
-        if (name.length === 0) {
+        if (0 === name.length) {
             err('usage: reticle project create <name>');
             return 2;
         }
@@ -293,17 +298,17 @@ const cmdProject = async (argv) => {
         hint(`next: \`reticle link --project ${created.projectId}\` to bind this repo`);
         return 0;
     }
-    if (sub === 'rename') {
+    if ('rename' === sub) {
         const id = argv[1];
         const name = argv.slice(2).join(' ').trim();
-        if (id === undefined || name.length === 0) {
+        if (id === undefined || 0 === name.length) {
             err('usage: reticle project rename <projectId> <new name>');
             return 2;
         }
         emit(await api('PATCH', `${url}/v1/projects/${encodeURIComponent(id)}`, token, { name }));
         return 0;
     }
-    if (sub === 'rm' || sub === 'delete') {
+    if ('rm' === sub || 'delete' === sub) {
         const id = argv[1];
         if (id === undefined) {
             err('usage: reticle project rm <projectId>');
@@ -357,7 +362,7 @@ const cmdLink = async (argv) => {
     await mkdir(reticleDir, { recursive: true });
     const linkPath = join(reticleDir, CLOUD_LINK_FILE);
     const prev = await readJson(linkPath);
-    const prevObj = typeof prev === 'object' && prev !== null ? prev : {};
+    const prevObj = 'object' === typeof prev && prev !== null ? prev : {};
     const cloudJson = {
         projectId,
         projectName,
@@ -369,7 +374,7 @@ const cmdLink = async (argv) => {
     await mkdir(home(), { recursive: true });
     const credPath = join(home(), CREDENTIALS_FILE);
     const creds = (await readJson(credPath)) ?? {};
-    const credObj = typeof creds === 'object' && creds !== null ? creds : {};
+    const credObj = 'object' === typeof creds && creds !== null ? creds : {};
     credObj[projectId] = key;
     await writeFile(credPath, `${JSON.stringify(credObj, null, 2)}\n`);
     emit({ linked: projectName, projectId, cloudJson: linkPath, credentials: credPath });
@@ -381,15 +386,15 @@ const cmdConfig = async (argv) => {
     const f = flags(argv);
     const linkPath = join(process.cwd(), RETICLE_DIR, CLOUD_LINK_FILE);
     const raw = await readJson(linkPath);
-    if (raw === null || typeof raw !== 'object') {
+    if (null === raw || typeof raw !== 'object') {
         err('no .reticle/cloud.json here — run `reticle link` first');
         return 2;
     }
     const cfg = raw;
-    const sync = typeof cfg['sync'] === 'object' && cfg['sync'] !== null
+    const sync = 'object' === typeof cfg['sync'] && cfg['sync'] !== null
         ? cfg['sync']
         : { runs: true, memory: true, flows: true };
-    const onoff = (v) => v === 'on' ? true : v === 'off' ? false : undefined;
+    const onoff = (v) => 'on' === v ? true : 'off' === v ? false : undefined;
     for (const k of ['runs', 'memory', 'flows']) {
         if (f[k] === undefined)
             continue;
@@ -417,7 +422,7 @@ const cmdPush = async () => {
     const fs = createNodeFileSystem();
     const reticleRoot = join(process.cwd(), RETICLE_DIR);
     const cloud = await resolveProjectCloud(fs, reticleRoot, homedir(), process.env);
-    if (cloud.config === null) {
+    if (null === cloud.config) {
         err('cloud not attached here — run `reticle link` (or set RETICLE_CLOUD_URL/KEY)');
         return 1;
     }
@@ -448,7 +453,7 @@ const cmdPush = async () => {
 const repoCloud = async () => {
     const fs = createNodeFileSystem();
     const cloud = await resolveProjectCloud(fs, join(process.cwd(), RETICLE_DIR), homedir(), process.env);
-    if (cloud.config === null)
+    if (null === cloud.config)
         throw new Error('cloud not attached here — run `reticle link` (or set RETICLE_CLOUD_URL/KEY)');
     return cloud.config;
 };

package/dist/cli/doctor-daemon-line.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What `doctor` says about the daemon it found — pure, so it can be tested without a socket.
+ *
+ * Doctor already stopped lying about the PORT: `probePresence` separates "a daemon is here" from "a
+ * stranger holds it" from "nothing is listening", which was the load-bearing half of the report. It
+ * still did not say WHICH daemon, though the `/status` payload it already fetches carries `version`
+ * and `contract` and it discarded both.
+ *
+ * That is the gap worth closing, because skew is invisible everywhere else: a CLI and a daemon on
+ * different contracts connect anyway and then disagree about behaviour, which reaches the agent as a
+ * bare `-32000` naming no version at all. Doctor is the command a human runs at exactly that moment.
+ *
+ * Same split as `classifyPort`/`probePresence`: the rule lives here and is tested; the fetching stays
+ * at the call site.
+ */
+/** The fields of `/status` this line cares about. Both optional — an old daemon reports neither. */
+export interface DaemonIdentity {
+    version?: string;
+    contract?: string;
+}
+export interface DaemonLine {
+    /** The `daemon ✓ …` line itself. */
+    text: string;
+    /** A skew sentence to print underneath, when this CLI and that daemon disagree. */
+    skew?: string;
+}
+/**
+ * Build the daemon line for a port that answered `/status`.
+ *
+ * `pid` comes from the pid file and is genuinely optional — a daemon started by another user, or one
+ * whose pid file was cleaned up, still answers. Printing `(pid null)` would be worse than printing
+ * nothing, which is the same class of mistake as the port lie this command already fixed.
+ */
+export declare function daemonLine(port: number, pid: number | null, peer: DaemonIdentity, self: {
+    version: string;
+    contract: string;
+}): DaemonLine;

package/dist/cli/doctor-daemon-line.js

@@ -0,0 +1,35 @@
+/**
+ * What `doctor` says about the daemon it found — pure, so it can be tested without a socket.
+ *
+ * Doctor already stopped lying about the PORT: `probePresence` separates "a daemon is here" from "a
+ * stranger holds it" from "nothing is listening", which was the load-bearing half of the report. It
+ * still did not say WHICH daemon, though the `/status` payload it already fetches carries `version`
+ * and `contract` and it discarded both.
+ *
+ * That is the gap worth closing, because skew is invisible everywhere else: a CLI and a daemon on
+ * different contracts connect anyway and then disagree about behaviour, which reaches the agent as a
+ * bare `-32000` naming no version at all. Doctor is the command a human runs at exactly that moment.
+ *
+ * Same split as `classifyPort`/`probePresence`: the rule lives here and is tested; the fetching stays
+ * at the call site.
+ */
+import { describeSkew } from '../version/version-skew.js';
+const FIX = 'Restart it so both ends are the same build: `reticle stop`, then let your agent reconnect.';
+/**
+ * Build the daemon line for a port that answered `/status`.
+ *
+ * `pid` comes from the pid file and is genuinely optional — a daemon started by another user, or one
+ * whose pid file was cleaned up, still answers. Printing `(pid null)` would be worse than printing
+ * nothing, which is the same class of mistake as the port lie this command already fixed.
+ */
+export function daemonLine(port, pid, peer, self) {
+    const parts = [];
+    if (null !== pid)
+        parts.push(`pid ${String(pid)}`);
+    if (peer.version !== undefined)
+        parts.push(`v${peer.version}`);
+    const detail = 0 === parts.length ? '' : ` (${parts.join(', ')})`;
+    const skew = describeSkew({ what: 'the daemon on this port', version: peer.version, contract: peer.contract, fix: FIX }, self);
+    const line = { text: `  daemon       ✓ running on :${String(port)}${detail}` };
+    return skew === undefined ? line : { ...line, skew };
+}

package/dist/cli/port-holder.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Who is holding the bridge port.
+ *
+ * `doctor` is what a user runs when the agent cannot reach the bridge, and the commonest real cause
+ * is that something else is on 4400. It already stopped saying "nothing is listening" for that case,
+ * but it did not say WHICH process — so the reader's next move was a shell command they had to know.
+ *
+ * Naming the holder is also the safe answer to a trap this project has hit for real: the obvious
+ * lookup, `lsof -ti tcp:4400 | xargs kill -9`, ALSO kills the agent's own `reticle mcp` proxy,
+ * because that proxy holds a client connection to the same port and `-ti` does not filter to
+ * listeners. Every invocation here is `-sTCP:LISTEN`, and the message never suggests `-ti`.
+ *
+ * The parser is pure and the lookup takes an injected exec, so the rule is tested on every platform
+ * while the shelling out stays at the call site.
+ */
+export interface PortHolder {
+    pid: number;
+    command: string;
+}
+/**
+ * The FIRST listener in `lsof -nP -iTCP:<port> -sTCP:LISTEN -F pc` output, or null.
+ *
+ * First, not "the only one": a dual-stack listener (IPv4 + IPv6) is reported twice, and on a port
+ * conflict the answer the reader needs is "something is there, here is what" rather than an
+ * exhaustive list. A second `p` record ends the first.
+ *
+ * Null on anything incomplete. Half an answer — a pid with no command — prints worse than the
+ * un-named message it would replace, which is the same mistake as the port lie this command fixed.
+ */
+export declare function parsePortHolder(stdout: string): PortHolder | null;
+/** What `doctor` prints for a port held by something that is not a Reticle daemon. */
+export declare function describeForeignHolder(port: number, holder: PortHolder | null, 
+/**
+ * The pid we recorded for this port, from the daemon pid file.
+ *
+ * When it matches the process actually holding the port, the port is held by OUR daemon — one
+ * that accepts TCP and never answers `/status`, i.e. wedged. That classifies as FOREIGN, which is
+ * right for "can anything bind this?" and wrong to say out loud: the reader goes hunting a
+ * stranger, and the fix that works (`reticle stop`, it respawns on the next call) is never named.
+ */
+ourPid?: number | null): string;
+/** The lookup itself. `exec` is injected so the shelling out never runs in a unit test. */
+export declare function findPortHolder(port: number, exec: (command: string, args: readonly string[]) => string | null): PortHolder | null;

package/dist/cli/port-holder.js

@@ -0,0 +1,99 @@
+/**
+ * Who is holding the bridge port.
+ *
+ * `doctor` is what a user runs when the agent cannot reach the bridge, and the commonest real cause
+ * is that something else is on 4400. It already stopped saying "nothing is listening" for that case,
+ * but it did not say WHICH process — so the reader's next move was a shell command they had to know.
+ *
+ * Naming the holder is also the safe answer to a trap this project has hit for real: the obvious
+ * lookup, `lsof -ti tcp:4400 | xargs kill -9`, ALSO kills the agent's own `reticle mcp` proxy,
+ * because that proxy holds a client connection to the same port and `-ti` does not filter to
+ * listeners. Every invocation here is `-sTCP:LISTEN`, and the message never suggests `-ti`.
+ *
+ * The parser is pure and the lookup takes an injected exec, so the rule is tested on every platform
+ * while the shelling out stays at the call site.
+ */
+/** `lsof -F pc` emits one field per line, prefixed by its selector: `p<pid>`, `c<command>`. */
+const PID_FIELD = 'p';
+const COMMAND_FIELD = 'c';
+/**
+ * The FIRST listener in `lsof -nP -iTCP:<port> -sTCP:LISTEN -F pc` output, or null.
+ *
+ * First, not "the only one": a dual-stack listener (IPv4 + IPv6) is reported twice, and on a port
+ * conflict the answer the reader needs is "something is there, here is what" rather than an
+ * exhaustive list. A second `p` record ends the first.
+ *
+ * Null on anything incomplete. Half an answer — a pid with no command — prints worse than the
+ * un-named message it would replace, which is the same mistake as the port lie this command fixed.
+ */
+export function parsePortHolder(stdout) {
+    let pid;
+    let command;
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (0 === line.length)
+            continue;
+        const value = line.slice(1);
+        if (line.startsWith(PID_FIELD)) {
+            if (pid !== undefined)
+                break; // a second record: the first one is the answer
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed) || parsed <= 0)
+                return null;
+            pid = parsed;
+            continue;
+        }
+        if (line.startsWith(COMMAND_FIELD) && command === undefined)
+            command = value;
+    }
+    return pid === undefined || command === undefined ? null : { pid, command };
+}
+/** What `doctor` prints for a port held by something that is not a Reticle daemon. */
+export function describeForeignHolder(port, holder, 
+/**
+ * The pid we recorded for this port, from the daemon pid file.
+ *
+ * When it matches the process actually holding the port, the port is held by OUR daemon — one
+ * that accepts TCP and never answers `/status`, i.e. wedged. That classifies as FOREIGN, which is
+ * right for "can anything bind this?" and wrong to say out loud: the reader goes hunting a
+ * stranger, and the fix that works (`reticle stop`, it respawns on the next call) is never named.
+ */
+ourPid) {
+    const tail = 'a daemon cannot bind it. Stop that process, or run Reticle on a different port ' +
+        '(`--port`), then retry.';
+    if (null === holder) {
+        /**
+         * We could not identify the holder — no `lsof` (every Windows user, and 35% of them by the
+         * 2026-08 telemetry; also a slim container), or the lookup timed out.
+         *
+         * This used to assert the port was held by "another process that is not a Reticle daemon",
+         * which is a claim the null case has NO evidence for. It is also the likeliest thing to be
+         * wrong: reaching here at all means presence is FOREIGN — the port accepts TCP and never
+         * answers `/status` — and the commonest cause of that is OUR OWN daemon, wedged. So on the one
+         * platform where the lookup cannot run, `doctor` sent the reader hunting a stranger and never
+         * named `reticle stop`, the fix that actually works.
+         *
+         * Say what is known, and name the recorded pid when there is one.
+         */
+        const ours = ourPid !== null && ourPid !== undefined
+            ? ` Reticle's own records show pid ${String(ourPid)} for this port — if that process is ` +
+                'still around it is a wedged Reticle daemon, and `reticle stop` clears it.'
+            : '';
+        return `port ${String(port)} is held by a process Reticle could not identify — ${tail}${ours}`;
+    }
+    if (ourPid !== null && ourPid !== undefined && ourPid === holder.pid) {
+        return (`port ${String(port)} is held by YOUR Reticle daemon (pid ${String(holder.pid)}), and it is ` +
+            'not responding — running but wedged, so nothing can use it and nothing else can bind the ' +
+            'port. Stop it with `reticle stop`; the next tool call starts a fresh one.');
+    }
+    return (`port ${String(port)} is held by pid ${String(holder.pid)} ("${holder.command}"), which is not ` +
+        `a Reticle daemon — ${tail}`);
+}
+/** The lookup itself. `exec` is injected so the shelling out never runs in a unit test. */
+export function findPortHolder(port, exec) {
+    // -n/-P skip DNS and service-name lookups (slow, and irrelevant here). -sTCP:LISTEN is the part
+    // that matters: without it this also reports the agent's own MCP proxy, which is a client of the
+    // port, not its owner.
+    const out = exec('lsof', ['-nP', `-iTCP:${String(port)}`, '-sTCP:LISTEN', '-F', 'pc']);
+    return null === out ? null : parsePortHolder(out);
+}

package/dist/cli.d.ts

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { parseCliArgs, CLI_USAGE } from './cli-parse.js';
+import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
-export type { CliResult } from './cli-parse.js';
+export type { CliResult } from './cli/cli-parse.js';