@reticlehq/server 2.11.0 → 2.13.0

package/dist/runs/context-tools.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import {} from '@reticlehq/core';
+import { runContextFor } from './run-context.js';
+import { openSessionIntents } from '../intent/open-intents.js';
+import { ReticleTool } from '../tools/tool-names.js';
+import { sessionIdShape } from '../tools/tool-kit.js';
+import { asString } from '../tools/tools-helpers.js';
+/**
+ * What this run has established, asked for by the one party that knows when it is needed.
+ *
+ * Reticle holds the trajectory: the journal, the verdicts, the intent ledger. The agent holds a copy
+ * in its context window, and that copy is the one that disappears — at a compaction, at the end of a
+ * turn, at the handover to a sub-agent. Reticle's does not disappear at the same moment. So this is
+ * not a competing memory; it is the ground truth compaction destroyed, handed back on request.
+ *
+ * ## Why it is PULLED
+ *
+ * The same content was once pushed onto every session-bound tool response. It cost +136% on a
+ * verdict and was cut, because most of the time the agent still had the context and we were paying
+ * on every call to duplicate what it knew. Nobody but the agent can tell when that stops being true.
+ * So the agent asks, once, at the moment it knows its own memory is gone, and pays once.
+ *
+ * ## Why it is on the EXTENDED surface rather than the default
+ *
+ * The default surface is a hard COUNT — editors budget tools across every connected MCP server, so a
+ * slot taken here is taken from a tool that has already earned it, and nothing on that list has been
+ * demoted for this. The claim behind this tool is unmeasured, which is the same test `reticle_intent`
+ * and the `reticle_capabilities` demotion were held to, and it fails that test today.
+ *
+ * The reachability argument is also stronger here than for most of the cold tail. The caller is,
+ * by construction, an agent that has just lost its context and is re-reading the tool list it was
+ * handed this turn — so `reticle_tools` (advertised on every surface) is exactly the call it is
+ * already going to make, and this tool is one `reticle_run` hop behind it. A tool that is only useful
+ * after a discovery step, to a caller who is already performing a discovery step, is the cheapest
+ * possible thing to leave off the hot list. It moves to the default surface when a measurement says
+ * the pull happens often enough to be worth a permanent slot, and not before.
+ */
+/** What the run has established, and where each part of it came from. */
+const CONTEXT_OUTPUT_SCHEMA = {
+    step: z
+        .number()
+        .describe('How many actions this run has dispatched. Counted off the journal, not a counter of its own.'),
+    established: z
+        .array(z.unknown())
+        .describe('What Reticle OBSERVED, folded and capped, each `{ key, fact, source?, doc?, epoch? }`. `key` is the subject, so re-observing it supersedes rather than appends. Anything seen under a replaced document or a pre-edit epoch is already gone from this list.'),
+    proven: z
+        .array(z.unknown())
+        .describe('Claims a verdict already settled, each `{ claim, verified, source?, doc?, epoch? }`. Read this before re-driving something: re-proving it is slow, and assuming it is a false green.'),
+    remaining: z
+        .array(z.string())
+        .describe('The intents from .reticle/intent.json that no verdict has discharged. Derived from the ledger, never a guess at what you meant to do next.'),
+};
+/** The ledger and the live page state this run is folded out of. `[]`/undefined when nothing is connected. */
+async function evidenceFor(deps, sessionId) {
+    try {
+        const session = deps.sessions.resolve(sessionId);
+        return {
+            actions: await session.readJournalActions(),
+            events: await session.queryEvents({}),
+            currentDocumentId: session.currentDocumentId,
+            currentEditEpoch: session.currentEditEpoch,
+        };
+    }
+    catch {
+        // `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: there is no run to report,
+        // and an empty context is the honest answer rather than a reason to fail the call.
+        return {
+            actions: [],
+            events: [],
+            currentDocumentId: undefined,
+            currentEditEpoch: undefined,
+        };
+    }
+}
+export const CONTEXT_TOOLS = [
+    {
+        name: ReticleTool.CONTEXT,
+        description: 'What THIS run has already established, so you do not rediscover it. Call it when your own copy is gone: right after a compaction, at the top of a fresh sub-agent, or at the start of a turn you did not begin. Returns `established` (what Reticle OBSERVED, with the source file:line where one was reported), `proven` (claims a verdict already settled, so you neither re-prove them nor assume them) and `remaining` (the intents from .reticle/intent.json that nothing has discharged). It is a FOLD over the journal, never a second store, so it cannot disagree with the ledger. Bounded and superseding rather than accumulating, and anything observed under a replaced document or before your last source edit is already dropped rather than presented as current. Only what Reticle observed goes in: it never reports what you intended or believed.',
+        example: {},
+        inputSchema: { ...sessionIdShape },
+        outputSchema: CONTEXT_OUTPUT_SCHEMA,
+        handler: async (deps, args) => {
+            const sessionId = asString(args['sessionId']);
+            const evidence = await evidenceFor(deps, sessionId);
+            return runContextFor({ ...evidence, intents: await openSessionIntents(deps, sessionId) });
+        },
+    },
+];

package/dist/runs/run-context.d.ts

@@ -0,0 +1,40 @@
+import { type EstablishedFact, type Intent, type JournalAction, type ProvenClaim, type ReticleEvent, type RunContext } from '@reticlehq/core';
+/**
+ * The SUBJECT a journal action was about: the ref it spent, else the target it resolved from.
+ *
+ * Exported so the feature-use instrument files a re-fetch under the same key this fold establishes
+ * it under. A second copy of this rule there would be a second definition of "the same subject".
+ */
+export declare function subjectOf(action: JournalAction): string | undefined;
+/**
+ * Fold the journal into candidate facts, newest last.
+ *
+ * Only the last `RUN_ESTABLISHED_CAP` actions are read: anything older cannot survive the fold, so
+ * parsing it would be work done to throw away. An action with no observed settle outcome states
+ * nothing and is skipped — "we drove it and cannot say what happened" is not an established fact,
+ * and writing it down as one is how a memory starts lying.
+ */
+export declare function establishedFromJournal(actions: readonly JournalAction[], events: readonly ReticleEvent[]): EstablishedFact[];
+/**
+ * What a verdict already settled, newest last.
+ *
+ * Both verdict tools write here. `reticle_act_and_wait` closes its attribution window with one;
+ * `reticle_assert` drives nothing, so it appends its record WITHOUT opening a window — same effect
+ * shape, so this fold reads one kind of verdict rather than two.
+ */
+export declare function provenFromJournal(actions: readonly JournalAction[], events: readonly ReticleEvent[]): ProvenClaim[];
+/**
+ * The context for one run.
+ *
+ * `step` is the journal's action count rather than a counter of its own, for the reason at the top
+ * of this file: a second counter is a second thing that can disagree with the ledger. The document
+ * and epoch are the session's own, so the staleness rule here is the same one every other verdict in
+ * this codebase is scoped by.
+ */
+export declare function runContextFor(input: {
+    actions: readonly JournalAction[];
+    events: readonly ReticleEvent[];
+    intents: readonly Intent[];
+    currentDocumentId: string | undefined;
+    currentEditEpoch: number | undefined;
+}): RunContext;

package/dist/runs/run-context.js

@@ -0,0 +1,158 @@
+import { EventType, JournalVerdictEffectSchema, RUN_ESTABLISHED_CAP, buildRunContext, } from '@reticlehq/core';
+/**
+ * The run, derived from the journal that is already there.
+ *
+ * `.reticle/sessions/<id>/` already holds an append-only causal ledger of every action dispatched
+ * and every event observed. The run is a FOLD over that, never a second store — the same argument
+ * that deleted `instrumentation_stalled` from this codebase applies without modification: two ways
+ * to compute one number is worse than one way, because the day they disagree the disagreement lands
+ * inside a verdict and a user finds it before we do. So nothing here writes: it reads the ledger and
+ * folds it, and if the fold is wrong the ledger is still the single authority.
+ *
+ * **One run per session, for now.** Nothing here assumes it: the fold is pure and takes its evidence
+ * as arguments, so a later multi-run or multi-agent model is a change of caller, not a rewrite. It
+ * is not built today because nobody has hit the case, and a coordination model invented ahead of its
+ * first user is a guess.
+ *
+ * Only what Reticle OBSERVED goes in. A settle outcome is an observation. A route change is an
+ * observation. A verdict a verification tool recorded is an observation. What the agent meant to do
+ * next is not, and never enters here.
+ */
+/**
+ * The one key the route is filed under.
+ *
+ * The subject of "the app is on /checkout" is the route itself, so a later route change SUPERSEDES
+ * rather than appends. Filing it per-path would accumulate every page ever visited, which is the
+ * token bomb the cap exists to prevent.
+ */
+const ROUTE_KEY = 'route';
+/** The conclusions this fold is allowed to state, as prose rather than transcript. */
+const Fact = {
+    route: (to) => `route is ${to}`,
+    settled: (verb) => `${verb} settled`,
+    unsettled: (verb) => `${verb} did not settle`,
+};
+/**
+ * The SUBJECT a journal action was about: the ref it spent, else the target it resolved from.
+ *
+ * Exported so the feature-use instrument files a re-fetch under the same key this fold establishes
+ * it under. A second copy of this rule there would be a second definition of "the same subject".
+ */
+export function subjectOf(action) {
+    const ref = action.args['ref'];
+    if ('string' === typeof ref && ref.length > 0)
+        return ref;
+    const target = action.args['target'];
+    if ('string' === typeof target && target.length > 0)
+        return target;
+    return undefined;
+}
+/** What the action did, in the caller's own vocabulary — 'click', 'fill', else the tool's name. */
+function verbOf(action) {
+    const named = action.args['action'];
+    return 'string' === typeof named && named.length > 0 ? named : action.tool;
+}
+/** The verdict a verification tool recorded on this action, if it recorded one. */
+function verdictOf(action) {
+    const parsed = JournalVerdictEffectSchema.safeParse(action.effect);
+    return parsed.success ? parsed.data : undefined;
+}
+/** Which document and edit epoch each action was observed under, read off its attributed events. */
+function scopeByAction(events) {
+    const out = new Map();
+    for (const event of events) {
+        if (event.actionId === undefined)
+            continue;
+        if (event.documentId === undefined && event.editEpoch === undefined)
+            continue;
+        const existing = out.get(event.actionId) ?? {};
+        out.set(event.actionId, {
+            doc: event.documentId ?? existing.doc,
+            epoch: event.editEpoch ?? existing.epoch,
+        });
+    }
+    return out;
+}
+/**
+ * Fold the journal into candidate facts, newest last.
+ *
+ * Only the last `RUN_ESTABLISHED_CAP` actions are read: anything older cannot survive the fold, so
+ * parsing it would be work done to throw away. An action with no observed settle outcome states
+ * nothing and is skipped — "we drove it and cannot say what happened" is not an established fact,
+ * and writing it down as one is how a memory starts lying.
+ */
+export function establishedFromJournal(actions, events) {
+    const scope = scopeByAction(events);
+    let route;
+    for (const event of events) {
+        if (EventType.ROUTE_CHANGE !== event.type)
+            continue;
+        const pathname = event.data['pathname'];
+        const to = 'string' === typeof pathname ? pathname : event.data['to'];
+        if ('string' !== typeof to)
+            continue;
+        route = { key: ROUTE_KEY, fact: Fact.route(to), doc: event.documentId, epoch: event.editEpoch };
+    }
+    const out = [];
+    for (const action of actions.slice(-RUN_ESTABLISHED_CAP)) {
+        const settled = action.settled;
+        if (undefined === settled)
+            continue;
+        const key = subjectOf(action);
+        if (undefined === key)
+            continue;
+        const verb = verbOf(action);
+        out.push({
+            key,
+            fact: settled ? Fact.settled(verb) : Fact.unsettled(verb),
+            // The source pointer the verdict already reported. Read off the ledger rather than looked up
+            // again: a second lookup could disagree with the one the agent was shown.
+            source: verdictOf(action)?.source,
+            ...(scope.get(action.actionId) ?? {}),
+        });
+    }
+    if (route !== undefined)
+        out.push(route);
+    return out;
+}
+/**
+ * What a verdict already settled, newest last.
+ *
+ * Both verdict tools write here. `reticle_act_and_wait` closes its attribution window with one;
+ * `reticle_assert` drives nothing, so it appends its record WITHOUT opening a window — same effect
+ * shape, so this fold reads one kind of verdict rather than two.
+ */
+export function provenFromJournal(actions, events) {
+    const scope = scopeByAction(events);
+    const out = [];
+    for (const action of actions.slice(-RUN_ESTABLISHED_CAP)) {
+        const verdict = verdictOf(action);
+        if (undefined === verdict)
+            continue;
+        out.push({
+            claim: verdict.claim,
+            verified: verdict.verified,
+            source: verdict.source,
+            ...(scope.get(action.actionId) ?? {}),
+        });
+    }
+    return out;
+}
+/**
+ * The context for one run.
+ *
+ * `step` is the journal's action count rather than a counter of its own, for the reason at the top
+ * of this file: a second counter is a second thing that can disagree with the ledger. The document
+ * and epoch are the session's own, so the staleness rule here is the same one every other verdict in
+ * this codebase is scoped by.
+ */
+export function runContextFor(input) {
+    return buildRunContext({
+        step: input.actions.length,
+        intents: input.intents,
+        established: establishedFromJournal(input.actions, input.events),
+        proven: provenFromJournal(input.actions, input.events),
+        currentDocumentId: input.currentDocumentId,
+        currentEditEpoch: input.currentEditEpoch,
+    });
+}

package/dist/runs/run-diff.d.ts

@@ -1,6 +1,6 @@
 import type { ReticleVerificationRun } from '@reticlehq/core';
 /** A per-flow change between two runs. Only flows with a meaningful change are reported. */
-export interface FlowDelta {
+interface FlowDelta {
     name: string;
     beforeMs: number;
     afterMs: number;
@@ -29,3 +29,4 @@ export interface RunDiff {
  * console diffs land once runs persist per-step detail.
  */
 export declare function diffRuns(before: ReticleVerificationRun, after: ReticleVerificationRun, noiseFloorPct?: number): RunDiff;
+export {};

package/dist/runs/run-store.d.ts

@@ -19,6 +19,16 @@ export type ReadRunResult = {
 interface RunStoreOptions {
     retention?: number;
     slack?: number;
+    /**
+     * Called after a run artifact is safely on disk. Used to wake cloud sync so a finished
+     * verification reaches the dashboard promptly instead of waiting for the next timer tick.
+     *
+     * A callback rather than a dependency on the sync daemon: the store's job is durability, and a
+     * store that imported the cloud would make "write a run" fail whenever the cloud did. It is
+     * invoked AFTER the rename, so nothing can observe a run that is not yet readable, and it must
+     * never throw — see the call site.
+     */
+    onWrote?: () => void;
 }
 export declare class RunStore {
     #private;

package/dist/runs/run-store.js

@@ -15,11 +15,13 @@ export class RunStore {
     #root;
     #retention;
     #slack;
+    #onWrote;
     constructor(fs, root, opts = {}) {
         this.#fs = fs;
         this.#root = root;
         this.#retention = opts.retention ?? RUN_RETENTION;
         this.#slack = opts.slack ?? RUN_RETENTION_SLACK;
+        this.#onWrote = opts.onWrote;
     }
     /**
      * Write one run artifact. Creates .reticle/runs/ first; byte-stable (fixed indent + trailing newline).
@@ -37,6 +39,14 @@ export class RunStore {
         const tmp = `${path}${TMP_EXT}`;
         await this.#fs.writeFile(tmp, `${JSON.stringify(run, null, JSON_INDENT)}\n`);
         await this.#fs.rename(tmp, path);
+        // AFTER the rename: a listener that reads the run back must find it there. Swallowed, because
+        // this is a notification — a sync that cannot be woken must never fail the write it followed.
+        try {
+            this.#onWrote?.();
+        }
+        catch {
+            // Not this store's problem, and not worth failing a durable write over.
+        }
         await this.#pruneOld();
     }
     /**

package/dist/runs/verification-sync.d.ts

@@ -1,16 +1,5 @@
-/**
- * Turn an MCP verification (a `reticle_flow_verify` suite run) into a first-class ReticleVerificationRun:
- * assemble the artifact from the already-computed replays, persist it to .reticle/runs/ (so
- * `reticle_run_export` and CI can read it), and — when logged in (cloud creds set) — best-effort push it
- * to the cloud's `POST /v1/runs` so the team's dashboard Runs tab shows what the agent just verified.
- *
- * This is the artifact tier that maps to the dashboard's "Runs" (the OEM/CI-consumable verdict); the
- * lighter per-flow RunRecord that feeds regression memory is synced separately in flow-replay-run.ts.
- * Both are best-effort + opt-in: no creds → the artifact still lands on disk, nothing leaves the machine.
- */
 import { type FlowReplayResult } from '@reticlehq/core';
 import type { ToolDeps } from '../tools/tools.js';
-/** A replay plus the wall-clock time it took — the shape the verify handler already collects. */
 export interface TimedReplay {
     replay: FlowReplayResult;
     durationMs: number;

package/dist/runs/verification-sync.js

@@ -8,15 +8,19 @@
  * lighter per-flow RunRecord that feeds regression memory is synced separately in flow-replay-run.ts.
  * Both are best-effort + opt-in: no creds → the artifact still lands on disk, nothing leaves the machine.
  */
+import { mcpClientIdentity } from '../mcp/client-identity.js';
 import { RunAgentKind, RunFramework, RunProfile, RunTrigger, } from '@reticlehq/core';
 import { homedir } from 'node:os';
 import { buildVerificationRun } from './build-verification-run.js';
 import { mapReplayToFlowResult } from './replay-mapping.js';
 import { defaultRunId } from './runner-port.js';
 import { RunStore } from './run-store.js';
-import { syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { log } from '../log.js';
+/** A replay plus the wall-clock time it took — the shape the verify handler already collects. */
+/** The author of record when no MCP peer introduced itself — a CLI run, or a client that skipped the handshake. */
+const RETICLE_MCP_AGENT_ID = 'reticle-mcp';
 /** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
 function assembleRun(deps, timed, projectId) {
     const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs));
@@ -25,7 +29,20 @@ function assembleRun(deps, timed, projectId) {
         durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),
         profile: RunProfile.DEV,
         project: { name: projectId ?? 'reticle', framework: RunFramework.OTHER },
-        agent: { id: 'reticle-mcp', kind: RunAgentKind.CODING_AGENT },
+        /*
+         * WHICH agent drove this, not merely THAT one did.
+         *
+         * This was hardcoded to 'reticle-mcp', so every run in every workspace claimed the same author.
+         * A dashboard built on it could say "an agent verified this" and never "Claude Code verified
+         * this, Cursor broke it" — which is the question a team actually has once more than one agent
+         * touches the repo. The name is the client's own claim from the MCP handshake; a plain CLI run
+         * with no MCP peer keeps the old id, because inventing a vendor there would be worse than
+         * admitting we do not know.
+         */
+        agent: {
+            id: mcpClientIdentity().name ?? RETICLE_MCP_AGENT_ID,
+            kind: RunAgentKind.CODING_AGENT,
+        },
         trigger: { kind: RunTrigger.MANUAL },
         changedFiles: [],
         flows,
@@ -58,9 +75,13 @@ export async function persistAndSyncVerificationRun(deps, timed, projectId) {
     const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
     if (null === cloud.config || !cloud.policy.runs)
         return run.runId; // not attached / runs disabled → local only
-    const result = await syncRunToCloud(run, cloud.config, (url, init) => fetch(url, init));
+    const result = await syncRunToCloud(run, cloud.config, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-run-sync-failed', { runId: run.runId, status: result.status, error: result.error });
     }
+    // The run is up; its CONTEXT is not. Nudged rather than pushed inline, so the counters and flows
+    // ride the ordinary cycle (with its cursor and its overlap guard) instead of growing a second,
+    // subtly different upload path here.
+    deps.onRunPersisted?.();
     return run.runId;
 }

package/dist/runs/verify-server.d.ts

@@ -18,7 +18,14 @@ export interface VerifyServerOptions {
 }
 /** Build the request listener. Reads + size-caps the body, then hands off to the pure handler. */
 export declare function createVerifyRequestListener(opts: VerifyServerOptions): http.RequestListener;
-/** Start the verify server on localhost. Resolves once listening; returns the bound server + port. */
+/**
+ * Start the verify server on localhost. Resolves once listening; returns the bound server + port.
+ *
+ * A failed bind REJECTS, naming the verify port. It used to emit `'error'` with no listener, so an
+ * EADDRINUSE on `--http-port` crashed the daemon with a raw stack, and the parent `serve` reported
+ * only that the daemon "did not come up" on the BRIDGE port — the one port that was fine (#687).
+ * Rejecting lets the daemon's start-failure path say what actually could not be honoured.
+ */
 export declare function startVerifyServer(opts: VerifyServerOptions, port: number): Promise<{
     server: http.Server;
     port: number;

package/dist/runs/verify-server.js

@@ -83,13 +83,25 @@ async function writeResponse(req, res, opts, raw) {
     res.writeHead(result.status, JSON_HEADERS);
     res.end(JSON.stringify(result.body));
 }
-/** Start the verify server on localhost. Resolves once listening; returns the bound server + port. */
+/**
+ * Start the verify server on localhost. Resolves once listening; returns the bound server + port.
+ *
+ * A failed bind REJECTS, naming the verify port. It used to emit `'error'` with no listener, so an
+ * EADDRINUSE on `--http-port` crashed the daemon with a raw stack, and the parent `serve` reported
+ * only that the daemon "did not come up" on the BRIDGE port — the one port that was fine (#687).
+ * Rejecting lets the daemon's start-failure path say what actually could not be honoured.
+ */
 export function startVerifyServer(opts, port) {
     const server = http.createServer(createVerifyRequestListener(opts));
     server.requestTimeout = REQUEST_TIMEOUT_MS;
     server.headersTimeout = HEADERS_TIMEOUT_MS;
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            reject(new Error(`the verify HTTP endpoint could not bind ${LOCALHOST}:${String(port)} — ${err.message}`));
+        };
+        server.once('error', onError);
         server.listen(port, LOCALHOST, () => {
+            server.removeListener('error', onError);
             const address = server.address();
             const boundPort = 'object' === typeof address && address !== null ? address.port : port;
             resolve({ server, port: boundPort });

package/dist/session/command-timeout.d.ts

@@ -9,8 +9,11 @@ import { AppRuntime } from '@reticlehq/core';
  * developer goes hunting through their own code for a fault that is not there.
  *
  * This advice previously blamed occlusion — "macOS suspends an occluded or off-Space WKWebView" —
- * which is false, and was the kind of wrong steer this function exists to prevent. A LOADED Tauri
- * webview keeps answering while minimized, app-hidden, occluded, and on another Space.
+ * which is false for those states, and was the kind of wrong steer this function exists to prevent.
+ * A LOADED Tauri webview keeps answering while minimized, occluded, and on another Space. `hide()`
+ * after load is the remaining headless path: a hidden macOS WKWebView has been observed to go quiet
+ * after a pause, but that is not something every machine demonstrates, so this message names it as
+ * a candidate rather than a fact.
  *
  * It then over-corrected: it asserted the hidden-before-load ordering as FACT. But the only evidence
  * here is `hidden === true` — the ordering is never observed. Measured on a Tauri shell pointed at an

package/dist/session/command-timeout.js

@@ -11,11 +11,12 @@ const ONE_WAY_ADVICE = 'The page is ALIVE — the SDK last reported to the bridg
     'replaced mid-session, a proxy buffering one way) rather than at your app.';
 const HIDDEN_ADVICE = 'The page last reported itself hidden, and this is a WKWebView (Tauri) window, so the webview is ' +
     'most likely not running the page at all. Two known causes, commonest first: (1) the window was ' +
-    'hidden BEFORE its first page load — a webview that has never been presented never loads, so hide ' +
+    'hidden BEFORE its first page load — a webview that has never been presented never loads, so park ' +
     'it from `on_page_load` instead of `setup` (see `reticle_tauri::on_page_load`, which does this for ' +
-    'RETICLE_HEADLESS=1); once the page HAS loaded, hiding it is safe. (2) the window never presented ' +
-    'for another reason — check that it is declared with a visible size and that the page URL actually ' +
-    'loaded. If neither fits, the page is reachable but not executing, which is worth reporting.';
+    'RETICLE_HEADLESS=1). (2) the window was hidden after load and then went quiet — that has been ' +
+    'observed on a hidden macOS WKWebView after a pause, even though capture still works; park it ' +
+    'off-screen rather than calling hide. If neither fits, the page is reachable but not executing, ' +
+    'which is worth reporting.';
 /** True when this session is a WebKit desktop shell — the only runtime that suffers this. */
 function isWebKitDesktop(context) {
     if (AppRuntime.TAURI === context.runtime)

package/dist/session/dev-server-probe.d.ts

@@ -69,13 +69,5 @@ export declare function probeDevServerStates(ports?: readonly number[], probe?:
     serving: number[];
     slow: number[];
 }>;
-/**
- * The strongest state either loopback family reports.
- *
- * Serving a document beats a bare connection beats nothing, so a server bound to only one family is
- * still seen at its best — the same "either, not both" rule `anyFamilyServes` follows, extended to
- * three states.
- */
-export declare function anyFamilyState(port: number, probe?: (port: number, host: string) => Promise<PortState>): Promise<PortState>;
 /** Every candidate port serving a document, in ascending order. Never rejects. */
 export declare function probeDevServers(ports?: readonly number[], probe?: (port: number) => Promise<boolean>): Promise<number[]>;

package/dist/session/dev-server-probe.js

@@ -132,7 +132,7 @@ export async function probeDevServerStates(ports = [...DEV_SERVER_PORTS], probe
  * still seen at its best — the same "either, not both" rule `anyFamilyServes` follows, extended to
  * three states.
  */
-export async function anyFamilyState(port, probe = probeState) {
+async function anyFamilyState(port, probe = probeState) {
     const answers = await Promise.all(PROBE_HOSTS.map((host) => probe(port, host).catch(() => PortState.CLOSED)));
     if (answers.includes(PortState.SERVES_DOCUMENT))
         return PortState.SERVES_DOCUMENT;

package/dist/session/last-act.d.ts

@@ -16,6 +16,12 @@
  */
 interface ActEffect {
     action?: string | undefined;
+    /**
+     * The ref the action dispatched against. Recorded so the verdict nudge can suggest a call about
+     * the element the agent actually touched, rather than a worked example from a document. Written
+     * on the SAME success path as `action`, so a refused act leaves neither.
+     */
+    ref?: string | undefined;
     /** DOM mutations inside the acted element's own subtree. Undefined means nobody measured. */
     mutatedWithin?: number | undefined;
 }
@@ -35,7 +41,7 @@ export declare class LastAct {
      * Marking only on the success path is what makes that unrepeatable: a failure mode added later
      * cannot forget to clean up state that was never written.
      */
-    markActed(cursor: number, action: string | undefined, mutatedWithin: number | undefined): void;
+    markActed(cursor: number, action: string | undefined, mutatedWithin: number | undefined, ref?: string): void;
     /**
      * A navigation — by URL or by reload — moves the floor without being an act.
      *

package/dist/session/last-act.js

@@ -18,9 +18,9 @@ export class LastAct {
      * Marking only on the success path is what makes that unrepeatable: a failure mode added later
      * cannot forget to clean up state that was never written.
      */
-    markActed(cursor, action, mutatedWithin) {
+    markActed(cursor, action, mutatedWithin, ref) {
         this.#cursor = cursor;
-        this.#effect = { action, mutatedWithin };
+        this.#effect = { action, mutatedWithin, ...(ref === undefined ? {} : { ref }) };
     }
     /**
      * A navigation — by URL or by reload — moves the floor without being an act.

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

@@ -0,0 +1,67 @@
+/**
+ * Telling the human that the agent went somewhere they cannot see.
+ *
+ * A lease is a separate pooled context, and it is the highest-value path in the product for
+ * autonomous work. It also has one failure mode that is entirely about people: the HUD lives in the
+ * human's OWN tab, so while an agent drives a lease that tab shows nothing at all. An idle agent and
+ * a busy one are then indistinguishable from the only seat a human occupies.
+ *
+ * That is not hypothetical. An agent followed the daemon's own throttle recommendation into a lease,
+ * drove fifteen calls, and the developer watching an empty HUD asked why nothing was running. The
+ * product was working perfectly and looked broken, which is the worst combination available.
+ *
+ * The fix rides on machinery that already exists — `pushNarration` posts `ReticleCommand.NARRATE`
+ * and every SDK in the field already renders it — so nothing here moves the wire contract. It is a
+ * message to tabs that are ALREADY connected, not a new capability.
+ */
+/** The minimum a session has to expose to be a candidate watcher. Structural, so tests need no SDK. */
+export interface WatcherCandidate {
+    id: string;
+    projectId: string | undefined;
+}
+/**
+ * Shown on a watching human's HUD when an agent takes a lease.
+ *
+ * States the fact and its consequence, because the fact alone ("agent leased a context") does not
+ * tell somebody why their screen is still. The consequence is the whole reason to say anything.
+ */
+export declare const AGENT_DRIVING_ELSEWHERE = "An agent is driving a separate leased context \u2014 its actions will not appear in this tab.";
+/** Shown when the lease is released, so a HUD that went quiet is explained in both directions. */
+export declare const AGENT_DRIVING_HERE_AGAIN = "The agent released its separate context \u2014 this tab is live again.";
+/**
+ * Shown to a tab that CONNECTS while a lease is already open.
+ *
+ * The acquire-time notice only reaches tabs that were already connected, so opening the app — or
+ * merely reloading it — during a lease landed somebody on a silent HUD with nothing explaining it.
+ * That is the same dark-HUD failure the acquire notice exists to prevent, arrived at from the other
+ * direction, and it is the more common one: a person opens the dashboard BECAUSE they want to watch.
+ *
+ * Worded for arrival rather than for a change of state — nothing just happened from this tab's point
+ * of view, so "an agent is driving elsewhere" would describe an event it never saw.
+ */
+export declare const AGENT_ALREADY_DRIVING_ELSEWHERE = "An agent is already driving a separate leased context \u2014 its actions will not appear in this tab.";
+/**
+ * Whether a session arriving now should be told a lease is already running.
+ *
+ * Same rules as `watchersToNotify`, expressed for one session: never tell a leased context about
+ * itself, and never tell somebody watching app A about a lease against app B.
+ */
+export declare function shouldGreetWithLeaseNotice(session: WatcherCandidate, leasedSessionIds: readonly string[], leasedProjectIds: readonly (string | undefined)[]): boolean;
+/**
+ * Which connected sessions belong to a human who should be told.
+ *
+ * Two exclusions, both deliberate:
+ *
+ * - Leased sessions. They ARE the agent's context; narrating "an agent is driving elsewhere" into
+ *   the tab doing the driving is noise, and with several leases open they would talk about each
+ *   other. Membership comes from the pool rather than an id prefix, because a naming convention is
+ *   not a fact and `pool.leasedSessionIds()` is.
+ *
+ * - Other projects. One daemon serves many, and somebody watching app A does not need to hear about
+ *   a lease taken against app B. A session that declares no project is NOT excluded: an older SDK
+ *   sends no projectId, and silently dropping those would reintroduce the dark HUD for exactly the
+ *   people least likely to work out why.
+ *
+ * Pure: no IO, no clock, no session objects. The caller does the posting.
+ */
+export declare function watchersToNotify(sessions: readonly WatcherCandidate[], leasedSessionIds: readonly string[], projectId: string | undefined): string[];