@reticlehq/server 2.7.0 → 2.9.0

package/dist/mcp/server-instructions.d.ts

@@ -0,0 +1,17 @@
+export interface InstructionState {
+    /**
+     * Has an app ever connected to Reticle for this project, on this port?
+     *
+     * Read from the durable connection memory rather than from the live session list: a daemon four
+     * seconds old has no sessions and that says nothing about whether the app is wired. The question
+     * is whether this install has EVER worked, not whether it is working this second.
+     */
+    previouslyConnected: boolean;
+}
+/** The instructions this daemon should advertise, given what it knows about the project. */
+/**
+ * Instructions are sent ONCE at initialize; the tool surface is re-sent every turn. Measured on this
+ * server: 621 tokens here against 5,480 per turn there, so anything true of every tool belongs in
+ * this block rather than repeated across sixteen parameter descriptions. See shared-params.ts.
+ */
+export declare function buildServerInstructions(state: InstructionState): string;

package/dist/mcp/server-instructions.js

@@ -0,0 +1,56 @@
+import { SHARED_PARAM_GUIDANCE } from './shared-params.js';
+/**
+ * What every connected agent is told, before it has asked anything.
+ *
+ * The MCP `instructions` string lands in the agent's context at the handshake — no skill file, no
+ * restart, no action from the user. For an agent that arrived through a plugin listing or a pasted
+ * config block rather than through the skill, it is the ONLY thing Reticle ever says unprompted.
+ *
+ * It used to open on tool grammar. That is the right thing to say to an agent that has an app to
+ * point the tools at, and the wrong thing to say to one that does not — and in the field the
+ * overwhelming majority of daemons never see an app connect, never run a command and never call a
+ * tool. Those sessions are not agents failing a hard step. They are agents that were never asked to
+ * take an easy one: the MCP server registers itself in a single line of config, so a user reaches
+ * "the tools are here" without ever reaching "the app is wired", and nothing in that state reads as
+ * unfinished. Registering the server is the cheapest part of the product and it is the only part
+ * many installs ever complete.
+ *
+ * So the lead is state-dependent. A project that has never had an app connect is told the one thing
+ * it needs; a project that has is not nagged about a step it already took. The verdict discipline
+ * and the feedback ask are constant, because they matter in both states.
+ */
+/** The tools, and the rule that only two of them decide anything. Constant across both states. */
+const VERDICT_DISCIPLINE = `Reticle verifies a running web app from the inside: look (reticle_snapshot / reticle_query), act and prove in one hop (reticle_act_and_wait), observe (reticle_state / reticle_network / reticle_console), assert (reticle_assert). Verify a user-facing change against the real app before you call it done, and never weaken a check to make it pass.
+
+Only reticle_act_and_wait and reticle_assert produce a verdict. reticle_act and everything else move or read the app and prove nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer reticle_act_and_wait({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. A verdict of verified:"unknown" is not a pass: it means Reticle drove the app and could not tell what happened. Report it as unknown.`;
+/**
+ * The first move, for a project no app has ever connected to.
+ *
+ * Deliberately concrete: the command, what it does to the app, and the call that confirms it. A
+ * general instruction to "set Reticle up" is the state these agents are already in — they have the
+ * tools and no app, and nothing tells them that combination is incomplete. It also names the dev
+ * server restart, because a plugin added to a config the running server already read is the single
+ * most common way this step half-succeeds.
+ */
+const FIRST_MOVE = `FIRST: no app has ever connected to Reticle in this project, so nothing here can be verified yet. Having these tools is not the same as being set up — the tools reach a daemon, and the daemon has nothing to look at until the app itself is instrumented.
+
+Fix that before anything else: run \`npx @reticlehq/server init\` in the project, then RESTART the dev server (a plugin added to a config the running server already read is not in the bundle), then load the app in a browser. Confirm with reticle_sessions — a session listed there is the proof, and until one appears no other tool can tell you anything about this app.`;
+/** The feedback ask. Constant: an agent that cannot get set up is the report we most need. */
+const FEEDBACK_ASK = `Feedback is first-class here, not a courtesy. Reticle is built FOR agents, so your experience is the only signal that decides what gets built or fixed — and it disappears when your context does. Send it with \`reticle_feedback\` the moment you notice, then carry on with your task:
+- Reticle broke, lied, or could not see something you needed (\`bug\` / \`gap\` / \`ambiguity\`).
+- You wished it could do something, or something works but costs too many calls (\`feature_request\` / \`improvement\`).
+- The install, the wiring, or the setup itself gave you trouble — including anything you had to work around by hand.
+
+Nothing is too minor, and a report costs one call. If the tools are unreachable (setup unfinished, daemon down), file the same report from the shell instead: \`reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"\`. Report defects in RETICLE — a bug you find in the app under test is Reticle working, and belongs in your answer to the user.`;
+/** The instructions this daemon should advertise, given what it knows about the project. */
+/**
+ * Instructions are sent ONCE at initialize; the tool surface is re-sent every turn. Measured on this
+ * server: 621 tokens here against 5,480 per turn there, so anything true of every tool belongs in
+ * this block rather than repeated across sixteen parameter descriptions. See shared-params.ts.
+ */
+export function buildServerInstructions(state) {
+    const base = state.previouslyConnected
+        ? `${VERDICT_DISCIPLINE}\n\n${FEEDBACK_ASK}`
+        : `${FIRST_MOVE}\n\n${VERDICT_DISCIPLINE}\n\n${FEEDBACK_ASK}`;
+    return `${base}\n\n${SHARED_PARAM_GUIDANCE}`;
+}

package/dist/mcp/shared-params.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Parameters that mean the same thing on every tool, documented ONCE instead of every turn.
+ *
+ * The advertised surface is re-sent on every turn; the MCP `instructions` block is sent once at
+ * initialize. Measured on this server: instructions cost 621 tokens total, the surface costs 5,480
+ * PER TURN — 87,672 over a 16-turn run. So a byte of prose moved from a parameter description into
+ * instructions is roughly 16x cheaper, and nothing is lost, because the text still reaches the model.
+ *
+ * `sessionId` is the clearest case: identical boilerplate on 16 tools, 2,076 bytes of the surface,
+ * re-explained on every turn to say the same thing it said last turn.
+ *
+ * This is deliberately NOT the `verify` experiment. That one removed the observation tools and
+ * measured what it cost: detection held but false alarms tripled, because evidence got expensive.
+ * This removes REPETITION, not evidence — every tool stays advertised and every observation stays
+ * one call away. Cost goes down; what the model can see does not change.
+ *
+ * The trade being made, stated: schema prose is expensive but sits adjacent to the call, while
+ * instructions are cheap but distant, and a client that drops `instructions` loses this text
+ * entirely. So the short forms below still have to be usable on their own — each one names the
+ * parameter's PURPOSE, and only the guidance moves.
+ */
+/** The short form left in the per-turn schema. Must still make sense with no instructions at all. */
+export declare const SHARED_PARAM_SHORT: Readonly<Record<string, string>>;
+/** The full text, sent once at initialize. Everything trimmed above is restated here. */
+export declare const SHARED_PARAM_GUIDANCE: string;
+/** Is this a parameter whose guidance now lives in the instructions block? */
+export declare function isSharedParam(name: string): boolean;

package/dist/mcp/shared-params.js

@@ -0,0 +1,36 @@
+/**
+ * Parameters that mean the same thing on every tool, documented ONCE instead of every turn.
+ *
+ * The advertised surface is re-sent on every turn; the MCP `instructions` block is sent once at
+ * initialize. Measured on this server: instructions cost 621 tokens total, the surface costs 5,480
+ * PER TURN — 87,672 over a 16-turn run. So a byte of prose moved from a parameter description into
+ * instructions is roughly 16x cheaper, and nothing is lost, because the text still reaches the model.
+ *
+ * `sessionId` is the clearest case: identical boilerplate on 16 tools, 2,076 bytes of the surface,
+ * re-explained on every turn to say the same thing it said last turn.
+ *
+ * This is deliberately NOT the `verify` experiment. That one removed the observation tools and
+ * measured what it cost: detection held but false alarms tripled, because evidence got expensive.
+ * This removes REPETITION, not evidence — every tool stays advertised and every observation stays
+ * one call away. Cost goes down; what the model can see does not change.
+ *
+ * The trade being made, stated: schema prose is expensive but sits adjacent to the call, while
+ * instructions are cheap but distant, and a client that drops `instructions` loses this text
+ * entirely. So the short forms below still have to be usable on their own — each one names the
+ * parameter's PURPOSE, and only the guidance moves.
+ */
+/** The short form left in the per-turn schema. Must still make sense with no instructions at all. */
+export const SHARED_PARAM_SHORT = {
+    sessionId: 'Target a specific tab. Omit unless you mean one — see instructions.',
+    since: 'Cursor from a prior reticle_act/reticle_observe.',
+    limit: 'Cap descriptors to the first N.',
+};
+/** The full text, sent once at initialize. Everything trimmed above is restated here. */
+export const SHARED_PARAM_GUIDANCE = 'Arguments that mean the same thing on every tool: `sessionId` — omit unless you mean a specific ' +
+    'tab; Reticle scopes to your project, prefers the active one, and refuses rather than guesses when ' +
+    'ambiguous. `since` — a cursor from a prior act/observe, bounding an observation to what came ' +
+    'after it. `limit` — caps returned descriptors, cutting tokens on broad queries.';
+/** Is this a parameter whose guidance now lives in the instructions block? */
+export function isSharedParam(name) {
+    return Object.hasOwn(SHARED_PARAM_SHORT, name);
+}

package/dist/pool/browser-pool.d.ts

@@ -60,7 +60,8 @@ interface BrowserPoolOptions {
 export declare class BrowserPool {
     #private;
     constructor(launch: Launcher, opts: BrowserPoolOptions);
-    /** Currently leased contexts. */
+    /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
+    leaseTtlMs(): number;
     /** Max simultaneous leases — the ceiling the parallel suite sizes its concurrency to. */
     capacity(): number;
     activeCount(): number;
@@ -68,8 +69,27 @@ export declare class BrowserPool {
     queuedCount(): number;
     /** The sessionIds of every currently leased context — used to report/group leased sessions. */
     leasedSessionIds(): string[];
-    /** Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown. */
+    /**
+     * Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown.
+     *
+     * Resolves an alias first, because the agent releases with the id it was GIVEN, which for an app
+     * that named its own session is not the id the pool navigated with. Releasing by that name used to
+     * be a silent no-op that left the slot held until the reaper took it.
+     */
     release(sessionId: string): Promise<void>;
+    /**
+     * Record that a lease is also known by the name the APP registered.
+     *
+     * Leases are keyed by the id the pool navigated with, and the SDK normally adopts that id off the
+     * URL so the two agree. An app that passes an explicit `session` to `connect()` keeps its own name
+     * instead, which is legitimate, and the lease tool then hands the agent THAT name because it is the
+     * one it has to drive with. Every later touch and release arrives under it.
+     *
+     * Without this the touches hit nothing, the lease ages out despite continuous activity, and the
+     * reaper closes the context mid-flow — the failure in #157, where a session died on the very call
+     * that would have read a computed value.
+     */
+    alias(registeredId: string, leaseId: string): void;
     /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
     touch(sessionId: string): void;
     /**

package/dist/pool/browser-pool.js

@@ -30,6 +30,8 @@ export class BrowserPool {
     /** Leases reclaimed for going stale — see reapedLeaseCount(). */
     #reapedLeases = 0;
     #active = new Map();
+    /** Registered-session-id → lease id, for apps that keep their own session name. See `alias`. */
+    #aliases = new Map();
     /**
      * Slots claimed-or-active — the real concurrency gate. Incremented SYNCHRONOUSLY the instant an
      * acquire passes the cap check, BEFORE the async context creation, so a burst of concurrent
@@ -50,7 +52,10 @@ export class BrowserPool {
         this.#ttl = opts.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
         this.#navTimeout = opts.navTimeoutMs ?? DEFAULT_NAV_TIMEOUT_MS;
     }
-    /** Currently leased contexts. */
+    /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
+    leaseTtlMs() {
+        return this.#ttl;
+    }
     /** Max simultaneous leases — the ceiling the parallel suite sizes its concurrency to. */
     capacity() {
         return this.#max;
@@ -66,13 +71,42 @@ export class BrowserPool {
     leasedSessionIds() {
         return [...this.#active.keys()];
     }
-    /** Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown. */
+    /**
+     * Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown.
+     *
+     * Resolves an alias first, because the agent releases with the id it was GIVEN, which for an app
+     * that named its own session is not the id the pool navigated with. Releasing by that name used to
+     * be a silent no-op that left the slot held until the reaper took it.
+     */
     release(sessionId) {
-        return this.#release(sessionId);
+        return this.#release(this.#leaseIdOf(sessionId));
+    }
+    /**
+     * Record that a lease is also known by the name the APP registered.
+     *
+     * Leases are keyed by the id the pool navigated with, and the SDK normally adopts that id off the
+     * URL so the two agree. An app that passes an explicit `session` to `connect()` keeps its own name
+     * instead, which is legitimate, and the lease tool then hands the agent THAT name because it is the
+     * one it has to drive with. Every later touch and release arrives under it.
+     *
+     * Without this the touches hit nothing, the lease ages out despite continuous activity, and the
+     * reaper closes the context mid-flow — the failure in #157, where a session died on the very call
+     * that would have read a computed value.
+     */
+    alias(registeredId, leaseId) {
+        if (registeredId === leaseId)
+            return;
+        if (!this.#active.has(leaseId))
+            return;
+        this.#aliases.set(registeredId, leaseId);
+    }
+    /** The lease this id refers to: itself, or whatever it is an alias for. */
+    #leaseIdOf(sessionId) {
+        return this.#active.has(sessionId) ? sessionId : (this.#aliases.get(sessionId) ?? sessionId);
     }
     /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
     touch(sessionId) {
-        const lease = this.#active.get(sessionId);
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
         if (lease !== undefined)
             lease.touchedAt = this.#now();
     }
@@ -173,6 +207,12 @@ export class BrowserPool {
         if (lease === undefined)
             return; // already released or lost to a crash
         this.#active.delete(sessionId);
+        // Drop any alias pointing here, or the map grows for the life of the daemon and a later lease
+        // reusing that registered name would resolve to a context that is already closed.
+        for (const [registered, leaseId] of this.#aliases) {
+            if (leaseId === sessionId)
+                this.#aliases.delete(registered);
+        }
         await lease.context.close().catch(() => undefined);
         this.#releaseSlot();
     }

package/dist/project/learned-routes.d.ts

@@ -0,0 +1,24 @@
+import { type ReticleEvent } from '@reticlehq/core';
+interface RouteLearningSession {
+    url: string;
+    onEvent(handler: (event: ReticleEvent) => void): () => void;
+}
+interface RouteLearningBridge {
+    sessions: {
+        all(): RouteLearningSession[];
+    };
+    attachSessionReady(handler: (session: RouteLearningSession) => void): void;
+}
+interface RouteLearningStore {
+    recordRoutes(routes: readonly string[]): Promise<void>;
+}
+/** Coalesce navigation bursts so one crawl does not lock and rewrite project.json per event. */
+export declare const ROUTE_PERSIST_DEBOUNCE_MS = 50;
+/** Convert a validated route-change payload into a bounded route identity. */
+export declare function routeFromEvent(event: ReticleEvent): string | undefined;
+/** Read the same route shape from a session's absolute URL. */
+export declare function routeFromUrl(value: string): string | undefined;
+export declare function routesFromEvents(events: readonly ReticleEvent[]): string[];
+/** Persist initial and subsequent routes for existing and future browser sessions. */
+export declare function attachRouteLearning(bridge: RouteLearningBridge, project: RouteLearningStore): void;
+export {};

package/dist/project/learned-routes.js

@@ -0,0 +1,63 @@
+import { EventType } from '@reticlehq/core';
+/** Coalesce navigation bursts so one crawl does not lock and rewrite project.json per event. */
+export const ROUTE_PERSIST_DEBOUNCE_MS = 50;
+/** Convert a validated route-change payload into a bounded route identity. */
+export function routeFromEvent(event) {
+    if (event.type !== EventType.ROUTE_CHANGE)
+        return undefined;
+    const pathname = event.data['pathname'];
+    if ('string' !== typeof pathname || 0 === pathname.length)
+        return undefined;
+    return pathname;
+}
+/** Read the same route shape from a session's absolute URL. */
+export function routeFromUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.pathname;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function routesFromEvents(events) {
+    return events.flatMap((event) => {
+        const route = routeFromEvent(event);
+        return route === undefined ? [] : [route];
+    });
+}
+/** Persist initial and subsequent routes for existing and future browser sessions. */
+export function attachRouteLearning(bridge, project) {
+    const attached = new WeakSet();
+    const pending = new Set();
+    let flushTimer;
+    const flush = () => {
+        flushTimer = undefined;
+        const routes = [...pending];
+        pending.clear();
+        if (routes.length > 0)
+            void project.recordRoutes(routes).catch(() => undefined);
+    };
+    const queue = (route) => {
+        pending.add(route);
+        if (flushTimer !== undefined)
+            clearTimeout(flushTimer);
+        flushTimer = setTimeout(flush, ROUTE_PERSIST_DEBOUNCE_MS);
+    };
+    const attach = (session) => {
+        if (attached.has(session))
+            return;
+        attached.add(session);
+        const initial = routeFromUrl(session.url);
+        if (initial !== undefined)
+            queue(initial);
+        session.onEvent((event) => {
+            const route = routeFromEvent(event);
+            if (route !== undefined)
+                queue(route);
+        });
+    };
+    for (const session of bridge.sessions.all())
+        attach(session);
+    bridge.attachSessionReady(attach);
+}

package/dist/project/project-store.d.ts

@@ -26,6 +26,12 @@ export declare class ProjectStore {
      * (last PER_NAME of any one name, then cap to TOTAL overall) and writes byte-stably.
      */
     recordRun(record: Omit<RunRecord, 'at'>): Promise<void>;
+    /**
+     * Add discovered routes to the learned app map. Empty input is a no-op so "nothing observed"
+     * does not materialize as `learned.routes: []`; non-empty updates are serialized per file so
+     * concurrent browser sessions accumulate rather than overwriting one another.
+     */
+    recordRoutes(routes: readonly string[]): Promise<void>;
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     lastRun(name: string): Promise<RunRecord | undefined>;
 }

package/dist/project/project-store.js

@@ -1,4 +1,4 @@
-import { PROJECT_FILE_VERSION, PROJECT_RUN_CAP, ProjectFileSchema, ProjectReadError, } from '@reticlehq/core';
+import { PROJECT_FILE_VERSION, PROJECT_ROUTE_CAP, PROJECT_RUN_CAP, ProjectFileSchema, ProjectReadError, } from '@reticlehq/core';
 import { reticleDirPaths } from './reticle-dir.js';
 import { withFileLock } from './file-lock.js';
 const JSON_INDENT = 2;
@@ -77,6 +77,30 @@ export class ProjectStore {
             await this.#fs.writeFile(path, this.#serialize(next));
         });
     }
+    /**
+     * Add discovered routes to the learned app map. Empty input is a no-op so "nothing observed"
+     * does not materialize as `learned.routes: []`; non-empty updates are serialized per file so
+     * concurrent browser sessions accumulate rather than overwriting one another.
+     */
+    async recordRoutes(routes) {
+        const additions = routes.filter((route) => route.length > 0);
+        if (0 === additions.length)
+            return;
+        const path = reticleDirPaths(this.#root).project;
+        await withFileLock(path, async () => {
+            const existing = await this.read();
+            const base = existing.ok ? existing.file : EMPTY_PROJECT;
+            const current = base.learned?.routes ?? [];
+            const merged = [...new Set([...current, ...additions])].slice(0, PROJECT_ROUTE_CAP);
+            if (merged.length === current.length &&
+                merged.every((route, index) => route === current[index]))
+                return;
+            const learned = { ...base.learned, routes: merged };
+            const next = { ...base, learned };
+            await this.#fs.mkdir(reticleDirPaths(this.#root).root);
+            await this.#fs.writeFile(path, this.#serialize(next));
+        });
+    }
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     async lastRun(name) {
         const read = await this.read();

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

@@ -13,6 +13,8 @@ export interface ReticleDirPaths {
     baselines: string;
     /**.../.reticle/project.json (cross-run outcome memory) */
     project: string;
+    /**.../.reticle/impact.json (what Reticle has done for this user, local only) */
+    impact: string;
     /**.../.reticle/visual (PNG baselines + diffs) */
     visual: string;
     /**.../.reticle/runs (verification-run artifacts) */

package/dist/project/reticle-dir.js

@@ -7,6 +7,7 @@ export function reticleDirPaths(root) {
         flows: join(root, ReticleDir.FLOWS_SUBDIR),
         baselines: join(root, ReticleDir.BASELINES_SUBDIR),
         project: join(root, ReticleDir.PROJECT_FILE),
+        impact: join(root, ReticleDir.IMPACT_FILE),
         visual: join(root, ReticleDir.VISUAL_SUBDIR),
         runs: join(root, ReticleDir.RUNS_SUBDIR),
         sessions: join(root, ReticleDir.SESSIONS_SUBDIR),

package/dist/session/connection-memory.d.ts

@@ -0,0 +1,59 @@
+/**
+ * One durable bit: has an app ever connected to Reticle on this port, for this project?
+ *
+ * `SessionManager.everConnected()` answers a narrower question than every reader of it assumed — it
+ * is scoped to the CURRENT PROCESS. Daemons are short-lived by design (they idle out and respawn),
+ * so a diagnosis built on that boolean tells a user whose app connected a minute ago that this
+ * install has never worked, and sends them looking for a missing config file that was always there.
+ * Reported repeatedly, and the confident phrasing is what made it expensive: "never seen one" reads
+ * as evidence about the install, not as a fact about a process that booted four seconds ago.
+ *
+ * Deliberately tiny: one JSON file per port under the daemon's state home, holding the set of
+ * projectIds that have connected. It is a HINT, so every failure mode here degrades to "we do not
+ * know" rather than throwing — a diagnostic that can crash the tool it is diagnosing is worse than
+ * no diagnostic at all.
+ */
+/**
+ * Record that a session connected. Best-effort — a daemon must never fail to serve a session
+ * because it could not write a hint about it.
+ */
+export declare function rememberConnected(stateDir: string, port: number, projectId: string | undefined): void;
+/**
+ * Whether an app has connected on this port before, for this project.
+ *
+ * An absent `projectId` asks the weaker question — "has ANY app connected on this port" — because
+ * that is the honest reading when the caller cannot name a project: the alternative is to answer
+ * "no" for a daemon that plainly has served apps, which is the same over-confident claim this file
+ * exists to remove.
+ */
+export declare function hasConnectedBefore(stateDir: string, port: number, projectId: string | undefined): boolean;
+/**
+ * Has an app connected before FOR THIS PROJECT — the question the first-move instructions ask.
+ *
+ * Separate from `hasConnectedBefore` because they are genuinely different questions and only one of
+ * them tolerates the untagged fallback. The no-session diagnosis wants "has this daemon ever served
+ * an app", and answering "no" there when it plainly has is the over-confident claim this file
+ * exists to remove. The first-move block claims something narrower and says so in its own first
+ * sentence: "no app has ever connected to Reticle IN THIS PROJECT".
+ *
+ * Deciding that narrower claim with the weaker question inverted it for exactly the population it
+ * was written for. An unwired project has no `.reticle.json`, so no projectId, so it fell into the
+ * untagged branch — which is true as soon as any app has ever connected on this port. On any
+ * machine where the default port has served anything at all, the guidance was suppressed and the
+ * agent was told the setup was done.
+ *
+ * So an absent projectId answers `false` here: a project with no Reticle identity has nothing
+ * recorded under another project's name that could be evidence about it. The cost of being wrong in
+ * this direction is one guidance block, read once at handshake, by a setup that is already working.
+ *
+ * KNOWN LIMIT, and the reason it is accepted rather than worked around. The WRITE side records the
+ * id the SDK supplied, while the read side asks `.reticle.json` — and the Vite plugin derives an id
+ * without writing that file. So a project wired by hand with the plugin and no `init` records a real
+ * id on every connect and reads `undefined` here forever, and is told at each handshake that nothing
+ * has connected. Two things make that tolerable: the block's own advice is to run `init`, which
+ * writes the file and heals the detection, so it is actionable rather than merely wrong; and the
+ * alternative — answering from the port — is the leak this function exists to close, which is the
+ * larger error by a wide margin. `no-session-watch` had already made exactly this call for its own
+ * diagnosis, which is why it now shares this function instead of keeping a second copy of the rule.
+ */
+export declare function hasProjectConnectedBefore(stateDir: string, port: number, projectId: string | undefined): boolean;

package/dist/session/connection-memory.js

@@ -0,0 +1,108 @@
+/**
+ * One durable bit: has an app ever connected to Reticle on this port, for this project?
+ *
+ * `SessionManager.everConnected()` answers a narrower question than every reader of it assumed — it
+ * is scoped to the CURRENT PROCESS. Daemons are short-lived by design (they idle out and respawn),
+ * so a diagnosis built on that boolean tells a user whose app connected a minute ago that this
+ * install has never worked, and sends them looking for a missing config file that was always there.
+ * Reported repeatedly, and the confident phrasing is what made it expensive: "never seen one" reads
+ * as evidence about the install, not as a fact about a process that booted four seconds ago.
+ *
+ * Deliberately tiny: one JSON file per port under the daemon's state home, holding the set of
+ * projectIds that have connected. It is a HINT, so every failure mode here degrades to "we do not
+ * know" rather than throwing — a diagnostic that can crash the tool it is diagnosing is worse than
+ * no diagnostic at all.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Sessions from an SDK old enough not to stamp a projectId still count, under this key. */
+const UNTAGGED = '(untagged)';
+/**
+ * Cap on remembered projects per port.
+ *
+ * A shared 4400 on a busy machine sees many projects over a week and this file is never garbage
+ * collected, so the set is bounded and oldest-out. The bit it answers is only ever used to soften a
+ * diagnosis, so losing the tail costs nothing.
+ */
+const MAX_REMEMBERED_PROJECTS = 32;
+function memoryPath(stateDir, port) {
+    return join(stateDir, `connected-${String(port)}.json`);
+}
+/** The remembered project ids for a port. Empty on absent, unreadable, or malformed state. */
+function read(stateDir, port) {
+    try {
+        const parsed = JSON.parse(readFileSync(memoryPath(stateDir, port), 'utf8'));
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((entry) => 'string' === typeof entry);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Record that a session connected. Best-effort — a daemon must never fail to serve a session
+ * because it could not write a hint about it.
+ */
+export function rememberConnected(stateDir, port, projectId) {
+    const key = projectId ?? UNTAGGED;
+    const known = read(stateDir, port);
+    if (known.includes(key))
+        return;
+    const next = [...known, key].slice(-MAX_REMEMBERED_PROJECTS);
+    try {
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(memoryPath(stateDir, port), JSON.stringify(next), 'utf8');
+    }
+    catch {
+        // An unwritable state home is already reported elsewhere; it must not break the session path.
+    }
+}
+/**
+ * Whether an app has connected on this port before, for this project.
+ *
+ * An absent `projectId` asks the weaker question — "has ANY app connected on this port" — because
+ * that is the honest reading when the caller cannot name a project: the alternative is to answer
+ * "no" for a daemon that plainly has served apps, which is the same over-confident claim this file
+ * exists to remove.
+ */
+export function hasConnectedBefore(stateDir, port, projectId) {
+    const known = read(stateDir, port);
+    if (projectId === undefined)
+        return known.length > 0;
+    return known.includes(projectId);
+}
+/**
+ * Has an app connected before FOR THIS PROJECT — the question the first-move instructions ask.
+ *
+ * Separate from `hasConnectedBefore` because they are genuinely different questions and only one of
+ * them tolerates the untagged fallback. The no-session diagnosis wants "has this daemon ever served
+ * an app", and answering "no" there when it plainly has is the over-confident claim this file
+ * exists to remove. The first-move block claims something narrower and says so in its own first
+ * sentence: "no app has ever connected to Reticle IN THIS PROJECT".
+ *
+ * Deciding that narrower claim with the weaker question inverted it for exactly the population it
+ * was written for. An unwired project has no `.reticle.json`, so no projectId, so it fell into the
+ * untagged branch — which is true as soon as any app has ever connected on this port. On any
+ * machine where the default port has served anything at all, the guidance was suppressed and the
+ * agent was told the setup was done.
+ *
+ * So an absent projectId answers `false` here: a project with no Reticle identity has nothing
+ * recorded under another project's name that could be evidence about it. The cost of being wrong in
+ * this direction is one guidance block, read once at handshake, by a setup that is already working.
+ *
+ * KNOWN LIMIT, and the reason it is accepted rather than worked around. The WRITE side records the
+ * id the SDK supplied, while the read side asks `.reticle.json` — and the Vite plugin derives an id
+ * without writing that file. So a project wired by hand with the plugin and no `init` records a real
+ * id on every connect and reads `undefined` here forever, and is told at each handshake that nothing
+ * has connected. Two things make that tolerable: the block's own advice is to run `init`, which
+ * writes the file and heals the detection, so it is actionable rather than merely wrong; and the
+ * alternative — answering from the port — is the leak this function exists to close, which is the
+ * larger error by a wide margin. `no-session-watch` had already made exactly this call for its own
+ * diagnosis, which is why it now shares this function instead of keeping a second copy of the rule.
+ */
+export function hasProjectConnectedBefore(stateDir, port, projectId) {
+    if (projectId === undefined)
+        return false;
+    return hasConnectedBefore(stateDir, port, projectId);
+}

package/dist/session/dev-command.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The literal command that starts THIS project's dev server, read from the project's own scripts.
+ *
+ * The no-session diagnosis has always said "ask the human to start it (`npm run dev`)". That is a
+ * guess on two axes — the script name and the package manager — and a guessed command is worse than
+ * none: the agent runs it, gets an error about a missing script, and concludes the app is broken
+ * rather than that Reticle was wrong. So this reads, and returns nothing when it cannot read.
+ *
+ * Pure apart from one injected reader, so every case is a unit test rather than a temp directory.
+ */
+/** A dev script, as something an agent can actually run. */
+export interface DevCommand {
+    /** The literal shell command, e.g. `pnpm run dev`. */
+    command: string;
+    /** The package.json script it runs. */
+    script: string;
+    /** The port the script PINS, when it pins one. Absent means the tool picks — never a guess. */
+    port?: number;
+}
+/**
+ * The dev command for the project in `directory`, or undefined when there is not one to be sure of.
+ *
+ * `read` is injected so the whole decision is testable without a filesystem; the daemon uses the
+ * default disk reader.
+ */
+export declare function detectDevCommand(directory: string, read?: (path: string) => string | undefined): DevCommand | undefined;