@reticlehq/server 2.8.0 → 2.10.0

package/dist/mcp/proxy-log.js

@@ -0,0 +1,132 @@
+/**
+ * The MCP proxy's own log file: where it lives, what bounds it, and how it is written.
+ *
+ * Split out of mcp-proxy.ts, which is the transport. This is housekeeping for a file, and the two
+ * share nothing but a port number — the proxy calls `proxyLog`, and everything else here exists to
+ * keep that file from becoming the largest thing on the user's disk.
+ */
+import { appendFileSync, mkdirSync, renameSync, statSync, truncateSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { log } from '../log.js';
+import { MAX_DAEMON_LOG_BYTES, rotateDaemonLog } from '../daemon/daemon.js';
+/**
+ * Which port this proxy serves, for the log file name. Set once at startup.
+ *
+ * One file per port, matching `daemon-<port>.log`. A single shared file interleaved every proxy on
+ * the machine into one stream, so the first question anyone asks of it — "what happened to MY
+ * session?" — needed a filter before it could be answered.
+ */
+let logPort;
+/**
+ * How much the proxy may append between size checks.
+ *
+ * Statting the file on every line would be a syscall per log line on a process that logs from a
+ * reconnect loop. Counting what we wrote costs nothing and is exact enough, because this process is
+ * the only writer of its own log. Well under the cap, so the cap is a cap rather than a suggestion.
+ */
+export const PROXY_LOG_CHECK_BYTES = 256 * 1024;
+/** Appended since the last real size check. Reset by every check, whatever the check decides. */
+let bytesSinceProxyLogCheck = 0;
+/**
+ * Keep the proxy log under the same cap as the daemon log, without a stat per write.
+ *
+ * Returns the new "bytes since the last check" counter, so the accounting is testable without a
+ * filesystem. Rotation itself is `rotateDaemonLog` — the proxy log had no cap at all while the
+ * daemon log on the SAME machine stayed small, which is the whole of this defect.
+ */
+export function accountProxyLogWrite(bytesSinceCheck, written, path, deps) {
+    const total = bytesSinceCheck + written;
+    if (PROXY_LOG_CHECK_BYTES > total)
+        return total;
+    rotateDaemonLog(path, deps);
+    return 0;
+}
+/**
+ * Reclaim a proxy log that a previous process already let run away. Returns the bytes reclaimed.
+ *
+ * Reported from the field: one machine's `proxy-4400.log` reached a third of a 460GB disk and broke
+ * builds, Docker and ordinary shell commands with ENOSPC. Nothing in Reticle degraded first, so the
+ * failure surfaced as the operating system refusing to write files. Files like that exist on real
+ * machines now, and the cap alone does not help them: the user should not have to find one with `du`.
+ *
+ * TRUNCATED IN PLACE, never renamed or unlinked. A rename moves the bytes without reclaiming a byte,
+ * and a file that a running process still holds open keeps its blocks allocated after an unlink
+ * until that handle closes — which is why the reporter recovered with `: > ~/.reticle/proxy-4400.log`
+ * and why that is the operation to copy here.
+ *
+ * Best-effort, in the same spirit as `rotateDaemonLog`: refusing to start the MCP server over
+ * housekeeping is strictly worse than a large file.
+ */
+export function recoverOversizedProxyLog(path, deps, max = MAX_DAEMON_LOG_BYTES) {
+    try {
+        const size = deps.fileSize(path);
+        if (max >= size)
+            return 0;
+        deps.truncateFile(path);
+        return size;
+    }
+    catch {
+        return 0;
+    }
+}
+/** The real filesystem behind the two rotation helpers. */
+const proxyLogFileOps = {
+    fileSize: (p) => statSync(p).size,
+    renameFile: (from, to) => renameSync(from, to),
+    truncateFile: (p) => truncateSync(p, 0),
+};
+/** Name the proxy log after the port it serves. Called before anything can log. */
+export function setProxyLogPort(port) {
+    logPort = port;
+    // The one moment we know a size check is worth its syscall, and the only place a file inherited
+    // from an older build can be brought back under control.
+    const reclaimed = recoverOversizedProxyLog(proxyLogPath(port), proxyLogFileOps);
+    if (0 < reclaimed) {
+        proxyLog('reticle_mcp_proxy_log_truncated', {
+            port,
+            reclaimedBytes: reclaimed,
+            note: 'the proxy log had grown past its cap and was truncated in place to reclaim the space',
+        });
+    }
+}
+/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
+export function proxyLogPath(port = logPort) {
+    const name = port === undefined ? 'mcp-proxy.log' : `proxy-${String(port)}.log`;
+    return join(homedir(), ReticleDir.ROOT, name);
+}
+/**
+ * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/proxy-<port>.log, which it
+ * does not. A dropped MCP connection is invisible from the agent's side — no message, no exit code —
+ * so the one thing that makes it diagnosable at all is a file somebody can read afterwards.
+ *
+ * EXPORTED because the crash handlers need it. `installProxyResilience` was wired to the bare stderr
+ * logger, so the proxy's own uncaught exceptions and unhandled rejections — the exact events that
+ * present to a human as "the MCP server disconnected" — were written to a stream the editor throws
+ * away. The handler ran, the process kept serving, and the reason went nowhere. Reported as "the
+ * proxy has no log file… when it dies the diagnostic dies with it", which was half right: the file
+ * existed, and the one path that most needed it was not using it.
+ */
+export function proxyLog(event, fields = {}) {
+    log(event, fields);
+    try {
+        const dir = join(homedir(), ReticleDir.ROOT);
+        mkdirSync(dir, { recursive: true });
+        // WITH A TIMESTAMP. This file is the only record of an outage that survives the session, and
+        // without one it cannot answer the two questions anyone brings to it: when did this happen, and
+        // how often. A real 3,283-line log on a dev machine held a `gave_up` — the exact event that used
+        // to precede `process.exit(1)` and cost the human a manual /mcp reconnect — and it was
+        // impossible to tell whether it happened during that person's work or a test run hours earlier.
+        // Evidence you cannot place in time is an anecdote.
+        const path = proxyLogPath();
+        const line = `${JSON.stringify({ t: new Date().toISOString(), event, ...fields })}\n`;
+        appendFileSync(path, line, 'utf8');
+        // A single proxy process is long-lived and logs from a reconnect loop, so rotating only at
+        // startup would leave the growth this file is capable of entirely unchecked while it runs.
+        bytesSinceProxyLogCheck = accountProxyLogWrite(bytesSinceProxyLogCheck, Buffer.byteLength(line, 'utf8'), path, proxyLogFileOps);
+    }
+    catch {
+        // Logging must never be the thing that kills the proxy.
+    }
+}

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. Only verified:"yes" is a pass — "unknown" means Reticle could not tell what happened, "no-fault" means nothing was declared to prove. Report either as not proved.`;
+/**
+ * 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 <one of those kinds> "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/mcp/sse-frame-parser.d.ts

@@ -0,0 +1,19 @@
+/** One parsed Server-Sent-Events frame: the event name (defaulted to "message") and its data. */
+export interface SseFrame {
+    event: string;
+    data: string;
+}
+/**
+ * Incremental SSE frame parser for the MCP front door.
+ *
+ * A single SSE field can split across TCP reads (`da` in one chunk, `ta: {...}` in the next), and a
+ * server may send CRLF or bare CR line endings — so the framing is stateful and edge-case-prone, yet it
+ * carried every MCP message the agent sends and was only ever exercised end-to-end. Pulled out of the
+ * socket handler as a pure, chunk-fed parser so those boundaries are unit-testable: feed raw chunks,
+ * get back each complete frame (a blank line terminates a frame; `event:` names it, `data:` lines
+ * accumulate newline-joined; `id:`/`retry:`/comments are ignored — not needed for the bridge).
+ */
+export declare class SseFrameParser {
+    #private;
+    push(chunk: string): SseFrame[];
+}

package/dist/mcp/sse-frame-parser.js

@@ -0,0 +1,41 @@
+/**
+ * Incremental SSE frame parser for the MCP front door.
+ *
+ * A single SSE field can split across TCP reads (`da` in one chunk, `ta: {...}` in the next), and a
+ * server may send CRLF or bare CR line endings — so the framing is stateful and edge-case-prone, yet it
+ * carried every MCP message the agent sends and was only ever exercised end-to-end. Pulled out of the
+ * socket handler as a pure, chunk-fed parser so those boundaries are unit-testable: feed raw chunks,
+ * get back each complete frame (a blank line terminates a frame; `event:` names it, `data:` lines
+ * accumulate newline-joined; `id:`/`retry:`/comments are ignored — not needed for the bridge).
+ */
+export class SseFrameParser {
+    #buffer = '';
+    #event = '';
+    #data = '';
+    push(chunk) {
+        this.#buffer += chunk;
+        // Normalise CRLF/CR so the splitter only handles \n, then hold the trailing partial line for the
+        // next chunk (it may complete later).
+        const normalised = this.#buffer.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        const lines = normalised.split('\n');
+        this.#buffer = lines.pop() ?? '';
+        const frames = [];
+        for (const line of lines) {
+            if ('' === line) {
+                if (this.#data !== '') {
+                    frames.push({ event: this.#event !== '' ? this.#event : 'message', data: this.#data });
+                }
+                this.#event = '';
+                this.#data = '';
+            }
+            else if (line.startsWith('event:')) {
+                this.#event = line.slice(6).trim();
+            }
+            else if (line.startsWith('data:')) {
+                const val = line.slice(5).trim();
+                this.#data = this.#data !== '' ? `${this.#data}\n${val}` : val;
+            }
+        }
+        return frames;
+    }
+}

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;

package/dist/session/dev-command.js

@@ -0,0 +1,89 @@
+/**
+ * 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.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Script names checked, in order.
+ *
+ * `start` is last on purpose: in a Next or CRA app it is the PRODUCTION server, which serves a build
+ * with no dev-only SDK in it, so starting it would look like success and connect nothing. It is only
+ * reached when the project offers nothing better.
+ */
+const DEV_SCRIPTS = ['dev', 'develop', 'start'];
+/** Lockfile → package manager, in precedence order. Anything else is npm. */
+const LOCKFILES = [
+    { file: 'pnpm-lock.yaml', manager: 'pnpm' },
+    { file: 'yarn.lock', manager: 'yarn' },
+];
+const DEFAULT_PACKAGE_MANAGER = 'npm';
+const PACKAGE_JSON = 'package.json';
+/** `--port 4311` / `--port=4311`, the flag every dev server in this list accepts. */
+const PORT_FLAG = /--port[= ]\s*(\d+)/;
+/** `PORT=8080 remix dev` — the other half of how a project pins its port. */
+const PORT_ENV = /(?:^|\s)PORT=(\d+)/;
+/** Reads a file, or undefined if it is not there / not readable. */
+function readTextFile(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The port the script pins, when it pins one at all. */
+function pinnedPort(script) {
+    const match = PORT_FLAG.exec(script) ?? PORT_ENV.exec(script);
+    const digits = match?.[1];
+    if (digits === undefined)
+        return undefined;
+    const port = Number.parseInt(digits, 10);
+    return Number.isSafeInteger(port) ? port : undefined;
+}
+/** The scripts block of a package.json, or an empty one for anything unreadable/unparseable. */
+function readScripts(raw) {
+    if (raw === undefined)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (null === parsed || 'object' !== typeof parsed)
+            return {};
+        const scripts = parsed.scripts;
+        if (null === scripts || 'object' !== typeof scripts)
+            return {};
+        return scripts;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * 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 function detectDevCommand(directory, read = readTextFile) {
+    const scripts = readScripts(read(join(directory, PACKAGE_JSON)));
+    const manager = LOCKFILES.find(({ file }) => read(join(directory, file)) !== undefined)?.manager ??
+        DEFAULT_PACKAGE_MANAGER;
+    for (const script of DEV_SCRIPTS) {
+        const body = scripts[script];
+        if ('string' !== typeof body || 0 === body.trim().length)
+            continue;
+        const port = pinnedPort(body);
+        return {
+            command: `${manager} run ${script}`,
+            script,
+            ...(port === undefined ? {} : { port }),
+        };
+    }
+    return undefined;
+}