@reticlehq/server 2.5.0 → 2.7.0

package/dist/pool/playwright-launcher.js

@@ -8,6 +8,7 @@
 import { BrowserLaunchKind } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../telemetry/connect-failure.js';
+import { chromiumInstallCommand, bundledPlaywrightVersion } from '../cli/chromium-hint.js';
 /**
  * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
  * the rest of this file needs a real Chromium.
@@ -48,8 +49,15 @@ function wrapBrowser(browser) {
         onDisconnected: (handler) => browser.on('disconnected', handler),
     };
 }
-/** The fix for the most common first-run failure: Chromium isn't installed for Playwright. */
-const CHROMIUM_MISSING_HINT = 'Chromium is not installed for Playwright. Run: npx playwright install chromium';
+/**
+ * The fix for the most common first-run failure: Chromium isn't installed for Playwright.
+ *
+ * Pinned to the playwright this process bundles. Unpinned, `npx` fetches the latest playwright and
+ * installs ITS browser revision — a build this launcher will never look at — so the user follows the
+ * advice, it succeeds, and the next launch fails identically. Shares one builder with `doctor` so the
+ * two cannot suggest different commands for the same missing browser.
+ */
+const CHROMIUM_MISSING_HINT = `Chromium is not installed for Playwright. Run: ${chromiumInstallCommand(bundledPlaywrightVersion())}`;
 /** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
 export function playwrightLauncher(opts = {}) {
     const headless = opts.headless ?? true;

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/live-control-tools.js

@@ -93,12 +93,37 @@ export const LIVE_CONTROL_TOOLS = [
         description: 'Drain and return any messages the human queued from the panel since the last poll. Use to ' +
             'explicitly check for human guidance without acting.',
         inputSchema: { ...sessionIdShape },
-        outputSchema: { messages: z.array(z.unknown()) },
+        outputSchema: {
+            messages: z.array(z.unknown()),
+            delivered: z
+                .array(z.unknown())
+                .optional()
+                .describe('Present ONLY when this poll found nothing new but the human HAS spoken this session: everything they said, including what was already handed to you inline on an earlier tool result. An empty `messages` never means silence.'),
+        },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
+            const messages = session.drainInbox();
+            if (messages.length > 0)
+                return Promise.resolve({ messages });
+            // Nothing NEW is not the same as nothing said. The inbox has two consumers — this poll and the
+            // control envelope spliced onto every tool result — and delivery is destructive, so a message
+            // handed over inline moments ago left this call reporting an empty queue with a note that read
+            // as "the human has said nothing". Reported from the field, from both ends: the agent believed
+            // it, and the person who typed the message got silence with no sign it had been seen.
+            const history = session.inboxHistory();
+            if (history.length > 0) {
+                return Promise.resolve({
+                    messages,
+                    delivered: [...history],
+                    note: `nothing NEW since your last poll — but the human has sent ` +
+                        `${String(history.length)} message(s) this session, listed in \`delivered\`. They were ` +
+                        `handed to you inline on an earlier tool result, which is why this queue is empty. An ` +
+                        `empty \`messages\` never means the human has said nothing.`,
+                });
+            }
             // An empty inbox and a panel that is not wired both return `[]`. The first means the human has
             // said nothing; the second means an agent is waiting on a channel that does not exist.
-            return Promise.resolve(noteEmptyRead({ messages: session.drainInbox() }, 'messages', {
+            return Promise.resolve(noteEmptyRead({ messages }, 'messages', {
                 noun: 'messages from the human since the last poll',
             }));
         },
@@ -126,16 +151,26 @@ export const LIVE_CONTROL_TOOLS = [
             marks: z.array(z.unknown()),
             pendingCount: z.number(),
             resolved: z.boolean().optional(),
+            resolvedNote: z
+                .string()
+                .optional()
+                .describe('The note on the mark that was actually retired. CHECK IT against the mark you meant to resolve: a bare `resolved:true` cannot tell you it closed the right one, and ids are only meaningful while the session that issued them lives.'),
         },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const resolveId = asString(args['resolve']);
             let resolved;
+            let resolvedNote;
             if (resolveId !== undefined) {
                 // Grab the note BEFORE retiring it so we can close the loop visually for the human.
                 const mark = session.allMarks().find((m) => m.id === resolveId);
                 resolved = session.resolveMark(resolveId);
                 if (resolved && mark !== undefined) {
+                    // Echoed back to the CALLER too, not only to the panel. A bare `resolved:true` is equally
+                    // consistent with "I retired the bug you fixed" and "I retired somebody else's", and an
+                    // agent hit exactly that — it closed a mark the human had recorded minutes later while
+                    // the two it had actually fixed vanished with no record.
+                    resolvedNote = mark.note;
                     // The human watching the panel sees their flagged bug get marked fixed (fire-and-forget).
                     session.pushNarration(`✓ fixed: ${mark.note}`);
                 }
@@ -148,6 +183,8 @@ export const LIVE_CONTROL_TOOLS = [
             };
             if (resolved !== undefined)
                 out.resolved = resolved;
+            if (resolvedNote !== undefined)
+                out.resolvedNote = resolvedNote;
             return Promise.resolve(out);
         },
     },

package/dist/session/live-control.d.ts

@@ -4,15 +4,6 @@ export interface InboxMessage {
     text: string;
     t: number;
 }
-/**
- * The human-in-the-loop half of a session: its lifecycle state, and the one-way inbox a person uses
- * to talk to the agent driving their browser.
- *
- * Server-owned on purpose — a paused session has to stay paused even if the page reloads, so this
- * cannot live in the tab. Split out of Session because it shares nothing with the transport, the
- * ring buffer, or the journal: it is state a HUMAN changes, on a human's timescale, while everything
- * else in Session is driven by the event stream.
- */
 export declare class LiveControl {
     #private;
     state(): SessionState;
@@ -22,6 +13,13 @@ export declare class LiveControl {
     setState(next: SessionState): void;
     /** Queue a human note. Empty/whitespace-only text is ignored so a stray enter cannot spam the agent. */
     push(text: string, t: number): void;
+    /**
+     * Everything the human has said this session, including what has already been delivered.
+     *
+     * Read-only and non-destructive by design — this is the answer to "did the human say anything
+     * while I was away", which a destructive drain can never give twice.
+     */
+    history(): readonly InboxMessage[];
     /** Return the queued notes AND clear them — delivered once, so a hint never repeats. */
     drain(): InboxMessage[];
     /** Diagnostic read of the inbox depth (does not clear). */

package/dist/session/live-control.js

@@ -8,9 +8,29 @@ import { HumanControlKind, SessionState } from '@reticlehq/core';
  * ring buffer, or the journal: it is state a HUMAN changes, on a human's timescale, while everything
  * else in Session is driven by the event stream.
  */
+/**
+ * How many delivered messages a session remembers.
+ *
+ * Enough that an agent picking up a long session can see what was said; bounded because a session
+ * can run for hours and this is a convenience, not a record.
+ */
+const HISTORY_CAP = 200;
 export class LiveControl {
     #state = SessionState.ACTIVE;
     #inbox = [];
+    /**
+     * Everything the human has said this session, delivered or not.
+     *
+     * The inbox has TWO consumers — the control envelope on every tool result, and the explicit
+     * message poll — and `drain` is destructive, so whichever ran first took the message and the other
+     * reported an empty queue. That produced a confident "no messages from the human since the last
+     * poll" about a message the human had definitely sent, with no way for the agent to tell the
+     * difference and no acknowledgement for the person who typed it.
+     *
+     * Delivered-once stays: a guidance hint that repeats every turn is noise. This only stops the
+     * delivery from being the same event as the forgetting.
+     */
+    #history = [];
     state() {
         return this.#state;
     }
@@ -29,7 +49,20 @@ export class LiveControl {
         const trimmed = text.trim();
         if (0 === trimmed.length)
             return;
-        this.#inbox.push({ text: trimmed, t });
+        const message = { text: trimmed, t };
+        this.#inbox.push(message);
+        this.#history.push(message);
+        if (this.#history.length > HISTORY_CAP)
+            this.#history.splice(0, this.#history.length - HISTORY_CAP);
+    }
+    /**
+     * Everything the human has said this session, including what has already been delivered.
+     *
+     * Read-only and non-destructive by design — this is the answer to "did the human say anything
+     * while I was away", which a destructive drain can never give twice.
+     */
+    history() {
+        return this.#history;
     }
     /** Return the queued notes AND clear them — delivered once, so a hint never repeats. */
     drain() {

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

@@ -1,10 +1,10 @@
 /**
  * Turning "no browser session connected" from a dead end into a next action.
  *
- * This is the most consequential sentence in the product. Measured over a day of telemetry: 74% of
- * sessions never call a Reticle tool, and of the ones that do, half make exactly ONE call — usually
- * `reticle_sessions` — and stop. Ten of those thirteen never touched a browser, and every recorded
- * session error is this one. The agent asks whether anything is connected, is told no, and leaves.
+ * This is the most consequential sentence in the product. Most sessions never call a Reticle tool at
+ * all, and of the ones that do, a large share make exactly ONE call — usually `reticle_sessions` —
+ * and stop. Almost none of those ever touched a browser, and this is the session error they hit. The
+ * agent asks whether anything is connected, is told no, and leaves.
  *
  * The old message asked the agent to check two things it cannot see from where it stands ("is your
  * app running with the SDK enabled?", "does it point at this port?"). The daemon can actually tell
@@ -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

@@ -1,10 +1,10 @@
 /**
  * Turning "no browser session connected" from a dead end into a next action.
  *
- * This is the most consequential sentence in the product. Measured over a day of telemetry: 74% of
- * sessions never call a Reticle tool, and of the ones that do, half make exactly ONE call — usually
- * `reticle_sessions` — and stop. Ten of those thirteen never touched a browser, and every recorded
- * session error is this one. The agent asks whether anything is connected, is told no, and leaves.
+ * This is the most consequential sentence in the product. Most sessions never call a Reticle tool at
+ * all, and of the ones that do, a large share make exactly ONE call — usually `reticle_sessions` —
+ * and stop. Almost none of those ever touched a browser, and this is the session error they hit. The
+ * agent asks whether anything is connected, is told no, and leaves.
  *
  * The old message asked the agent to check two things it cannot see from where it stands ("is your
  * app running with the SDK enabled?", "does it point at this port?"). The daemon can actually tell
@@ -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
@@ -29,12 +30,12 @@ const RETRY = SELF_RECOVERING_MARKER;
  * The way out that needs no human at all.
  *
  * `reticle_lease` opens a browser Reticle drives itself, instead of waiting for somebody's tab to
- * dial in. Measured over a day of telemetry it is the single strongest predictor of a session that
- * works: the 5 sessions that used it had a MEDIAN of 30 tool calls and produced 46% of every bug
- * found, against a median of 1 call for the 20 active sessions that did not — and not one
- * single-call bounce used one. It is also advertised on no profile except `full`, so an agent only
- * ever finds it if it already knew it existed. Naming it HERE puts it in front of the agent at the
- * one moment it is the answer, and costs nothing on the turns when it is not.
+ * dial in. In the field it is the single strongest predictor of a session that works: sessions that
+ * use it drive an order of magnitude more tool calls than those that do not, they account for a
+ * disproportionate share of every bug found, and no single-call bounce has ever used one. It is also
+ * advertised on no profile except `full`, so an agent only ever finds it if it already knew it
+ * existed. Naming it HERE puts it in front of the agent at the one moment it is the answer, and
+ * costs nothing on the turns when it is not.
  *
  * Only offered when the app is known to carry the SDK: leasing an uninstrumented app just burns a
  * browser and comes back `ready:false`.
@@ -42,18 +43,98 @@ 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 one cause that produces a PERFECTLY healthy everything and still never connects.
+ *
+ * The SDK refuses to dial from a page that is not on localhost unless `allowNonLocalhost` is set.
+ * That is deliberate — Reticle must not be reachable from a page it does not trust — but the refusal
+ * happens page-side, so the daemon sees only silence, `doctor` sees only a healthy daemon, and every
+ * checklist item passes. Reported from the field by an agent on a hosts-file alias (the normal setup
+ * for white-label and multi-tenant apps): the whole setup was lost to a flag named in no checklist,
+ * and `init`'s own fallback snippet guards on `hostname === 'localhost'`, so on such a host the
+ * connect never runs and there is not even a console line to find.
+ *
+ * Only offered on the wired-and-listening branch: that is where a correctly installed app that
+ * cannot connect actually lands.
+ */
+const NON_LOCALHOST_GATE = 'One more cause that leaves every other check healthy: if the app is served on anything other ' +
+    'than localhost (a hosts-file alias, a LAN IP, a tunnel), the SDK refuses to connect unless it ' +
+    'is given `allowNonLocalhost: true` — the refusal is page-side, so nothing here can see it. ' +
+    "Check the browser console for that message and pass the flag in the app's reticle.connect().";
+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}`);
+        // Lead with the stronger EVIDENCE, and do not overstate what it is.
+        //
+        // `initialized` is one thing only: whether a `.reticle.json` sits in the directory this daemon
+        // is running in. It is NOT "this project has never been through `reticle init`", and the two
+        // come apart constantly — a monorepo whose daemon runs at the root while the app lives in
+        // `apps/web`, or any app wired by the babel/vite plugin rather than by `init`. An earlier
+        // version of this branch asserted the strong claim and led with it, on the reasoning that it was
+        // a certainty while the port scan was a guess. It is not a certainty. Caught driving Reticle's
+        // OWN repo, where the message told an agent the project had never been through `init` about a
+        // fixture that is instrumented and working — "the one sentence I was most likely to act on was
+        // wrong", which is the exact failure this whole file exists to prevent.
+        //
+        // So: report what was actually checked, name the directory, and name the case where the absence
+        // is expected rather than diagnostic.
+        if (!initialized) {
+            return ('no browser session connected. Two things to weigh, and neither of them is proof. ' +
+                `(1) Nothing is listening on the ports Reticle scans (${SCANNED_PORTS}), so the dev server ` +
+                'may not be running — ask the human to start it (`npm run dev`). That scan is narrow ' +
+                'though: a server on any other port is invisible to it, so if the app IS running, ask for ' +
+                'its URL rather than assuming it is down. ' +
+                '(2) There is no `.reticle.json` in the directory this daemon is running in. That is the ' +
+                "file `reticle init` writes, so the app may carry no Reticle SDK — but check the app's " +
+                'OWN directory before re-running `init`: in a monorepo the daemon often runs at the root ' +
+                'while the app lives in a subdirectory, and an app wired by the Vite or Babel plugin ' +
+                `carries the SDK without that file at all. ${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 were proof of absence. Reported twice: a
+            // scripted drive of 2.5.0 asserted the app was not running while it served 200 on :7699, and
+            // an agent was told nothing was listening while a dev server answered on :5000 under a custom
+            // hostname. The common defaults have since been added to the scanned set, which narrows the
+            // gap and cannot close it — anything passed to `--port` is still invisible.
+            '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. ' +
+            // Reachable only for a project that HAS been through `init` — the uninstrumented case is
+            // answered above, leading with that certainty instead of behind this scan's guess.
+            `${RETRY}`);
     }
     if (!initialized) {
         return (`no browser session connected, but something IS listening on port ${ports} — so a server is ` +
@@ -66,5 +147,5 @@ export function diagnoseNoSession(facts) {
         `wired for Reticle — so the app is either serving a build made before the wiring landed, or ` +
         `dialling a different daemon than this one (this daemon is on ${String(port)}). Ask the human ` +
         'to restart the dev server and hard-reload the page; if it still does not appear, check that ' +
-        `the app's reticle port matches ${String(port)}. ${SELF_SERVE} ${RETRY}`);
+        `the app's reticle port matches ${String(port)}. ${NON_LOCALHOST_GATE} ${SELF_SERVE} ${RETRY}`);
 }

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/review-store.d.ts

@@ -21,6 +21,15 @@ export interface ReviewMark {
     at: number;
     status: MarkStatus;
 }
+/** Tests only — assertions on `m1` must not depend on which test ran first. */
+export declare function resetMarkIdsForTest(): void;
+/** What `resolve` actually did, including WHICH mark — so a caller can verify it hit the right one. */
+export interface ResolveOutcome {
+    resolved: boolean;
+    id: string;
+    /** The retired mark's note. Absent when nothing was resolved. */
+    note?: string;
+}
 export declare class ReviewStore {
     #private;
     /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
@@ -36,4 +45,14 @@ export declare class ReviewStore {
      * false for an unknown id or an already-resolved mark (so resolve is idempotent).
      */
     resolve(id: string): boolean;
+    /**
+     * Resolve, and say WHICH mark was retired.
+     *
+     * The bare boolean is what made the misattribution silent: `{"resolved":true}` is equally
+     * consistent with "I retired the bug you fixed" and "I retired somebody else's". Echoing the note
+     * lets a caller check the answer against what it believed it was resolving, which is exactly what
+     * the agent that hit this asked for — it had been re-reading the whole list after every resolve
+     * and hand-diffing the notes to get the same assurance.
+     */
+    resolveDetail(id: string): ResolveOutcome;
 }

package/dist/session/review-store.js

@@ -11,14 +11,31 @@ import { MarkStatus } from '@reticlehq/core';
  */
 /** Prefix on review-mark ids (m1, m2, …) — distinguishes them from command ids. */
 const MARK_ID_PREFIX = 'm';
+/**
+ * Shared by every store in the process, so an id is never reissued.
+ *
+ * The sequence used to live on the instance, which looked right and was not: a store is created per
+ * Session, and a Session is recreated on every page reload and socket reattach. Each new store began
+ * again at `m1`, so an id an agent was still holding silently came to denote a DIFFERENT mark — and
+ * `resolve` retired that one instead, reporting success. Reported from the field by an agent that
+ * closed a bug nobody had fixed while the two it had fixed vanished unrecorded.
+ *
+ * Process-wide is deliberately not "forever": a daemon restart resets it, but a restart also
+ * destroys every session, so any id from before it resolves to nothing and `resolve` correctly
+ * returns false. The identity echo below covers what remains.
+ */
+let nextMarkId = 0;
+/** Tests only — assertions on `m1` must not depend on which test ran first. */
+export function resetMarkIdsForTest() {
+    nextMarkId = 0;
+}
 export class ReviewStore {
     #marks = [];
-    #seq = 0;
     /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
     add(data, at) {
-        this.#seq += 1;
+        nextMarkId += 1;
         const mark = {
-            id: `${MARK_ID_PREFIX}${String(this.#seq)}`,
+            id: `${MARK_ID_PREFIX}${String(nextMarkId)}`,
             note: data.note,
             anchor: data.anchor,
             strategy: data.strategy,
@@ -51,10 +68,22 @@ export class ReviewStore {
      * false for an unknown id or an already-resolved mark (so resolve is idempotent).
      */
     resolve(id) {
+        return this.resolveDetail(id).resolved;
+    }
+    /**
+     * Resolve, and say WHICH mark was retired.
+     *
+     * The bare boolean is what made the misattribution silent: `{"resolved":true}` is equally
+     * consistent with "I retired the bug you fixed" and "I retired somebody else's". Echoing the note
+     * lets a caller check the answer against what it believed it was resolving, which is exactly what
+     * the agent that hit this asked for — it had been re-reading the whole list after every resolve
+     * and hand-diffing the notes to get the same assurance.
+     */
+    resolveDetail(id) {
         const mark = this.#marks.find((m) => m.id === id);
         if (mark === undefined || mark.status === MarkStatus.RESOLVED)
-            return false;
+            return { resolved: false, id };
         mark.status = MarkStatus.RESOLVED;
-        return true;
+        return { resolved: true, id, note: mark.note };
     }
 }