@reticlehq/server 3.8.2 → 3.10.0

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',
         };
     });

package/dist/command/setup/agent-next-steps.d.ts

@@ -0,0 +1,77 @@
+import { McpClient } from '@reticlehq/init';
+import { AgentClient } from '@reticlehq/core/telemetry';
+import type { SetupMcpResult } from './setup-mcp.js';
+/** What registration did for one client. */
+export declare const AgentReg: {
+    /** The Claude Code plugin carries Reticle. */
+    readonly PLUGIN: "plugin";
+    readonly ADDED: "added";
+    readonly ALREADY: "already";
+    readonly FAILED: "failed";
+    readonly MANUAL: "manual";
+    /** Found, and Reticle is not in its config. Read-only callers (`status`) only. */
+    readonly MISSING: "missing";
+};
+export type AgentReg = (typeof AgentReg)[keyof typeof AgentReg];
+export interface AgentRow {
+    readonly id: McpClient;
+    readonly reg: AgentReg;
+    /** The config path for a hand edit. */
+    readonly path?: string;
+    /** The command to retry a failed CLI registration, with the launcher that run used. */
+    readonly retry?: string;
+    /** The plugin AND a user-scope `reticle` entry: the client has two servers. */
+    readonly duplicate?: boolean;
+    /** The entry is the floating npx form: the note that names the commands that replace it. */
+    readonly stale?: string;
+}
+/**
+ * The rows for one `setupMcp` run, in its order.
+ *
+ * @param launcher the installed bin that run registered (`SetupMcpIo.launcher`), so a retry line
+ *   names the same command.
+ */
+export declare function agentRows(result: SetupMcpResult, launcher?: string): AgentRow[];
+/** The "Your agents:" block: one line per client, each with its own next step. */
+export declare function agentLines(rows: readonly AgentRow[]): string[];
+/** The clients worth waiting for: the ones that have Reticle registered. */
+export declare function awaitedClients(rows: readonly AgentRow[]): AgentClient[];
+/** One agent, as `reticle status` reports it. */
+export interface AgentStatus {
+    readonly name: string;
+    readonly connected: boolean;
+    /** The step still missing. Absent when connected. */
+    readonly next?: string;
+    /** The line a person reads: "Connected: Cursor ✓", or the name and the step still missing. */
+    readonly said: string;
+}
+/** Per client: connected, or the exact step still missing. */
+export declare function agentStatuses(rows: readonly AgentRow[], connected: ReadonlySet<string>): AgentStatus[];
+/** The lines the installer prints after its wait. */
+export declare function connectionLines(rows: readonly AgentRow[], connected: ReadonlySet<string>): string[];
+/** The clock the wait runs on. Injected, so a test does not wait. */
+export interface WaitClock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * Poll `read` until every client in `want` has connected, or `budgetMs` has passed. Returns the
+ * last read. Bounded: it never waits longer than the budget.
+ */
+export declare function waitForAgents(want: readonly string[], read: () => ReadonlySet<string>, clock: WaitClock, budgetMs: number, pollMs: number): Promise<ReadonlySet<string>>;
+/** `$CLAUDE_CONFIG_DIR`, else home: where Claude Code keeps `.claude.json`. */
+export declare function claudeStateDir(): string;
+/** What `installedAgentRows` reads. It never writes. */
+export interface AgentProbe {
+    exists(path: string): boolean;
+    readFile(path: string): string | null;
+    homeDir(): string;
+}
+/**
+ * The agents on this machine and whether Reticle is in each config, read only. For `reticle status`,
+ * which must not register anything and must not spawn a client CLI.
+ *
+ * @param claudeStateDir the directory that holds `.claude.json`: `$CLAUDE_CONFIG_DIR`, else home.
+ * @param launcher the installed bin a new registration would use, for the stale-entry fix.
+ */
+export declare function installedAgentRows(io: AgentProbe, projectDir: string | undefined, pluginActive: boolean, claudeStateDir?: string, launcher?: string): AgentRow[];

package/dist/command/setup/agent-next-steps.js

@@ -0,0 +1,284 @@
+/**
+ * One next step for each coding agent, and whether each one really connected.
+ *
+ * Registration writes a config. An agent reads that config only at a time the client decides, so
+ * "registered" is not "the agent has the tools". This file names, per client, the one step that
+ * loads the tools, and reads which agents did connect (`agents-connected.ts`) to say so.
+ *
+ * Only the Claude Code plugin gets "no restart". Its docs say `/reload-plugins` loads it. For every
+ * other client the step is the conservative one: their docs do not say a running session picks up a
+ * new server.
+ */
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { claudeAddCommand, claudeHasReticle, claudeRemoveUserCommand, claudeStaleEntryNote, claudeUserEntryIsFloating, clientSpec, codexNamesOurServer, ConfigFormat, detectMcpClients, McpClient, } from '@reticlehq/init';
+import { MCP_SERVER_NAME } from '@reticlehq/core';
+import { AgentClient } from '@reticlehq/core/telemetry';
+/** What registration did for one client. */
+export const AgentReg = {
+    /** The Claude Code plugin carries Reticle. */
+    PLUGIN: 'plugin',
+    ADDED: 'added',
+    ALREADY: 'already',
+    FAILED: 'failed',
+    MANUAL: 'manual',
+    /** Found, and Reticle is not in its config. Read-only callers (`status`) only. */
+    MISSING: 'missing',
+};
+/** The one table of client to next step. Change a step here, nowhere else. */
+const AGENT_STEPS = {
+    [McpClient.CLAUDE_CODE]: {
+        name: 'Claude Code',
+        agent: AgentClient.CLAUDE_CODE,
+        step: 'restart Claude Code, then /mcp shows reticle',
+    },
+    [McpClient.CURSOR]: {
+        name: 'Cursor',
+        agent: AgentClient.CURSOR,
+        step: 'restart Cursor, then turn Reticle on in Settings › MCP',
+    },
+    [McpClient.CODEX]: {
+        name: 'Codex',
+        agent: AgentClient.CODEX,
+        step: 'restart Codex, then /mcp shows reticle',
+    },
+    [McpClient.GEMINI]: {
+        name: 'Gemini CLI',
+        agent: AgentClient.GEMINI_CLI,
+        step: 'restart Gemini CLI, then /mcp shows reticle',
+    },
+    [McpClient.WINDSURF]: {
+        name: 'Windsurf',
+        agent: AgentClient.WINDSURF,
+        step: 'restart Windsurf, then turn Reticle on in its MCP settings',
+    },
+    [McpClient.VSCODE]: {
+        name: 'VS Code',
+        agent: AgentClient.VSCODE,
+        step: 'run "Developer: Reload Window" in VS Code',
+    },
+    [McpClient.OPENCODE]: {
+        name: 'OpenCode',
+        agent: AgentClient.OPENCODE,
+        step: 'restart OpenCode',
+    },
+    [McpClient.ANTIGRAVITY]: {
+        name: 'Antigravity',
+        agent: AgentClient.ANTIGRAVITY,
+        step: 'restart Antigravity',
+    },
+};
+const NextStepCopy = {
+    HEADING: 'Your agents:',
+    PLUGIN_ACTIVE: 'plugin active: type /reload-plugins if it is open',
+    PLUGIN_NOT_CONNECTED: 'start Claude Code, or type /reload-plugins in an open session',
+    ADDED: 'added: ',
+    ALREADY: 'already set up',
+    NOT_ADDED: 'not added: ',
+    FAILED: 'registration failed: ',
+    FAILED_FILE: 'check the permissions of its config file, then run `reticle setup mcp`',
+    MANUAL_HEAD: 'add the reticle entry to ',
+    MANUAL_TAIL: ' by hand',
+    MISSING: 'not added: run `reticle setup mcp`',
+    CONNECTED_HEAD: 'Connected: ',
+    CONNECTED_TAIL: ' ✓',
+    NOT_CONNECTED: ' not connected yet: ',
+    DUPLICATE: '    ⚠ a user-scope reticle server is registered too, so Claude Code has two. Remove it: ',
+    STALE: '    ⚠ ',
+};
+const NAME_COLUMN = Math.max(...Object.values(AGENT_STEPS).map((s) => s.name.length)) + 2;
+/**
+ * The rows for one `setupMcp` run, in its order.
+ *
+ * @param launcher the installed bin that run registered (`SetupMcpIo.launcher`), so a retry line
+ *   names the same command.
+ */
+export function agentRows(result, launcher) {
+    const known = (id) => id in AGENT_STEPS;
+    const rows = [];
+    for (const id of result.detected) {
+        if (!known(id)) {
+            continue;
+        }
+        if (result.pluginActive.includes(id)) {
+            rows.push(pluginRow(id, result.duplicates.includes(id)));
+            continue;
+        }
+        const manual = result.manual.find((m) => m.id === id);
+        if (manual !== undefined) {
+            rows.push({ id, reg: AgentReg.MANUAL, path: manual.configPath });
+        }
+        else if (result.failed.includes(id)) {
+            rows.push(McpClient.CLAUDE_CODE === id
+                ? { id, reg: AgentReg.FAILED, retry: claudeAddCommand(launcher).display }
+                : { id, reg: AgentReg.FAILED });
+        }
+        else if (result.alreadyThere.includes(id)) {
+            rows.push(alreadyRow(id, result.stale.includes(id), launcher));
+        }
+        else if (result.registered.includes(id)) {
+            rows.push({ id, reg: AgentReg.ADDED });
+        }
+    }
+    return rows;
+}
+function alreadyRow(id, stale, launcher) {
+    return stale
+        ? { id, reg: AgentReg.ALREADY, stale: claudeStaleEntryNote(launcher) }
+        : { id, reg: AgentReg.ALREADY };
+}
+function pluginRow(id, duplicate) {
+    return duplicate ? { id, reg: AgentReg.PLUGIN, duplicate } : { id, reg: AgentReg.PLUGIN };
+}
+function failedStep(row) {
+    return row.retry === undefined ? NextStepCopy.FAILED_FILE : `run \`${row.retry}\``;
+}
+/** What one row says before anything is known about the connection. */
+function registrationText(row) {
+    const { step } = AGENT_STEPS[row.id];
+    switch (row.reg) {
+        case AgentReg.PLUGIN:
+            return NextStepCopy.PLUGIN_ACTIVE;
+        case AgentReg.ADDED:
+            return `${NextStepCopy.ADDED}${step}`;
+        case AgentReg.ALREADY:
+            return NextStepCopy.ALREADY;
+        case AgentReg.FAILED:
+            return `${NextStepCopy.FAILED}${failedStep(row)}`;
+        case AgentReg.MANUAL:
+            return `${NextStepCopy.NOT_ADDED}${NextStepCopy.MANUAL_HEAD}${row.path ?? ''}${NextStepCopy.MANUAL_TAIL}`;
+        case AgentReg.MISSING:
+            return NextStepCopy.MISSING;
+    }
+}
+/** The "Your agents:" block: one line per client, each with its own next step. */
+export function agentLines(rows) {
+    if (0 === rows.length) {
+        return [];
+    }
+    return [
+        NextStepCopy.HEADING,
+        ...rows.flatMap((row) => {
+            const lines = [`  ${AGENT_STEPS[row.id].name.padEnd(NAME_COLUMN)}${registrationText(row)}`];
+            if (true === row.duplicate) {
+                lines.push(`${NextStepCopy.DUPLICATE}${claudeRemoveUserCommand()}`);
+            }
+            if (row.stale !== undefined) {
+                lines.push(`${NextStepCopy.STALE}${row.stale}`);
+            }
+            return lines;
+        }),
+    ];
+}
+/** A row whose client has Reticle in its config, so a connection can be waited for. */
+function isRegistered(row) {
+    return AgentReg.PLUGIN === row.reg || AgentReg.ADDED === row.reg || AgentReg.ALREADY === row.reg;
+}
+/** The clients worth waiting for: the ones that have Reticle registered. */
+export function awaitedClients(rows) {
+    return rows.filter(isRegistered).map((row) => AGENT_STEPS[row.id].agent);
+}
+function missingStep(row) {
+    if (AgentReg.PLUGIN === row.reg) {
+        return NextStepCopy.PLUGIN_NOT_CONNECTED;
+    }
+    if (isRegistered(row)) {
+        return AGENT_STEPS[row.id].step;
+    }
+    return registrationText(row);
+}
+/** Per client: connected, or the exact step still missing. */
+export function agentStatuses(rows, connected) {
+    return rows.map((row) => {
+        const { name, agent } = AGENT_STEPS[row.id];
+        if (isRegistered(row) && connected.has(agent)) {
+            return {
+                name,
+                connected: true,
+                said: `${NextStepCopy.CONNECTED_HEAD}${name}${NextStepCopy.CONNECTED_TAIL}`,
+            };
+        }
+        const next = missingStep(row);
+        const said = isRegistered(row)
+            ? `${name}${NextStepCopy.NOT_CONNECTED}${next}`
+            : `${name} ${next}`;
+        return { name, connected: false, next, said };
+    });
+}
+/** The lines the installer prints after its wait. */
+export function connectionLines(rows, connected) {
+    return agentStatuses(rows, connected).map((status) => status.said);
+}
+/**
+ * Poll `read` until every client in `want` has connected, or `budgetMs` has passed. Returns the
+ * last read. Bounded: it never waits longer than the budget.
+ */
+export async function waitForAgents(want, read, clock, budgetMs, pollMs) {
+    const start = clock.now();
+    let seen = read();
+    while (!want.every((client) => seen.has(client)) && clock.now() - start < budgetMs) {
+        await clock.sleep(pollMs);
+        seen = read();
+    }
+    return seen;
+}
+const CLAUDE_CONFIG_DIR_ENV = 'CLAUDE_CONFIG_DIR';
+/** `$CLAUDE_CONFIG_DIR`, else home: where Claude Code keeps `.claude.json`. */
+export function claudeStateDir() {
+    return process.env[CLAUDE_CONFIG_DIR_ENV] ?? homedir();
+}
+const CLAUDE_STATE_FILE = '.claude.json';
+/**
+ * Does this client's config name a `reticle` server, in any shape?
+ *
+ * Presence, not "the entry we would write now". An entry that starts an installed launcher, or an
+ * older npx entry, still starts Reticle. `setup mcp` repairs a stale entry; `status` only reports
+ * whether one is there. A file that does not parse reads as absent.
+ */
+function configNamesReticle(spec, existing) {
+    if (ConfigFormat.TOML === spec.format) {
+        return codexNamesOurServer(existing, spec.serversKey);
+    }
+    if (null === existing) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(existing);
+        const servers = 'object' === typeof parsed && null !== parsed
+            ? parsed[spec.serversKey]
+            : undefined;
+        return 'object' === typeof servers && null !== servers && MCP_SERVER_NAME in servers;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The agents on this machine and whether Reticle is in each config, read only. For `reticle status`,
+ * which must not register anything and must not spawn a client CLI.
+ *
+ * @param claudeStateDir the directory that holds `.claude.json`: `$CLAUDE_CONFIG_DIR`, else home.
+ * @param launcher the installed bin a new registration would use, for the stale-entry fix.
+ */
+export function installedAgentRows(io, projectDir, pluginActive, claudeStateDir = io.homeDir(), launcher) {
+    const rows = [];
+    if (pluginActive) {
+        // A user-scope entry next to the plugin is a second server.
+        rows.push(pluginRow(McpClient.CLAUDE_CODE, claudeHasReticle(io, undefined, claudeStateDir)));
+    }
+    else if (claudeHasReticle(io, projectDir, claudeStateDir)) {
+        rows.push(alreadyRow(McpClient.CLAUDE_CODE, claudeUserEntryIsFloating(io, claudeStateDir), launcher));
+    }
+    else if (io.exists(join(claudeStateDir, CLAUDE_STATE_FILE))) {
+        rows.push({ id: McpClient.CLAUDE_CODE, reg: AgentReg.MISSING });
+    }
+    for (const client of detectMcpClients(io)) {
+        rows.push({
+            id: client.id,
+            reg: configNamesReticle(clientSpec(client.id), client.existing)
+                ? AgentReg.ALREADY
+                : AgentReg.MISSING,
+        });
+    }
+    return rows;
+}

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

@@ -13,8 +13,11 @@ import { AgentAction, AGENT_CLIENTS, joinFor, parentOf, } from './agent-configs.
 /** Two spaces, because that is what every one of these files already uses. */
 const INDENT = 2;
 const RETICLE_KEY = 'reticle';
-/** A fresh Continue config. YAML is only ever created, never edited. */
-const CONTINUE_YAML = 'mcpServers:\n  - name: reticle\n    type: stdio\n    command: npx\n    args: ["@reticlehq/server", "mcp"]\n';
+/**
+ * A fresh Continue config. YAML is only ever created, never edited. The args are a JSON array,
+ * which is valid YAML flow syntax and keeps a Windows path escaped.
+ */
+const continueYaml = (entry) => `mcpServers:\n  - name: ${RETICLE_KEY}\n    type: stdio\n    command: ${String(entry['command'])}\n    args: ${JSON.stringify(entry['args'])}\n`;
 /**
  * Write what the plan says to write, and nothing else.
  *
@@ -32,8 +35,8 @@ export function applyAgentPlan(plan, io) {
         }
         try {
             io.mkdirp(parentOf(step.file));
-            if (AgentAction.CREATE_YAML === step.action) {
-                io.writeFile(step.file, CONTINUE_YAML);
+            if (AgentAction.CREATE_YAML === step.action && undefined !== step.entry) {
+                io.writeFile(step.file, continueYaml(step.entry));
                 return { ...base, action: 'created' };
             }
             const key = step.key;
@@ -99,10 +102,12 @@ export function applyAgentSkills(io, where) {
     const join = joinFor(where.platform);
     for (const client of AGENT_CLIENTS) {
         const dir = client.skillDir;
-        if (undefined === dir)
+        if (undefined === dir) {
             continue;
-        if (!io.exists(join(where.home, client.marker[where.platform])))
+        }
+        if (!io.exists(join(where.home, client.marker[where.platform]))) {
             continue;
+        }
         try {
             const target = join(where.home, dir);
             io.mkdirp(target);

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

@@ -13,6 +13,7 @@ declare const HandedOverSchema: z.ZodObject<{
     pid: z.ZodNumber;
     url: z.ZodString;
     appDir: z.ZodString;
+    bridgePort: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type HandedOver = z.infer<typeof HandedOverSchema>;
 /**
@@ -32,6 +33,14 @@ export declare function handedOverUrl(dir: string, appDir: string, deps: {
     alive: (pid: number) => boolean;
     answers: (url: string) => Promise<boolean>;
 }): Promise<string | undefined>;
+/**
+ * True when the live server `init` handed over for `appDir` was started for a daemon port other than
+ * `bridgePort`. Attaching to it leaves the page dialling the old port, even when no daemon on that
+ * port is left to retire. A record with no port gives false, as before.
+ */
+export declare function handedOverToOtherPort(dir: string, appDir: string, bridgePort: number, deps: {
+    alive: (pid: number) => boolean;
+}): boolean;
 /**
  * Stop the server `init` handed over for `appDir`, and forget it. True when one was stopped.
  *

package/dist/command/setup/bringup/dev-server-files.js

@@ -34,6 +34,11 @@ const HandedOverSchema = z.object({
     pid: z.number().int().positive(),
     url: z.string().min(1),
     appDir: z.string().min(1),
+    /**
+     * The daemon port the server was started for. Absent in a record from an older build. Reticle's
+     * static server adds a snippet that dials this port, so it cannot follow a port move.
+     */
+    bridgePort: z.number().int().positive().optional(),
 });
 /**
  * Written when `init` leaves a server running, so the next `init` can attach to it.
@@ -70,6 +75,18 @@ export async function handedOverUrl(dir, appDir, deps) {
         return undefined;
     return (await deps.answers(record.url)) ? record.url : undefined;
 }
+/**
+ * True when the live server `init` handed over for `appDir` was started for a daemon port other than
+ * `bridgePort`. Attaching to it leaves the page dialling the old port, even when no daemon on that
+ * port is left to retire. A record with no port gives false, as before.
+ */
+export function handedOverToOtherPort(dir, appDir, bridgePort, deps) {
+    const record = readRecord(join(dir, recordName(appDir)));
+    if (undefined === record || record.appDir !== appDir || !deps.alive(record.pid)) {
+        return false;
+    }
+    return undefined !== record.bridgePort && record.bridgePort !== bridgePort;
+}
 /**
  * Stop the server `init` handed over for `appDir`, and forget it. True when one was stopped.
  *

package/dist/command/setup/bringup/static-page-server.d.ts

@@ -8,8 +8,11 @@
  * starts `npm run dev`, and the rest of setup (wait, open, prove the connect) runs unchanged.
  *
  * It is run as its own process (`node static-page-server.js --dir <app>`), not inside init, because it
- * has to outlive init exactly like any handed-over dev server. It imports nothing but Node, so the
- * built file runs on its own.
+ * has to outlive init exactly like any handed-over dev server. It imports only Node and
+ * `@reticlehq/init`, so the built file runs on its own.
+ *
+ * It adds the connect snippet to each HTML page it serves, so init does not edit the file the user
+ * hands over (#1544). The file on disk stays byte-identical.
  *
  * Loopback only, on both families: a page served to the LAN would publish the pairing token the
  * snippet carries.
@@ -21,9 +24,16 @@ export interface StaticPageServer {
     readonly url: string;
     close(): Promise<void>;
 }
+/**
+ * The connect literal for the page in `root`: the bridge port, and the project id its `.reticle.json`
+ * names. The same literal init wrote into the page before #1544.
+ */
+export declare function staticPageConnect(root: string, bridgePort: number): string;
 export declare function startStaticPageServer(opts: {
     root: string;
     port: number;
+    /** The connect literal to add to each HTML page. Absent: pages are served as written. */
+    connect?: string | undefined;
 }): Promise<StaticPageServer>;
 /**
  * The command setup runs for a page with no dev server of its own, or undefined when this is not
@@ -32,4 +42,6 @@ export declare function startStaticPageServer(opts: {
 export declare function staticPageDevCommand(opts: {
     appDir: string;
     isStaticPage: boolean;
+    /** The daemon port the added snippet dials. Absent: the page is served as written. */
+    bridgePort?: number | undefined;
 }): string | undefined;