@reticlehq/server 3.3.0 → 3.4.0

package/dist/memory/intent/intent-shard.d.ts

@@ -21,7 +21,6 @@
  */
 import { z } from 'zod';
 import { type Intent } from '@reticlehq/core/artifacts';
-import type { FileSystemPort } from '../project/fs/fs-port.js';
 /**
  * How settled a record is.
  *
@@ -52,12 +51,12 @@ declare const IntentRecordSchema: z.ZodObject<{
         flow: z.ZodOptional<z.ZodString>;
         files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
-        flow?: string | undefined;
         route?: string | undefined;
+        flow?: string | undefined;
         files?: string[] | undefined;
     }, {
-        flow?: string | undefined;
         route?: string | undefined;
+        flow?: string | undefined;
         files?: string[] | undefined;
     }>>;
     provenBy: z.ZodOptional<z.ZodObject<{
@@ -101,8 +100,8 @@ declare const IntentRecordSchema: z.ZodObject<{
     statement: string;
     declaredAt: number;
     surface?: {
-        flow?: string | undefined;
         route?: string | undefined;
+        flow?: string | undefined;
         files?: string[] | undefined;
     } | undefined;
     source?: string | undefined;
@@ -126,8 +125,8 @@ declare const IntentRecordSchema: z.ZodObject<{
     statement: string;
     declaredAt: number;
     surface?: {
-        flow?: string | undefined;
         route?: string | undefined;
+        flow?: string | undefined;
         files?: string[] | undefined;
     } | undefined;
     source?: string | undefined;
@@ -159,12 +158,12 @@ export declare const IntentShardSchema: z.ZodObject<{
             flow: z.ZodOptional<z.ZodString>;
             files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         }, "strip", z.ZodTypeAny, {
-            flow?: string | undefined;
             route?: string | undefined;
+            flow?: string | undefined;
             files?: string[] | undefined;
         }, {
-            flow?: string | undefined;
             route?: string | undefined;
+            flow?: string | undefined;
             files?: string[] | undefined;
         }>>;
         provenBy: z.ZodOptional<z.ZodObject<{
@@ -208,8 +207,8 @@ export declare const IntentShardSchema: z.ZodObject<{
         statement: string;
         declaredAt: number;
         surface?: {
-            flow?: string | undefined;
             route?: string | undefined;
+            flow?: string | undefined;
             files?: string[] | undefined;
         } | undefined;
         source?: string | undefined;
@@ -233,8 +232,8 @@ export declare const IntentShardSchema: z.ZodObject<{
         statement: string;
         declaredAt: number;
         surface?: {
-            flow?: string | undefined;
             route?: string | undefined;
+            flow?: string | undefined;
             files?: string[] | undefined;
         } | undefined;
         source?: string | undefined;
@@ -262,8 +261,8 @@ export declare const IntentShardSchema: z.ZodObject<{
         statement: string;
         declaredAt: number;
         surface?: {
-            flow?: string | undefined;
             route?: string | undefined;
+            flow?: string | undefined;
             files?: string[] | undefined;
         } | undefined;
         source?: string | undefined;
@@ -291,8 +290,8 @@ export declare const IntentShardSchema: z.ZodObject<{
         statement: string;
         declaredAt: number;
         surface?: {
-            flow?: string | undefined;
             route?: string | undefined;
+            flow?: string | undefined;
             files?: string[] | undefined;
         } | undefined;
         source?: string | undefined;
@@ -311,24 +310,6 @@ export declare const IntentShardSchema: z.ZodObject<{
     }>;
 }>;
 export type IntentShard = z.infer<typeof IntentShardSchema>;
-/** One line per intent: enough to decide whether to open the shard, and no more. */
-declare const IntentIndexEntrySchema: z.ZodObject<{
-    id: z.ZodString;
-    subject: z.ZodString;
-    statement: z.ZodString;
-    status: z.ZodEnum<["proposed", "agreed", "proved", "stale"]>;
-}, "strip", z.ZodTypeAny, {
-    status: "proved" | "proposed" | "agreed" | "stale";
-    id: string;
-    subject: string;
-    statement: string;
-}, {
-    status: "proved" | "proposed" | "agreed" | "stale";
-    id: string;
-    subject: string;
-    statement: string;
-}>;
-export type IntentIndexEntry = z.infer<typeof IntentIndexEntrySchema>;
 export declare const IntentIndexSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     entries: z.ZodArray<z.ZodObject<{
@@ -366,7 +347,6 @@ export declare const IntentIndexSchema: z.ZodObject<{
 }>;
 export type IntentIndex = z.infer<typeof IntentIndexSchema>;
 export declare const emptyShard: (subject: string) => IntentShard;
-export declare const emptyIndex: () => IntentIndex;
 /** The verification lifecycle a legacy record carried, mapped onto the settledness axis. */
 export declare const statusFromState: (state: Intent["state"]) => IntentStatus;
 /**
@@ -383,6 +363,4 @@ export declare const indexFrom: (shards: readonly IntentShard[]) => IntentIndex;
 export declare const shardsFrom: (records: readonly IntentRecord[]) => IntentShard[];
 /** Serialise byte-stably, with keys sorted so a re-save of unchanged data is a no-op diff. */
 export declare const serialise: (value: unknown) => string;
-/** Read + validate one JSON file, failing soft: a hand-merged file with a conflict marker is real. */
-export declare const readJsonFile: <T>(fs: FileSystemPort, path: string, parse: (raw: unknown) => T, fallback: T) => Promise<T>;
 export {};

package/dist/memory/intent/intent-shard.js

@@ -96,7 +96,6 @@ export const emptyShard = (subject) => ({
     subject,
     intents: {},
 });
-export const emptyIndex = () => ({ version: INTENT_SHARD_VERSION, entries: [] });
 /** The verification lifecycle a legacy record carried, mapped onto the settledness axis. */
 export const statusFromState = (state) => 'proved' === state ? IntentStatus.PROVED : IntentStatus.AGREED;
 /**
@@ -142,12 +141,3 @@ const sortKeys = (value) => {
         return value;
     return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
 };
-/** Read + validate one JSON file, failing soft: a hand-merged file with a conflict marker is real. */
-export const readJsonFile = async (fs, path, parse, fallback) => {
-    try {
-        return parse(JSON.parse(await fs.readFile(path)));
-    }
-    catch {
-        return fallback;
-    }
-};

package/dist/memory/journal/drive-flow.d.ts

@@ -1,4 +1,4 @@
-import type { FlowName, Predicate } from '@reticlehq/core';
+import type { FlowFile, FlowName, Predicate } from '@reticlehq/core';
 /**
  * What this module needs a recorded step to BE, named structurally rather than imported.
  *
@@ -15,6 +15,10 @@ export interface TapeStep {
     expect?: Predicate;
     /** Recorder-internal, and the field journeys are cut on. Never written to the saved flow. */
     route?: string;
+    page?: string;
+    endPage?: string;
+    /** The intent the agent declared on this action. The first one names the journey. */
+    intent?: string;
 }
 /** The compiled shape a flow store accepts. Structural, for the same reason as `TapeStep`. */
 export interface DriveProgram {
@@ -22,6 +26,7 @@ export interface DriveProgram {
     version: number;
     steps: TapeStep[];
     startPath?: string;
+    author?: FlowFile['author'];
 }
 /**
  * What a session drove, saved as a replayable flow — without anybody asking for it.
@@ -36,21 +41,21 @@ export interface DriveProgram {
  */
 /** The one condition on saving, and the reason the whole thing is safe. */
 export declare function carriesAnAssertion(steps: readonly TapeStep[]): boolean;
+/** Every auto-saved flow's name starts here, which is what lets a merge tell them from hand-named ones. */
+export declare const DRIVE_FLOW_PREFIX = "drive-";
 /**
- * A stable name for what this session drove — led by what it proved.
+ * A readable name for a journey, led by WHY it was driven.
  *
- * Two properties, and the name used to have only the second. It has to be STABLE: teardown fires on
- * every socket close and a reconnecting tab keeps its id, so a name that moves leaves one journey
- * scattered across several files, each a partial copy of the others. And it has to be READABLE,
- * because `presenter-controls.ts` renders it straight into the replay button's `textContent` — so
- * the label a person actually sees was `drive-sdc991872-6d66-4adf-8780-f931c62905f9`, twice, for two
- * different journeys. A session id is a fact about the socket, not about the feature.
+ * The agent's own `intent` on the action is the best name there is — it is the sentence a person
+ * would use — so it leads when one was declared. Without one, what the journey proved names it (the
+ * strongest claim first), and the route follows so two journeys stay apart.
  *
- * So the claim leads, the route follows, and a SHORT session discriminator trails: two sessions that
- * prove the same thing on the same route stay separate files rather than overwriting each other,
- * which is the one thing the full id was buying that the claim cannot.
+ * No session id. It used to trail every name so two sessions never overwrote each other, which also
+ * made every session's drive of the same journey its own file. Two DIFFERENT journeys that land on
+ * one name are now told apart at save by their shape, and two copies of the SAME journey merge —
+ * see FlowStore.saveJourney.
  */
-export declare function driveFlowName(sessionId: string, route?: string, steps?: readonly TapeStep[]): FlowName;
+export declare function driveFlowName(route?: string, steps?: readonly TapeStep[]): FlowName;
 export interface DriveFlowOutcome {
     /** The flows that were written — one per journey the session contained. */
     readonly saved?: readonly string[];
@@ -65,7 +70,7 @@ export interface DriveFlowOutcome {
     readonly unprovenSteps?: number;
 }
 /** A flow per journey, so two journeys in one session are two regression tests rather than one. */
-export declare function driveFlowsFrom(sessionId: string, tape: {
+export declare function driveFlowsFrom(tape: {
     steps: readonly TapeStep[];
     startPath?: string;
 } | undefined): {

package/dist/memory/journal/drive-flow.js

@@ -1,4 +1,4 @@
-import { PredicateKind, REPLAY_PROGRAM_VERSION, asFlowName } from '@reticlehq/core';
+import { ActionType, PredicateKind, QueryBy, REPLAY_PROGRAM_VERSION, asFlowName, defaultIsSensitiveKey, } from '@reticlehq/core';
 import { clauseOfKind } from '@reticlehq/core';
 /**
  * What a session drove, saved as a replayable flow — without anybody asking for it.
@@ -30,7 +30,7 @@ const segment = (value, max) => value
  * DOM-shaped claims are the weakest. Naming a flow after the strongest thing it proves is the same
  * judgement the honesty grade makes, reused where a human reads it.
  *
- * Returns '' when a step claims nothing nameable, and the caller keeps the old session-only name.
+ * Returns '' when a step claims nothing nameable.
  */
 function provedSlug(steps) {
     for (const step of steps) {
@@ -63,42 +63,29 @@ function provedSlug(steps) {
     }
     return '';
 }
+/** Every auto-saved flow's name starts here, which is what lets a merge tell them from hand-named ones. */
+export const DRIVE_FLOW_PREFIX = 'drive-';
 /**
- * A stable name for what this session drove — led by what it proved.
+ * A readable name for a journey, led by WHY it was driven.
  *
- * Two properties, and the name used to have only the second. It has to be STABLE: teardown fires on
- * every socket close and a reconnecting tab keeps its id, so a name that moves leaves one journey
- * scattered across several files, each a partial copy of the others. And it has to be READABLE,
- * because `presenter-controls.ts` renders it straight into the replay button's `textContent` — so
- * the label a person actually sees was `drive-sdc991872-6d66-4adf-8780-f931c62905f9`, twice, for two
- * different journeys. A session id is a fact about the socket, not about the feature.
+ * The agent's own `intent` on the action is the best name there is — it is the sentence a person
+ * would use — so it leads when one was declared. Without one, what the journey proved names it (the
+ * strongest claim first), and the route follows so two journeys stay apart.
  *
- * So the claim leads, the route follows, and a SHORT session discriminator trails: two sessions that
- * prove the same thing on the same route stay separate files rather than overwriting each other,
- * which is the one thing the full id was buying that the claim cannot.
+ * No session id. It used to trail every name so two sessions never overwrote each other, which also
+ * made every session's drive of the same journey its own file. Two DIFFERENT journeys that land on
+ * one name are now told apart at save by their shape, and two copies of the SAME journey merge —
+ * see FlowStore.saveJourney.
  */
-export function driveFlowName(sessionId, route, steps = []) {
-    const safe = sessionId.replace(/[^a-zA-Z0-9-]/g, '-').slice(0, 40);
-    const proved = provedSlug(steps);
-    // The route is part of the name, so two journeys in one session do not overwrite each other —
-    // and so a re-drive of the same journey rewrites its own flow rather than adding a near-duplicate.
-    const leg = (route ?? '')
-        .replace(/[^a-zA-Z0-9]+/g, '-')
-        .replace(/^-|-$/g, '')
-        .slice(0, 24);
-    // Minted here, not at the call site. This function is where a drive's flow name comes into
-    // existence, and every character it can emit has just been forced through the safe-segment
-    // replacements above — so this IS the validated boundary the brand is meant to be created at.
-    // Returning `string` pushed a cast onto each caller, which is the hole `flowPath`'s parameter
-    // type was added to close.
-    // Nothing nameable was proved, so keep the name this function has always produced.
-    if ('' === proved) {
-        return asFlowName(0 === leg.length ? `drive-${safe}` : `drive-${safe}-${leg}`);
-    }
-    // Enough of the session to keep two of them apart, and little enough to read past.
-    const discriminator = safe.replace(/-/g, '').slice(0, 8);
-    const parts = ['drive', proved, ...(0 === leg.length ? [] : [leg]), discriminator];
-    return asFlowName(parts.join('-'));
+export function driveFlowName(route, steps = []) {
+    const intent = steps.find((step) => step.intent !== undefined)?.intent;
+    const leg = segment(route ?? '', 24);
+    const why = intent === undefined ? '' : segment(intent, 48);
+    const lead = '' !== why ? why : provedSlug(steps);
+    // Minted here: every character has just been forced through `segment`, so this IS the validated
+    // boundary the brand is meant to be created at.
+    const parts = [lead, ...('' !== why || 0 === leg.length ? [] : [leg])].filter((p) => '' !== p);
+    return asFlowName(`${DRIVE_FLOW_PREFIX}${0 === parts.length ? 'journey' : parts.join('-')}`);
 }
 /**
  * Turn this session's ambient tape into a flow, when it is worth one.
@@ -125,18 +112,39 @@ export function driveFlowName(sessionId, route, steps = []) {
  */
 function segmentsByRoute(steps) {
     const out = [];
+    let signedIn = false;
     for (const step of steps) {
         const last = out.at(-1);
-        if (last !== undefined && last.route === step.route) {
+        const previous = last?.steps.at(-1);
+        // The same journey when the route is unchanged, or when the previous ACTION moved the app here
+        // — cart → shipping → payment is one flow, and cutting it left three fragments that each
+        // proved a page and none proved the journey. Not after a sign-in: that is the cut this exists
+        // for, and a login that navigates onward must still not open the next flow.
+        const caused = previous !== undefined && step.route !== undefined && previous.endPage === step.route;
+        if (last !== undefined && (last.route === step.route || (caused && !signedIn))) {
             last.steps.push(step);
+            signedIn ||= typesASecret(step);
             continue;
         }
+        signedIn = typesASecret(step);
         out.push({ ...(step.route === undefined ? {} : { route: step.route }), steps: [step] });
     }
     return out;
 }
+/**
+ * A fill into a field the network channel would redact — the sign-in a journey must not carry.
+ * Read off the recorder's anchor args: a testid names the field by `value`, a role by `name`.
+ */
+function typesASecret(step) {
+    const action = step.args['action'];
+    if (ActionType.FILL !== action && ActionType.TYPE !== action)
+        return false;
+    const by = step.args['by'];
+    const field = QueryBy.TESTID === by ? step.args['value'] : step.args['name'];
+    return 'string' === typeof field && defaultIsSensitiveKey(field);
+}
 /** A flow per journey, so two journeys in one session are two regression tests rather than one. */
-export function driveFlowsFrom(sessionId, tape) {
+export function driveFlowsFrom(tape) {
     if (tape === undefined || 0 === tape.steps.length)
         return { programs: [], outcome: {} };
     const programs = [];
@@ -148,7 +156,7 @@ export function driveFlowsFrom(sessionId, tape) {
         }
         const startPath = segment.route ?? tape.startPath;
         programs.push({
-            name: driveFlowName(sessionId, startPath, segment.steps),
+            name: driveFlowName(startPath, segment.steps),
             version: REPLAY_PROGRAM_VERSION,
             // The route is recorder-internal and has no business on disk — `startPath` is where the
             // on-disk flow says the same thing, in the field replay actually reads.

package/dist/memory/journal/on-disk/workspace-tiers.js

@@ -49,6 +49,8 @@ export const WORKSPACE_TIERS = {
     [ReticleDir.AMBIENT_FILE]: localFile,
     [ReticleDir.ENVELOPES_FILE]: localFile,
     [ReticleDir.FLAKE_FILE]: localFile,
+    // What THIS machine's drives covered, and the best each level reached — the gate's ratchet.
+    [ReticleDir.COVERAGE_FILE]: localFile,
     [ReticleDir.TIERS_FILE]: localFile,
     // The user's own record of what Reticle did for them, on THIS machine.
     [ReticleDir.IMPACT_FILE]: localFile,

package/dist/memory/journal/session-end.d.ts

@@ -79,8 +79,16 @@ interface SessionEndDeps {
      * this handler follows.
      */
     flows?: {
-        save: (program: DriveProgram, annotations?: undefined, projectId?: ProjectId) => Promise<unknown>;
+        saveJourney: (program: DriveProgram, projectId: ProjectId | undefined, prefix: string) => Promise<unknown>;
     };
+    /**
+     * The flow store for a session's own `.reticle`. Drive flows used to go to `flows` above — the
+     * daemon's launch directory — while replay reads the session's project, so a daemon started
+     * anywhere else saved flows nothing could replay. Absent, `flows` is used.
+     */
+    flowsAt?: (root: string) => NonNullable<SessionEndDeps['flows']>;
+    /** Who is driving — stamped on each saved flow. Injected: teardown does not reach into MCP. */
+    author?: () => DriveProgram['author'];
     /**
      * Called when a run artifact is written, so cloud sync can cycle instead of waiting for its timer.
      *

package/dist/memory/journal/session-end.js

@@ -1,4 +1,11 @@
-import { driveFlowsFrom } from './drive-flow.js';
+import { DRIVE_FLOW_PREFIX, driveFlowsFrom, } from './drive-flow.js';
+import { log } from '../../log.js';
+/** What a session's teardown writes to the daemon log when a by-product fails to save. */
+const SESSION_END_LOG = {
+    FLOW_SAVE_FAILED: 'reticle_drive_flow_save_failed',
+    RUN_RECORD_FAILED: 'reticle_drive_run_record_failed',
+};
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 import { journalActionsPath, sessionDirPath } from '../project/dir/reticle-dir.js';
 import { asSessionId } from '@reticlehq/core';
 import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
@@ -78,24 +85,27 @@ export function makeSessionEnd(deps) {
         // would buy under a minute of latency for a mutable handle held across two wiring sites.
         // A DRIVE IS A REGRESSION TEST, and it used to need somebody to remember to say so.
         //
-        // `record{start}` + `flow_save` is the agent-facing route and agents do not take it: the corpus
-        // measures 3 of 33 flows mutation-testable and 6 of 112 steps declaring a consequence, while the
-        // engine catches 84 of the 86 bugs it structurally can. The ceiling is how many flows EXIST that
-        // could go red, so a drive that is never saved is a regression test paid for and thrown away.
+        // `record{start}` + `flow_save` is the agent-facing route and agents do not take it: few saved
+        // flows are mutation-testable and few steps declare a consequence, while the engine catches
+        // nearly every bug it structurally can. The ceiling is how many flows EXIST that could go red,
+        // so a drive that is never saved is a regression test paid for and thrown away.
         //
         // Saved only when the tape declared a consequence — see drive-flow.ts for why the alternative is
         // a false-green factory running once per session.
         try {
             await saveDrivenFlow(deps, session);
         }
-        catch {
-            // a flow is a by-product of the session; failing to write one never fails the teardown
+        catch (error) {
+            // A flow is a by-product of the session; failing to write one never fails the teardown. It is
+            // logged, because a drive that leaves no flow and no reason is otherwise undiagnosable.
+            log(SESSION_END_LOG.FLOW_SAVE_FAILED, { error: errorMessage(error) });
         }
         try {
             await recordDriveRun(deps, session);
         }
-        catch {
-            // an artifact is a report ABOUT the session; failing to write one never fails the teardown
+        catch (error) {
+            // An artifact is a report ABOUT the session; failing to write one never fails the teardown.
+            log(SESSION_END_LOG.RUN_RECORD_FAILED, { error: errorMessage(error) });
         }
         try {
             // Bound the journal on disk HERE, not only at daemon start.
@@ -196,13 +206,15 @@ export async function recordDriveRun(deps, session) {
 /** Persist what this session drove as a replayable flow, when it declared anything provable. */
 async function saveDrivenFlow(deps, session) {
     const takeTape = deps.takeAmbientTape;
-    const flows = deps.flows;
+    const flows = deps.flowsAt?.(session.artifactRoot ?? deps.reticleRoot) ?? deps.flows;
     if (takeTape === undefined || flows === undefined)
         return;
     // One flow per journey the session contained, not one flow per session — see drive-flow.ts.
-    const { programs, outcome } = driveFlowsFrom(session.id, takeTape());
+    const { programs, outcome } = driveFlowsFrom(takeTape());
+    const author = deps.author?.();
     for (const program of programs) {
-        await flows.save(program, undefined, session.projectId);
+        // Folded into any saved copy of the same journey, so each session does not add a near-copy.
+        await flows.saveJourney(author === undefined ? program : { ...program, author }, session.projectId, DRIVE_FLOW_PREFIX);
     }
     // The funnel step that makes the SECOND run cheap.
     //

package/dist/memory/project/dir/reticle-dir.d.ts

@@ -33,6 +33,8 @@ export interface ReticleDirPaths {
     capsules: string;
     /**.../.reticle/flake.json (per-flow flake ledger) */
     flake: string;
+    /**.../.reticle/coverage.json (app-wide coverage ledger, all six levels) */
+    coverage: string;
     /**.../.reticle/assertion-tiers.json (last-passing assertion tiers; anti-reward-hacking baseline) */
     tiers: string;
 }

package/dist/memory/project/dir/reticle-dir.js

@@ -18,6 +18,7 @@ export function reticleDirPaths(root) {
         ambient: join(root, ReticleDir.AMBIENT_FILE),
         capsules: join(root, ReticleDir.CAPSULES_SUBDIR),
         flake: join(root, ReticleDir.FLAKE_FILE),
+        coverage: join(root, ReticleDir.COVERAGE_FILE),
         tiers: join(root, ReticleDir.TIERS_FILE),
     };
 }

package/dist/memory/project/project-tools.js

@@ -38,7 +38,9 @@ function numericDelta(before, after) {
  * "what's broken vs before" from the cloud. Absent creds / unreachable → undefined (agent stays local).
  */
 async function cloudRegression(deps, sessionId) {
-    const config = resolveCloudConfig(process.env);
+    // The same resolver every caller uses (stored key for a linked repo, else the exported one);
+    // the environment alone only for an embedder that wires no linked-credential port.
+    const config = await (deps.linkedCloud?.() ?? Promise.resolve(resolveCloudConfig(process.env)));
     if (null === config)
         return undefined;
     let projectId;

package/dist/portal/bridge/auth-failure-reason.d.ts

@@ -4,7 +4,7 @@
  * A daemon left running by one project answers the next project's app and rejects it on token, and
  * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
  * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
- * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
+ * need opposite fixes: "your token is wrong" versus "that daemon is not yours, use your own port".
  *
  * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
  * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those

package/dist/portal/bridge/auth-failure-reason.js

@@ -4,7 +4,7 @@
  * A daemon left running by one project answers the next project's app and rejects it on token, and
  * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
  * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
- * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
+ * need opposite fixes: "your token is wrong" versus "that daemon is not yours, use your own port".
  *
  * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
  * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those
@@ -62,7 +62,9 @@ export function authFailureReason(servedProjects, helloProject, helloToken) {
     if (helloProject !== undefined &&
         1 === servedProjects.size &&
         !servedProjects.has(helloProject)) {
-        const reason = `${DIFFERENT_PROJECT_PREFIX} — run \`reticle stop\` and retry`;
+        // Not "stop it": that daemon is serving somebody else's app. This project needs its own port,
+        // which the CLI and the build plugins both read from `.reticle.json`.
+        const reason = `${DIFFERENT_PROJECT_PREFIX} — set a free "port" in .reticle.json, then restart the dev server`;
         return Buffer.byteLength(reason, 'utf8') <= MAX_REASON_BYTES ? reason : PLAIN;
     }
     if (helloToken === undefined || 0 === helloToken.length)

package/dist/portal/bridge/bridge.d.ts

@@ -38,6 +38,14 @@ export declare const WS_CLOSE_REASON: {
      * refusal on this path: nothing about the app is wrong and retrying is the correct response.
      */
     readonly HANDSHAKE_POOL_FULL: string;
+    /**
+     * A page's HELLO failed the wire schema for a reason other than its protocol number — the SDK and
+     * this daemon are different releases whose contracts no longer agree. The socket is still closed
+     * with the short `invalid message` the SDK already prints; this is the sentence the no-session
+     * diagnosis records, because "never dialled the bridge" was what `init` said about a page this
+     * daemon had just turned away. Same `cause — fix` shape as the protocol-skew reasons.
+     */
+    readonly INVALID_HELLO: string;
 };
 interface BridgeOptions {
     port: number;

package/dist/portal/bridge/bridge.js

@@ -69,6 +69,16 @@ export const WS_CLOSE_REASON = {
         'this dial never got to identify itself. Nothing is wrong with the app; the pool drains on its ' +
         'own and reloading the page reconnects. If it persists, something else on this machine is ' +
         'opening sockets to this port.',
+    /**
+     * A page's HELLO failed the wire schema for a reason other than its protocol number — the SDK and
+     * this daemon are different releases whose contracts no longer agree. The socket is still closed
+     * with the short `invalid message` the SDK already prints; this is the sentence the no-session
+     * diagnosis records, because "never dialled the bridge" was what `init` said about a page this
+     * daemon had just turned away. Same `cause — fix` shape as the protocol-skew reasons.
+     */
+    INVALID_HELLO: "invalid message: the page's hello does not match this daemon's wire contract — put " +
+        '@reticlehq/browser, the build plugin and @reticlehq/server on one release, run `reticle stop`, ' +
+        'then restart the dev server',
 };
 /**
  * A dial turned away at the ORIGIN gate, in words the reader can act on.
@@ -179,6 +189,25 @@ function helloProtocolMismatch(text) {
     }
     return null;
 }
+/**
+ * What a HELLO says about the page it came from, read loosely enough to survive the schema failing.
+ * Null when the message is not a hello at all — only an SDK sends one, so only then is a refusal
+ * evidence about an app.
+ */
+function peekHelloPage(text) {
+    try {
+        const json = JSON.parse(text);
+        if (json.kind !== MessageKind.HELLO)
+            return null;
+        return {
+            ...('string' === typeof json.url ? { url: json.url } : {}),
+            ...('string' === typeof json.projectId ? { projectId: json.projectId } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
 /** Normalize ws RawData (string | Buffer | Buffer[] | ArrayBuffer) into a UTF-8 string. */
 function rawToString(raw) {
     if ('string' === typeof raw)
@@ -436,10 +465,19 @@ export class Bridge {
                         // Told to the AGENT too, not only to the SDK that is about to stop retrying. Without this
                         // the next tool call answers "no browser session connected", which reads as "no app is
                         // running" — so an SDK too old to connect is invisible.
-                        this.sessions.noteClosure(reason, this.#clock());
+                        this.sessions.noteClosure(reason, this.#clock(), peekHelloPage(text) ?? {});
                         socket.close(WS_CLOSE.PROTOCOL_MISMATCH[0], reason);
                         return;
                     }
+                    // Recorded only for a HELLO on a socket that has none yet: that is a page being turned
+                    // away, and it used to leave no trace, so `init` reported "never dialled the bridge" about
+                    // a page this daemon had just refused. A malformed frame on a live session is a different
+                    // failure and says nothing about whether the app can connect.
+                    const refused = undefined === session ? peekHelloPage(text) : null;
+                    if (null !== refused) {
+                        log('hello_invalid', { ...refused });
+                        this.sessions.noteClosure(WS_CLOSE_REASON.INVALID_HELLO, this.#clock(), refused);
+                    }
                     socket.close(...WS_CLOSE.INVALID_MESSAGE);
                     return;
                 }
@@ -498,7 +536,10 @@ export class Bridge {
                             presented: parsed.token !== undefined && 0 < parsed.token.length,
                             tokenSource: this.#tokenSource,
                         });
-                        this.sessions.noteClosure(reason, this.#clock());
+                        this.sessions.noteClosure(reason, this.#clock(), {
+                            url: parsed.url,
+                            ...(parsed.projectId === undefined ? {} : { projectId: parsed.projectId }),
+                        });
                         socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
                         return;
                     }

package/dist/portal/input/js-coverage.d.ts

@@ -0,0 +1,25 @@
+import type { Page } from 'playwright';
+/**
+ * V8 JS coverage on a page Reticle drives — the raw half of "what of the app ever ran".
+ *
+ * Started once per page with `resetOnNavigation: false`, so a reload keeps counting instead of
+ * starting over. A take stops and immediately restarts: the counts it returns are since the last
+ * take, and the reader folds them as a union (see features/exhaust/code-coverage.ts).
+ *
+ * Chromium only. Anything else — or a page that closed — answers false/undefined rather than
+ * throwing: coverage is an addition to a drive, never a reason for one to fail.
+ */
+/** One script's coverage — the shape `stopJSCoverage` returns, narrowed to what is read. */
+export interface ScriptCoverage {
+    url: string;
+    functions: {
+        functionName: string;
+        ranges: {
+            startOffset: number;
+            endOffset: number;
+            count: number;
+        }[];
+    }[];
+}
+export declare function startJsCoverage(page: Page, covering: WeakSet<Page>): Promise<boolean>;
+export declare function takeJsCoverage(page: Page, covering: WeakSet<Page>): Promise<ScriptCoverage[] | undefined>;