@reticlehq/server 3.8.0 → 3.8.2

package/SKILL.md

@@ -138,7 +138,7 @@ Stop at the first row that fits. Replaying a saved journey costs a few hundred t
 | "Did my edit break anything?" | `reticle_verify { action: "change", files: ["src/App.tsx"] }` |
 | "Does every saved journey still work?" | `reticle_verify { action: "flows" }` |
 | "Does this new behaviour work?" | `reticle_act_and_wait` on the step that ENDS the journey |
-| No MCP at all | `npx @reticlehq/server verify <url> --expect '<predicate JSON>'` |
+| No MCP tools (a cloud agent, a worker) | `npx @reticlehq/server serve`, then `npx @reticlehq/server verify <url> --expect '<predicate JSON>'`. `open <url> --navigate` moves a connected tab to `<url>` |
 
 `change` answers `unknown` when no saved flow covers your files: nothing ran, so drive it yourself and never read it as a pass. A locator that was renamed rather than broken: `reticle_verify { action: "heal", flowName }` proposes the rebind, and `apply: true` writes it after it proves the saved consequence again.
 
@@ -161,7 +161,7 @@ A journey in one call: `reticle_act { steps: [{ target, action, args?, expect? }
 | ref no longer resolves | the DOM re-rendered: target by `testid` or `role`+`name` |
 | predicate did not parse | it names the field: fix the shape against the table above |
 | destructive action blocked | `args.confirmDangerous: true`, only if the user wants that press |
-| version skew | `npx @reticlehq/server stop`, then retry |
+| version skew | update the CLI and the app SDK (`npx @reticlehq/server update` in the app's folder), then restart the MCP host |
 | port held by a non-Reticle process | stop that process, or run Reticle on another `--port` |
 | tab served from another worktree | start the dev server in your own worktree; keep the port |
 

package/dist/command/cli/answers/gate-hook-message.d.ts

@@ -23,6 +23,8 @@ interface GateHookInput {
     deleted: readonly string[];
     /** Changed interactive components no saved flow has ever driven. */
     unflowed?: readonly string[];
+    /** Saved flows exist but none records a source location, so no flow can be matched to a file. */
+    flowsWithoutSources?: boolean;
     /** Coverage levels below their best, already worded (`branched 100% -> 50%`). */
     coverageRegressed?: readonly string[];
     /** Changed files the browser loaded and never ran a function of. */

package/dist/command/cli/answers/gate-hook-message.js

@@ -14,6 +14,8 @@ import { GateExit } from './gate-exit.js';
 /** Named so a reader of the hook output knows the flag is real and not a suggestion. */
 export const GATE_SKIP_ENV = 'RETICLE_SKIP_GATE';
 const MAX_NAMED = 5;
+/** Where source stamps come from; the file extension alone does not say which plugin applies. */
+const STAMP_ADVICE = 'source stamps come from @reticlehq/vite-plugin (JSX and Svelte), @reticlehq/next or @reticlehq/babel-plugin. Vue and Angular templates have no source stamps yet';
 /** A short list, then a count — a hook that prints forty names is a hook people turn off. */
 function name(list) {
     const shown = list.slice(0, MAX_NAMED).join(', ');
@@ -40,7 +42,9 @@ export function gateHookMessage(exit, input) {
     if (input.deleted.length > 0)
         lines.push(`  coverage deleted while its files changed: ${name(input.deleted)}`);
     if (input.unflowed !== undefined && input.unflowed.length > 0)
-        lines.push(`  changed, and no saved flow drives it: ${name(input.unflowed)} — drive it with reticle_act_and_wait and a declared \`until\``);
+        lines.push(true === input.flowsWithoutSources
+            ? `  changed, but the saved flows carry no source locations, so the gate cannot match a flow to them: ${name(input.unflowed)} — ${STAMP_ADVICE}`
+            : `  changed, and no saved flow drives it: ${name(input.unflowed)} — drive it with reticle_act_and_wait and a declared \`until\``);
     if (input.coverageRegressed !== undefined && input.coverageRegressed.length > 0)
         lines.push(`  coverage fell: ${name(input.coverageRegressed)} — something new is uncovered; reticle_verify { action: "crawl", exhaustive: true } names it. If the drop was intended, \`reticle gate --accept-coverage\` records it`);
     if (input.unexecuted !== undefined && input.unexecuted.length > 0)

package/dist/command/cli/auth/cloud-session.d.ts

@@ -14,27 +14,9 @@ declare const SessionSchema: z.ZodObject<{
     url: z.ZodString;
     token: z.ZodString;
     orgName: z.ZodString;
-    /**
-     * WHICH tenant this session signed into. Optional because every session file written before
-     * org-scoped credentials lacks it; the link path treats "unknown" as "cannot prove a stored key
-     * is ours" and mints, which is the safe direction.
-     */
     orgId: z.ZodOptional<z.ZodString>;
-    /** Who signed in. Absent in sessions written before it was recorded. */
     email: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    token: string;
-    url: string;
-    orgName: string;
-    orgId?: string | undefined;
-    email?: string | undefined;
-}, {
-    token: string;
-    url: string;
-    orgName: string;
-    orgId?: string | undefined;
-    email?: string | undefined;
-}>;
+}, z.core.$strip>;
 export type Session = z.infer<typeof SessionSchema>;
 /** Trailing slashes are not identity: `https://x/` and `https://x` are one host. */
 export declare const normalizeUrl: (url: string) => string;

package/dist/command/cli/auth/device-flow.d.ts

@@ -18,21 +18,7 @@ export declare const DeviceStartSchema: z.ZodObject<{
     verificationUriComplete: z.ZodString;
     interval: z.ZodNumber;
     expiresAt: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    expiresAt: number;
-    deviceCode: string;
-    userCode: string;
-    verificationUri: string;
-    verificationUriComplete: string;
-    interval: number;
-}, {
-    expiresAt: number;
-    deviceCode: string;
-    userCode: string;
-    verificationUri: string;
-    verificationUriComplete: string;
-    interval: number;
-}>;
+}, z.core.$strip>;
 /**
  * What `/v1/auth/device/token` answers while polling. Everything past `status` is optional because
  * only an APPROVED poll carries a token, and `org.id` is absent on a cloud older than org-scoped
@@ -44,28 +30,8 @@ export declare const DevicePollSchema: z.ZodObject<{
     org: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         name: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        name: string;
-        id?: string | undefined;
-    }, {
-        name: string;
-        id?: string | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    status: string;
-    token?: string | undefined;
-    org?: {
-        name: string;
-        id?: string | undefined;
-    } | undefined;
-}, {
-    status: string;
-    token?: string | undefined;
-    org?: {
-        name: string;
-        id?: string | undefined;
-    } | undefined;
-}>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /**
  * Where a sign-in started, carried to the approval page as `from` so the platform can attribute the
  * signup. The platform's `/device` reads the same closed set (plus `app`, its own).

package/dist/command/cli/cli-doctor.js

@@ -31,6 +31,7 @@ import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
 import { describeUnsynced } from '../../memory/cloud/unsynced-roots.js';
 import { machineUnsyncedRoots } from '../../memory/project/sync-status.js';
 import { attachState, describeAttachState } from '../../surface/mcp/attach-memory.js';
+import { agentLinkText } from './doctor/doctor-agent-link.js';
 import { findOccupiedSiblings, siblingListenerNote } from './ports/sibling-ports.js';
 import { daemonsServingProjectElsewhere, resolveDaemonForProject, splitBrainNote, wrongDaemonNote, } from '../daemon/daemon-resolve.js';
 import { isAlive } from '../daemon/daemon.js';
@@ -43,8 +44,9 @@ import { hasConnectedDocument, observeWebDocument, } from '../../portal/session/
  */
 /** Narrow the `/status` payload to the two fields the daemon line reads. */
 function asIdentity(payload) {
-    if (typeof payload !== 'object' || null === payload)
+    if (typeof payload !== 'object' || null === payload) {
         return {};
+    }
     const record = payload;
     const pick = (key) => {
         const value = record[key];
@@ -99,8 +101,9 @@ export async function handleDoctor(port) {
             contract: CONTRACT_FINGERPRINT,
         });
         line(built.text);
-        if (built.skew !== undefined)
+        if (built.skew !== undefined) {
             line(doctorRow(DoctorRow.VERSION, `✗ ${built.skew}`));
+        }
         // The same payload already carries whether anything has CONNECTED, and doctor was reading
         // `version` off it and dropping the rest. Without this the command is silent on the one step the
         // funnel stalls on: wired correctly, daemon up, and no page has ever dialled in.
@@ -128,18 +131,22 @@ export async function handleDoctor(port) {
     else {
         line(doctorRow(DoctorRow.DAEMON, `✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`));
     }
-    if (sessions !== undefined)
+    if (sessions !== undefined) {
         line(sessions.text);
-    for (const row of coverageLines(daemonStatus))
+    }
+    for (const row of coverageLines(daemonStatus)) {
         line(row);
+    }
     // Runs nothing will send, named by folder with the one command that sends them.
-    for (const entry of await machineUnsyncedRoots(createNodeFileSystem(), homedir(), process.env))
+    for (const entry of await machineUnsyncedRoots(createNodeFileSystem(), homedir(), process.env)) {
         line(doctorRow(DoctorRow.UNSYNCED, `✗ ${describeUnsynced(entry, process.cwd())}`));
+    }
     line(doctorRow(DoctorRow.BRIDGE_PORT, `${port}  (your app must dial THIS port, not your dev-server port)`));
     const projectPort = readProjectPort(process.cwd());
     const mismatch = diagnosePortMismatch(port, projectPort);
-    if (mismatch !== undefined)
+    if (mismatch !== undefined) {
         line(doctorRow(DoctorRow.PORT_CHECK, `✗ ${mismatch}`));
+    }
     const projectId = readProjectId(process.cwd());
     // The hop between the agent and this daemon, stated as its own row rather than inferred from the
     // ones above it. `sessions` says the BROWSER reached the daemon; nothing said whether the AGENT
@@ -151,26 +158,23 @@ export async function handleDoctor(port) {
     // attached here" and sends the reader to re-register a server that is registered and running —
     // the confident wrong answer for a link that is not missing but misaimed.
     const split = splitBrainLine(port, projectId);
-    line(doctorRow(DoctorRow.AGENT_LINK, split !== undefined
-        ? `✗ ${split}`
-        : attachAction === undefined
-            ? // A RECORD, not a live check, and the row now says so. The attach memory is durable
-                // and per-port: once a client has attached, enumerated and called, this stays green
-                // forever. A registration pointing at a path that no longer exists produces a client
-                // that cannot start at all, and this row reported the link healthy throughout —
-                // measured, on this machine, for the two days after `packages/` was dissolved and
-                // nothing updated ~/.claude.json. `doctor` is what a stuck human runs, so a row that
-                // answers "did this ever work" while looking like "does this work" is the wrong
-                // shape here even though every word of it is true.
-                '✓ an MCP client attached here and called tools before (a record, not a live check)'
-            : `✗ ${attachAction}`));
+    // The record alone cannot answer whether the link works NOW (#1710): when the port is held
+    // but `/status` does not answer, the record below would still read healthy or blame the
+    // client, while the daemon row above already names the one fix for the held port. So in that
+    // state the agent link row only points back at the daemon row instead of repeating the
+    // record or adding a second command. No probe runs here: `/status` and `/mcp/sse` share one
+    // HTTP server, so silence on `/status` already answers the MCP question, and an SSE connect
+    // would flip agent presence on a daemon with no agents attached.
+    const foreign = presence === PortPresence.FOREIGN;
+    line(doctorRow(DoctorRow.AGENT_LINK, agentLinkText({ split, attachAction, foreign })));
     // Remaining half of #261. The SDK dialling a port we are not on is invisible as a refused inbound,
     // but a listener on a well-known Reticle port is visible. Report the observation; do not conclude
     // it is the daemon this app wants — somebody else's daemon looks the same from here.
     const occupiedSiblings = await findOccupiedSiblings(port, probeDaemon);
     const siblingNote = siblingListenerNote(port, occupiedSiblings);
-    if (siblingNote !== undefined)
+    if (siblingNote !== undefined) {
         line(doctorRow(DoctorRow.SIBLING, siblingNote));
+    }
     // The check this checklist was missing: is the APP wired, not just the tools. Everything above can
     // be green in a project that has never been through `init`, and that combination is precisely the
     // one `doctor` gets run to explain.
@@ -182,8 +186,9 @@ export async function handleDoctor(port) {
         configPresent: existsSync(join(process.cwd(), RETICLE_CONFIG_BASENAME)),
     }));
     // Are prompts reaching `.reticle/`, and is the work reaching the user's own workspace.
-    for (const row of await captureAndSyncLines(process.cwd(), process.env))
+    for (const row of await captureAndSyncLines(process.cwd(), process.env)) {
         line(row);
+    }
     // Where to LOOK when something is wrong. The daemon has always written a structured log here and
     // nothing ever said so, so the first move in every investigation was reading source instead of
     // reading the log. `RETICLE_TRACE=1` turns the same stream into a per-stage trace — see
@@ -255,8 +260,9 @@ export async function handleDoctor(port) {
         line(doctorRow(DoctorRow.DESKTOP, '✓ desktop wiring looks right'));
     }
     const keychain = keychainNoteFor({ read: readProjectFile });
-    if (keychain !== undefined)
+    if (keychain !== undefined) {
         line(doctorRow(DoctorRow.DESKTOP, `⚠ ${keychain}`));
+    }
 }
 /**
  * Two rows: does each agent hand its prompts to Reticle, and does the daemon send this
@@ -283,7 +289,8 @@ async function captureAndSyncLines(cwd, env) {
         ? 'no push yet'
         : `last push ${new Date(state.lastPushAt).toISOString()}`;
     lines.push(doctorRow(DoctorRow.SYNC, `${on ? '✓ on' : '✗ off'}: ${gate.why}; ${last}`));
-    if (state.lastError !== undefined)
+    if (state.lastError !== undefined) {
         lines.push(doctorRow(DoctorRow.SYNC, `✗ last error: ${state.lastError}`));
+    }
     return lines;
 }

package/dist/command/cli/cli-flow-commands.js

@@ -169,9 +169,13 @@ acceptCoverage = false) {
             .map(([name]) => name);
         // Only against a suite that exists: a project with no flows yet is NOTHING_TO_CHECK, and
         // demanding a flow per edited component on its first day would block every stop.
+        const flowSourcesAll = toFlowSources(allFlows);
         const unflowed = 0 === allFlows.length
             ? []
-            : unflowedFiles(toFlowSources(allFlows), changed, (file) => isInteractiveSource(readChangedFile(process.cwd(), file)));
+            : unflowedFiles(flowSourcesAll, changed, (file) => isInteractiveSource(readChangedFile(process.cwd(), file)));
+        // Flows exist but none carries a source stamp (a stack without source stamping, or flows saved before stamping was added): `unflowed`
+        // then names every changed component, which would read as "nothing drove it" when a flow did.
+        const flowsWithoutSources = allFlows.length > 0 && flowSourcesAll.every((f) => 0 === (f.sources ?? []).length);
         // The coverage ledger, when one exists: a level that fell below its best, and changed code the
         // browser loaded and never ran. A project that never folded coverage has an empty ledger and
         // neither can fire.
@@ -217,6 +221,7 @@ acceptCoverage = false) {
             ...(result.downgraded.length > 0 ? { downgraded: result.downgraded } : {}),
             ...(result.deleted.length > 0 ? { deletedCoverage: result.deleted } : {}),
             ...(result.unflowed.length > 0 ? { unflowed: result.unflowed } : {}),
+            ...(result.unflowed.length > 0 && flowsWithoutSources ? { flowsWithoutSources } : {}),
             ...(result.coverageRegressed.length > 0
                 ? { coverageRegressed: result.coverageRegressed }
                 : {}),
@@ -257,6 +262,7 @@ acceptCoverage = false) {
                     downgraded: result.downgraded.map((d) => d.flow),
                     deleted: result.deleted,
                     unflowed: result.unflowed,
+                    flowsWithoutSources,
                     coverageRegressed: result.coverageRegressed.map((r) => `${r.level} ${String(r.was)}% -> ${String(r.now)}%`),
                     unexecuted: result.unexecuted,
                     regressed: regressed?.length ?? 0,

package/dist/command/cli/cli-parse-serve.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
+ * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
+ * CI, which flips the default) because there is no display there to be headed on.
+ */
+export declare const HEADLESS_FLAG = "--headless";
+export declare const DRIVE_FLAG = "--drive";
+export declare const HTTP_FLAG = "--http";
+export declare const HTTP_PORT_FLAG = "--http-port";
+export declare const HTTP_TOKEN_FLAG = "--http-token";
+type ServeFlags = {
+    kind: 'ok';
+    port: number;
+    driveUrl?: string;
+    headless: boolean;
+    http: boolean;
+    httpPort?: number;
+    httpToken?: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+export declare function parseServeFlags(args: string[], defaultPort: number, defaultHeadless: boolean): ServeFlags;
+export {};

package/dist/command/cli/cli-parse-serve.js

@@ -0,0 +1,124 @@
+/**
+ * The serve / mcp / `_daemon` flag grammar, including the verify HTTP endpoint.
+ *
+ * Split out of `cli-parse.ts` when that file crossed the line cap. These three commands share one
+ * flag set: the bridge port, a drive URL, headless, and the verify endpoint `--http` starts.
+ */
+import { HEADED_FLAG, PORT_FLAG, missingValue, notANumber, unknownArgument, } from './cli-parse-grammar.js';
+/**
+ * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
+ * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
+ * CI, which flips the default) because there is no display there to be headed on.
+ */
+export const HEADLESS_FLAG = '--headless';
+export const DRIVE_FLAG = '--drive';
+export const HTTP_FLAG = '--http';
+export const HTTP_PORT_FLAG = '--http-port';
+export const HTTP_TOKEN_FLAG = '--http-token';
+const requiresHttp = (flag) => ({
+    kind: 'error',
+    message: `${flag} requires ${HTTP_FLAG} — it configures the verify endpoint ${HTTP_FLAG} starts`,
+});
+/**
+ * The verify endpoint cannot use the bridge port.
+ *
+ * `reticle serve --http --http-port 4400` reached `listen` and died with a raw
+ * `EADDRINUSE 127.0.0.1:4400`. That number is this daemon's bridge port, and MCP is already
+ * served there. Name both ports and stop before anything listens (#1786).
+ */
+const httpPortIsBridge = (httpPort, bridgePort) => ({
+    kind: 'error',
+    message: `${HTTP_PORT_FLAG} ${String(httpPort)} is the bridge port ${String(bridgePort)}. ` +
+        'Pick another port. MCP is already served on the bridge port.',
+});
+export function parseServeFlags(args, defaultPort, defaultHeadless) {
+    let port = defaultPort;
+    let driveUrl;
+    let headless = defaultHeadless;
+    let http = false;
+    let httpPort;
+    let httpToken;
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        // `i < args.length` already guarantees this, but the index signature does not say so and the
+        // unknown-argument error needs a real string to name.
+        if (arg === undefined) {
+            break;
+        }
+        if (arg === PORT_FLAG) {
+            i++;
+            const n = args[i];
+            if (n === undefined) {
+                return missingValue(PORT_FLAG);
+            }
+            const parsed = parseInt(n, 10);
+            if (isNaN(parsed)) {
+                return notANumber(PORT_FLAG, n);
+            }
+            port = parsed;
+        }
+        else if (arg === DRIVE_FLAG) {
+            i++;
+            driveUrl = args[i];
+            if (driveUrl === undefined) {
+                return missingValue(DRIVE_FLAG);
+            }
+        }
+        else if (arg === HEADED_FLAG) {
+            headless = false;
+        }
+        else if (arg === HEADLESS_FLAG) {
+            headless = true;
+        }
+        else if (arg === HTTP_FLAG) {
+            http = true;
+        }
+        else if (arg === HTTP_PORT_FLAG) {
+            i++;
+            const n = args[i];
+            if (n === undefined) {
+                return missingValue(HTTP_PORT_FLAG);
+            }
+            const parsed = parseInt(n, 10);
+            if (isNaN(parsed)) {
+                return notANumber(HTTP_PORT_FLAG, n);
+            }
+            httpPort = parsed;
+        }
+        else if (arg === HTTP_TOKEN_FLAG) {
+            i++;
+            httpToken = args[i];
+            if (httpToken === undefined) {
+                return missingValue(HTTP_TOKEN_FLAG);
+            }
+        }
+        else {
+            return unknownArgument(arg);
+        }
+        i++;
+    }
+    // Without `--http` these flags configure an endpoint nothing starts, and they were accepted and
+    // silently ignored — worse than being rejected, because the whole reason to pass them is to be
+    // honoured (#687).
+    if (!http && httpPort !== undefined) {
+        return requiresHttp(HTTP_PORT_FLAG);
+    }
+    if (!http && httpToken !== undefined) {
+        return requiresHttp(HTTP_TOKEN_FLAG);
+    }
+    // `port` is the bridge port this command will bind. The caller passes the resolved default
+    // (RETICLE_PORT, the project port, this project's daemon, or 4400). `--port` replaces it.
+    if (httpPort !== undefined && httpPort === port) {
+        return httpPortIsBridge(httpPort, port);
+    }
+    return {
+        kind: 'ok',
+        port,
+        headless,
+        http,
+        ...(driveUrl !== undefined ? { driveUrl } : {}),
+        ...(httpPort !== undefined ? { httpPort } : {}),
+        ...(httpToken !== undefined ? { httpToken } : {}),
+    };
+}

package/dist/command/cli/cli-parse.d.ts

@@ -6,6 +6,7 @@
 import { type ParsedFeedback } from './cli-parse-feedback.js';
 import { HEADED_FLAG, PORT_FLAG } from './cli-parse-grammar.js';
 export { HEADED_FLAG, PORT_FLAG };
+export { DRIVE_FLAG, HEADLESS_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, } from './cli-parse-serve.js';
 export { AGENT_FLAG, BUG_FLAG, CONTACT_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from './cli-parse-feedback.js';
 import { CLI_USAGE } from './cli-usage.js';
 export { CLI_USAGE };
@@ -38,16 +39,6 @@ export declare const PROBE_COMMANDS: ReadonlySet<string>;
 export declare const LOCAL_COMMANDS: readonly string[];
 /** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
 export declare function knownCommand(arg: string | undefined): string;
-/**
- * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
- * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
- * CI, which flips the default) because there is no display there to be headed on.
- */
-export declare const HEADLESS_FLAG = "--headless";
-export declare const DRIVE_FLAG = "--drive";
-export declare const HTTP_FLAG = "--http";
-export declare const HTTP_PORT_FLAG = "--http-port";
-export declare const HTTP_TOKEN_FLAG = "--http-token";
 /**
  * A predicate for a flow-free, one-shot verdict against the daemon that is already running.
  *