@reticlehq/server 3.7.0 → 3.8.1

package/dist/command/setup/probe/dev-port.js

@@ -0,0 +1,117 @@
+/**
+ * Something already serving half of the port the dev server is about to take (#1377).
+ *
+ * With a Docker or nginx stack on 5173, `init` started `pnpm dev`, and on macOS Vite can bind
+ * `[::1]` beside a process holding `0.0.0.0:5173` and print no error. `localhost:5173` then served
+ * the instrumented dev server and `127.0.0.1:5173` the stale container bundle, which looked like
+ * "the SDK sometimes doesn't connect". Busy-port detection read the dev server's own output, and
+ * Vite says nothing in that case, so the port is asked before anything is spawned. Only that
+ * one-sided case is refused; a port busy on both loopbacks is one the dev server sees and moves off.
+ */
+import { readFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { join } from 'node:path';
+import { frameworkDevPort } from '@reticlehq/init';
+/** A `port:` in a dev config: it may move the server, so the framework default is not assumed. */
+const CONFIG_SETS_PORT = /\bport\s*:/;
+/**
+ * The port the dev server will take, when that is known: the one its script pins, else the
+ * framework's default unless the dev config names a port of its own. Undefined otherwise, and
+ * nothing is probed: a guessed port refusing a start would be a worse failure than this one.
+ */
+export function expectedDevPort(facts) {
+    if (facts.pinned !== undefined)
+        return facts.pinned;
+    if (facts.framework === undefined)
+        return undefined;
+    if (facts.devConfig !== undefined && CONFIG_SETS_PORT.test(facts.devConfig))
+        return undefined;
+    return frameworkDevPort(facts.framework);
+}
+/** How long one loopback address may take to answer. Local, so anything slower is nothing. */
+const PROBE_TIMEOUT_MS = 400;
+/** Both loopbacks: the case this exists for is a server on one and not the other. */
+const LOOPBACKS = ['127.0.0.1', '::1'];
+function answers(port, host) {
+    return new Promise((resolve) => {
+        const socket = connect({ port, host });
+        const done = (open) => {
+            socket.destroy();
+            resolve(open);
+        };
+        socket.setTimeout(PROBE_TIMEOUT_MS, () => done(false));
+        socket.once('connect', () => done(true));
+        socket.once('error', () => done(false));
+    });
+}
+/**
+ * The one loopback something answers on at `port` while the other is free, or undefined.
+ *
+ * Only that split is refused. A port busy on both loopbacks is one the dev server sees: Vite and
+ * Next move to the next port and print it, and setup reads that, as it always has. A second Vite
+ * app on 5173 is the common case, and stopping there would break a start that works. The dev server
+ * cannot see a listener on only one loopback, because it binds the other with no error, and then
+ * `localhost` and `127.0.0.1` serve two different apps.
+ */
+export async function loneLoopbackOnDevPort(port) {
+    const open = await Promise.all(LOOPBACKS.map((host) => answers(port, host)));
+    const answering = LOOPBACKS.filter((_, i) => true === open[i]);
+    return 1 === answering.length ? answering[0] : undefined;
+}
+/** What setup says instead of starting a dev server on the other half of a split port. */
+export function splitDevPortNote(port, host) {
+    const shown = (h) => (h.includes(':') ? `[${h}]` : h);
+    const other = LOOPBACKS.find((h) => h !== host) ?? host;
+    return (`Port ${String(port)} is half taken: something answers on ${shown(host)}:${String(port)} and ` +
+        `nothing on ${shown(other)}:${String(port)}. The dev server would bind ${shown(other)} with no ` +
+        'error, and then localhost and 127.0.0.1 would serve two different apps, so which one a browser ' +
+        'or a lease reaches would be luck. If it is this app already running, re-run with ' +
+        `--url http://localhost:${String(port)} to attach to it. Otherwise stop whatever holds the ` +
+        'port, or give the dev server another one.');
+}
+/** The dev configs that can move a framework's server off its default port. */
+const DEV_CONFIGS = [
+    'vite.config.ts',
+    'vite.config.js',
+    'vite.config.mts',
+    'vite.config.mjs',
+    'vite.config.cjs',
+    'astro.config.mjs',
+    'astro.config.ts',
+    'angular.json',
+];
+/** The text of every dev config present in `appDir`, joined, or undefined when there is none. */
+export function devConfigText(appDir) {
+    const texts = DEV_CONFIGS.flatMap((name) => {
+        try {
+            return [readFileSync(join(appDir, name), 'utf8')];
+        }
+        catch {
+            return [];
+        }
+    });
+    return 0 === texts.length ? undefined : texts.join('\n');
+}
+/** The scripts a project runs itself with, in the order init picks them. */
+const DEV_SCRIPTS = ['dev', 'start', 'serve'];
+const PINNED_PORT = [/--port[= ]\s*(\d+)/, /(?:^|\s)-p\s*(\d+)/, /(?:^|\s)PORT=(\d+)/];
+/** The port the project's dev script pins (`--port`, `-p`, `PORT=`), or undefined. */
+export function pinnedDevPort(appDir) {
+    let scripts = {};
+    try {
+        const manifest = JSON.parse(readFileSync(join(appDir, 'package.json'), 'utf8'));
+        scripts = manifest.scripts ?? {};
+    }
+    catch {
+        return undefined;
+    }
+    const body = DEV_SCRIPTS.map((name) => scripts[name]).find((value) => 'string' === typeof value && 0 < value.trim().length);
+    if (body === undefined)
+        return undefined;
+    for (const pattern of PINNED_PORT) {
+        const digits = pattern.exec(body)?.[1];
+        if (digits !== undefined)
+            return Number.parseInt(digits, 10);
+    }
+    return undefined;
+}

package/dist/command/setup/probe/page-probe.d.ts

@@ -14,7 +14,7 @@
 export interface PageProbe {
     /** The server answered at all. */
     readonly served: boolean;
-    /** The SDK appears in what it answered with. */
+    /** The SDK is referenced in what it answered with. A reference, not proof that the SDK loaded. */
     readonly sdkInPage: boolean;
     /**
      * The server ANSWERED and its certificate was refused. A self-signed dev cert is an ordinary

package/dist/command/setup/probe/page-probe.js

@@ -16,6 +16,10 @@ export const PageFinding = {
     SDK_MISSING: 'sdk-missing',
     SDK_PRESENT: 'sdk-present',
 };
+/** Where a reference that never loaded shows itself. Shared by both SDK_PRESENT sentences. */
+const FAILED_IMPORT = 'open the browser console and look for a failed import of @reticlehq/browser: a CDN 404 (for ' +
+    'example a version that is not published yet, or a private registry), a blocked script, or a ' +
+    'wrong path.';
 /** Pure, so the mapping is testable without a server or a browser. */
 export function readPage(probe) {
     if (true === probe.tlsRefused)
@@ -34,8 +38,11 @@ export function readPage(probe) {
  * the one piece of positive evidence in the run.
  */
 export function describePage(finding, url, daemonSpoke = false) {
+    // The probe reads the HTML text. It sees a REFERENCE to the SDK, not an SDK that loaded: a
+    // pinned CDN version that returns 404 leaves the reference in place and no SDK in the page.
     if (PageFinding.SDK_PRESENT === finding && daemonSpoke) {
-        return `The SDK IS in the page at ${url}; the daemon's account above says what became of it.`;
+        return (`The page at ${url} references the SDK. That does not prove the SDK loaded: the daemon's ` +
+            `account above says if an SDK session dialled. If none did, ${FAILED_IMPORT}`);
     }
     switch (finding) {
         case PageFinding.NOT_SERVED:
@@ -56,9 +63,10 @@ export function describePage(finding, url, daemonSpoke = false) {
             // gate cell the page console read "could not open a websocket to ws://localhost:<port>, 3
             // attempts, all failed": the SDK dialled three times and the socket failed, having returned
             // early from nothing. What is knowable here is that the SDK is present and no session arrived.
-            return (`The SDK IS in the page at ${url} and never dialled the bridge: a localhost guard, a ` +
+            return (`The page at ${url} references the SDK, and the SDK never dialled the bridge. First, ` +
+                `${FAILED_IMPORT} If the import loaded, the cause is a localhost guard, a ` +
                 'production-only check, a bridge port that differs on the two sides, or `localhost` ' +
-                'resolving to IPv6 where the daemon is only on IPv4 — `npx @reticlehq/server doctor` names ' +
+                'resolving to IPv6 where the daemon is only on IPv4. `npx @reticlehq/server doctor` names ' +
                 'that last one, and the page console names the first three.');
     }
 }

package/dist/command/setup/remaining-steps.d.ts

@@ -1,10 +1,3 @@
-/**
- * What is left to do by hand, from wherever setup stopped.
- *
- * Naming a cause is not the same as being recoverable. Setup can misbehave, and when it does the
- * caller should not have to re-read the whole procedure and work out for itself which parts already
- * worked — it should pick up at the step that did not. Ordered, and only ever the REMAINING steps.
- */
 /** How far a run got. Everything here is knowable from the result object setup already builds. */
 export interface Progress {
     readonly initDone: boolean;

package/dist/command/setup/remaining-steps.js

@@ -5,6 +5,7 @@
  * caller should not have to re-read the whole procedure and work out for itself which parts already
  * worked — it should pick up at the step that did not. Ordered, and only ever the REMAINING steps.
  */
+import { FEEDBACK_KIND_CHOICES } from '@reticlehq/core';
 const DOCS_INDEX = 'https://docs.reticle.sh/llms.txt';
 /**
  * The shell form on purpose, not `reticle_session { action: "feedback" }`.
@@ -14,7 +15,7 @@ const DOCS_INDEX = 'https://docs.reticle.sh/llms.txt';
  * the tool surface is unreachable. Naming the tool here would ask the reader to file through the
  * thing that is broken. The shell command needs no daemon and no session.
  */
-const FEEDBACK_CMD = 'npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"';
+const FEEDBACK_CMD = `npx @reticlehq/server feedback --agent --kind ${FEEDBACK_KIND_CHOICES} "what happened"`;
 export function remainingSteps(p) {
     const steps = [];
     if (!p.initDone) {
@@ -35,7 +36,7 @@ export function remainingSteps(p) {
             'what produce a verdict. Or hand the whole drive to Reticle with `reticle_verify { action: ' +
             '"explore", persona: "<who does what>" }`, which records what it drove so later runs replay ' +
             'with no model in the loop; that route runs on the Reticle platform and needs a linked ' +
-            'project (`reticle connect`); a new account gets 10 free credits to try it.');
+            'project (`reticle connect`); a new account gets free credits to try it.');
     }
     // Whether anything is actually outstanding, read BEFORE the docs pointer is added -- that line is
     // an offer, not a task, and a run with nothing left still gets it.

package/dist/command/setup/run-setup.d.ts

@@ -12,6 +12,7 @@
 import { type CandidateSession } from './session-pick.js';
 import { type PageProbe } from './probe/page-probe.js';
 import { AppShape } from './desktop-shape.js';
+import { InitStop } from '@reticlehq/core/telemetry';
 /**
  * Said before Reticle starts its own static server for a plain page, while it can still be acted
  * on: the page may already be served by something with an API behind it, and only the person
@@ -36,6 +37,8 @@ export interface SetupOutcome {
     /** True when the app is running, instrumented and connected. Writing files alone is not that. */
     readonly ok: boolean;
     readonly reachedPhase: SetupPhase;
+    /** On a failure: the step it stopped at, for the `init_completed` event. */
+    readonly stop?: InitStop | undefined;
     readonly url?: string | undefined;
     readonly sessionId?: string | undefined;
     /**
@@ -82,6 +85,12 @@ export interface SetupEffects {
      * starting a second one on the next port.
      */
     readonly existingAppUrl?: () => Promise<string | undefined>;
+    /**
+     * The one loopback address something answers on at a port, when the other is free. Undefined
+     * when both are free or both answer. Asked before the dev server is started, never after: see
+     * probe/dev-port.ts.
+     */
+    readonly loneLoopbackOnDevPort?: (port: number) => Promise<string | undefined>;
     /** Everything the dev server has printed so far. */
     readonly devServerOutput: () => string;
     readonly devServerExited: () => boolean;
@@ -147,6 +156,8 @@ export interface SetupInput {
     readonly devCommandIsStaticPage?: boolean | undefined;
     /** The app is already served here, so nothing is started. */
     readonly suppliedUrl?: string | undefined;
+    /** The port the dev command will take, when it is known. See probe/dev-port.ts. */
+    readonly devPort?: number | undefined;
     /**
      * The caller's own budget for the connect wait, when they named one.
      *

package/dist/command/setup/run-setup.js

@@ -27,7 +27,9 @@ const WINDOWS_QUIET_MEANS_HUNG_MS_APPLIES = 'win32' === process.platform;
 import { liveSessionOfProject, pickSession } from './session-pick.js';
 import { readPage, describePage, findingBeforeOpen, PageFinding, } from './probe/page-probe.js';
 import { remainingSteps } from './remaining-steps.js';
+import { splitDevPortNote } from './probe/dev-port.js';
 import { AppShape, isDesktop, policyFor } from './desktop-shape.js';
+import { InitStop } from '@reticlehq/core/telemetry';
 /** Where a run got to, and why it stopped if it did. */
 /**
  * How long to keep asking whether the SDK has reached the page before giving up on opening a window.
@@ -81,6 +83,16 @@ const asProgress = (input, o) => ({
     ...(undefined === o.url ? {} : { url: o.url }),
     ...(undefined === input.devCommand ? {} : { devCommand: input.devCommand }),
 });
+/** The connect step a web page stopped at. A bundle-connect page's HTML never shows the SDK. */
+const connectStop = (finding, htmlCarriesSdk) => {
+    if (PageFinding.NOT_SERVED === finding)
+        return InitStop.PAGE_NOT_SERVED;
+    if (PageFinding.TLS_REFUSED === finding)
+        return InitStop.PAGE_TLS_REFUSED;
+    if (PageFinding.SDK_MISSING === finding && htmlCarriesSdk)
+        return InitStop.SDK_MISSING;
+    return InitStop.NO_SESSION;
+};
 const stop = (input, phase, partial, notes) => ({
     ok: false,
     reachedPhase: phase,
@@ -143,9 +155,20 @@ export async function runSetupPhases(input, fx) {
             'No dev command: the project names no dev, start or serve script, and no app url was given (`reticle init --url <app>`). ' +
                 'Stopping here rather than invent one — start the app yourself and pass --url to say ' +
                 'where it is serving, or add a dev/start/serve script to package.json and re-run.');
-            return stop(input, SetupPhase.DEV_SERVER, {}, notes);
+            return stop(input, SetupPhase.DEV_SERVER, { stop: InitStop.NO_DEV_COMMAND }, notes);
         }
         else {
+            // Not this project's announced server (that branch is above). Something answering on one
+            // loopback and not the other is the split a new server cannot see: it binds the free one with
+            // no error, and the two addresses serve different apps (#1377). Something on both loopbacks
+            // is a busy port the dev server sees and moves off, so it starts as before.
+            const lone = undefined === input.devPort || undefined === fx.loneLoopbackOnDevPort
+                ? undefined
+                : await fx.loneLoopbackOnDevPort(input.devPort);
+            if (undefined !== lone && undefined !== input.devPort) {
+                note(splitDevPortNote(input.devPort, lone));
+                return stop(input, SetupPhase.DEV_SERVER, { stop: InitStop.SPLIT_LOOPBACK }, notes);
+            }
             if (true === input.devCommandIsStaticPage)
                 note(STATIC_PAGE_URL_HINT);
             await fx.startDevServer(input.devCommand, input.appDir);
@@ -190,8 +213,10 @@ export async function runSetupPhases(input, fx) {
                     break;
                 }
                 if (WaitVerdict.DEAD === verdict) {
-                    note(portBusyMessage(fx.devServerOutput()) ?? devServerDiedMessage(fx.devServerOutput()));
-                    return stop(input, SetupPhase.DEV_SERVER, {}, notes);
+                    const busy = portBusyMessage(fx.devServerOutput());
+                    note(busy ?? devServerDiedMessage(fx.devServerOutput()));
+                    const step = undefined === busy ? InitStop.DEV_SERVER_EXITED : InitStop.PORT_BUSY;
+                    return stop(input, SetupPhase.DEV_SERVER, { stop: step }, notes);
                 }
                 if (WaitVerdict.HUNG === verdict) {
                     // Says BOTH were checked. A server that prints nothing but IS listening is the CRA case and
@@ -206,7 +231,8 @@ export async function runSetupPhases(input, fx) {
                             ? `The dev server did not become ready${within}. `
                             : `The dev server stopped making progress before ${watching} became ready. `) +
                         'Check its log, increase --timeout for a slow build, or pass --url with the address it serves.');
-                    return stop(input, SetupPhase.DEV_SERVER, {}, notes);
+                    const step = undefined === watching ? InitStop.NO_URL : InitStop.NOT_READY;
+                    return stop(input, SetupPhase.DEV_SERVER, { stop: step }, notes);
                 }
                 await fx.sleep(input.pollMs);
             }
@@ -344,6 +370,7 @@ export async function runSetupPhases(input, fx) {
         await fx.sleep(input.pollMs);
     }
     if (null === session) {
+        let step = InitStop.DESKTOP_NO_SESSION;
         if (isDesktop(input.shape)) {
             // Nothing outside the app can fetch its webview, so there is no page to describe. What is
             // wrong here is desktop-shaped: the preload, the capture helper, or a CSP that blocks the
@@ -376,9 +403,10 @@ export async function runSetupPhases(input, fx) {
             if (PageFinding.SDK_MISSING !== finding || input.htmlCarriesSdk) {
                 note(describePage(finding, url, undefined !== why));
             }
+            step = connectStop(finding, input.htmlCarriesSdk);
         }
         await releaseLease(lease);
-        return stop(input, SetupPhase.CONNECT, { url }, notes);
+        return stop(input, SetupPhase.CONNECT, { url, stop: step }, notes);
     }
     // ── connected, which is where ONBOARDING ends ────────────────────────────────────────────────
     //

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

@@ -31,6 +31,8 @@ interface SetupCommandInput extends Omit<SetupInput, 'shape'> {
     readonly pairingToken?: string | undefined;
     /** False for `--no-first-run`: connect, and say nothing more. */
     readonly firstRun: boolean;
+    /** The framework init detected, for the dev server's default port. See probe/dev-port.ts. */
+    readonly framework?: string | undefined;
     /** `--json`: an agent is reading, so nothing is driven on its behalf. */
     readonly json: boolean;
     /**

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

@@ -8,8 +8,9 @@
 import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { planAgentConfigs } from './agent-configs.js';
+import { planAgentConfigs, platformKey } from './agent-configs.js';
 import { AppShape, describeShape, readShape } from './desktop-shape.js';
+import { devConfigText, expectedDevPort, loneLoopbackOnDevPort, pinnedDevPort, } from './probe/dev-port.js';
 import { SigningEnv, tauriSigningEnv } from './tauri-signing.js';
 import { stopOnInterrupt } from './terminal/interrupt.js';
 import { stopOnCrash, crashSentence } from './terminal/crash.js';
@@ -92,7 +93,7 @@ function hasElectronDependency(dir) {
 const agentWord = (n) => (1 === n ? 'agent' : 'agents');
 /** Returns how many agents it wrote a config for, so a caller does not then say "none found". */
 export function registerOtherAgents(print) {
-    const platform = process.platform;
+    const platform = platformKey(process.platform);
     const home = homedir();
     const results = applyAgentPlan(planAgentConfigs({ home, platform, exists: agentIo.exists, readFile: agentIo.readFile }), agentIo);
     const wrote = results.filter((r) => 'created' === r.action || 'merged' === r.action);
@@ -219,7 +220,7 @@ export async function runSetupCommand(input, print) {
             flowSaved: false,
             notes: undefined === daemon.message ? [] : [daemon.message],
             fallback: [
-                `Once those sessions are done, free the port with \`npx @reticlehq/server kill --port ${String(input.bridgePort)}\` and re-run init.`,
+                `Once those sessions are done, free the port with \`npx @reticlehq/server stop --force --port ${String(input.bridgePort)}\` and re-run init.`,
             ],
         };
     }
@@ -265,6 +266,9 @@ export async function runSetupCommand(input, print) {
             server.start(command, cwd, { ...input.env, ...signing });
             return Promise.resolve();
         },
+        // Asked before the dev script is spawned: a listener on one loopback only is not this
+        // project's, and the dev server could not see it (#1377).
+        loneLoopbackOnDevPort,
         // The server the plugin announced (Vite), or failing that the one a previous init handed over
         // and recorded — the only way to know a Next or Angular server on the port is this project's own.
         existingAppUrl: async () => urlOfExistingApp(readDevServers(reticleStateHome()), {
@@ -327,7 +331,21 @@ export async function runSetupCommand(input, print) {
     // activity, and on a slow desktop build the daemon init had just started idled out mid-wait.
     const releaseDaemon = holdDaemon(input.bridgePort);
     try {
-        const outcome = await runSetupPhases({ ...input, shape, projectId: readProjectId(input.appDir) }, effects);
+        // The port the project's own dev script will take, when it can be known (#1377). Not with
+        // --url, where nothing is started.
+        const devPort = undefined === input.devCommand || undefined !== input.suppliedUrl
+            ? undefined
+            : expectedDevPort({
+                pinned: pinnedDevPort(input.appDir),
+                framework: input.framework,
+                devConfig: devConfigText(input.appDir),
+            });
+        const outcome = await runSetupPhases({
+            ...input,
+            shape,
+            projectId: readProjectId(input.appDir),
+            ...(undefined === devPort ? {} : { devPort }),
+        }, effects);
         // The app stays up only when there is something worth watching.
         if (outcome.ok) {
             server.handOver(outcome.url);

package/dist/command/update/updater.d.ts

@@ -1,9 +1,4 @@
-/** Which way the installed version moved. A rollback means a release hurt someone enough to retreat. */
-declare const VersionChangeDirection: {
-    readonly UPDATE: "update";
-    readonly ROLLBACK: "rollback";
-};
-type VersionChangeDirection = (typeof VersionChangeDirection)[keyof typeof VersionChangeDirection];
+import { VersionChangeDirection } from './version-seen.js';
 /**
  * Report a completed version move. Never throws — an install that worked must still be reported done.
  *

package/dist/command/update/updater.js

@@ -10,11 +10,8 @@ import { windowsShellArg } from '@reticlehq/init';
 import { TelemetryEventKind } from '@reticlehq/core/telemetry';
 import { getTelemetry } from '../../telemetry/telemetry.js';
 import { wasNudged } from './nudge-credit.js';
-/** Which way the installed version moved. A rollback means a release hurt someone enough to retreat. */
-const VersionChangeDirection = {
-    UPDATE: 'update',
-    ROLLBACK: 'rollback',
-};
+import { VersionChangeDirection, noteRunningVersion } from './version-seen.js';
+import { INSTALL_STATE_DIR } from '../../telemetry/install-source.js';
 /**
  * Report a completed version move. Never throws — an install that worked must still be reported done.
  *
@@ -30,6 +27,8 @@ export async function reportVersionChange(from, to, direction) {
             // updated from a shell script or a package bump with no agent involved at all.
             versionChange: { from, to, direction, ...(nudged ? { nudged } : {}) },
         });
+        // Record the new version now, so the next start does not report this move a second time.
+        noteRunningVersion(to, INSTALL_STATE_DIR);
     }
     catch {
         /* best-effort, like every other send */

package/dist/command/update/version-seen.d.ts

@@ -0,0 +1,24 @@
+/** Which way the installed version moved. A rollback means a release hurt someone enough to retreat. */
+export declare const VersionChangeDirection: {
+    readonly UPDATE: "update";
+    readonly ROLLBACK: "rollback";
+};
+export type VersionChangeDirection = (typeof VersionChangeDirection)[keyof typeof VersionChangeDirection];
+export interface VersionMove {
+    readonly from: string;
+    readonly to: string;
+    readonly direction: VersionChangeDirection;
+}
+/** What a version that is not one of our release numbers reports as. */
+export declare const OTHER_VERSION = "other";
+/**
+ * A version string that came from outside this process, made safe to send: one of our release
+ * numbers as it is, anything else as `other`, and nothing when there is no value.
+ */
+export declare function releaseVersionOf(raw: string | undefined): string | undefined;
+/**
+ * Record `current` as the last version this machine ran, and return the move when the record held
+ * a different version. Never throws. A home that cannot be written reports no move, so a read-only
+ * home does not send a move on every start.
+ */
+export declare function noteRunningVersion(current: string, stateDir: string): VersionMove | undefined;

package/dist/command/update/version-seen.js

@@ -0,0 +1,65 @@
+/**
+ * `version_changed` for every version move on a machine, not only a move through `reticle update`.
+ *
+ * Each CLI start compares its version with the last version that this machine ran, kept in
+ * `~/.reticle/last-version`. A difference is one move. The file then holds the new version, so the
+ * move is reported once. The first start on a machine records the version and reports nothing: an
+ * install is not a move.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isNewerVersion } from './update-nudge.js';
+/** Which way the installed version moved. A rollback means a release hurt someone enough to retreat. */
+export const VersionChangeDirection = {
+    UPDATE: 'update',
+    ROLLBACK: 'rollback',
+};
+const LAST_VERSION_FILE = 'last-version';
+/** Our own release numbers only. Anything else in the file is not sent. */
+const RELEASE_VERSION = /^\d+\.\d+\.\d+(?:-[a-z]+(?:\.\d+)?)?$/;
+/** What a version that is not one of our release numbers reports as. */
+export const OTHER_VERSION = 'other';
+/**
+ * A version string that came from outside this process, made safe to send: one of our release
+ * numbers as it is, anything else as `other`, and nothing when there is no value.
+ */
+export function releaseVersionOf(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    return RELEASE_VERSION.test(raw) ? raw : OTHER_VERSION;
+}
+/**
+ * Record `current` as the last version this machine ran, and return the move when the record held
+ * a different version. Never throws. A home that cannot be written reports no move, so a read-only
+ * home does not send a move on every start.
+ */
+export function noteRunningVersion(current, stateDir) {
+    const file = join(stateDir, LAST_VERSION_FILE);
+    let last;
+    try {
+        last = readFileSync(file, 'utf8').trim();
+    }
+    catch {
+        last = undefined;
+    }
+    if (last === current) {
+        return undefined;
+    }
+    try {
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(file, current, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    // ponytail: read-then-write is not atomic. Two first starts of a new version at the same moment
+    // can both report the move. Use an exclusive claim file if the duplicates show in the data.
+    if (last === undefined || !RELEASE_VERSION.test(last) || !RELEASE_VERSION.test(current)) {
+        return undefined;
+    }
+    const direction = isNewerVersion(current, last)
+        ? VersionChangeDirection.UPDATE
+        : VersionChangeDirection.ROLLBACK;
+    return { from: last, to: current, direction };
+}

package/dist/command/version/peer-announce.d.ts

@@ -1,8 +1,16 @@
 export declare const PEER_VERSION_PARAM = "peerVersion";
 export declare const PEER_CONTRACT_PARAM = "peerContract";
+/** The coding agent's own session id, on the same connect. */
+export declare const AGENT_SESSION_PARAM = "agentSession";
+/** The agent's session id in this process's environment, when it is a plain id. */
+export declare function agentSessionInEnv(env: NodeJS.ProcessEnv): string | undefined;
+/** The query suffix that announces the agent's session, or '' when the agent named none. */
+export declare function agentSessionQuery(env: NodeJS.ProcessEnv): string;
+/** The announced session id, when it is a plain id. */
+export declare function agentSessionOf(value: string | null): string | undefined;
 /**
  * Compare an attaching agent process against this daemon: the skew to tell THAT connection, or
  * undefined when they agree. Returned rather than queued daemon-wide, because it is true only for the
  * agent that announced it (#1136).
  */
-export declare function agentPeerSkew(version: string | null, contract: string | null): string | undefined;
+export declare function agentPeerSkew(version: string | null, contract: string | null, pageSdkVersions?: readonly (string | undefined)[]): string | undefined;

package/dist/command/version/peer-announce.js

@@ -16,19 +16,42 @@ import { SERVER_VERSION } from './identity/server-version.js';
 import { daemonFix, describeSkew } from './version-skew.js';
 export const PEER_VERSION_PARAM = 'peerVersion';
 export const PEER_CONTRACT_PARAM = 'peerContract';
+/** The coding agent's own session id, on the same connect. */
+export const AGENT_SESSION_PARAM = 'agentSession';
+/**
+ * Where an agent puts its session id in its MCP server's environment. Claude Code sets
+ * `CLAUDE_CODE_SESSION_ID`, the same id its hooks receive as `session_id` (checked 2026-10-19).
+ * Other agents set none that is documented, so their connections announce nothing.
+ */
+const AGENT_SESSION_ENVS = ['CLAUDE_CODE_SESSION_ID'];
+/** A session id is a plain token: anything else is not used as a file name. */
+const PLAIN_ID = /^[\w-]{1,128}$/;
+/** The agent's session id in this process's environment, when it is a plain id. */
+export function agentSessionInEnv(env) {
+    return agentSessionOf(AGENT_SESSION_ENVS.map((name) => env[name]).find((v) => v !== undefined) ?? null);
+}
+/** The query suffix that announces the agent's session, or '' when the agent named none. */
+export function agentSessionQuery(env) {
+    const id = agentSessionInEnv(env);
+    return id === undefined ? '' : `&${AGENT_SESSION_PARAM}=${encodeURIComponent(id)}`;
+}
+/** The announced session id, when it is a plain id. */
+export function agentSessionOf(value) {
+    return null !== value && PLAIN_ID.test(value) ? value : undefined;
+}
 /**
  * Compare an attaching agent process against this daemon: the skew to tell THAT connection, or
  * undefined when they agree. Returned rather than queued daemon-wide, because it is true only for the
  * agent that announced it (#1136).
  */
-export function agentPeerSkew(version, contract) {
+export function agentPeerSkew(version, contract, pageSdkVersions = []) {
     const skew = describeSkew({
         what: "the agent's MCP server",
         version: version ?? undefined,
         contract: contract ?? undefined,
         // Inverted from cli-launch: here THIS process is the daemon and the peer is the agent's
         // MCP server, so the daemon is the newer half whenever the announcing agent is behind.
-        fix: daemonFix(SERVER_VERSION, version ?? undefined),
+        fix: daemonFix(SERVER_VERSION, version ?? undefined, pageSdkVersions),
     }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
     return skew;
 }

package/dist/command/version/sdk-fix.d.ts

@@ -5,25 +5,24 @@
  * because those answers are never actively wrong. When a project directory IS in hand, name the
  * packages actually in package.json and the manager the lockfile implies.
  *
- * Does not import `init/`. The library path must never reach the installer
- * (`library-path-boundary.test.ts`); `reticleDepsOf` lives in `update/` for that reason, and the
- * lockfile → manager map is the same evidence `detectPackageManager` reads, kept here so a HELLO
- * does not load the install plan.
+ * The manager is init's own rule, `detectPackageManager` over `resolveLockfiles`, read through a
+ * declared crossing (`library-path-boundary.test.ts`); a copy kept here had fallen behind it.
  */
+import { PackageManager } from '@reticlehq/init';
 /** What a project contributes to the remedy, when we were able to read one. */
 interface SdkFixContext {
     /** `@reticlehq/*` packages declared in package.json. Empty / omitted means none yet. */
     packages?: readonly string[];
     packageManager: PackageManagerName;
 }
-/** Lockfile / marker → manager, same evidence `init/detect.ts` uses. */
+/** init's manager names, under the name this module exports. */
 export declare const PackageManagerName: {
     readonly PNPM: "pnpm";
     readonly YARN: "yarn";
     readonly BUN: "bun";
     readonly NPM: "npm";
 };
-export type PackageManagerName = (typeof PackageManagerName)[keyof typeof PackageManagerName];
+export type PackageManagerName = PackageManager;
 /**
  * The one sentence telling the human how to bring the page's SDK in line with this daemon.
  *