@reticlehq/server 2.6.0 → 2.8.0

package/dist/tools/react-grace.js

@@ -0,0 +1,87 @@
+/**
+ * "The app ignored this response" is only sayable once the app has had a chance to read it.
+ *
+ * `response-ignored` fires when a write succeeded on the server and nothing on the client moved. It
+ * is a real and valuable finding — a lost write, a response parsed into the void, a render that never
+ * happened. It is also an ACCUSATION, and it is decided by where a window happens to end.
+ *
+ * Waiting for in-flight requests before taking the verdict made that boundary dangerous in a way it
+ * was not before. Previously the write was still pending when the window closed, so it never reached
+ * the settled list and this rule could not fire at all. Now the response lands inside the window BY
+ * DESIGN — and the app's re-render happens in a later task, a few milliseconds after it. Close the
+ * window in that gap and every channel agrees that the app took a successful write and did nothing.
+ *
+ * The verdict is then `verified:"no"` on a completely correct application, produced entirely by where
+ * we chose to stop looking. For a verification tool that is the more damaging direction of error: a
+ * false green is a missed catch, but a false accusation sends someone to fix code that is not broken,
+ * and it is how the instrument stops being believed.
+ *
+ * So the response is not the end of the window — the app's REACTION to it is. The grace is paid only
+ * in the exact case that would otherwise be accused: a successful mutating write with nothing moved
+ * after it. Every other action returns without a single poll.
+ *
+ * Deliberately short. This covers a task-boundary re-render, not a slow app: if nothing has moved
+ * within the grace, "ignored" has become an honest description and the finding should stand.
+ */
+import { EventType } from '@reticlehq/core';
+/**
+ * How long to let the app react. A React commit after a resolved fetch is one or two task hops; this
+ * is generous against that and still far too short to paper over an app that genuinely dropped the
+ * response.
+ */
+const REACTION_GRACE_MS = 300;
+/** Poll cadence — the same as the settle wait, for the same reason. */
+const POLL_MS = 50;
+const MUTATING = ['POST', 'PUT', 'PATCH', 'DELETE'];
+/** Movement that would clear `response-ignored`; mirrors `uiAdvanced` in the detector. */
+const MOVEMENT = new Set([
+    EventType.DOM_ADDED,
+    EventType.DOM_REMOVED,
+    EventType.DOM_ATTR,
+    EventType.DOM_TEXT,
+    EventType.STATE_CHANGE,
+    EventType.ROUTE_CHANGE,
+]);
+function moved(events) {
+    return events.some((e) => MOVEMENT.has(e.type));
+}
+/**
+ * Is this a window that would be wrongly accused if it ended right now?
+ *
+ * True only for the accusable shape: a SUCCESSFUL MUTATING request settled, and nothing has moved. A
+ * read that changed nothing is a prefetch, a failed write is a different finding entirely, and an
+ * action that already moved the UI has nothing to wait for — none of them buy a grace period.
+ */
+export function awaitsReaction(events) {
+    if (moved(events))
+        return false;
+    return events.some((e) => {
+        if (e.type !== EventType.NET_REQUEST)
+            return false;
+        const method = 'string' === typeof e.data['method'] ? e.data['method'].toUpperCase() : '';
+        const ok = e.data['ok'];
+        return MUTATING.includes(method) && true === ok;
+    });
+}
+/**
+ * Wait, bounded by BOTH the grace and the caller's remaining budget, for the app to react to a write
+ * it has just been told succeeded.
+ *
+ * Returns whether the app moved. A `false` is not a verdict — it hands the question back to the
+ * contradiction engine, which will raise `response-ignored` exactly as it does today. The point is
+ * only that by then the app has been given its chance, so the finding means what it says.
+ */
+export async function waitForReaction(session, since, budgetMs, opts) {
+    if (!awaitsReaction(session.eventsSince(since)))
+        return true;
+    const window = Math.min(REACTION_GRACE_MS, budgetMs);
+    if (window <= 0)
+        return false;
+    const deadline = session.elapsed() + window;
+    while (session.elapsed() < deadline) {
+        await opts.sleep(Math.min(POLL_MS, deadline - session.elapsed()));
+        if (moved(session.eventsSince(since)))
+            return true;
+    }
+    return false;
+}

package/dist/tools/read-tools.js

@@ -11,7 +11,7 @@ import { replayProgram } from '../flows/replay.js';
 import { diffLines } from '../project/baselines.js';
 import { selectPath, capDepth, projectComponentState } from '../session/state-select.js';
 import { costHint } from '../session/output-budget.js';
-import { buildReactionReport } from '../events/reaction.js';
+import { buildReactionReport, summarizeReaction } from '../events/reaction.js';
 import { asString, asNumber, parseInteractive } from './tools-helpers.js';
 import { sessionIdShape, commandOrThrow, snapshotTree } from './tool-kit.js';
 import { bufferEnvelope } from '../session/session-health.js';
@@ -178,17 +178,33 @@ export const READ_TOOLS = [
             const report = buildReactionReport(events, session.elapsed() - rec.cursor);
             // Self-generating oracles: propose ranked mustHold from what the recorded window actually did.
             const proposedConsequences = proposeConsequences(events);
-            return Promise.resolve({
+            const digest = summarizeReaction(report);
+            // Say that the timeline was left out, and where it lives.
+            //
+            // Dropping the raw events is right: they were most of a response large enough to truncate the
+            // part that mattered. But a field that simply stops appearing is indistinguishable from one
+            // this version never had, and an agent cannot ask for something it does not know exists. The
+            // same rule the capped diff arrays follow: a trim is never silent.
+            const timeline = events.length > 0
+                ? {
+                    timeline_omitted: `${String(events.length)} event(s) were recorded and are not included here. Call reticle_observe { since: ${String(rec.cursor)} } for the raw timeline.`,
+                }
+                : {};
+            const body = {
                 recordingName: name,
                 program,
+                ...timeline,
                 ...(unstable > 0
                     ? {
                         warning: unanchoredWarning(unstable),
                     }
                     : {}),
                 ...(proposedConsequences.length > 0 ? { proposedConsequences } : {}),
-                ...report,
-                cost: costHint(report, events.length),
+                ...digest,
+            };
+            return Promise.resolve({
+                ...body,
+                cost: costHint(body, events.length),
             });
         },
     },

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

@@ -0,0 +1,79 @@
+/**
+ * Spend the budget you were given before reporting that you ran out of certainty.
+ *
+ * `waitForPredicate` resolves the instant the predicate holds. On an app that navigates
+ * optimistically — which is normal, correct behaviour, and the norm on exactly the flows agents
+ * verify most: login, submit, save — that instant arrives while the write is still in flight. The
+ * verdict was then taken over a window the app had not finished writing, and came back
+ * `unknown / unsettled` with a recovery note asking the CALLER to re-check.
+ *
+ * Measured on the most common flow there is: a login that genuinely succeeded returned at 492ms out
+ * of an 8000ms budget. The declared signal had fired with matching data, state had moved from
+ * anonymous to authenticated, the token was in storage, honesty grade was `signal` and capture
+ * integrity was clean. Seven and a half seconds of authorised waiting went unused, and the agent was
+ * handed a shrug.
+ *
+ * A false NEGATIVE is not the mirror of a false positive here. A false positive stops an agent early;
+ * a false negative makes it redo work that already succeeded, and — far worse — teaches it to
+ * discount the verdict channel. The verdict channel is the entire product, and an agent that learns
+ * to ignore `unknown` will ignore the true ones too.
+ *
+ * What this does NOT do is decide the request succeeded. At 492ms nobody can know that, and inventing
+ * a green here would be the exact defect this product exists to prevent. It waits for the answer
+ * rather than guessing at it:
+ *
+ *   - everything settles → the normal contradiction machinery sees the real responses, so a failure
+ *     still contradicts and a success no longer looks like an absence;
+ *   - still in flight when the budget genuinely runs out → `unsettled`, as before, but now an honest
+ *     limit instead of an early exit.
+ */
+/** Just the shape this needs — a real Session satisfies it, and a test can supply it. */
+export interface SettleSource {
+    eventsSince(cursor: number): readonly {
+        type: string;
+        data: Record<string, unknown>;
+    }[];
+    elapsed(): number;
+}
+interface WaitOpts {
+    /** Injected so the wait is testable without real time passing (rule: never call the clock inline). */
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * Requests that started in this window and have not come back.
+ *
+ * A settle for a request this window never saw START is ignored on purpose: the window is floored at
+ * the act cursor, so a response belonging to an earlier action can land inside it, and counting that
+ * as progress would let unrelated traffic close the window early.
+ */
+export declare function inFlightRequestIds(events: readonly {
+    type: string;
+    data: Record<string, unknown>;
+}[]): string[];
+/**
+ * The same outstanding requests, as "METHOD url" — what an unsettled verdict has to be able to name.
+ *
+ * A correlation id is the right key for the wait and useless in a sentence: an agent told that
+ * `r-17` is open cannot act on it, while `POST /api/login` is the thing to re-check or to assert
+ * directly. Read off the NET_PENDING the window already holds, so this costs one pass over events
+ * that are in hand.
+ */
+export declare function inFlightRequestLabels(events: readonly {
+    type: string;
+    data: Record<string, unknown>;
+}[]): string[];
+export interface SettleResult {
+    /** True when nothing this window started is still outstanding. */
+    settled: boolean;
+    /** What was still open when the wait ended — empty when `settled`. */
+    stillInFlight: string[];
+}
+/**
+ * Wait, bounded by `budgetMs`, for the requests this window started to come back.
+ *
+ * Returns immediately when nothing is in flight, so the common green path — an action with no traffic
+ * — pays nothing at all. A zero or negative budget means no wait: the caller may have spent the whole
+ * timeout reaching the predicate, and a negative deadline must mean "stop", never "loop forever".
+ */
+export declare function waitForInFlight(session: SettleSource, since: number, budgetMs: number, opts: WaitOpts): Promise<SettleResult>;
+export {};

package/dist/tools/settle-in-flight.js

@@ -0,0 +1,106 @@
+/**
+ * Spend the budget you were given before reporting that you ran out of certainty.
+ *
+ * `waitForPredicate` resolves the instant the predicate holds. On an app that navigates
+ * optimistically — which is normal, correct behaviour, and the norm on exactly the flows agents
+ * verify most: login, submit, save — that instant arrives while the write is still in flight. The
+ * verdict was then taken over a window the app had not finished writing, and came back
+ * `unknown / unsettled` with a recovery note asking the CALLER to re-check.
+ *
+ * Measured on the most common flow there is: a login that genuinely succeeded returned at 492ms out
+ * of an 8000ms budget. The declared signal had fired with matching data, state had moved from
+ * anonymous to authenticated, the token was in storage, honesty grade was `signal` and capture
+ * integrity was clean. Seven and a half seconds of authorised waiting went unused, and the agent was
+ * handed a shrug.
+ *
+ * A false NEGATIVE is not the mirror of a false positive here. A false positive stops an agent early;
+ * a false negative makes it redo work that already succeeded, and — far worse — teaches it to
+ * discount the verdict channel. The verdict channel is the entire product, and an agent that learns
+ * to ignore `unknown` will ignore the true ones too.
+ *
+ * What this does NOT do is decide the request succeeded. At 492ms nobody can know that, and inventing
+ * a green here would be the exact defect this product exists to prevent. It waits for the answer
+ * rather than guessing at it:
+ *
+ *   - everything settles → the normal contradiction machinery sees the real responses, so a failure
+ *     still contradicts and a success no longer looks like an absence;
+ *   - still in flight when the budget genuinely runs out → `unsettled`, as before, but now an honest
+ *     limit instead of an early exit.
+ */
+import { EventType } from '@reticlehq/core';
+/** How often to re-read the buffer. Short enough to return promptly, long enough not to spin. */
+const POLL_MS = 50;
+const idOf = (data) => 'string' === typeof data['id'] ? data['id'] : undefined;
+/**
+ * Requests that started in this window and have not come back.
+ *
+ * A settle for a request this window never saw START is ignored on purpose: the window is floored at
+ * the act cursor, so a response belonging to an earlier action can land inside it, and counting that
+ * as progress would let unrelated traffic close the window early.
+ */
+export function inFlightRequestIds(events) {
+    const settled = new Set();
+    for (const e of events) {
+        if (e.type !== EventType.NET_REQUEST)
+            continue;
+        const id = idOf(e.data);
+        if (id !== undefined)
+            settled.add(id);
+    }
+    const open = [];
+    for (const e of events) {
+        if (e.type !== EventType.NET_PENDING)
+            continue;
+        const id = idOf(e.data);
+        if (id !== undefined && !settled.has(id) && !open.includes(id))
+            open.push(id);
+    }
+    return open;
+}
+/**
+ * The same outstanding requests, as "METHOD url" — what an unsettled verdict has to be able to name.
+ *
+ * A correlation id is the right key for the wait and useless in a sentence: an agent told that
+ * `r-17` is open cannot act on it, while `POST /api/login` is the thing to re-check or to assert
+ * directly. Read off the NET_PENDING the window already holds, so this costs one pass over events
+ * that are in hand.
+ */
+export function inFlightRequestLabels(events) {
+    const open = new Set(inFlightRequestIds(events));
+    const labels = [];
+    for (const e of events) {
+        if (e.type !== EventType.NET_PENDING)
+            continue;
+        const id = idOf(e.data);
+        if (id === undefined || !open.has(id))
+            continue;
+        open.delete(id); // one label per request, however many times its start was recorded
+        const method = 'string' === typeof e.data['method'] ? e.data['method'] : 'request';
+        const url = 'string' === typeof e.data['url'] ? e.data['url'] : 'an unreported url';
+        labels.push(`${method} ${url}`);
+    }
+    return labels;
+}
+/**
+ * Wait, bounded by `budgetMs`, for the requests this window started to come back.
+ *
+ * Returns immediately when nothing is in flight, so the common green path — an action with no traffic
+ * — pays nothing at all. A zero or negative budget means no wait: the caller may have spent the whole
+ * timeout reaching the predicate, and a negative deadline must mean "stop", never "loop forever".
+ */
+export async function waitForInFlight(session, since, budgetMs, opts) {
+    let open = inFlightRequestIds(session.eventsSince(since));
+    if (0 === open.length)
+        return { settled: true, stillInFlight: [] };
+    if (budgetMs <= 0)
+        return { settled: false, stillInFlight: open };
+    const deadline = session.elapsed() + budgetMs;
+    while (session.elapsed() < deadline) {
+        // Never overshoot the budget: the last sleep is trimmed to whatever is actually left.
+        await opts.sleep(Math.min(POLL_MS, deadline - session.elapsed()));
+        open = inFlightRequestIds(session.eventsSince(since));
+        if (0 === open.length)
+            return { settled: true, stillInFlight: [] };
+    }
+    return { settled: false, stillInFlight: open };
+}

package/dist/tools/snapshot-delta.d.ts

@@ -24,13 +24,20 @@ interface SnapshotDelta {
     addedCount: number;
     removedCount: number;
 }
+/** Where focus moved, when it moved. Absent fields mean nothing held focus on that side. */
+export interface FocusChange {
+    from?: string;
+    to?: string;
+}
 type DeltaDecision = {
     mode: typeof SnapshotDeltaMode.FULL;
 } | {
     mode: typeof SnapshotDeltaMode.UNCHANGED;
+    focusChanged?: FocusChange;
 } | {
     mode: typeof SnapshotDeltaMode.DELTA;
     delta: SnapshotDelta;
+    focusChanged?: FocusChange;
 };
 /** Pure: decide full vs delta vs unchanged given the previous tree (same route) and the next tree. */
 export declare function snapshotDelta(prevTree: string | undefined, nextTree: string): DeltaDecision;

package/dist/tools/snapshot-delta.js

@@ -12,7 +12,108 @@
  * invalidates the prior snapshot (a diff across pages would be meaningless), so the next snapshot
  * returns full — never a misleading cross-page delta.
  */
-import { normalizeLines, diffLines } from '../project/baselines.js';
+/**
+ * Identity for comparison, ref for action.
+ *
+ * The delta path used `normalizeLines` from the baseline layer, which strips the ref marker on
+ * purpose — a ref stored in a baseline would make every later diff noisy. Correct there, wrong here:
+ * every delta line came back as `- button "Row actions"` with no ref, and acting needs a ref, so the
+ * full snapshot had to be taken anyway. The diff call cost tokens and bought nothing. One helper, two
+ * callers, opposite requirements — so this path keeps the ref-stripped line as the KEY and emits the
+ * ORIGINAL line with its ref.
+ *
+ * Focus is stripped from the key too. It rides in the line as `[focused]`, alone or comma-joined with
+ * other states, so a focus move used to surface as one line removed and its twin added — structural
+ * change reported where nothing had been added at all. Focus is a property OF a line, so it gets its
+ * own field. Only focus is exempt: `disabled` moving is a real change and must still show.
+ */
+/** The ref marker, as `formatLine` writes it. Bounded quantifier: `\s*` backtracks polynomially. */
+const REF_MARKER = /\s?\(ref=e\d+\)/;
+/** The state bracket — ` [disabled,checked,expanded,focused]` — and the one state that is not structural. */
+const STATE_BRACKET = /\s\[([a-z,]+)\]$/;
+const FOCUSED_STATE = 'focused';
+/** True when this line carries focus. */
+function isFocused(line) {
+    return true === STATE_BRACKET.exec(line)?.[1]?.split(',').includes(FOCUSED_STATE);
+}
+/** The same line with focus removed — and the bracket dropped when focus was all it held. */
+function withoutFocus(line) {
+    const match = STATE_BRACKET.exec(line);
+    const states = match?.[1];
+    if (null === match || undefined === match || undefined === states)
+        return line;
+    const rest = states.split(',').filter((s) => s !== FOCUSED_STATE);
+    const head = line.slice(0, match.index);
+    return 0 === rest.length ? head : `${head} [${rest.join(',')}]`;
+}
+/** What makes two lines "the same element" for diffing: no ref, no focus, no surrounding space. */
+function deltaKey(line) {
+    return withoutFocus(line.replace(REF_MARKER, '')).trim();
+}
+function deltaLines(tree) {
+    return tree
+        .split('\n')
+        .map((line) => ({ key: deltaKey(line), text: withoutFocus(line).trim() }))
+        .filter((line) => line.key.length > 0);
+}
+/**
+ * Multiset diff on the key, emitting the original text.
+ *
+ * Multiset rather than set because duplicate labels are the norm — twelve identical `Row actions`
+ * buttons — and the count is the only thing that says how many left. Emitting the ORIGINAL text is
+ * what finally tells them apart: with refs, "which twelve" has an answer.
+ */
+function diffKeyed(prev, next) {
+    const bucket = (lines) => {
+        const map = new Map();
+        for (const line of lines) {
+            const existing = map.get(line.key);
+            if (existing === undefined)
+                map.set(line.key, [line.text]);
+            else
+                existing.push(line.text);
+        }
+        return map;
+    };
+    const before = bucket(prev);
+    const after = bucket(next);
+    const removed = [];
+    const added = [];
+    for (const key of new Set([...before.keys(), ...after.keys()])) {
+        const was = before.get(key) ?? [];
+        const now = after.get(key) ?? [];
+        // Pair the SAME REF first. Twelve identical `Row actions` buttons are one key, and the ref is the
+        // only thing that says which of them left — an end-of-list surplus would name an arbitrary one.
+        const survived = new Set(now);
+        const wentOrChanged = was.filter((text) => !survived.has(text));
+        const arrivedOrChanged = now.filter((text) => !new Set(was).has(text));
+        // Whatever is left over on both sides is the SAME element with a re-minted ref (a re-render, or a
+        // navigation that restarts the sequence). Pairing those off is what stops a ref change reading as
+        // a removal plus an addition; only the count difference is a real structural change.
+        const paired = Math.min(wentOrChanged.length, arrivedOrChanged.length);
+        removed.push(...wentOrChanged.slice(paired));
+        added.push(...arrivedOrChanged.slice(paired));
+    }
+    return { removed, added };
+}
+/**
+ * Where focus sits now: the line to show, plus the identity to compare it BY.
+ *
+ * These have to be two different things. Comparing the rendered lines said focus had moved whenever
+ * the focused element merely changed — typing into a focused textbox rewrites its `[value=...]`, so
+ * `from` and `to` came back naming the same element with different text. Focus identity is the
+ * ELEMENT, so the comparison is on the ref, and the line is only what gets displayed. Where there is
+ * no ref to compare (a non-interactive line), the ref-stripped key stands in.
+ *
+ * Read from the raw tree so a line the diff filters out cannot silently swallow the focus report.
+ */
+function focusedLine(tree) {
+    const focused = tree.split('\n').find((line) => isFocused(line));
+    if (focused === undefined)
+        return undefined;
+    const text = withoutFocus(focused).trim();
+    return { id: REF_MARKER.exec(focused)?.[0]?.trim() ?? deltaKey(focused), text };
+}
 export const SnapshotDeltaMode = {
     FULL: 'full',
     DELTA: 'delta',
@@ -22,12 +123,25 @@ export const SnapshotDeltaMode = {
 export function snapshotDelta(prevTree, nextTree) {
     if (prevTree === undefined)
         return { mode: SnapshotDeltaMode.FULL };
-    const { added, removed } = diffLines(normalizeLines(prevTree), normalizeLines(nextTree));
-    if (0 === added.length && 0 === removed.length)
-        return { mode: SnapshotDeltaMode.UNCHANGED };
+    const { added, removed } = diffKeyed(deltaLines(prevTree), deltaLines(nextTree));
+    const before = focusedLine(prevTree);
+    const now = focusedLine(nextTree);
+    // Reported only on a MOVE. Repeating "focus is still here" every turn is the noise the delta exists
+    // to remove, and an absent field is how the agent knows nothing happened.
+    const focusChanged = before?.id === now?.id
+        ? undefined
+        : {
+            ...(before === undefined ? {} : { from: before.text }),
+            ...(now === undefined ? {} : { to: now.text }),
+        };
+    const moved = focusChanged === undefined ? {} : { focusChanged };
+    if (0 === added.length && 0 === removed.length) {
+        return { mode: SnapshotDeltaMode.UNCHANGED, ...moved };
+    }
     return {
         mode: SnapshotDeltaMode.DELTA,
         delta: { added, removed, addedCount: added.length, removedCount: removed.length },
+        ...moved,
     };
 }
 const DEFAULT_MAX_ENTRIES = 50;
@@ -105,8 +219,18 @@ export function applySnapshotDelta(raw, opts, cache) {
     // statement about the cap, not about the page. Carried through on both branches: a delta computed
     // over a prefix is real but not exhaustive either.
     const capped = true === r['truncated'] ? { truncated: true, note: CAPPED_DIFF_NOTE } : {};
+    // Spread onto BOTH branches. A value computed correctly and declared nowhere on the way out is the
+    // defect shape that hit this release five separate times: nothing throws, no test reddens, the
+    // field is simply absent forever.
+    const moved = decision.focusChanged === undefined ? {} : { focusChanged: decision.focusChanged };
     if (decision.mode === SnapshotDeltaMode.UNCHANGED) {
-        return { mode: SnapshotDeltaMode.UNCHANGED, status: r['status'], ...capped };
+        return { mode: SnapshotDeltaMode.UNCHANGED, status: r['status'], ...moved, ...capped };
     }
-    return { mode: SnapshotDeltaMode.DELTA, delta: decision.delta, status: r['status'], ...capped };
+    return {
+        mode: SnapshotDeltaMode.DELTA,
+        delta: decision.delta,
+        status: r['status'],
+        ...moved,
+        ...capped,
+    };
 }

package/dist/tools/tool-kit.d.ts

@@ -84,11 +84,58 @@ export declare const sessionIdShape: {
     sessionId: z.ZodOptional<z.ZodString>;
 };
 /**
- * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime
- * (health, pool lease reminder, age cleanup nudge, and the delivered-once human-control envelope).
- * They are declared here and merged into each session-bound tool's outputSchema so a schema-strict
- * client (structuredContent validation) keeps them instead of silently dropping them — the `control`
- * envelope is the human-in-the-loop guidance channel, so losing it is a safety failure, not cosmetic.
+ * Every key `runTool` splices onto a session-bound result, as a closed list.
+ *
+ * These are wire strings and were inlined at the splice sites, which is exactly how four of them
+ * came to be spliced and never declared. `sessionEnvelopeShape` is derived from this object and
+ * `envelope-keys-declared.test.ts` fails if a member is missing from it, so the two cannot drift.
+ *
+ * Each of these is a channel that exists BECAUSE the agent had no other way to learn the fact.
+ * Undeclared, a schema-strict client validating `structuredContent` drops it, and the channel is
+ * indistinguishable from never having been built.
+ */
+export declare const EnvelopeKey: {
+    /** Session health — which tab, how fresh. */
+    readonly SESSION: "session";
+    /** One-shot pool-lease reminder. */
+    readonly SESSION_LEASE: "session_lease";
+    /** One-shot "these sessions are old, clean them up". */
+    readonly SESSION_AGE_WARNING: "session_age_warning";
+    /** The delivered-once human-in-the-loop guidance envelope. Losing it is a safety failure. */
+    readonly CONTROL: "control";
+    /**
+     * Rides alongside `session` whenever the tab is THROTTLED. It was declared on `reticle_act`'s
+     * schema and nowhere else, so on a validating profile every other session-bound tool silently
+     * dropped it — a throttled tab, where drives can no-op, returned a healthy-looking result.
+     */
+    readonly WARNING: "warning";
+    /** One-shot "ask the human how this went". */
+    readonly FEEDBACK_PROMPT: "feedback_prompt";
+    /** One-shot "a newer Reticle exists". */
+    readonly UPDATE_AVAILABLE: "update_available";
+    /**
+     * "You have driven this page N times without asking for a verdict."
+     *
+     * The largest known lever on the metric this product is judged by: verdict-less sessions
+     * overwhelmingly never call a verdict-producing tool at all. It was spliced undeclared, so on a
+     * validating client the nudge was built, fired, and thrown away before any agent saw it.
+     */
+    readonly VERIFY_NEXT: "verify_next";
+    /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
+    readonly FEEDBACK_INVITE: "feedback_invite";
+    /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
+    readonly VERSION_SKEW: "version_skew";
+    /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
+    readonly FEEDBACK_UNDELIVERED: "feedback_undelivered";
+};
+export type EnvelopeKey = (typeof EnvelopeKey)[keyof typeof EnvelopeKey];
+/**
+ * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime.
+ * Merged into each session-bound tool's outputSchema so a schema-strict client (structuredContent
+ * validation) keeps them instead of silently dropping them.
+ *
+ * Derived from `EnvelopeKey` rather than re-listed: this shape and the splice sites disagreed for a
+ * whole release, and every key that went missing was a channel nobody could see was missing.
  */
 export declare const sessionEnvelopeShape: z.ZodRawShape;
 /** Unwrap a browser command result or throw its error so the agent sees a clean failure. */