@reticlehq/server 2.10.0 → 2.11.0

package/dist/project/memory-fs.js

@@ -0,0 +1,88 @@
+/**
+ * An in-memory `FileSystemPort`, and the map it wrote into.
+ *
+ * Three specs had hand-rolled their own copy of this before it was extracted, each one slightly
+ * different and each one a fresh chance to reintroduce the same fixture bug: the code under test
+ * joins paths with the PLATFORM separator, the fixtures are written with POSIX ones, and a spec that
+ * forgets to normalise passes on macOS and fails on Windows. Normalising at the port — once, here —
+ * is what stops that recurring.
+ *
+ * Exposing `written` is the other reason this exists. A store's return value says what it believes it
+ * did; the map says where the bytes actually went, which is the only way to test a defect about
+ * writing to the wrong directory.
+ */
+/** POSIX form, so a `\`-joined path and a `/`-joined one are the same key. */
+const norm = (path) => path.split('\\').join('/');
+export function createMemoryFs() {
+    const written = new Map();
+    const dirs = new Set();
+    const notFound = () => {
+        const err = new Error('ENOENT: no such file or directory');
+        err.code = 'ENOENT';
+        return err;
+    };
+    const fs = {
+        readFile(path) {
+            const value = written.get(norm(path));
+            return value === undefined ? Promise.reject(notFound()) : Promise.resolve(value);
+        },
+        writeFile(path, data) {
+            written.set(norm(path), data);
+            return Promise.resolve();
+        },
+        appendFile(path, data) {
+            written.set(norm(path), (written.get(norm(path)) ?? '') + data);
+            return Promise.resolve();
+        },
+        readFileBytes(path) {
+            const value = written.get(norm(path));
+            return value === undefined
+                ? Promise.reject(notFound())
+                : Promise.resolve(new TextEncoder().encode(value));
+        },
+        writeFileBytes(path, data) {
+            written.set(norm(path), new TextDecoder().decode(data));
+            return Promise.resolve();
+        },
+        mkdir(path) {
+            dirs.add(norm(path));
+            return Promise.resolve();
+        },
+        exists(path) {
+            const key = norm(path);
+            return Promise.resolve(written.has(key) || dirs.has(key));
+        },
+        readdir(path) {
+            const prefix = `${norm(path)}/`;
+            const names = new Set();
+            for (const key of written.keys()) {
+                if (key.startsWith(prefix)) {
+                    const rest = key.slice(prefix.length).split('/')[0];
+                    if (rest !== undefined && rest.length > 0)
+                        names.add(rest);
+                }
+            }
+            return Promise.resolve([...names]);
+        },
+        rename(from, to) {
+            const value = written.get(norm(from));
+            if (value === undefined)
+                return Promise.reject(notFound());
+            written.set(norm(to), value);
+            written.delete(norm(from));
+            return Promise.resolve();
+        },
+        rm(path) {
+            written.delete(norm(path));
+            dirs.delete(norm(path));
+            return Promise.resolve();
+        },
+        stat(path) {
+            return written.has(norm(path)) ? Promise.resolve({ mtimeMs: 0 }) : Promise.reject(notFound());
+        },
+        isNotFound(error) {
+            return 'ENOENT' === error?.code;
+        },
+    };
+    return { fs, written, dirs };
+}

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

@@ -32,6 +32,23 @@ export declare class ProjectStore {
      * concurrent browser sessions accumulate rather than overwriting one another.
      */
     recordRoutes(routes: readonly string[]): Promise<void>;
+    /**
+     * The best observability this project has reached, and the raiser of that bar.
+     *
+     * Read returns undefined on a first run or an unreadable file, which is the honest "no best to
+     * fall from" — never a zero, which would make every first run look like a recovery.
+     */
+    bestObservability(): Promise<{
+        percent: number;
+    } | undefined>;
+    /**
+     * Raise the bar, if this run cleared it. Lowering is deliberately impossible.
+     *
+     * A best that could fall would let a weakened run quietly redefine what good looks like, which is
+     * precisely the gaming the figure exists to resist. Serialized per file so two sessions racing
+     * cannot lose the higher of the two.
+     */
+    raiseObservability(percent: number): Promise<void>;
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     lastRun(name: string): Promise<RunRecord | undefined>;
 }

package/dist/project/project-store.js

@@ -101,6 +101,39 @@ export class ProjectStore {
             await this.#fs.writeFile(path, this.#serialize(next));
         });
     }
+    /**
+     * The best observability this project has reached, and the raiser of that bar.
+     *
+     * Read returns undefined on a first run or an unreadable file, which is the honest "no best to
+     * fall from" — never a zero, which would make every first run look like a recovery.
+     */
+    async bestObservability() {
+        const existing = await this.read();
+        return existing.ok ? existing.file.learned?.bestObservability : undefined;
+    }
+    /**
+     * Raise the bar, if this run cleared it. Lowering is deliberately impossible.
+     *
+     * A best that could fall would let a weakened run quietly redefine what good looks like, which is
+     * precisely the gaming the figure exists to resist. Serialized per file so two sessions racing
+     * cannot lose the higher of the two.
+     */
+    async raiseObservability(percent) {
+        const path = reticleDirPaths(this.#root).project;
+        await withFileLock(path, async () => {
+            const existing = await this.read();
+            const base = existing.ok ? existing.file : EMPTY_PROJECT;
+            const current = base.learned?.bestObservability?.percent;
+            if (current !== undefined && percent <= current)
+                return;
+            const learned = {
+                ...base.learned,
+                bestObservability: { percent, at: this.#clock.now() },
+            };
+            await this.#fs.mkdir(reticleDirPaths(this.#root).root);
+            await this.#fs.writeFile(path, this.#serialize({ ...base, learned }));
+        });
+    }
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     async lastRun(name) {
         const read = await this.read();

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

@@ -0,0 +1,24 @@
+/**
+ * Record where this project lives, so a daemon started somewhere else can still find it.
+ *
+ * Called at the end of `init`, which is the one moment both halves are known for certain: the
+ * directory being initialised, and the projectId that was just written into its `.reticle.json`.
+ *
+ * Deliberately runs on EVERY init, not only the first. Most init runs report "already wired", and a
+ * re-run in a re-cloned or moved checkout is exactly when the remembered path has gone stale — so
+ * the run that would have been a no-op is the one that repairs the entry.
+ *
+ * Every failure is swallowed. This is a cache that makes a later resolution better; a read-only home
+ * directory, a full disk or a hand-mangled file must not turn a successful init into a failed one.
+ * The user's project is wired either way, and `init`'s report is the first thing a new user reads.
+ */
+/** The sync filesystem seam `init` already carries. Narrowed to what this needs. */
+export interface RegistryIo {
+    readFile(path: string): string | null;
+    writeFile(path: string, content: string): void;
+    exists(path: string): boolean;
+    homeDir(): string;
+}
+/** The `projectId` a `.reticle.json` declares, or undefined when it declares none we can use. */
+export declare function projectIdOf(configSource: string | null): string | undefined;
+export declare function rememberProjectOnDisk(io: RegistryIo, projectId: string, directory: string, now: number): boolean;

package/dist/project/remember-project.js

@@ -0,0 +1,40 @@
+import { join } from 'node:path';
+import { PROJECT_REGISTRY_FILE, ReticleDir, emptyProjectRegistry, parseProjectRegistry, rememberProject, } from '@reticlehq/core';
+/** The `projectId` a `.reticle.json` declares, or undefined when it declares none we can use. */
+export function projectIdOf(configSource) {
+    if (null === configSource || 0 === configSource.length)
+        return undefined;
+    try {
+        const parsed = JSON.parse(configSource);
+        if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+            return undefined;
+        const id = parsed['projectId'];
+        return 'string' === typeof id && id.length > 0 ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function rememberProjectOnDisk(io, projectId, directory, now) {
+    if (0 === projectId.length || 0 === directory.length)
+        return false;
+    try {
+        const path = join(io.homeDir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+        const existing = io.exists(path) ? io.readFile(path) : null;
+        const registry = null === existing ? emptyProjectRegistry() : parseProjectRegistry(safeJson(existing));
+        const next = rememberProject(registry, projectId, directory, now);
+        io.writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function safeJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/project/session-root.d.ts

@@ -0,0 +1,15 @@
+import type { ToolDeps } from '../tools/tool-kit.js';
+/**
+ * The `.reticle` directory a tool call's artifacts belong in.
+ *
+ * Every call site that reads or writes a project artifact goes through here, and that is the whole
+ * point of the function existing rather than each site asking `deps.artifactRootFor` itself. The
+ * write half and the read half MUST agree: a `flow_save` that resolves to the project while
+ * `verify_change` still reads the daemon's own directory would be a worse defect than the one being
+ * fixed — the flow would save successfully and then be invisible to the tool that exists to replay
+ * it, which reads as "no flows covered this change" rather than as an error.
+ *
+ * Falls back to `deps.reticleRoot` whenever resolution cannot name a project, which is exactly the
+ * behaviour every call site had before the resolver existed.
+ */
+export declare function sessionRoot(deps: ToolDeps, sessionId: string | undefined): string;

package/dist/project/session-root.js

@@ -0,0 +1,31 @@
+/**
+ * The `.reticle` directory a tool call's artifacts belong in.
+ *
+ * Every call site that reads or writes a project artifact goes through here, and that is the whole
+ * point of the function existing rather than each site asking `deps.artifactRootFor` itself. The
+ * write half and the read half MUST agree: a `flow_save` that resolves to the project while
+ * `verify_change` still reads the daemon's own directory would be a worse defect than the one being
+ * fixed — the flow would save successfully and then be invisible to the tool that exists to replay
+ * it, which reads as "no flows covered this change" rather than as an error.
+ *
+ * Falls back to `deps.reticleRoot` whenever resolution cannot name a project, which is exactly the
+ * behaviour every call site had before the resolver existed.
+ */
+export function sessionRoot(deps, sessionId) {
+    return deps.artifactRootFor?.(sessionProjectIdOf(deps, sessionId)).root ?? deps.reticleRoot;
+}
+/**
+ * The connected session's projectId, or undefined when there is no session to ask.
+ *
+ * `sessions.resolve` throws when nothing is connected, when the id names no session, and when
+ * several are connected and none was named. All three mean the same thing here — we cannot tell
+ * which project this call is about — and none of them is a reason to fail the caller's tool.
+ */
+function sessionProjectIdOf(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).projectId;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/runs/run-tools.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { sessionRoot } from '../project/session-root.js';
 import { RunReadError } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asString } from '../tools/tools-helpers.js';
@@ -36,7 +37,7 @@ export const RUN_TOOLS = [
             error: z.string().optional(),
         },
         handler: async (deps, args) => {
-            const store = new RunStore(deps.fs, deps.reticleRoot);
+            const store = new RunStore(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
             // format:"diff" is a whole-history operation (two most-recent runs), not a single-run read.
             if ('diff' === asString(args['format'])) {
                 const pair = await store.latestTwo();

package/dist/session/lease-availability.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Whether the self-serve escape hatch can actually be taken, said in the same breath as the offer.
+ *
+ * `reticle_lease` is what `status`, `doctor` and the no-session diagnosis all recommend when no tab
+ * is connected: it opens a browser Reticle drives itself, so the agent does not have to wait for a
+ * human. It is the right advice and it is the one thing that cannot work when Chromium is missing or
+ * sitting at a revision this Playwright will not use — and the command giving the advice is usually
+ * the command that just diagnosed exactly that.
+ *
+ * Reported from the field, verbatim in shape: `doctor` printed `chromium ✗ wrong revision — the
+ * bundled playwright wants chromium-1234; the cache holds chromium-1228`, and then offered the lease
+ * as the way out. The reporter followed it, and could not have succeeded.
+ *
+ * Two things this refuses to do:
+ *
+ * **It does not fire on an absent probe.** A probe that could not run is not evidence the browser is
+ * missing, and a caveat asserting otherwise would be the same overclaiming this file exists to stop.
+ *
+ * **It does not tell the agent to install the browser.** A ~150MB download on somebody else's
+ * machine is not an agent's call to make unprompted, so the message names the command and hands it
+ * to the human rather than implying the agent should just run it.
+ */
+/** What the caller learned about the browser. Gathered by the caller so this stays pure. */
+export interface LeaseBrowserState {
+    /** Does the executable this Playwright wants actually exist on disk? */
+    exists: boolean;
+    /** The install command, already pinned to the bundled Playwright by `chromium-hint`. */
+    installCommand?: string | undefined;
+    /** The revision this Playwright wants, when the path names one. */
+    wantedRevision?: string | undefined;
+    /** Chromium revisions actually present, wanted or not. */
+    installedRevisions?: readonly string[] | undefined;
+}
+/**
+ * The sentence to append to a lease recommendation, or undefined when the lease is fine.
+ *
+ * Undefined rather than an empty string on the healthy path: a caller composing a message should not
+ * have to filter blanks, and a healthy install must pay nothing at all for this check.
+ */
+export declare function leaseCaveat(state: LeaseBrowserState | undefined): string | undefined;

package/dist/session/lease-availability.js

@@ -0,0 +1,43 @@
+/**
+ * Whether the self-serve escape hatch can actually be taken, said in the same breath as the offer.
+ *
+ * `reticle_lease` is what `status`, `doctor` and the no-session diagnosis all recommend when no tab
+ * is connected: it opens a browser Reticle drives itself, so the agent does not have to wait for a
+ * human. It is the right advice and it is the one thing that cannot work when Chromium is missing or
+ * sitting at a revision this Playwright will not use — and the command giving the advice is usually
+ * the command that just diagnosed exactly that.
+ *
+ * Reported from the field, verbatim in shape: `doctor` printed `chromium ✗ wrong revision — the
+ * bundled playwright wants chromium-1234; the cache holds chromium-1228`, and then offered the lease
+ * as the way out. The reporter followed it, and could not have succeeded.
+ *
+ * Two things this refuses to do:
+ *
+ * **It does not fire on an absent probe.** A probe that could not run is not evidence the browser is
+ * missing, and a caveat asserting otherwise would be the same overclaiming this file exists to stop.
+ *
+ * **It does not tell the agent to install the browser.** A ~150MB download on somebody else's
+ * machine is not an agent's call to make unprompted, so the message names the command and hands it
+ * to the human rather than implying the agent should just run it.
+ */
+/**
+ * The sentence to append to a lease recommendation, or undefined when the lease is fine.
+ *
+ * Undefined rather than an empty string on the healthy path: a caller composing a message should not
+ * have to filter blanks, and a healthy install must pay nothing at all for this check.
+ */
+export function leaseCaveat(state) {
+    if (state === undefined || state.exists)
+        return undefined;
+    // Present-at-the-wrong-revision and absent-entirely have different fixes and different readings,
+    // and collapsing them is what made the reported loop unbreakable — "the check is broken" and
+    // "none of these count" look identical from a flat `missing`.
+    const installed = state.installedRevisions ?? [];
+    const mismatch = state.wantedRevision !== undefined && installed.length > 0
+        ? ` This Playwright wants ${state.wantedRevision} and the cache holds ${installed.join(', ')}, so the builds already on this machine will not be used.`
+        : '';
+    const command = state.installCommand === undefined ? '' : ` The fix is: ${state.installCommand}.`;
+    return ('NOTE — reticle_lease cannot run here: it drives a Reticle-owned Chromium and that browser is ' +
+        `not available.${mismatch}${command} That download is the human's call, not something to run ` +
+        'unprompted on their machine, so hand this back rather than treating the lease as a way forward.');
+}

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

@@ -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 { type LeaseBrowserState } from './lease-availability.js';
 export interface NoSessionFacts {
     /** Whether ANY session has connected to this daemon since it booted. */
     everConnected: boolean;
@@ -36,6 +37,15 @@ export interface NoSessionFacts {
     slowListeners?: readonly number[];
     /** The port this daemon is on — half of the mismatch the old message asked about. */
     port: number;
+    /**
+     * What the caller knows about the Chromium a lease would drive.
+     *
+     * Every branch below offers `reticle_lease` as the way not to wait for a human. When that browser
+     * is missing or at a revision this Playwright will not use, the offer is the one thing that cannot
+     * help — and it was being made by the same output that had just diagnosed exactly that. Optional:
+     * absent means the caller did not probe, which is not evidence the browser is missing.
+     */
+    leaseBrowser?: LeaseBrowserState | undefined;
     /**
      * The directory `initialized` was decided in, named in the message when it is known.
      *

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

@@ -18,8 +18,9 @@
  * 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 { leaseCaveat } from './lease-availability.js';
 import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
-import { STALL_AFTER_MS } from '../telemetry/instrumentation-stall.js';
+import { STALL_AFTER_MS } from './stall-clock.js';
 /** The one framework whose most likely cause differs from every other framework's. */
 const NUXT = 'nuxt';
 /**
@@ -58,6 +59,17 @@ const RETRY = SELF_RECOVERING_MARKER;
 const URL_THEN_LEASE = 'Once you have that URL, open it with reticle_lease {action:"acquire", url} rather than a shell ' +
     'command — it needs no CLI on PATH (reach it with reticle_run {tool:"reticle_lease"} if it is ' +
     'not advertised directly).';
+/**
+ * The lease advice, with the reason it cannot be taken when that is the case.
+ *
+ * A function rather than a constant so the caveat cannot be forgotten at one of the six sites that
+ * offer the lease — which is exactly how the offer came to be made by the command that had already
+ * diagnosed the problem.
+ */
+function leaseAdvice(base, facts) {
+    const caveat = leaseCaveat(facts.leaseBrowser);
+    return caveat === undefined ? base : `${base} ${caveat}`;
+}
 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).';
@@ -292,7 +304,7 @@ export function diagnoseNoSession(facts) {
         }
         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 ${OPEN_CMD_BARE}), or reload the tab. ${SELF_SERVE} ${RETRY}`);
+            `the app (or run ${OPEN_CMD_BARE}), or reload the tab. ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
     }
     // Ranked ahead of every "we have never seen one" branch below, because it is the one fact that
     // OUTRANKS them: those branches all reason from an absence, and this reasons from a recorded
@@ -303,7 +315,7 @@ export function diagnoseNoSession(facts) {
             ? `${unattributedListeners(listening)} If the dev server is not running, start it first ` +
                 '(the command is in `next_action`).'
             : unattributedListeners(listening);
-        return `${RESTARTED_LEAD} ${OPEN_THE_APP} ${listeners} ${rankedCauses(facts)} ${SELF_SERVE} ${RETRY}`;
+        return `${RESTARTED_LEAD} ${OPEN_THE_APP} ${listeners} ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`;
     }
     // A config found elsewhere outranks every "you may have no SDK" branch below: those reason from
     // an absence in ONE directory, and this is a file we read in another. Ranked here so the reader is
@@ -311,7 +323,7 @@ export function diagnoseNoSession(facts) {
     if (!initialized && (facts.configsElsewhere ?? []).length > 0) {
         return ('no browser session connected, and this daemon has never seen one. ' +
             `${configsElsewhereClause(facts)} ${unattributedListeners(listening)} ${OPEN_THE_APP} ` +
-            `${rankedCauses(facts)} ${SELF_SERVE} ${RETRY}`);
+            `${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
     }
     if (0 === listening.length) {
         // Lead with the stronger EVIDENCE, and do not overstate what it is.
@@ -341,7 +353,7 @@ export function diagnoseNoSession(facts) {
                 `file ${INIT_CMD} 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.${searchedClause(facts)} ${URL_THEN_LEASE} ${RETRY}`);
+                `carries the SDK without that file at all.${searchedClause(facts)} ${leaseAdvice(URL_THEN_LEASE, facts)} ${RETRY}`);
         }
         return (`${stallClause(facts)}no browser session connected, and this daemon has never seen one. ${OPEN_THE_APP} ` +
             'Nothing is listening on the ports Reticle scans ' +
@@ -359,7 +371,7 @@ export function diagnoseNoSession(facts) {
             // 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. ${URL_THEN_LEASE} ` +
+            `the app IS running, ask the human for its URL rather than assuming it is down. ${leaseAdvice(URL_THEN_LEASE, facts)} ` +
             // 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}`);
@@ -377,5 +389,5 @@ export function diagnoseNoSession(facts) {
     return (`${stallClause(facts)}no browser session connected, and this daemon has never seen one for this project, which is ` +
         `wired for Reticle. ${OPEN_THE_APP} ${unattributedListeners(listening)} ` +
         'If the page IS open and still does not appear, the app is wired and the SDK is not reaching ' +
-        `this daemon (on ${String(port)}). ${rankedCauses(facts)} ${SELF_SERVE} ${RETRY}`);
+        `this daemon (on ${String(port)}). ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
 }

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

@@ -17,7 +17,7 @@ import { readProjectFramework, readProjectId, readProjectPort } from '../cli/cli
 import { discoverProjectConfigs } from '../cli/config-discovery.js';
 import { hasProjectConnectedBefore, rememberConnected } from './connection-memory.js';
 import { reticleStateHome } from '../daemon/daemon.js';
-import { stallUptime } from '../telemetry/instrumentation-stall.js';
+import { stallUptime } from './stall-clock.js';
 /** Slow enough to be free, fast enough that a dev server started 15s ago is already reflected. */
 const REFRESH_MS = 15_000;
 /** The URL an auto-attach opens. `localhost` for the same reason the probe uses it: both stacks. */

package/dist/session/session.d.ts

@@ -1,6 +1,7 @@
 import type { WebSocket } from 'ws';
 import type { ImpactSnapshot } from '@reticlehq/core';
 import { LastAct } from './last-act.js';
+import { GapLedger } from '../honesty/gap-ledger.js';
 import { type PageRuntime } from './command-timeout.js';
 import { type SessionHealth } from './session-health.js';
 export type { SessionHealth };
@@ -111,6 +112,14 @@ export declare class Session {
      * from it, and the split between those two tool calls is the whole reason it exists.
      */
     readonly lastAct: LastAct;
+    /**
+     * What this app still cannot tell Reticle, as of the most recent verdict.
+     *
+     * Lives on the session because that is the scope the question belongs to: "am I done with this
+     * app" is a session question, and a gap closed halfway through must not follow the agent to the
+     * end of it.
+     */
+    readonly gaps: GapLedger;
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).
      * If the reaper had auto-ended the session, a fresh command means the agent is alive again, so the

package/dist/session/session.js

@@ -1,5 +1,6 @@
 import { recordImpact } from '../impact/impact-recorder.js';
 import { LastAct } from './last-act.js';
+import { GapLedger } from '../honesty/gap-ledger.js';
 import { commandTimeoutMessage } from './command-timeout.js';
 import { readHealthEvent } from './session-health.js';
 /** The HUD does not need 200 frames to watch a counter climb; the last state always lands. */
@@ -370,6 +371,14 @@ export class Session {
      * from it, and the split between those two tool calls is the whole reason it exists.
      */
     lastAct = new LastAct();
+    /**
+     * What this app still cannot tell Reticle, as of the most recent verdict.
+     *
+     * Lives on the session because that is the scope the question belongs to: "am I done with this
+     * app" is a session question, and a gap closed halfway through must not follow the agent to the
+     * end of it.
+     */
+    gaps = new GapLedger();
     // ── Server-authoritative liveness (immune to browser-tab throttling) ──────────────
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).

package/dist/session/stall-clock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * When a run with nothing connected is worth mentioning to a human.
+ *
+ * Ten minutes sits well past setup latency — reading a doc, restarting a dev server, opening a tab —
+ * and short enough that the warning still arrives while somebody is at the keyboard.
+ */
+export declare const STALL_AFTER_MS: number;
+/** Start the clock, from the same place the instrumentation clock is marked. */
+export declare function markStallClock(now: number): void;
+/**
+ * How long this daemon has waited with no app, or undefined if the question is moot.
+ *
+ * Moot means the clock was never started, or an app already connected. A run that starts slowly and
+ * then works has nothing to report, which is why this returns undefined rather than a duration.
+ */
+export declare function stallUptime(now: number): number | undefined;
+/** Tests only. */
+export declare function resetStallClock(): void;

package/dist/session/stall-clock.js

@@ -0,0 +1,48 @@
+/**
+ * How long this daemon has waited with no app connected.
+ *
+ * This is what survived `instrumentation_stalled`. The EVENT was removed: it claimed to separate
+ * "never wired" from "died before reporting" and did not, because it only fired on a flush tick or a
+ * graceful shutdown, so a killed daemon was invisible to it exactly as before. Everything it carried
+ * is derivable from `daemon_started` minus `app_instrumented`, joined on `sessionId` — and that set
+ * difference is strictly MORE complete, because it does catch the killed daemons. A second way to
+ * compute the same number that disagrees with the first is worse than not having it.
+ *
+ * The CLOCK is a different thing and stays. Two live features read it, neither of them a metric: the
+ * no-session diagnosis tells an agent how long this daemon has been waiting, and the daemon warns on
+ * stderr when a run passes the threshold with nothing connected. Both are help for somebody stuck
+ * mid-install, which is the moment they are least able to work it out themselves.
+ *
+ * It lives under `session/` rather than `telemetry/` now, beside the two files that read it. The old
+ * home is why the removal looked like it would take the diagnosis with it.
+ */
+import { appEverConnected } from '../telemetry/app-instrumented.js';
+/**
+ * When a run with nothing connected is worth mentioning to a human.
+ *
+ * Ten minutes sits well past setup latency — reading a doc, restarting a dev server, opening a tab —
+ * and short enough that the warning still arrives while somebody is at the keyboard.
+ */
+export const STALL_AFTER_MS = 10 * 60 * 1000;
+let daemonStartedAt;
+/** Start the clock, from the same place the instrumentation clock is marked. */
+export function markStallClock(now) {
+    daemonStartedAt = now;
+}
+/**
+ * How long this daemon has waited with no app, or undefined if the question is moot.
+ *
+ * Moot means the clock was never started, or an app already connected. A run that starts slowly and
+ * then works has nothing to report, which is why this returns undefined rather than a duration.
+ */
+export function stallUptime(now) {
+    if (daemonStartedAt === undefined)
+        return undefined;
+    if (appEverConnected())
+        return undefined;
+    return now - daemonStartedAt;
+}
+/** Tests only. */
+export function resetStallClock() {
+    daemonStartedAt = undefined;
+}