@reticlehq/server 3.8.2 → 3.9.0

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

@@ -9,7 +9,9 @@
  */
 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>;
+hold?: boolean, 
+/** A longer limit, for a caller that must not mistake a busy daemon for a stuck one. */
+timeoutMs?: number): Promise<unknown>;
 /** One connected tab as `reticle status` reports it — the at-a-glance health line. */
 interface StatusSession {
     sessionId: string;

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

@@ -42,13 +42,15 @@ const ReticleStatusSchema = z
  */
 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) {
+hold = false, 
+/** A longer limit, for a caller that must not mistake a busy daemon for a stuck one. */
+timeoutMs = STATUS_PROBE_TIMEOUT_MS) {
     return new Promise((resolve) => {
         const req = http.get({
             host,
             port,
             path: hold ? `${STATUS_PATH}?${STATUS_HOLD_QUERY}=1` : STATUS_PATH,
-            timeout: STATUS_PROBE_TIMEOUT_MS,
+            timeout: timeoutMs,
             // 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.
             agent: loopbackAgent,

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

@@ -0,0 +1,9 @@
+/** The argv word that runs the daemon itself. `serve` and the MCP proxy spawn it; a person never types it. */
+export declare const DAEMON_INNER_COMMAND = "_daemon";
+/**
+ * True when `commandLine` runs a Reticle daemon (#1937).
+ *
+ * The MCP proxy (`reticle mcp`) and every other process fail this test, so nothing that relies on
+ * it can stop the agent's proxy or a stranger's process.
+ */
+export declare function isReticleDaemonCommand(commandLine: string): boolean;

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

@@ -0,0 +1,11 @@
+/** The argv word that runs the daemon itself. `serve` and the MCP proxy spawn it; a person never types it. */
+export const DAEMON_INNER_COMMAND = '_daemon';
+/**
+ * True when `commandLine` runs a Reticle daemon (#1937).
+ *
+ * The MCP proxy (`reticle mcp`) and every other process fail this test, so nothing that relies on
+ * it can stop the agent's proxy or a stranger's process.
+ */
+export function isReticleDaemonCommand(commandLine) {
+    return commandLine.trim().split(/\s+/).includes(DAEMON_INNER_COMMAND);
+}

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

@@ -1,3 +1,4 @@
+import { type DeathCause } from './lifetime/death-cause.js';
 import { type EscapeRequest, type EscapeResult } from './win32-escape.js';
 export { MAX_DAEMON_LOG_BYTES, recoverOversizedLog } from './lifetime/log-cap.js';
 /** Env override for the whole state directory — see ReticleEnv.STATE_DIR. */
@@ -22,6 +23,11 @@ export declare function rotateDaemonLog(path: string, deps: {
     renameFile(from: string, to: string): void;
 }, max?: number): boolean;
 export declare function readPid(port: number, home?: string): number | null;
+/**
+ * Whether a process with this pid exists. `EPERM` means it exists and this process may not signal
+ * it, which a daemon that WMI started can answer on Windows; only `ESRCH` means it is gone. Reading
+ * every throw as "dead" reclaimed a live daemon and started a second one on its port.
+ */
 export declare function isAlive(pid: number): boolean;
 export declare function writePid(port: number): void;
 /**
@@ -81,10 +87,11 @@ export interface SpawnDaemonDeps {
     /** Windows only: start the daemon outside the Job Object of this process. See win32-escape.ts. */
     readonly escapeJob?: (request: EscapeRequest) => EscapeResult;
     /**
-     * A predecessor died without a clean stop; `ageMs` is how long it had run. Optional so a test that
-     * does not care reports nothing. The default sends `daemon_died_unclean`.
+     * A predecessor died without a clean stop; `ageMs` is how long it had run, and `cause` is what its
+     * own log says about how it ended. Optional so a test that does not care reports nothing. The
+     * default sends `daemon_died_unclean`.
      */
-    onUncleanDeath?(ageMs: number): void;
+    onUncleanDeath?(ageMs: number, cause?: DeathCause): void;
 }
 /**
  * Spawn the reticle daemon as a detached background process, redirecting output to the log file.

package/dist/command/daemon/daemon.js

@@ -5,6 +5,7 @@ import { spawn } from 'node:child_process';
 import { daemonRegistryFileName, DaemonSpawnMethod, ReticleEnv, } from '@reticlehq/core';
 import { log } from '../../log.js';
 import { uncleanPredecessor } from './lifetime/unclean-predecessor.js';
+import { deathCauseFromLog, readLogTail } from './lifetime/death-cause.js';
 import { reportDaemonDiedUnclean } from '../../telemetry/proxy-telemetry.js';
 import { MAX_DAEMON_LOG_BYTES, pruneOldDaemonLogs } from './lifetime/log-cap.js';
 import { escapeJobViaWmi } from './win32-escape.js';
@@ -59,13 +60,18 @@ export function readPid(port, home = reticleStateHome()) {
     const n = parseInt(readFileSync(path, 'utf8').trim(), 10);
     return isNaN(n) ? null : n;
 }
+/**
+ * Whether a process with this pid exists. `EPERM` means it exists and this process may not signal
+ * it, which a daemon that WMI started can answer on Windows; only `ESRCH` means it is gone. Reading
+ * every throw as "dead" reclaimed a live daemon and started a second one on its port.
+ */
 export function isAlive(pid) {
     try {
         process.kill(pid, 0);
         return true;
     }
-    catch {
-        return false;
+    catch (err) {
+        return err instanceof Error && 'code' in err && 'EPERM' === err.code;
     }
 }
 export function writePid(port) {
@@ -206,17 +212,22 @@ function defaultSpawnDaemonDeps() {
         pidAlive: isAlive,
         platform: process.platform,
         escapeJob: escapeJobViaWmi,
-        onUncleanDeath: (ageMs) => void reportDaemonDiedUnclean(ageMs),
+        onUncleanDeath: (ageMs, cause) => void reportDaemonDiedUnclean(ageMs, cause),
     };
 }
 /**
  * Report a dead predecessor, aged from its pidfile: the parent writes that file at spawn time.
  * Read before the unlink, because after it nothing is left to age. A report must never stop a start.
  */
-function reportUncleanAge(pidFilePath, deps) {
+function reportUncleanAge(pidFilePath, logFilePath, deps) {
     try {
         // The clock is read at this I/O boundary, the same as the log timestamps in this file.
-        deps.onUncleanDeath?.(Math.max(0, Date.now() - statSync(pidFilePath).mtimeMs));
+        const now = Date.now();
+        const startedMs = statSync(pidFilePath).mtimeMs;
+        // Read before `rotateDaemonLog`, which renames the file this daemon wrote.
+        const tail = readLogTail(logFilePath);
+        const cause = tail === undefined ? undefined : deathCauseFromLog(tail, startedMs, now);
+        deps.onUncleanDeath?.(Math.max(0, now - startedMs), cause);
     }
     catch {
         // An unreadable pidfile has no age to report.
@@ -283,7 +294,7 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
         // because after it there is no trace left that the previous daemon died at all.
         orphanPid = uncleanPredecessor(existing, false, process.pid);
         if (null !== orphanPid) {
-            reportUncleanAge(pidFilePath, deps);
+            reportUncleanAge(pidFilePath, logFilePath, deps);
         }
         try {
             unlinkSync(pidFilePath);

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

@@ -0,0 +1,24 @@
+/**
+ * The daemon's exit, with a bound (#1937).
+ *
+ * The exit used to await the telemetry summary and then `server.close()`, with no limit on the
+ * close. The close waits for the browser pool, the cloud sync flush and every open HTTP connection.
+ * When one of them never settled, the process stayed alive with its port held, and every tool call
+ * found a daemon that did not answer.
+ */
+export declare const ExitCode: {
+    readonly CLEAN: 0;
+    readonly FAILED: 1;
+};
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+/**
+ * The most the summary and the close get together. The summary send has its own 2s bound, and the
+ * pool needs a few seconds to close its browsers.
+ */
+export declare const DAEMON_EXIT_BUDGET_MS = 10000;
+/** Send the summary, close, and resolve to the exit code. Never takes longer than `budgetMs`. */
+export declare function exitAfterClose(steps: {
+    summary: () => Promise<void>;
+    close: () => Promise<void>;
+    budgetMs?: number;
+}): Promise<ExitCode>;

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

@@ -0,0 +1,39 @@
+/**
+ * The daemon's exit, with a bound (#1937).
+ *
+ * The exit used to await the telemetry summary and then `server.close()`, with no limit on the
+ * close. The close waits for the browser pool, the cloud sync flush and every open HTTP connection.
+ * When one of them never settled, the process stayed alive with its port held, and every tool call
+ * found a daemon that did not answer.
+ */
+import { log } from '../../../log.js';
+export const ExitCode = {
+    CLEAN: 0,
+    FAILED: 1,
+};
+/**
+ * The most the summary and the close get together. The summary send has its own 2s bound, and the
+ * pool needs a few seconds to close its browsers.
+ */
+export const DAEMON_EXIT_BUDGET_MS = 10_000;
+/** Send the summary, close, and resolve to the exit code. Never takes longer than `budgetMs`. */
+export async function exitAfterClose(steps) {
+    const budgetMs = steps.budgetMs ?? DAEMON_EXIT_BUDGET_MS;
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`the daemon did not finish its shutdown within ${String(budgetMs)}ms`));
+        }, budgetMs);
+    });
+    try {
+        await Promise.race([steps.summary().then(steps.close), deadline]);
+        return ExitCode.CLEAN;
+    }
+    catch (err) {
+        log('reticle_daemon_close_error', { error: err instanceof Error ? err.message : String(err) });
+        return ExitCode.FAILED;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/command/daemon/lifetime/death-cause.d.ts

@@ -0,0 +1,15 @@
+import { DaemonEnd, type DaemonDeath } from '@reticlehq/core';
+/** What the log says about the dead daemon. `ageMs` is the caller's to add. */
+export type DeathCause = Omit<DaemonDeath, 'ageMs'> & {
+    end: DaemonEnd;
+};
+/**
+ * Read the cause of death of the daemon that started at `startedMs`.
+ *
+ * The log is append-only across launches, so only lines at or after `startedMs` count. A daemon
+ * that crashed before it wrote any line leaves only a raw Node stack, after the last line of the
+ * daemon before it; the error code is read from there.
+ */
+export declare function deathCauseFromLog(text: string, startedMs: number, nowMs: number): DeathCause;
+/** The last part of the log at `path`, or undefined when it cannot be read. Never throws. */
+export declare function readLogTail(path: string): string | undefined;

package/dist/command/daemon/lifetime/death-cause.js

@@ -0,0 +1,130 @@
+/**
+ * Why a daemon died, read from its own log by the start that finds it dead.
+ *
+ * The daemon log already says how a daemon ended: a heartbeat every 30 s, a line for a signal, a
+ * line for an exit, and a line for a failed start (see heartbeat.ts). Nobody uploads that file, so
+ * `daemon_died_unclean` carried only the age, and a reboot, a killed process tree, an out-of-memory
+ * kill and a crash at startup sent the same event. The next start reads the log before it rotates
+ * it, and sends the cause with the event.
+ *
+ * Only facts that are names or numbers leave this module: an end, a signal name, a Node error code,
+ * counts. Never a message, because a message can carry the user's paths.
+ */
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+import { DaemonEnd, NODE_ERROR_CODE } from '@reticlehq/core';
+import { DAEMON_HEARTBEAT_EVENT, classifyDaemonLife } from './heartbeat.js';
+import { DAEMON_START_FAILED_EVENT } from './startup-failure.js';
+/**
+ * A Node error code where Node writes one: `[ERR_MODULE_NOT_FOUND]`, `code: 'EADDRINUSE'`, or
+ * `listen EADDRINUSE:`. A bare upper-case word elsewhere is not a code.
+ */
+const ERROR_CODE_IN_TEXT = /\b(E[A-Z]{3,30}|ERR_[A-Z0-9_]{2,60})(?=\]|'|"|:)/g;
+/** Upper-case words that sit before a colon and are not codes. */
+const NOT_A_CODE = new Set(['ERROR', 'EXIT', 'ENV']);
+function parse(raw) {
+    let record;
+    try {
+        record = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if ('object' !== typeof record || null === record) {
+        return undefined;
+    }
+    const r = record;
+    const t = 'string' === typeof r['t'] ? Date.parse(r['t']) : Number.NaN;
+    if (!Number.isFinite(t) || 'string' !== typeof r['event']) {
+        return undefined;
+    }
+    return { ...r, t, event: r['event'] };
+}
+/** The last Node error code in `text`, or undefined. Only the code, never the text around it. */
+function lastErrorCode(text) {
+    const codes = [...text.matchAll(ERROR_CODE_IN_TEXT)].map((m) => m[1]);
+    const code = codes.filter((c) => c !== undefined && !NOT_A_CODE.has(c)).at(-1);
+    return code !== undefined && NODE_ERROR_CODE.test(code) ? code : undefined;
+}
+const count = (v) => 'number' === typeof v && Number.isInteger(v) && 0 <= v ? v : undefined;
+/**
+ * Read the cause of death of the daemon that started at `startedMs`.
+ *
+ * The log is append-only across launches, so only lines at or after `startedMs` count. A daemon
+ * that crashed before it wrote any line leaves only a raw Node stack, after the last line of the
+ * daemon before it; the error code is read from there.
+ */
+export function deathCauseFromLog(text, startedMs, nowMs) {
+    const ours = [];
+    const rawAfterLastLine = [];
+    const rawInOurs = [];
+    for (const raw of text.split('\n')) {
+        const trimmed = raw.trim();
+        if (0 === trimmed.length) {
+            continue;
+        }
+        const parsed = parse(trimmed);
+        if (parsed === undefined) {
+            (0 < ours.length ? rawInOurs : rawAfterLastLine).push(trimmed);
+            continue;
+        }
+        if (parsed.t >= startedMs) {
+            ours.push(parsed);
+        }
+        else {
+            rawAfterLastLine.length = 0;
+        }
+    }
+    const life = classifyDaemonLife(ours, nowMs);
+    const cause = { end: life.end };
+    if (life.silentForMs !== undefined) {
+        cause.silentMs = Math.max(0, Math.round(life.silentForMs));
+    }
+    if (life.signal !== undefined && /^SIG[A-Z0-9]{1,12}$/.test(life.signal)) {
+        cause.signal = life.signal;
+    }
+    const lastBeat = ours.findLast((l) => l.event === DAEMON_HEARTBEAT_EVENT);
+    if (lastBeat !== undefined) {
+        const sessions = count(lastBeat['sessions']);
+        const rssMb = count(lastBeat['rssMb']);
+        if (sessions !== undefined) {
+            cause.sessions = sessions;
+        }
+        if ('boolean' === typeof lastBeat['served']) {
+            cause.served = lastBeat['served'];
+        }
+        if (rssMb !== undefined) {
+            cause.rssMb = rssMb;
+        }
+    }
+    const failed = ours.findLast((l) => l.event === DAEMON_START_FAILED_EVENT);
+    const error = ('string' === typeof failed?.['error'] ? lastErrorCode(failed['error']) : undefined) ??
+        // Raw lines before this daemon's first line belong to the daemon before it, unless this one
+        // wrote no line at all, which is a crash before its first log line.
+        lastErrorCode((0 < ours.length ? rawInOurs : rawAfterLastLine).join('\n'));
+    if (error !== undefined) {
+        cause.error = error;
+    }
+    return cause;
+}
+/** How much of the end of a daemon log the next start reads. The last beats and a stack fit. */
+const LOG_TAIL_BYTES = 256 * 1024;
+/** The last part of the log at `path`, or undefined when it cannot be read. Never throws. */
+export function readLogTail(path) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+        const size = fstatSync(fd).size;
+        const length = Math.min(size, LOG_TAIL_BYTES);
+        const buffer = Buffer.alloc(length);
+        readSync(fd, buffer, 0, length, size - length);
+        return buffer.toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            closeSync(fd);
+        }
+    }
+}

package/dist/command/daemon/lifetime/heartbeat.d.ts

@@ -17,6 +17,7 @@
  *
  * A heartbeat nobody interprets is just log volume.
  */
+import { DaemonEnd } from '@reticlehq/core';
 /** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
 export declare const DAEMON_HEARTBEAT_EVENT = "reticle_daemon_alive";
 /**
@@ -43,6 +44,11 @@ interface HeartbeatFacts {
      * and make a long-lived daemon look freshly idle.
      */
     served: boolean;
+    /**
+     * Resident memory in MB. Optional, so a caller that cannot read it sends no number rather than
+     * a guess. The next start reports it when this daemon dies, which separates a memory death.
+     */
+    rssMb?: number;
 }
 interface DaemonHeartbeatOptions {
     log: (event: string, fields: Record<string, unknown>) => void;
@@ -74,20 +80,7 @@ export declare class DaemonHeartbeat {
     start(): void;
     stop(): void;
 }
-/** How a daemon's life ended, as far as its own log can say. */
-export declare const DaemonEnd: {
-    /** Still beating within tolerance. */
-    readonly ALIVE: "alive";
-    /** Logged its own exit, with no signal before it. */
-    readonly CLEAN: "clean";
-    /** A signal arrived — the cause an exit line with `code: 0` does not carry. */
-    readonly SIGNALLED: "signalled";
-    /** The beat simply stopped. No exit, no signal: killed, crashed, or swept. */
-    readonly DIED_SILENTLY: "died_silently";
-    /** No beat was ever emitted, so this log cannot answer the question. */
-    readonly UNKNOWN: "unknown";
-};
-export type DaemonEnd = (typeof DaemonEnd)[keyof typeof DaemonEnd];
+export { DaemonEnd };
 /**
  * One parsed line of a daemon log. The index signature is not laziness: these lines carry whatever
  * their event needed (`code`, `port`, `pid`, `reason`, …), and a reader that refused unknown keys
@@ -116,4 +109,3 @@ export interface DaemonLife {
  * signal we never sent is the same confident-wrong this module replaces.
  */
 export declare function classifyDaemonLife(lines: readonly LogLine[], nowMs: number): DaemonLife;
-export {};

package/dist/command/daemon/lifetime/heartbeat.js

@@ -17,6 +17,7 @@
  *
  * A heartbeat nobody interprets is just log volume.
  */
+import { DaemonEnd } from '@reticlehq/core';
 import { DAEMON_LOG_TRUNCATED_EVENT, guardDaemonLog } from './log-cap.js';
 /** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
 export const DAEMON_HEARTBEAT_EVENT = 'reticle_daemon_alive';
@@ -90,6 +91,7 @@ export class DaemonHeartbeat {
             everyMs: this.#intervalMs,
             sessions: facts.sessions,
             served: facts.served,
+            ...(facts.rssMb === undefined ? {} : { rssMb: facts.rssMb }),
         });
     }
     start() {
@@ -106,19 +108,8 @@ export class DaemonHeartbeat {
         this.#timer = undefined;
     }
 }
-/** How a daemon's life ended, as far as its own log can say. */
-export const DaemonEnd = {
-    /** Still beating within tolerance. */
-    ALIVE: 'alive',
-    /** Logged its own exit, with no signal before it. */
-    CLEAN: 'clean',
-    /** A signal arrived — the cause an exit line with `code: 0` does not carry. */
-    SIGNALLED: 'signalled',
-    /** The beat simply stopped. No exit, no signal: killed, crashed, or swept. */
-    DIED_SILENTLY: 'died_silently',
-    /** No beat was ever emitted, so this log cannot answer the question. */
-    UNKNOWN: 'unknown',
-};
+// The vocabulary lives in core, because `daemon_died_unclean` reports it too.
+export { DaemonEnd };
 /**
  * Read a daemon log back and say how it ended.
  *

package/dist/command/daemon/port-state.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What holds the bridge port, said the same way by every surface (#1937).
+ *
+ * A Reticle daemon stuck in its exit held the port and answered nothing. `status` called the port
+ * free, the MCP proxy called the holder "not a Reticle daemon", and `restart` refused to stop it.
+ * The pid file did not name it, because the next start had replaced that file. Its command line
+ * still did.
+ */
+import { type PortHolder } from '../cli/ports/port-holder.js';
+import { PortPresence } from './binding/port-presence.js';
+/** The listener on `port`, and whether its command line is a Reticle daemon's. */
+export declare function identifyPortHolder(port: number, exec: (command: string, args: readonly string[]) => string | null): PortHolder | null;
+/** The sentence for the state of `port`, with the holder named when something holds it. */
+export declare function describePortState(presence: PortPresence, port: number): string;

package/dist/command/daemon/port-state.js

@@ -0,0 +1,31 @@
+/**
+ * What holds the bridge port, said the same way by every surface (#1937).
+ *
+ * A Reticle daemon stuck in its exit held the port and answered nothing. `status` called the port
+ * free, the MCP proxy called the holder "not a Reticle daemon", and `restart` refused to stop it.
+ * The pid file did not name it, because the next start had replaced that file. Its command line
+ * still did.
+ */
+import { captureLookup, describeForeignHolder, findPortHolder, } from '../cli/ports/port-holder.js';
+import { describePresence, PortPresence } from './binding/port-presence.js';
+import { isReticleDaemonCommand } from './daemon-argv.js';
+import { readPid } from './daemon.js';
+/** The listener on `port`, and whether its command line is a Reticle daemon's. */
+export function identifyPortHolder(port, exec) {
+    const holder = findPortHolder(port, exec);
+    if (null === holder) {
+        return null;
+    }
+    const commandLine = exec('ps', ['-o', 'command=', '-p', String(holder.pid)]);
+    return {
+        ...holder,
+        reticleDaemon: null !== commandLine && isReticleDaemonCommand(commandLine),
+    };
+}
+/** The sentence for the state of `port`, with the holder named when something holds it. */
+export function describePortState(presence, port) {
+    if (PortPresence.FOREIGN !== presence) {
+        return describePresence(presence, port);
+    }
+    return describeForeignHolder(port, identifyPortHolder(port, captureLookup), readPid(port));
+}

package/dist/command/setup/agent-configs.d.ts

@@ -82,6 +82,8 @@ interface AgentPlanInput {
     readonly platform: keyof PlatformPaths;
     readonly exists: (path: string) => boolean;
     readonly readFile: (path: string) => string;
+    /** The installed bin to register (`InitHost.mcpLauncher`). Absent: the pinned npx command. */
+    readonly launcher?: string | undefined;
 }
 /**
  * Join for the platform the CALLER named, never the one this process happens to run on.

package/dist/command/setup/agent-configs.js

@@ -19,6 +19,7 @@
  *    not ours to do.
  */
 import { posix, win32 } from 'node:path';
+import { isReticleRegistration, serverInvocation } from '@reticlehq/init';
 export const AgentConfidence = {
     /** Documented by the vendor. Safe to create before the agent exists. */
     OFFICIAL: 'official',
@@ -34,11 +35,16 @@ export const AgentAction = {
     SKIP: 'skip',
 };
 const NPX = 'npx';
-const SERVER_PACKAGE = '@reticlehq/server';
-const MCP_SUBCOMMAND = 'mcp';
+/** In every entry we write: the npx package name, or the installed launcher's path. */
+const RETICLE_SCOPE = '@reticlehq';
 const RETICLE_KEY = 'reticle';
-/** The stdio entry, in the shape most clients expect. */
-const STDIO = { command: NPX, args: [SERVER_PACKAGE, MCP_SUBCOMMAND] };
+/** The stdio `{ command, args }` that starts the MCP server. One rule for init and setup. */
+function stdioFor(launcher) {
+    const [command = NPX, ...args] = serverInvocation(launcher);
+    return { command, args };
+}
+/** The stdio entry, in the shape most clients expect. `planAgentConfigs` sets its command. */
+const STDIO = stdioFor();
 /**
  * The `PlatformPaths` row to plan for on a host that reports `platform`.
  *
@@ -234,7 +240,15 @@ export const AGENT_CLIENTS = [
  * mentions the word in a comment is not mistaken for a registration.
  */
 function yamlHasReticle(text) {
-    return text.includes(`name: ${RETICLE_KEY}`) && text.includes(SERVER_PACKAGE);
+    return text.includes(`name: ${RETICLE_KEY}`) && text.includes(RETICLE_SCOPE);
+}
+/** Every string in an entry's `command` and `args`. */
+function entryStrings(entry) {
+    if ('object' !== typeof entry || null === entry) {
+        return [];
+    }
+    const { command, args } = entry;
+    return [command, args].flat().filter((v) => 'string' === typeof v);
 }
 const forPlatform = (p, os) => p[os];
 /**
@@ -276,6 +290,8 @@ export function planAgentConfigs(input) {
         const join = joinFor(platform);
         const file = join(home, forPlatform(c.paths, platform));
         const detected = exists(join(home, forPlatform(c.marker, platform)));
+        const stdio = stdioFor(input.launcher);
+        const entry = c.entry === undefined ? undefined : { ...c.entry, ...stdio };
         // A NEW yaml file has nobody's formatting to destroy. An existing one does: `mcpServers` there
         // is a list of named entries, and a naive rewrite loses comments, anchors and ordering.
         if ('yaml-manual' === c.format) {
@@ -299,6 +315,7 @@ export function planAgentConfigs(input) {
                     name: c.name,
                     file,
                     action: AgentAction.CREATE_YAML,
+                    entry: stdio,
                     why: 'no config yet, so a valid one can be written outright',
                 };
         }
@@ -319,7 +336,7 @@ export function planAgentConfigs(input) {
                 file,
                 action: AgentAction.CREATE,
                 key: c.key,
-                entry: c.entry,
+                entry,
                 why: detected
                     ? 'installed, with no config yet'
                     : 'a documented path, so a later install finds it already wired',
@@ -339,7 +356,7 @@ export function planAgentConfigs(input) {
                 file,
                 action: AgentAction.MANUAL,
                 key: c.key,
-                entry: c.entry,
+                entry,
                 why: "the existing config is not plain JSON (comments or trailing commas), and rewriting it would reformat somebody else's file",
             };
         }
@@ -347,18 +364,28 @@ export function planAgentConfigs(input) {
         const existing = 'object' === typeof bucket && null !== bucket
             ? bucket[RETICLE_KEY]
             : undefined;
-        if (existing !== undefined) {
-            const ours = JSON.stringify(existing) === JSON.stringify(c.entry);
+        if (existing !== undefined && JSON.stringify(existing) === JSON.stringify(entry)) {
+            return {
+                id: c.id,
+                name: c.name,
+                file,
+                action: AgentAction.ALREADY,
+                key: c.key,
+                entry,
+                why: 'already registered',
+            };
+        }
+        // An older entry of our own (a floating npx command, a launcher that moved) is replaced. Any
+        // other `reticle` entry is somebody's own choice.
+        if (existing !== undefined && !isReticleRegistration(entryStrings(existing))) {
             return {
                 id: c.id,
                 name: c.name,
                 file,
-                action: ours ? AgentAction.ALREADY : AgentAction.MANUAL,
+                action: AgentAction.MANUAL,
                 key: c.key,
-                entry: c.entry,
-                why: ours
-                    ? 'already registered'
-                    : 'a different `reticle` entry is there, and it is not ours to replace',
+                entry,
+                why: 'a different `reticle` entry is there, and it is not ours to replace',
             };
         }
         return {
@@ -367,7 +394,7 @@ export function planAgentConfigs(input) {
             file,
             action: AgentAction.MERGE,
             key: c.key,
-            entry: c.entry,
+            entry,
             why: 'adding our key beside the servers already there',
         };
     });