@reticlehq/server 2.7.0 → 2.9.0

package/dist/journal/attach-journal.js

@@ -1,17 +1,28 @@
+import { log } from '../log.js';
 import { isValidSessionId } from '../project/reticle-dir.js';
 import { JournalRecorder } from './journal-recorder.js';
 import { SessionJournal } from './session-journal.js';
 /**
  * Build the per-session journal attachment the bridge fires on session creation. Off when disabled;
- * silently skips a session whose id is not a safe path segment (never crashes the live session over a
+ * skips a session whose id is not a safe path segment (never crashes the live session over a
  * journaling concern). The recorder's clock is the session's own elapsed time.
+ *
+ * That skip used to be SILENT, which is the part that mattered. The id becomes a directory name, so
+ * one that is not a safe path segment cannot be journalled — but the session itself connects and
+ * drives perfectly well, so the only observable difference is that the durable causal record for it
+ * does not exist. Every query that reads back through the journal then returns nothing, and nothing
+ * anywhere says why. An app self-assigning an unusual id gets a quietly degraded session; a hostile
+ * one gets the same, which is why this is worth a line either way. Nothing escapes the directory —
+ * the guard holds, and that is exactly why the failure is invisible rather than loud.
  */
 export function makeJournalAttach(deps) {
     return (session) => {
         if (!deps.enabled)
             return;
-        if (!isValidSessionId(session.id))
+        if (!isValidSessionId(session.id)) {
+            log('journal_skipped_unsafe_session_id', { sessionId: session.id });
             return;
+        }
         const journal = new SessionJournal(deps.fs, deps.reticleRoot, session.id);
         // Same SessionJournal is both the write sink and the read fall-through for queries after eviction.
         session.setJournal(new JournalRecorder(journal, { now: () => session.elapsed() }), journal);

package/dist/journal/journal-query.d.ts

@@ -13,6 +13,19 @@ export interface EventQueryOptions {
  * session), ordered by `seq` (falling back to `t` for any pre-2.2 event without one). Neither source is
  * a strict superset — the journal holds everything already flushed (incl. evicted), the buffer holds the
  * most-recent tail that may not be flushed yet — so the union is the complete picture.
+ *
+ * ...for THIS connection. The session id survives a reload (it lives in sessionStorage), so the next
+ * connection reopens the same journal file while `seq` and `t` both restart at zero in the fresh
+ * page. Once the buffer has evicted anything — permanent about a minute into any session — every
+ * query falls through to that file and the PREVIOUS connection's tail arrives carrying timestamps
+ * that look like this connection's. Field reports: contradictions from before an explicit
+ * `reticle_session end`, two logins from different runs counted as one duplicate write, and findings
+ * from before a `since` cursor the caller had passed explicitly (`since` filters on `t`, which is
+ * exactly the field that restarted).
+ *
+ * The buffer is the authority on what this connection has emitted: the journal is written from the
+ * same stream and can only lag it, so nothing beyond the buffer's newest seq can belong here.
+ * Overlapping seqs need no rule — appends are ordered, so the newest write already wins the dedupe.
  */
 export declare function mergeEventsBySeq(journal: readonly ReticleEvent[], buffer: readonly ReticleEvent[]): ReticleEvent[];
 /** Apply since/until/actionId bounds to an event list. */

package/dist/journal/journal-query.js

@@ -3,15 +3,40 @@
  * session), ordered by `seq` (falling back to `t` for any pre-2.2 event without one). Neither source is
  * a strict superset — the journal holds everything already flushed (incl. evicted), the buffer holds the
  * most-recent tail that may not be flushed yet — so the union is the complete picture.
+ *
+ * ...for THIS connection. The session id survives a reload (it lives in sessionStorage), so the next
+ * connection reopens the same journal file while `seq` and `t` both restart at zero in the fresh
+ * page. Once the buffer has evicted anything — permanent about a minute into any session — every
+ * query falls through to that file and the PREVIOUS connection's tail arrives carrying timestamps
+ * that look like this connection's. Field reports: contradictions from before an explicit
+ * `reticle_session end`, two logins from different runs counted as one duplicate write, and findings
+ * from before a `since` cursor the caller had passed explicitly (`since` filters on `t`, which is
+ * exactly the field that restarted).
+ *
+ * The buffer is the authority on what this connection has emitted: the journal is written from the
+ * same stream and can only lag it, so nothing beyond the buffer's newest seq can belong here.
+ * Overlapping seqs need no rule — appends are ordered, so the newest write already wins the dedupe.
  */
 export function mergeEventsBySeq(journal, buffer) {
+    // ponytail: an EMPTY buffer cannot say where this connection has got to, so nothing is dropped
+    // there — a fresh connection emits page-health immediately, so the window is small and the safe
+    // direction is keeping evidence rather than inventing a boundary.
+    let newest;
+    for (const event of buffer) {
+        if ('number' === typeof event.seq && (newest === undefined || event.seq > newest)) {
+            newest = event.seq;
+        }
+    }
     const bySeq = new Map();
     const noSeq = [];
     for (const event of [...journal, ...buffer]) {
-        if ('number' === typeof event.seq)
-            bySeq.set(event.seq, event);
-        else
+        if ('number' !== typeof event.seq) {
             noSeq.push(event);
+            continue;
+        }
+        if (newest !== undefined && event.seq > newest)
+            continue;
+        bySeq.set(event.seq, event);
     }
     return [...bySeq.values(), ...noSeq].sort((a, b) => {
         if (a.seq !== undefined && b.seq !== undefined)

package/dist/journal/workspace-gitignore.d.ts

@@ -0,0 +1,10 @@
+import type { FileSystemPort } from '../project/fs-port.js';
+/**
+ * Write `.reticle/.gitignore` if it is not already there.
+ *
+ * Never overwrites — once the file exists it belongs to whoever edited it last, and silently
+ * reverting somebody's change to a file we placed in their repository is worse than not having
+ * written it. Best-effort throughout: this runs on the daemon's start path, and a workspace that
+ * cannot be written must not stop a daemon coming up. Nothing about verification depends on it.
+ */
+export declare function ensureWorkspaceGitignore(fs: FileSystemPort, root: string): Promise<void>;

package/dist/journal/workspace-gitignore.js

@@ -0,0 +1,59 @@
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+/**
+ * The `.reticle/` entries that are LOCAL state, and must never be committed by accident.
+ *
+ * Split from the durable half deliberately, and the split is the whole design: `contract.json`,
+ * `flows/`, `baselines/` and `capsules/` are meant to be checked in — a flow that cannot be shared
+ * is not a regression check anybody else can run — while everything below is per-machine churn.
+ *
+ * The reason this matters beyond tidiness: a session journal carries URLs, request and response
+ * bodies, and DOM text from the app under test. `.reticle/` is created by the daemon rather than by
+ * the user, so it arrives untracked and unexplained, and one `git add -A` puts an app's traffic into
+ * a shared repository. Reticle created the directory; the ignore for it is Reticle's to write.
+ */
+const TRANSIENT = [
+    `${ReticleDir.SESSIONS_SUBDIR}/`,
+    `${ReticleDir.RUNS_SUBDIR}/`,
+    `${ReticleDir.VISUAL_SUBDIR}/`,
+    ReticleDir.PROJECT_FILE,
+    ReticleDir.AMBIENT_FILE,
+    ReticleDir.ENVELOPES_FILE,
+    ReticleDir.FLAKE_FILE,
+    ReticleDir.TIERS_FILE,
+    '*.log',
+    '*.tmp',
+];
+const HEADER = [
+    '# Written by Reticle, and only about the directory Reticle owns.',
+    '#',
+    '# The entries below are per-machine state — session journals, run artifacts, learned envelopes.',
+    '# Journals contain URLs, request and response bodies and page text from the app under test, so',
+    '# they are worth keeping out of a shared repository on their own account.',
+    '#',
+    `# Deliberately NOT ignored: ${ReticleDir.CONTRACT_FILE}, ${ReticleDir.FLOWS_SUBDIR}/, ${ReticleDir.BASELINES_SUBDIR}/ and`,
+    `# ${ReticleDir.CAPSULES_SUBDIR}/. Those are meant to be committed — a saved flow only earns its keep`,
+    '# when a teammate or CI can replay it.',
+    '#',
+    '# Edit freely: Reticle writes this once and never rewrites it.',
+];
+/**
+ * Write `.reticle/.gitignore` if it is not already there.
+ *
+ * Never overwrites — once the file exists it belongs to whoever edited it last, and silently
+ * reverting somebody's change to a file we placed in their repository is worse than not having
+ * written it. Best-effort throughout: this runs on the daemon's start path, and a workspace that
+ * cannot be written must not stop a daemon coming up. Nothing about verification depends on it.
+ */
+export async function ensureWorkspaceGitignore(fs, root) {
+    const path = join(root, '.gitignore');
+    try {
+        if (await fs.exists(path))
+            return;
+        await fs.mkdir(root);
+        await fs.writeFile(path, `${[...HEADER, '', ...TRANSIENT].join('\n')}\n`);
+    }
+    catch {
+        /* a workspace we cannot write is not a reason to fail a session */
+    }
+}

package/dist/license/license.js

@@ -161,7 +161,7 @@ export function describeLicense(now, env = process.env, baked = BAKED_ISSUER_PUB
             }
             : {
                 status: 'eval',
-                detail: 'evaluation mode — enterprise features run free (no issuer key configured)',
+                detail: 'evaluation mode: enterprise features run free (no issuer key configured)',
             };
     }
     const publicKey = loadPublicKey(pem);

package/dist/mcp/mcp-proxy.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Re-exported so every existing caller (and every spec) keeps importing the proxy's log from the
+ * proxy. Where the code lives is a file-size decision; where it is imported from is an API.
+ */
+export { accountProxyLogWrite, proxyLog, proxyLogPath, PROXY_LOG_CHECK_BYTES, recoverOversizedProxyLog, setProxyLogPort, } from './proxy-log.js';
 /**
  * Overridable so the survival spec can reach exhaustion in seconds instead of minutes — the same
  * reason the idle windows take an env override. A positive integer only; anything else falls back,
@@ -7,23 +12,6 @@ export declare const MAX_RECONNECT_ATTEMPTS: number;
 export declare function reconnectDelayMs(attempt: number): number;
 /** JSON-RPC id the proxy uses for its own replayed `initialize` — never one the client could send. */
 export declare const RECONNECT_INITIALIZE_ID = "__reticle_proxy_reinit";
-/** Name the proxy log after the port it serves. Called before anything can log. */
-export declare function setProxyLogPort(port: number): void;
-/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
-export declare function proxyLogPath(port?: number | undefined): string;
-/**
- * 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 declare function proxyLog(event: string, fields?: Record<string, unknown>): void;
 /**
  * JSON-RPC requests forwarded on behalf of the client that have not been answered yet.
  *
@@ -56,9 +44,36 @@ export declare class PendingRequests {
  * daemon under a live client left 20 of 20 concurrent calls hanging until the client's own timeout,
  * with the MCP server still perfectly alive. An agent cannot tell that apart from "still working".
  */
-export declare function streamLossReplies(pending: PendingRequests, reason: string): string[];
-/** The one shape every "the transport ate your call" answer takes, whichever leg died. */
-export declare function transportLossReply(id: unknown, reason: string): string;
+export declare function streamLossReplies(pending: PendingRequests, reason: string, nextStep?: string): string[];
+/**
+ * The one shape every "the transport ate your call" answer takes, whichever leg died.
+ *
+ * `nextStep` is appended when the caller knows one. Without it this reply describes a condition and
+ * stops there, which is all a first-run user got out of their first ever tool call.
+ */
+export declare function transportLossReply(id: unknown, reason: string, nextStep?: string): string;
+/**
+ * How long a request may sit in the queue, unsent, before the proxy answers it itself.
+ *
+ * The second population the stress test found. A request that was FORWARDED and lost is failed when
+ * the stream drops; one that never got forwarded — queued while dormant or reconnecting — was
+ * waiting for a session that, with a squatter holding the port, never arrives. It then hung until
+ * the client's own timeout, or forever if the client has none.
+ *
+ * Comfortably longer than a daemon restart (~1-2s) so a normal blip still flushes and succeeds, and
+ * well under the 60s an MCP client typically allows, so the answer comes from us with a reason
+ * rather than from their timer with none.
+ */
+export declare const QUEUE_WAIT_MS = 20000;
+/** Retry a first connect, or report it? Pure, so the window can be held against the queue's. */
+export declare function shouldRetryFirstConnect(error: unknown, elapsedMs: number): boolean;
+/**
+ * What to do about it, carried on the reply the queue expiry sends.
+ *
+ * A bare -32001 on the first call after an install says nothing a user can act on: not whether to
+ * wait, not whether to retry, not whether the install itself is broken.
+ */
+export declare function queueExpiryNextStep(port: number): string;
 /**
  * Makes a reconnect invisible to the client.
  *
@@ -115,15 +130,6 @@ export declare function waitForDaemon(port: number): Promise<void>;
  * to reconnect and how to answer what it cannot send.
  */
 export declare function buildSessionUrl(rawData: string, port: number): string | null;
-/**
- * Bridge stdio ↔ SSE: connects to the running daemon's MCP endpoint and forwards
- * Claude Code's stdin/stdout JSON-RPC through it. Never resolves — runs until stdin closes.
- *
- * A dropped SSE stream used to exit the process, which is what made the agent's `reticle_*` tools
- * vanish mid-session with no message and no way for the agent to get them back — only a human running
- * `/mcp` could. The daemon demonstrably stays up across these drops, so the stream ending is a
- * transport event, not a shutdown: reconnect to it and replay the handshake instead of dying.
- */
 export declare function startMcpProxy(port: number, 
 /**
  * Bring a daemon back before reconnecting. Without it the proxy retried a DEAD port until the
@@ -131,4 +137,3 @@ export declare function startMcpProxy(port: number,
  * failure mode for a daemon that crashed, was stopped, or shut itself down as idle.
  */
 ensureDaemon?: () => Promise<void>): Promise<never>;
-export {};