@reticlehq/server 3.2.0 → 3.3.0

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

@@ -15,11 +15,22 @@
  * 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. */
+/**
+ * What an agent needs to know about the continuity of one session.
+ *
+ * Every field here measures the SDK-to-daemon LINK. None of them measures the app: the origin the
+ * page was served from can stop answering entirely without any of these moving, because the socket
+ * that reports them is between the daemon and a document the browser is already holding. Reported
+ * as a false read of app health in #938, where a tab whose dev server was dead carried `outages: 0`
+ * and `connectedSinceMs: 11min` and was taken for a healthy app.
+ */
 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. */
+    /**
+     * How many times this session dropped and came back. Zero means the LINK never dropped; it does
+     * not mean the app behind it is alive.
+     */
     outages: number;
     /** The most recent gap, when there has been one. */
     lastOutage?: {

package/dist/portal/session/session-health.d.ts

@@ -38,6 +38,22 @@ export interface SessionHealth {
      * on `reticle_sessions` or `reticle_lease` is not on the surface it reads every call.
      */
     versionSkew?: string;
+    /**
+     * The session's event ledger, once it has grown enough to be worth a reader's attention.
+     *
+     * Present only past `LEDGER_NOTICE_FRACTION` of the cap, so a healthy session costs nothing --
+     * the same rule `pendingNavigationMs` follows. A ledger below that is doing its job quietly.
+     *
+     * It is here because nothing reported it. A repeating uncaught error wrote one session's ledger
+     * until the disk was full; neither the daemon nor `doctor` nor any
+     * health counter said a word, and the user found out when the disk was full (#986). A cap bounds
+     * the damage but does not make the writing visible, and this block is the surface an agent
+     * already reads on every act and assert.
+     */
+    ledger?: {
+        bytes: number;
+        capBytes: number;
+    };
 }
 /**
  * How long a request may be in flight before it is worth reporting on session health.
@@ -84,6 +100,18 @@ interface BufferEnvelope {
  * so a clean/empty result there is trustworthy and costs zero tokens.
  */
 export declare function bufferEnvelope(session: HealthSubject): BufferEnvelope;
+/**
+ * The session registered under `session.id` NOW, for describing a tab after a call that may have
+ * replaced its document. A reload or full navigation registers a new Session under the same id, and
+ * the object a handler resolved first is the page that unloaded; it reported itself hidden on the way
+ * out, so its health said "throttled" about a tab that was fine. Optional-called because test doubles
+ * are partial registries.
+ */
+export declare function currentOf<S extends {
+    id: string;
+}>(registry: {
+    get?: (id: string) => S | undefined;
+}, session: S): S;
 /** The `session` (and optional throttled `warning`) block spliced onto act/assert results. */
 interface HealthEnvelope {
     session?: SessionHealth;
@@ -142,4 +170,37 @@ interface HealthReport {
  * keep its previous value instead of silently flipping a session to "visible" on a partial report.
  */
 export declare function readHealthEvent(data: Record<string, unknown>): HealthReport;
+/**
+ * The ledger block for the health payload, or nothing when it is not worth saying.
+ *
+ * Absent below `LEDGER_NOTICE_FRACTION` of the cap, and absent when the size has not been measured
+ * yet -- a reader must be able to tell "not measured" from "empty", and a zero reported before the
+ * first append would be a claim rather than a reading.
+ */
+export declare function ledgerNotice(ledger: {
+    bytes: number;
+    capBytes: number;
+} | undefined): {
+    ledger?: {
+        bytes: number;
+        capBytes: number;
+    };
+};
+/**
+ * Every health field that is present only when it means something.
+ *
+ * One place answers "which optional facts belong on the health block", so a session does not have
+ * to know the rule for each. A healthy session gets an empty object back and its health block
+ * carries only the fields that are always true.
+ */
+export declare function healthNotices(events: readonly ReticleEvent[], elapsed: number, ledger: {
+    bytes: number;
+    capBytes: number;
+} | undefined): {
+    pendingNavigationMs?: number;
+    ledger?: {
+        bytes: number;
+        capBytes: number;
+    };
+};
 export {};

package/dist/portal/session/session-health.js

@@ -1,4 +1,4 @@
-import { BrowserBrand, EventType, BUFFER_EVICTION_WARNING, THROTTLED_STARVED_NOTE, THROTTLED_WARNING, } from '@reticlehq/core';
+import { BrowserBrand, EventType, BUFFER_EVICTION_WARNING, THROTTLED_STARVED_NOTE, SESSION_HEALTH, THROTTLED_WARNING, } from '@reticlehq/core';
 /**
  * How long a request may be in flight before it is worth reporting on session health.
  *
@@ -68,6 +68,16 @@ export function bufferEnvelope(session) {
         return {};
     return { buffer: { held: total, dropped, note: BUFFER_EVICTION_WARNING } };
 }
+/**
+ * The session registered under `session.id` NOW, for describing a tab after a call that may have
+ * replaced its document. A reload or full navigation registers a new Session under the same id, and
+ * the object a handler resolved first is the page that unloaded; it reported itself hidden on the way
+ * out, so its health said "throttled" about a tab that was fine. Optional-called because test doubles
+ * are partial registries.
+ */
+export function currentOf(registry, session) {
+    return registry.get?.(session.id) ?? session;
+}
 /**
  * Build the health envelope for a tool result. When the session is **nominal** (focused, not
  * throttled, no escape-hatch recommendation) the block is OMITTED entirely — a healthy session
@@ -152,3 +162,32 @@ export function readHealthEvent(data) {
         brand: Object.values(BrowserBrand).find((known) => known === data['brand']),
     };
 }
+/**
+ * The ledger block for the health payload, or nothing when it is not worth saying.
+ *
+ * Absent below `LEDGER_NOTICE_FRACTION` of the cap, and absent when the size has not been measured
+ * yet -- a reader must be able to tell "not measured" from "empty", and a zero reported before the
+ * first append would be a claim rather than a reading.
+ */
+export function ledgerNotice(ledger) {
+    if (ledger === undefined || 0 >= ledger.capBytes)
+        return {};
+    const fraction = ledger.bytes / ledger.capBytes;
+    return fraction < SESSION_HEALTH.LEDGER_NOTICE_FRACTION ? {} : { ledger };
+}
+/**
+ * Every health field that is present only when it means something.
+ *
+ * One place answers "which optional facts belong on the health block", so a session does not have
+ * to know the rule for each. A healthy session gets an empty object back and its health block
+ * carries only the fields that are always true.
+ */
+export function healthNotices(events, elapsed, ledger) {
+    // From event t=0, not a cursor: a wedge that began before the current action is exactly the case
+    // a per-window reading cannot see, and is the one both reporters hit.
+    const stuck = pendingNavigationMs(events, elapsed);
+    return {
+        ...(stuck === undefined ? {} : { pendingNavigationMs: stuck }),
+        ...ledgerNotice(ledger),
+    };
+}

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

@@ -45,6 +45,12 @@ export interface SessionInfo {
      * A tab that dropped for four seconds and came back is indistinguishable from one that never left
      * (#117), and that difference decides whether a verdict over the window can be trusted. Attached
      * by `SessionManager.list()`, which is the layer that sees every connect and disconnect.
+     *
+     * Scoped to the SDK-to-daemon LINK, and the names do not say so on their own. A zombie tab whose
+     * dev server had died reported `outages: 0` and `connectedSinceMs: 11min`, and both were correct:
+     * the page's socket was still attached to the daemon. Read as app health, they said the app was
+     * up while nothing was listening on the port (#938). The describe() on the `reticle_sessions`
+     * output schema carries that caveat, because that is where an agent reads it.
      */
     attachment?: {
         connectedSinceMs: number;

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

@@ -22,6 +22,15 @@ export declare class SessionManager {
     add(session: Session): Session | undefined;
     remove(session: Session): boolean;
     get(sessionId: string): Session | undefined;
+    /**
+     * Did this id belong to a session that has since disconnected?
+     *
+     * `resolve` answers a departed id with its live SUCCESSOR, which is what keeps a reload working
+     * for everything that observes. A caller that is about to do something DESTRUCTIVE needs the
+     * other answer: whether the thing it named is still there. Ending a session it did not name is
+     * not a recoverable mistake (#983).
+     */
+    departed(sessionId: string): SessionIdentity | undefined;
     list(): SessionInfo[];
     /** Continuity for one session — "has this been attached the whole time I am reasoning about?" */
     attachmentOf(sessionId: string): ReturnType<AttachmentHistory['of']>;

package/dist/portal/session/session-manager.js

@@ -3,7 +3,7 @@ import { notePendingNoSessionReason } from '../../telemetry/tool-refused.js';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
 import { AttachmentHistory } from './presence/attachment-history.js';
-import { pickDocumentSuccessor } from './session-successor.js';
+import { openedBeforeDeparture, pickDocumentSuccessor, } from './session-successor.js';
 import { SESSION_DISCONNECTED_REASON } from './facts/session-replaced.js';
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export function originOf(url) {
@@ -87,6 +87,8 @@ export class SessionManager {
      * id forgets its tombstone — the live session is the answer then.
      */
     #tombstones = new Map();
+    /** The tabs already open when each tombstoned session departed: siblings, never its successor. */
+    #siblingsAtDeparture = new Map();
     /**
      * The active project's scope, set once from the daemon's .reticle.json. When a tool resolves a session
      * without passing its own scope, this is applied — so auto-selection is project-scoped by default
@@ -128,6 +130,7 @@ export class SessionManager {
         declareDrivenRedactionKeys(session.id, session.redactKeys);
         this.#attachment.attached(session.id);
         this.#tombstones.delete(session.id);
+        this.#siblingsAtDeparture.delete(session.id);
         return previous;
     }
     /**
@@ -158,6 +161,9 @@ export class SessionManager {
             return;
         if (this.#tombstones.has(session.id))
             this.#tombstones.delete(session.id);
+        this.#siblingsAtDeparture.set(session.id, new Set([...this.#sessions.values()]
+            .filter((s) => s !== session && openedBeforeDeparture(s, session))
+            .map((s) => s.id)));
         this.#tombstones.set(session.id, {
             id: session.id,
             url: session.url,
@@ -168,13 +174,17 @@ export class SessionManager {
             if (oldest === undefined)
                 break;
             this.#tombstones.delete(oldest);
+            this.#siblingsAtDeparture.delete(oldest);
         }
     }
     #successorOf(sessionId) {
         const departed = this.#tombstones.get(sessionId);
         if (departed === undefined)
             return undefined;
-        const picked = pickDocumentSuccessor(this.all().map((s) => ({
+        const siblings = this.#siblingsAtDeparture.get(sessionId);
+        const picked = pickDocumentSuccessor(this.all()
+            .filter((s) => true !== siblings?.has(s.id))
+            .map((s) => ({
             id: s.id,
             url: s.url,
             ...(s.projectId === undefined ? {} : { projectId: s.projectId }),
@@ -186,6 +196,17 @@ export class SessionManager {
     get(sessionId) {
         return this.#sessions.get(sessionId);
     }
+    /**
+     * Did this id belong to a session that has since disconnected?
+     *
+     * `resolve` answers a departed id with its live SUCCESSOR, which is what keeps a reload working
+     * for everything that observes. A caller that is about to do something DESTRUCTIVE needs the
+     * other answer: whether the thing it named is still there. Ending a session it did not name is
+     * not a recoverable mistake (#983).
+     */
+    departed(sessionId) {
+        return this.#tombstones.get(sessionId);
+    }
     list() {
         return [...this.#sessions.values()].map((s) => {
             const info = s.info();

package/dist/portal/session/session-successor.d.ts

@@ -26,6 +26,17 @@ export interface SuccessorClock {
  * A same-id reconnect is a successor: the id survived in sessionStorage, the document did not.
  */
 export declare function pickDocumentSuccessor(live: readonly SessionIdentity[], departed: SessionIdentity): SessionIdentity | undefined;
+/**
+ * Whether `candidate` was already connected before the agent last drove `departed`.
+ *
+ * Such a tab is a SIBLING, never the document the departed tab's navigation produced: that document
+ * can only have connected after the command that caused it. Without this, two tabs of one project
+ * were resolved as "unique at the origin" in the gap before the departed tab came back, and a verdict
+ * for tab A was graded on tab B (#983, reproduced by driving). Measured as ages rather than instants,
+ * so both sides read the same clock at the same moment and the comparison does not drift while a
+ * caller polls.
+ */
+export declare function openedBeforeDeparture(candidate: Pick<Session, 'staleMs'>, departed: Pick<Session, 'agentIdleMs'>): boolean;
 export interface SuccessorRegistry {
     get(id: string): Session | undefined;
     all(): readonly Session[];

package/dist/portal/session/session-successor.js

@@ -100,6 +100,19 @@ export function pickDocumentSuccessor(live, departed) {
         return undefined;
     return others[0];
 }
+/**
+ * Whether `candidate` was already connected before the agent last drove `departed`.
+ *
+ * Such a tab is a SIBLING, never the document the departed tab's navigation produced: that document
+ * can only have connected after the command that caused it. Without this, two tabs of one project
+ * were resolved as "unique at the origin" in the gap before the departed tab came back, and a verdict
+ * for tab A was graded on tab B (#983, reproduced by driving). Measured as ages rather than instants,
+ * so both sides read the same clock at the same moment and the comparison does not drift while a
+ * caller polls.
+ */
+export function openedBeforeDeparture(candidate, departed) {
+    return candidate.staleMs() > departed.agentIdleMs();
+}
 /**
  * Poll until a successor of `departed` is live, or the budget runs out. Null on timeout — never
  * throws, because failing to follow is a legitimate `observation_lost`, not an error.
@@ -115,7 +128,7 @@ export async function awaitDocumentSuccessor(sessions, departed, timeoutMs, cloc
         // out of the pick, or same-id-first would keep returning the page that just unloaded.
         const picked = pickDocumentSuccessor(sessions
             .all()
-            .filter((s) => s !== departed)
+            .filter((s) => s !== departed && !openedBeforeDeparture(s, departed))
             .map(identityOf), departedIdentity);
         if (picked !== undefined) {
             const live = sessions.get(picked.id);

package/dist/portal/session/session-verdict-facts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The facts a SESSION contributes to a verdict, in the shape `decideVerified` takes.
+ *
+ * `decideVerified` is pure and has no session, so anything it needs about the link has to be
+ * threaded in. Two tools produce verdicts — `reticle_assert` and `reticle_act_and_wait` — and both
+ * were threading the same fields with the same conditional-spread idiom and the same comment
+ * beside it. A third fact (`versionSkew`) would have been a third copy.
+ *
+ * One function instead, for the ordinary reason: when a fourth fact arrives, a verdict surface that
+ * learns it in one place cannot half-learn it. That failure mode is not hypothetical here — the
+ * repo already records `net` assertions being discarded on one half of a surface because a filter
+ * was updated on the other.
+ *
+ * Every field is omitted rather than defaulted when absent. An SDK too old to declare sends
+ * nothing, and an empty value is a claim nobody made.
+ */
+/** What a session can tell a verdict. Optional throughout: absent means nobody said. */
+export interface SessionVerdictFacts {
+    readonly sdkVersion?: string;
+    readonly versionSkew?: string;
+}
+/** The shape read here — structural, so a test double needs no session. */
+export interface VerdictRelevantSession {
+    readonly sdkVersion?: string | undefined;
+    readonly versionSkew?: string | undefined;
+    readonly channels?: readonly string[] | undefined;
+}
+export declare function sessionVerdictFacts(session: VerdictRelevantSession): SessionVerdictFacts;

package/dist/portal/session/session-verdict-facts.js

@@ -0,0 +1,15 @@
+export function sessionVerdictFacts(session) {
+    const facts = {};
+    // So the unread-body remedy can check it applies to THIS page.
+    if (session.sdkVersion !== undefined)
+        facts.sdkVersion = session.sdkVersion;
+    /*
+     * An empty string is NOT a skew. The bridge sets this only on a real mismatch, but a defaulted
+     * or cleared field reaching the verdict would cost every call a `yes` it had earned — which is a
+     * worse failure than the one this exists to fix.
+     */
+    if (session.versionSkew !== undefined && session.versionSkew.length > 0) {
+        facts.versionSkew = session.versionSkew;
+    }
+    return facts;
+}

package/dist/portal/session/session.d.ts

@@ -44,6 +44,11 @@ export declare class Session implements HandshakeFacts {
      * root, which is what every counter did unconditionally before this existed.
      */
     artifactRoot: string | undefined;
+    /**
+     * Same-origin endpoints this session's project declared as background (`.reticle.json`
+     * `background`). Stamped with `artifactRoot`, from the same project. Empty excludes nothing.
+     */
+    background: readonly string[];
     url: string;
     title: string;
     adapters: string[];

package/dist/portal/session/session.js

@@ -5,19 +5,19 @@ import { LastAct } from './last-act.js';
 import { GapLedger } from '@reticlehq/engine/evidence/gap-ledger.js';
 import { CaptureLedger } from '../../surface/tools/feature-capture.js';
 import { commandTimeoutMessage } from './timing/command-timeout.js';
-import { readHealthEvent, pendingNavigationMs } from './session-health.js';
+import { readHealthEvent, healthNotices } from './session-health.js';
 import { MIRRORED_COMMANDS, mirroredNarration } from './presence/session-mirror.js';
 /** The HUD does not need 200 frames to watch a counter climb; the last state always lands. */
 const IMPACT_PUSH_DEBOUNCE_MS = 700;
 import { PendingCommands, CommandTimeoutError } from './page-commands/pending-commands.js';
 import { span } from '../../trace.js';
 import { keepCallerContextInDaemon, noteToDaemonLog } from './daemon-answers.js';
-import { isKnownRealm, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
+import { isKnownRealm, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, HudUseDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
 import { RingBuffer } from '@reticlehq/engine/window/ring-buffer.js';
 import { readJournalWriteLoss, readQueryEvents, } from '../../memory/journal/journal-query.js';
 import {} from '@reticlehq/engine/window/ambient.js';
 import { ObservedState } from './facts/observed-state.js';
-import { recordBrowserLatency, recordSdkFailure } from '../../telemetry/session-metrics.js';
+import { recordBrowserLatency, recordHudUse, recordSdkFailure, } from '../../telemetry/session-metrics.js';
 import { LiveControl } from './human/live-control.js';
 import { ReviewStore } from './human/review-store.js';
 import { buildSessionRecommendation } from './presence/session-recommendation.js';
@@ -63,6 +63,11 @@ export class Session {
      * root, which is what every counter did unconditionally before this existed.
      */
     artifactRoot;
+    /**
+     * Same-origin endpoints this session's project declared as background (`.reticle.json`
+     * `background`). Stamped with `artifactRoot`, from the same project. Empty excludes nothing.
+     */
+    background = [];
     url;
     title;
     adapters;
@@ -188,17 +193,16 @@ export class Session {
     }
     /** The attachable health block — single source of truth for the tools. */
     health() {
-        // From event t=0, not a cursor: a wedge that began before the current action is exactly the
-        // case a per-window reading cannot see, and is the one both reporters hit.
-        const stuck = pendingNavigationMs(this.eventsSince(0), this.elapsed());
         const base = {
             lastSeenMs: this.lastSeenMs(),
             throttled: this.throttled(),
             focused: this.#focused,
-            ...(stuck === undefined ? {} : { pendingNavigationMs: stuck }),
             // Carried onto every act/assert result, not just reticle_sessions: skew drops actions
             // SILENTLY, and the fields it contradicts are on the act verdict.
             ...(this.versionSkew === undefined ? {} : { versionSkew: this.versionSkew }),
+            // The absence-gated facts: a stuck navigation and an ledger worth naming. Both are absent on
+            // a healthy session, and `healthNotices` owns which is which.
+            ...healthNotices(this.eventsSince(0), this.elapsed(), this.#journalReader?.ledger?.()),
         };
         // attach the escape-hatch hint only when un-scriptable (keeps field absent otherwise).
         const recommendation = buildSessionRecommendation({
@@ -261,6 +265,14 @@ export class Session {
     keepCallerContext = keepCallerContextInDaemon;
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event, byteSize) {
+        // Telemetry about the HUD, not evidence about the app: taken off here, before the buffer, so no
+        // verdict, settle window or agent read can ever see a person's clicks on Reticle's own panel.
+        if (event.type === EventType.HUD_USED) {
+            const use = HudUseDataSchema.safeParse(event.data);
+            if (use.success)
+                recordHudUse(use.data);
+            return;
+        }
         if (event.documentId !== undefined)
             this.#documentId = event.documentId;
         if (event.editEpoch !== undefined)

package/dist/surface/mcp/mcp-proxy.js

@@ -10,9 +10,9 @@ export { probeDaemon, waitForDaemon } from './proxy/proxy-daemon-probe.js';
 import { probeDaemon } from './proxy/proxy-daemon-probe.js';
 import { SERVER_VERSION } from '../../command/version/identity/server-version.js';
 import { buildServerInstructions } from './server-instructions.js';
-import { hasProjectConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
+import { hasAnyProjectConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
 import { reticleStateHome } from '../../command/daemon/daemon.js';
-import { readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
+import { projectIdsAt } from '../../command/cli/ports/resolve/cli-port.js';
 import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from '../../command/version/peer-announce.js';
 import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, onQueueExpired, OnDrop, OnRequest, } from './proxy/proxy-lifecycle.js';
 import { describePresence, probePresence } from '../../command/daemon/binding/port-presence.js';
@@ -289,7 +289,7 @@ export function buildSessionUrl(rawData, port) {
 function proxyInstructions(port) {
     try {
         return buildServerInstructions({
-            previouslyConnected: hasProjectConnectedBefore(reticleStateHome(), port, readProjectId(process.cwd())),
+            previouslyConnected: hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(process.cwd())),
         });
     }
     catch {

package/dist/surface/mcp/proxy-idle-exit.d.ts

@@ -10,7 +10,7 @@
 export declare const PROXY_IDLE_EXIT_MS: number;
 /** The local diagnostic emitted before an abandoned proxy exits. */
 export declare const PROXY_IDLE_EXIT_EVENT = "reticle_mcp_proxy_idle_exit";
-export interface ProxyIdleExitOptions {
+interface ProxyIdleExitOptions {
     /** Called once after the client link has stayed quiet for the whole grace. */
     onExit: (idleMs: number) => void;
     /** True while a request or queued message still needs an answer. */
@@ -43,3 +43,4 @@ export declare class ProxyIdleExit {
  * zero as the explicit opt-out. Invalid values retain the conservative one-day default.
  */
 export declare function resolveProxyIdleExitMs(raw: string | undefined): number;
+export {};

package/dist/surface/mcp/server-instructions.js

@@ -31,7 +31,18 @@ import { surfaceVocabulary, listOf } from './surface-vocabulary.js';
  * measured reason. A briefing that names a tool the agent was not given does not merely confuse it;
  * it makes the agent stop using the product altogether.
  */
-const verdictDiscipline = (v) => `Reticle verifies a running web app from the inside: go (${v.navigate}), look (${listOf(v.look, v.find)}), act and prove in one hop (${v.actAndWait}), observe (${listOf(v.observe, v.state, v.network, v.console)}), assert (${v.assert}). Verify a user-facing change against the real app before you call it done, and never weaken a check to make it pass.
+/*
+ * `reticle gate` is FOLDED INTO the done sentence rather than given a paragraph, and that is the
+ * budget rule working rather than a stylistic choice.
+ *
+ * The instruction block has a hard byte cap whose own note says a raise must be paid for with a
+ * measurement, and that if one cannot be shown the right answer is to cut an older sentence. There
+ * is no measurement for `gate`: it is built, it has anti-reward-hacking, and it appeared in no
+ * surface an agent reads, which is an argument and not a number. Cutting a measured sentence to
+ * make room for an unmeasured one would be strictly worse. So it costs about a hundred characters
+ * inside the sentence that already names the exact moment it applies to, and the cap did not move.
+ */
+const verdictDiscipline = (v) => `Reticle verifies a running web app from the inside: go (${v.navigate}), look (${listOf(v.look, v.find)}), act and prove in one hop (${v.actAndWait}), observe (${listOf(v.observe, v.state, v.network, v.console)}), assert (${v.assert}). Verify a user-facing change against the real app before you call it done — \`npx @reticlehq/server gate --since <ref>\` fails unless a passing artifact covers every flow your edits affect — and never weaken a check to make it pass.
 
 Only ${v.actAndWait} and ${v.assert} produce a verdict. ${v.act.length > 0 ? `${v.act} and e` : 'E'}verything else moves or reads the app and proves nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer ${v.actAndWait}({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. Only verified:"yes" is a pass — "unknown" means Reticle could not tell what happened, "no-fault" means nothing was declared to prove. Report either as not proved.
 

package/dist/surface/tools/act/already-true.d.ts

@@ -0,0 +1,40 @@
+import type { Predicate } from '@reticlehq/engine/question/predicate/predicate-schema.js';
+import type { PredicateSession } from '@reticlehq/engine/question/predicate/predicate-session.js';
+import type { Baselines } from '@reticlehq/engine/question/predicate/predicate.js';
+/** Everything the pre-action check learned, which is three facts about one reading. */
+export interface AlreadyTrueReading {
+    /** The consequence held BEFORE the action, so the action proved nothing about it. */
+    alreadyTrue: boolean;
+    /** That pre-existing match was against something hidden — a stronger reason to doubt the claim. */
+    alreadyTrueHiddenMatch: boolean;
+    /**
+     * WHAT was already true, kept rather than discarded.
+     *
+     * `already_true` tells an agent its assertion held before it acted; the next question is always
+     * "true how?" and it was unanswerable, because the reading decided the bit and was then thrown
+     * away. Afterwards the action has run and the state may have moved, so the one moment that
+     * mattered is gone. Present only when the answer is yes: a verdict that was genuinely caused
+     * carries its own evidence and needs no baseline beside it.
+     */
+    alreadyTrueEvidence?: unknown;
+    /**
+     * What each comparing leaf was reading BEFORE the action — the predicate language's past tense.
+     *
+     * Taken here because this is already the one place that looks at the app before it is touched,
+     * and a second pre-action pass would be a second round trip for a reading we are standing next
+     * to. Empty unless the caller actually asked for a comparison, so nothing pays for it.
+     */
+    baselines: Baselines;
+}
+/**
+ * Ask whether the declared consequence was already true, once, before the action.
+ *
+ * Only for predicates that read live DOM state. Event-based ones are floored at this act's cursor
+ * and cannot be satisfied by the past, so they need no pre-check and pay nothing. One extra query,
+ * on the path where a green is otherwise unfalsifiable.
+ *
+ * Gathered here rather than as three locals at the call site because they are three readings OF ONE
+ * THING, and `act-tools.ts` sits on the 1000-line cohesion cap: the rule says split before adding,
+ * and this is the unit that wanted splitting.
+ */
+export declare function readAlreadyTrue(session: PredicateSession, until: Predicate | undefined, since: number): Promise<AlreadyTrueReading>;

package/dist/surface/tools/act/already-true.js

@@ -0,0 +1,36 @@
+import { evaluatePredicate } from '@reticlehq/engine/question/predicate/predicate.js';
+import { readsDomState } from '@reticlehq/engine/evidence/already-true.js';
+import { alreadyTrueHiddenMatch as alreadyTrueHiddenMatchOf } from '@reticlehq/engine/evidence/already-true.js';
+import { captureBaselines } from '@reticlehq/engine/evidence/baseline.js';
+/**
+ * Ask whether the declared consequence was already true, once, before the action.
+ *
+ * Only for predicates that read live DOM state. Event-based ones are floored at this act's cursor
+ * and cannot be satisfied by the past, so they need no pre-check and pay nothing. One extra query,
+ * on the path where a green is otherwise unfalsifiable.
+ *
+ * Gathered here rather than as three locals at the call site because they are three readings OF ONE
+ * THING, and `act-tools.ts` sits on the 1000-line cohesion cap: the rule says split before adding,
+ * and this is the unit that wanted splitting.
+ */
+export async function readAlreadyTrue(session, until, since) {
+    // Before the pre-check, because the pre-check EVALUATES the predicate and a relative leaf with no
+    // baseline yet would report `inconclusive` — reading the app twice to answer a question we had
+    // not taken the reading for.
+    const baselines = await captureBaselines(session, until);
+    const precheck = until !== undefined && readsDomState(until)
+        ? await evaluatePredicate(session, until, since, false, baselines)
+        : undefined;
+    const alreadyTrue = precheck?.pass ?? false;
+    if (!alreadyTrue || until === undefined) {
+        return { alreadyTrue: false, alreadyTrueHiddenMatch: false, baselines };
+    }
+    return {
+        alreadyTrue: true,
+        baselines,
+        // The pre-check evidence is already in hand, so asking whether the match was against something
+        // hidden costs nothing and lets the message name it (#889).
+        alreadyTrueHiddenMatch: alreadyTrueHiddenMatchOf(until, precheck?.evidence),
+        ...(precheck?.evidence === undefined ? {} : { alreadyTrueEvidence: precheck.evidence }),
+    };
+}

package/dist/surface/tools/act/navigation/navigate-arrival.d.ts

@@ -24,6 +24,12 @@ import type { NavigateArrival } from './navigate-result.js';
  * and the SDK to dial back; short enough to not hang. A caller who knows the app is slower says so.
  */
 export declare const ARRIVAL_TIMEOUT_MS = 5000;
+/**
+ * The navigation target as an absolute URL, resolved against the tab being navigated — the same
+ * resolution the browser applies. An agent passes a path (`/orders?id=4`) as often as a full URL,
+ * and `samePage` cannot parse a path, so without this a relative navigation could never confirm.
+ */
+export declare function absoluteTarget(target: string, base: string): string;
 /**
  * Which session an arrival may be attributed to.
  *

package/dist/surface/tools/act/navigation/navigate-arrival.js

@@ -41,6 +41,19 @@ function samePage(a, b) {
         return false;
     }
 }
+/**
+ * The navigation target as an absolute URL, resolved against the tab being navigated — the same
+ * resolution the browser applies. An agent passes a path (`/orders?id=4`) as often as a full URL,
+ * and `samePage` cannot parse a path, so without this a relative navigation could never confirm.
+ */
+export function absoluteTarget(target, base) {
+    try {
+        return new URL(target, base).href;
+    }
+    catch {
+        return target;
+    }
+}
 /**
  * The sessions already on `target` — the set `ArrivalScope.priorIds` is built from, sampled before
  * the navigation is dispatched.

package/dist/surface/tools/act/settle-in-flight.d.ts

@@ -34,6 +34,10 @@ export interface SettleSource {
         data: Record<string, unknown>;
     }[];
     elapsed(): number;
+    /** The page under test — what makes a request third-party. Absent: nothing is foreign. */
+    url?: string;
+    /** Same-origin endpoints the project declared as background. Absent: nothing is excluded. */
+    background?: readonly string[];
 }
 interface WaitOpts {
     /** Injected so the wait is testable without real time passing (rule: never call the clock inline). */
@@ -49,7 +53,7 @@ interface WaitOpts {
 export declare function inFlightRequestIds(events: readonly {
     type: string;
     data: Record<string, unknown>;
-}[]): string[];
+}[], appOrigin?: string, background?: readonly string[]): string[];
 /**
  * The same outstanding requests, as "METHOD url" — what an unsettled verdict has to be able to name.
  *
@@ -61,7 +65,7 @@ export declare function inFlightRequestIds(events: readonly {
 export declare function inFlightRequestLabels(events: readonly {
     type: string;
     data: Record<string, unknown>;
-}[]): string[];
+}[], appOrigin?: string, background?: readonly string[]): string[];
 /**
  * Endpoints called MORE THAN ONCE in this window, busiest first, as "METHOD url ×N".
  *