@reticlehq/server 2.5.0 → 2.6.0

package/dist/mcp/mcp-proxy.js

@@ -373,8 +373,21 @@ function postToSession(url, body) {
         req.end();
     });
 }
+/**
+ * Turn an `endpoint` frame's data into a POST target, or null when there is nothing usable in it.
+ *
+ * An empty (or whitespace) data field is the shape a malformed daemon response takes, and it used to
+ * be accepted: `postUrl` became `''`, which is not `null`, so the proxy considered itself CONNECTED
+ * and posted every subsequent message to the empty string. Each one failed, the queue never armed
+ * its deadline because nothing was ever queued, and the agent held a session that could not carry a
+ * single call. Refusing the frame keeps the proxy in its disconnected path, which already knows how
+ * to reconnect and how to answer what it cannot send.
+ */
 export function buildSessionUrl(rawData, port) {
-    return rawData.startsWith('/') ? `http://${LOOPBACK_HOST}:${port}${rawData}` : rawData;
+    const trimmed = rawData.trim();
+    if ('' === trimmed)
+        return null;
+    return trimmed.startsWith('/') ? `http://${LOOPBACK_HOST}:${port}${trimmed}` : trimmed;
 }
 /**
  * Bridge stdio ↔ SSE: connects to the running daemon's MCP endpoint and forwards
@@ -469,6 +482,13 @@ ensureDaemon) {
         function onSseEvent(event, data, p) {
             if ('endpoint' === event) {
                 const url = buildSessionUrl(data, p);
+                if (null === url) {
+                    proxyLog('reticle_mcp_proxy_empty_endpoint', {
+                        port,
+                        note: 'endpoint frame carried no URL; staying disconnected rather than posting to nowhere',
+                    });
+                    return;
+                }
                 postUrl = url;
                 // A stream that reached `endpoint` is a USABLE session — that, not a set of response
                 // headers, is what earns a fresh retry budget. Resetting on headers let a daemon that
@@ -491,18 +511,19 @@ ensureDaemon) {
                 emit(data);
             }
         }
-        function scheduleReconnect(reason, detail) {
+        function scheduleReconnect(reason, detail, pendingLost = 0) {
             if (stopped)
                 return;
             postUrl = null;
             attempts++;
             // Once per process: this session has now lost its tools at least once, which is the number
-            // that says whether the transport work actually landed for real users.
-            reportMcpOutage(OutageStage.FIRST, { reason, attempts });
+            // that says whether the transport work actually landed for real users. `pendingLost` is the
+            // part an agent can FEEL — 320 of 321 measured drops killed nothing in flight.
+            reportMcpOutage(OutageStage.FIRST, { reason, attempts, pendingLost });
             // The severe stage: we are about to stop retrying. Reported so the share of sessions where
             // MCP never came back on its own is a number rather than an anecdote.
             if (attempts > MAX_RECONNECT_ATTEMPTS) {
-                reportMcpOutage(OutageStage.BUDGET_SPENT, { reason, attempts });
+                reportMcpOutage(OutageStage.BUDGET_SPENT, { reason, attempts, pendingLost });
                 // Stop RETRYING, never stop SERVING. See onReconnectBudgetSpent: exiting here made the
                 // client mark the MCP server disconnected and left a human to reconnect it by hand.
                 dormant = onReconnectBudgetSpent() === OnDrop.DORMANT;
@@ -557,9 +578,11 @@ ensureDaemon) {
                     settled = true;
                     // Answer anything the dead session owed BEFORE reconnecting. The new session cannot know
                     // about it, so silence here is permanent.
-                    for (const reply of streamLossReplies(pending, reason))
+                    const lost = streamLossReplies(pending, reason);
+                    for (const reply of lost)
                         emit(reply);
-                    scheduleReconnect(reason, detail);
+                    // How many calls this drop actually killed. Zero means the agent could not feel it.
+                    scheduleReconnect(reason, detail, lost.length);
                 };
                 const sse = new SseFrameParser();
                 res.on('data', (chunk) => {

package/dist/mcp/mcp.js

@@ -30,6 +30,27 @@ export function withSessionEnvelope(name, outputSchema) {
     return { ...sessionEnvelopeShape, ...outputSchema };
 }
 const SERVER_INFO = { name: MCP_SERVER_NAME, version: SERVER_VERSION };
+/**
+ * What every agent is told at `initialize`, before it has called a single tool.
+ *
+ * This is the only channel that reaches an agent with NO dependency on the project: no CLAUDE.md, no
+ * AGENTS.md, no pasted skill, no successful `reticle init`. An agent whose setup half-worked has read
+ * none of those files and is precisely the agent whose report we need — so the standing instruction
+ * to send feedback has to live here, where it arrives with the connection itself.
+ *
+ * Kept to a handful of lines: it is prepended to every session's context, so each sentence is paid
+ * for on every turn, forever.
+ */
+const SERVER_INSTRUCTIONS = `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.
+
+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.`;
 /** First sentence of a description (purpose only) for lean profiles — keeps per-turn def cost
  * down. Cuts at the first sentence-ending period or newline; falls back to a 160-char cap. The
  * first clause retains the essentials (enum hints like "role | text | label" live there). */
@@ -292,7 +313,11 @@ function toolNameOf(request) {
 }
 export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT) {
     const encoding = (process.env[ENCODING_ENV] ?? '').toLowerCase();
-    const server = new McpServer(SERVER_INFO);
+    // Which surface this daemon advertises. The 18-tool default and the 48-tool full surface are
+    // different products from inside an agent's context, so outcomes are only comparable when the
+    // session says which one it saw.
+    getSessionMetrics().recordSurface(profile);
+    const server = new McpServer(SERVER_INFO, { instructions: SERVER_INSTRUCTIONS });
     // Which agent is on the other end, taken from its own `initialize` handshake. Registered as a lazy
     // hook rather than read here: the handshake has not happened yet at construction time, and a
     // feedback report filed twenty tool calls later is exactly when we want the answer.
@@ -300,8 +325,10 @@ export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT) {
         const info = server.server.getClientVersion();
         // Record it as a side effect of the first read so the session summary can report WHICH agents
         // drove this daemon — the multi-agent story, visible without a second plumbing path.
+        // Name AND version: the version was already in this handshake and was being dropped, so a
+        // regression in agent behaviour could never be attributed to a client build.
         if (info?.name !== undefined)
-            getSessionMetrics().recordClient(info.name);
+            getSessionMetrics().recordClient(info.name, info.version);
         return info === undefined ? undefined : { name: info.name, version: info.version };
     });
     // Cast once to our bridge type so every per-tool call site is typed without `any`.

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

@@ -77,6 +77,15 @@ export declare class BrowserPool {
      * forever. Returns the released sessionIds. This is the fault-tolerance backstop for the pool.
      */
     sweepExpired(): Promise<string[]>;
+    /**
+     * How many leases this pool has reclaimed for going stale.
+     *
+     * Read by the no-session diagnosis: an aged-out lease used to be reported as "the tab was closed
+     * … ask the human to reopen the app", which is wrong on every clause and sent one reporter looking
+     * for a port mismatch (#157). A count is enough — the message says "likeliest", not "certainly",
+     * because nothing here knows WHICH session the caller just lost.
+     */
+    reapedLeaseCount(): number;
     /**
      * Lease an isolated context, navigate it to `url`, and return a handle. If the pool is at capacity,
      * waits FIFO until a slot frees (or until `signal` aborts, if provided).

package/dist/pool/browser-pool.js

@@ -27,6 +27,8 @@ export class BrowserPool {
     #browser;
     #launching;
     #closed = false;
+    /** Leases reclaimed for going stale — see reapedLeaseCount(). */
+    #reapedLeases = 0;
     #active = new Map();
     /**
      * Slots claimed-or-active — the real concurrency gate. Incremented SYNCHRONOUSLY the instant an
@@ -85,8 +87,20 @@ export class BrowserPool {
             .map(([sessionId]) => sessionId);
         for (const sessionId of expired)
             await this.#release(sessionId);
+        this.#reapedLeases += expired.length;
         return expired;
     }
+    /**
+     * How many leases this pool has reclaimed for going stale.
+     *
+     * Read by the no-session diagnosis: an aged-out lease used to be reported as "the tab was closed
+     * … ask the human to reopen the app", which is wrong on every clause and sent one reporter looking
+     * for a port mismatch (#157). A count is enough — the message says "likeliest", not "certainly",
+     * because nothing here knows WHICH session the caller just lost.
+     */
+    reapedLeaseCount() {
+        return this.#reapedLeases;
+    }
     /**
      * Lease an isolated context, navigate it to `url`, and return a handle. If the pool is at capacity,
      * waits FIFO until a slot frees (or until `signal` aborts, if provided).
@@ -138,6 +152,15 @@ export class BrowserPool {
         this.#active.clear();
         this.#occupied = 0;
         await Promise.all(contexts.map((c) => c.close().catch(() => undefined)));
+        // If a launch is in flight, await it so we can close the resulting browser — otherwise it
+        // resolves after shutdown returns and the Chromium process is orphaned (hundreds of MB leaked).
+        const inflight = this.#launching;
+        if (inflight !== undefined) {
+            const launched = await inflight.catch(() => undefined);
+            if (launched !== undefined && launched !== this.#browser) {
+                await launched.close().catch(() => undefined);
+            }
+        }
         const browser = this.#browser;
         this.#browser = undefined;
         if (browser !== undefined)
@@ -168,27 +191,33 @@ export class BrowserPool {
             const onFree = () => {
                 // The pool shut down while we waited → reject rather than relaunch a browser.
                 if (this.#closed) {
+                    if (signal !== undefined)
+                        signal.removeEventListener('abort', onAbort);
                     reject(new Error('browser pool is shut down'));
                     return;
                 }
                 // Claim the freed slot; if another woken waiter beat us to it, re-queue.
-                if (this.#tryClaim())
+                if (this.#tryClaim()) {
+                    if (signal !== undefined)
+                        signal.removeEventListener('abort', onAbort);
                     resolve();
-                else
+                }
+                else {
                     this.#waiters.push(onFree);
+                }
+            };
+            const onAbort = () => {
+                const i = this.#waiters.indexOf(onFree);
+                if (i >= 0)
+                    this.#waiters.splice(i, 1);
+                reject(new Error('acquire aborted'));
             };
             if (signal !== undefined) {
                 if (signal.aborted) {
                     reject(new Error('acquire aborted'));
                     return;
                 }
-                signal.addEventListener('abort', () => {
-                    // Remove ourselves from the queue so a later wake doesn't claim a slot we'll never use.
-                    const i = this.#waiters.indexOf(onFree);
-                    if (i >= 0)
-                        this.#waiters.splice(i, 1);
-                    reject(new Error('acquire aborted'));
-                }, { once: true });
+                signal.addEventListener('abort', onAbort, { once: true });
             }
             this.#waiters.push(onFree);
         });

package/dist/session/attachment-history.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Whether a session was attached for the whole window an agent is about to reason about.
+ *
+ * `reticle_sessions` answers "which tabs are connected RIGHT NOW", and **a tab that dropped for four
+ * seconds and came back looks identical to one that never dropped** (#117). That is the difference
+ * between a verdict you can trust and one that describes what you happened to see — the same problem
+ * `honesty.integrity` solves for a single action, applied to the session.
+ *
+ * Measured HERE rather than reported by the SDK. The browser transport does track
+ * `#disconnectedSince` (`transport.ts:95`), and reading it would need a wire change and a new thing
+ * for every SDK version to remember to send. The daemon already sees both halves — `remove()` when
+ * the socket drops, `add()` when it returns — so the gap is computable with no protocol change at
+ * all, and it cannot drift out of sync with what the daemon actually observed.
+ *
+ * The clock is injected, per the repo rule: this is arithmetic over timestamps, and a test that
+ * needs to wait four seconds to check a four-second gap is a test nobody runs.
+ */
+/** What an agent needs to know about the continuity of one session. */
+export interface Attachment {
+    /** How long THIS attachment has lasted. Resets on reconnect — it is not the session's lifetime. */
+    connectedSinceMs: number;
+    /** How many times this session dropped and came back. Zero means it never left. */
+    outages: number;
+    /** The most recent gap, when there has been one. */
+    lastOutage?: {
+        startedMs: number;
+        durationMs: number;
+    };
+}
+export declare class AttachmentHistory {
+    #private;
+    constructor(now?: () => number);
+    /** A session connected, or reconnected. A reconnect closes the open gap and counts an outage. */
+    attached(sessionId: string): void;
+    /** A session dropped. The gap stays open until it comes back, or the record is forgotten. */
+    detached(sessionId: string): void;
+    /** Drop a session's history. A long-lived daemon must not accumulate one record per tab forever. */
+    forget(sessionId: string): void;
+    /**
+     * The continuity of one session, or `undefined` when it has never been seen.
+     *
+     * Undefined rather than a zeroed record on purpose: `outages: 0` reads as "it never dropped", which
+     * is a confident claim about a session this has no knowledge of.
+     */
+    of(sessionId: string): Attachment | undefined;
+}

package/dist/session/attachment-history.js

@@ -0,0 +1,65 @@
+/**
+ * Whether a session was attached for the whole window an agent is about to reason about.
+ *
+ * `reticle_sessions` answers "which tabs are connected RIGHT NOW", and **a tab that dropped for four
+ * seconds and came back looks identical to one that never dropped** (#117). That is the difference
+ * between a verdict you can trust and one that describes what you happened to see — the same problem
+ * `honesty.integrity` solves for a single action, applied to the session.
+ *
+ * Measured HERE rather than reported by the SDK. The browser transport does track
+ * `#disconnectedSince` (`transport.ts:95`), and reading it would need a wire change and a new thing
+ * for every SDK version to remember to send. The daemon already sees both halves — `remove()` when
+ * the socket drops, `add()` when it returns — so the gap is computable with no protocol change at
+ * all, and it cannot drift out of sync with what the daemon actually observed.
+ *
+ * The clock is injected, per the repo rule: this is arithmetic over timestamps, and a test that
+ * needs to wait four seconds to check a four-second gap is a test nobody runs.
+ */
+export class AttachmentHistory {
+    #now;
+    #records = new Map();
+    constructor(now = Date.now) {
+        this.#now = now;
+    }
+    /** A session connected, or reconnected. A reconnect closes the open gap and counts an outage. */
+    attached(sessionId) {
+        const at = this.#now();
+        const prior = this.#records.get(sessionId);
+        if (prior?.detachedAt === undefined) {
+            this.#records.set(sessionId, { attachedAt: at, outages: prior?.outages ?? 0 });
+            return;
+        }
+        this.#records.set(sessionId, {
+            attachedAt: at,
+            outages: prior.outages + 1,
+            lastOutage: { startedMs: prior.detachedAt, durationMs: at - prior.detachedAt },
+        });
+    }
+    /** A session dropped. The gap stays open until it comes back, or the record is forgotten. */
+    detached(sessionId) {
+        const prior = this.#records.get(sessionId);
+        if (prior === undefined)
+            return;
+        this.#records.set(sessionId, { ...prior, detachedAt: this.#now() });
+    }
+    /** Drop a session's history. A long-lived daemon must not accumulate one record per tab forever. */
+    forget(sessionId) {
+        this.#records.delete(sessionId);
+    }
+    /**
+     * The continuity of one session, or `undefined` when it has never been seen.
+     *
+     * Undefined rather than a zeroed record on purpose: `outages: 0` reads as "it never dropped", which
+     * is a confident claim about a session this has no knowledge of.
+     */
+    of(sessionId) {
+        const record = this.#records.get(sessionId);
+        if (record === undefined)
+            return undefined;
+        return {
+            connectedSinceMs: this.#now() - record.attachedAt,
+            outages: record.outages,
+            ...(record.lastOutage === undefined ? {} : { lastOutage: record.lastOutage }),
+        };
+    }
+}

package/dist/session/no-session-diagnosis.d.ts

@@ -27,6 +27,13 @@ interface NoSessionFacts {
     listening: readonly number[];
     /** The port this daemon is on — half of the mismatch the old message asked about. */
     port: number;
+    /**
+     * This daemon has reaped at least one EXPIRED pooled lease.
+     *
+     * Deliberately not "the session that just vanished was that lease" — nothing knows that. It is
+     * evidence, not proof, and the message below is worded accordingly.
+     */
+    leaseExpired?: boolean;
 }
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session

package/dist/session/no-session-diagnosis.js

@@ -18,6 +18,7 @@
  * Pure: everything it needs is passed in, so the probe that discovers listening ports stays out of
  * the hot resolve() path and this stays unit-testable.
  */
+import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session
  * recovery: a message that already carries its own next action must not be handed a second, more
@@ -42,18 +43,67 @@ const RETRY = SELF_RECOVERING_MARKER;
 const SELF_SERVE = 'You do not have to wait for the human: reticle_lease {action:"acquire", url} opens a browser ' +
     'Reticle drives itself, and returns a sessionId you can use immediately (reach it with ' +
     'reticle_run {tool:"reticle_lease"} if it is not advertised directly; release it when you finish).';
+/**
+ * The ports the scan actually covers, rendered for the message.
+ *
+ * Derived from DEV_SERVER_PORTS rather than re-typed: a message that lists ports the scan does not
+ * check, or omits ones it does, is a new version of the same defect — a confident claim about
+ * evidence that was never gathered.
+ */
+/**
+ * The second half of the answer for a project that never went through `init`.
+ *
+ * Held separately because it must appear ONLY when the project is uninstrumented — telling a wired
+ * project to re-run `init` sends the reader back to a step that already succeeded, which is its own
+ * kind of wrong answer.
+ */
+const UNINSTRUMENTED = 'Separately: this project has not been through `reticle init`, which is what installs the SDK ' +
+    'and wires it into the build — so even once the dev server is up, the app will carry no SDK and ' +
+    "no session will appear. Run `reticle init` in the app's directory too.";
+const SCANNED_PORTS = [...DEV_SERVER_PORTS].join(', ');
 export function diagnoseNoSession(facts) {
     const { everConnected, initialized, listening, port } = facts;
     const ports = listening.join(', ');
     if (everConnected) {
+        // A reaped lease first, because it is the one cause we have POSITIVE evidence for. Reported
+        // from the field (#157): an aged-out lease produced "the tab was closed … ask the human to
+        // reopen the app", which is wrong on every clause — there is no human tab, and the recovery it
+        // names is unavailable to the caller while the one that works goes unmentioned. The reporter
+        // went looking for a port mismatch. Hedged rather than swapped: a human tab may ALSO have
+        // closed, and this does not know which session went.
+        if (true === facts.leaseExpired) {
+            return ('no browser session connected — but one WAS connected to this daemon earlier, so the wiring ' +
+                'is correct. This daemon has expired at least one pooled lease, so the likeliest cause is ' +
+                'that a lease you were using aged out; a lease is a headless context, not a human tab, and ' +
+                'it takes its cookies with it (so an authenticated app needs signing in again). Re-acquire ' +
+                'with reticle_lease {action:"acquire", url} and carry on. If you were driving a human tab ' +
+                `instead, it went away — reopen it or run \`reticle open\`. ${RETRY}`);
+        }
         return ('no browser session connected — but one WAS connected to this daemon earlier, so the wiring ' +
             'is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen ' +
             `the app (or run \`reticle open\`), or reload the tab. ${SELF_SERVE} ${RETRY}`);
     }
     if (0 === listening.length) {
-        return ('no browser session connected, and nothing is listening on any of the usual dev-server ports ' +
-            '— so the app is almost certainly not running. This is not a Reticle wiring problem: ask the ' +
-            `human to start their dev server (\`npm run dev\`), then open the app in a browser. ${RETRY}`);
+        return ('no browser session connected, and nothing is listening on the ports Reticle scans ' +
+            `(${SCANNED_PORTS}). The likeliest cause by far is that the dev server is not running: ask ` +
+            'the human to start it (`npm run dev`), then open the app in a browser. ' +
+            // The caveat is here rather than omitted because the scan is NARROW, and the old sentence
+            // spent its confidence as though an empty result from eleven ports were proof of absence.
+            // Reported from a scripted drive of 2.5.0: this branch asserted the app was not running while
+            // it served 200 on :7699. A dev server on any other port — 4173 from `vite preview`, 1420
+            // from Tauri, 5175 from a second Vite, anything passed to --port — is invisible to it.
+            'That scan is narrow, so it is not proof: a server on any other port is invisible to it. If ' +
+            // Deliberately NOT offering reticle_lease here, and a test pins that: a lease opens a URL, and
+            // if nothing is listening there is nothing at any URL to open. Asking for the real one is the
+            // only move that can recover the :7699 case.
+            'the app IS running, ask the human for its URL rather than assuming it is down. ' +
+            // BOTH facts at once when the project was never wired. This branch fires before the
+            // `!initialized` one, so an uninstrumented project used to be told only "start your dev
+            // server" — the reader starts it, calls again, and is told ONLY THEN that no app carries the
+            // SDK. Two round trips to learn two things the daemon knew on the first call, and this is the
+            // largest cohort in the funnel (#171): 77 users attached an agent and never instrumented an
+            // app. They have a daemon (they registered the MCP server) and no SDK anywhere.
+            `${initialized ? '' : UNINSTRUMENTED} ${RETRY}`);
     }
     if (!initialized) {
         return (`no browser session connected, but something IS listening on port ${ports} — so a server is ` +

package/dist/session/no-session-watch.d.ts

@@ -16,4 +16,6 @@ import type { SessionManager } from './session-manager.js';
  * this directory has been through `reticle init` — so they belong together rather than as two
  * adjacent blocks in the bootstrap.
  */
-export declare function wireSessionScope(sessions: SessionManager, activeProjectId: string | undefined, port: number): () => void;
+export declare function wireSessionScope(sessions: SessionManager, activeProjectId: string | undefined, port: number, 
+/** Reader for the pool's aged-out-lease count; omitted when this daemon runs no pool. */
+reapedLeases?: () => number): () => void;

package/dist/session/no-session-watch.js

@@ -42,6 +42,7 @@ function startNoSessionWatch(options) {
         initialized: options.initialized,
         listening,
         port: options.port,
+        leaseExpired: (options.reapedLeases?.() ?? 0) > 0,
     }));
     return () => {
         clearInterval(timer);
@@ -54,8 +55,15 @@ function startNoSessionWatch(options) {
  * this directory has been through `reticle init` — so they belong together rather than as two
  * adjacent blocks in the bootstrap.
  */
-export function wireSessionScope(sessions, activeProjectId, port) {
+export function wireSessionScope(sessions, activeProjectId, port, 
+/** Reader for the pool's aged-out-lease count; omitted when this daemon runs no pool. */
+reapedLeases) {
     if (activeProjectId !== undefined)
         sessions.setDefaultScope({ projectId: activeProjectId });
-    return startNoSessionWatch({ sessions, port, initialized: activeProjectId !== undefined });
+    return startNoSessionWatch({
+        sessions,
+        port,
+        initialized: activeProjectId !== undefined,
+        ...(reapedLeases === undefined ? {} : { reapedLeases }),
+    });
 }

package/dist/session/pending-commands.js

@@ -13,6 +13,7 @@ export class PendingCommands {
                 this.#pending.delete(id);
                 reject(new Error(describeTimeout()));
             }, timeoutMs);
+            timer.unref();
             this.#pending.set(id, { resolve, reject, timer });
         });
     }

package/dist/session/session-info.d.ts

@@ -4,7 +4,8 @@ export interface SessionInfo {
     url: string;
     /** Stable build-stamped project identity; absent for v1.0 SDKs that don't send it. */
     projectId?: string;
-    title: string;
+    /** Absent when the page has no title — never the empty string. Fall back to `url`. */
+    title?: string;
     adapters: string[];
     hasCapabilities: boolean;
     /** Present only when the page's SDK version differs from the daemon's — see version-skew.ts. */
@@ -22,6 +23,21 @@ export interface SessionInfo {
     pendingMarks?: number;
     /** present with pendingMarks — nudges the agent to drain them with reticle_review. */
     review_suggestion?: string;
+    /**
+     * Continuity of this attachment — `{ connectedSinceMs, outages, lastOutage? }`.
+     *
+     * A tab that dropped for four seconds and came back is indistinguishable from one that never left
+     * (#117), and that difference decides whether a verdict over the window can be trusted. Attached
+     * by `SessionManager.list()`, which is the layer that sees every connect and disconnect.
+     */
+    attachment?: {
+        connectedSinceMs: number;
+        outages: number;
+        lastOutage?: {
+            startedMs: number;
+            durationMs: number;
+        };
+    };
 }
 /** The read-only slice of a Session that the projection needs. Keeps this module class-free. */
 interface SessionView {

package/dist/session/session-info.js

@@ -18,7 +18,11 @@ export function buildSessionInfo(session) {
         sessionId: session.id,
         url: session.url,
         ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
-        title: session.title,
+        // Omitted when blank, never `""`. An empty title cannot be told apart from "we sampled before
+        // the page set one", and two such tabs make the listing unusable. Moving the sample later does
+        // not fix it — a page may set its title after connect, or never — so the projection refuses the
+        // bad answer and the reader falls back to `url`, which is right here in the same record.
+        ...('' === session.title.trim() ? {} : { title: session.title }),
         adapters: session.adapters,
         hasCapabilities: session.hasCapabilities,
         // On every listing, not buried in a log — skew explains failures that read as app bugs.

package/dist/session/session-manager.d.ts

@@ -1,4 +1,5 @@
 import { Session, type SessionInfo } from './session.js';
+import { AttachmentHistory } from './attachment-history.js';
 /**
  * The agent's active project, used to scope auto-selection. `projectId` is the stable build-stamped
  * identity (authoritative when present); `url` is the app origin, a fallback hint for older SDKs that
@@ -18,6 +19,8 @@ export declare class SessionManager {
     remove(session: Session): boolean;
     get(sessionId: string): Session | undefined;
     list(): SessionInfo[];
+    /** Continuity for one session — "has this been attached the whole time I am reasoning about?" */
+    attachmentOf(sessionId: string): ReturnType<AttachmentHistory['of']>;
     /** Every connected session — used by the liveness reaper to sweep for idle/disconnected ones. */
     all(): Session[];
     count(): number;