@reticlehq/server 3.1.0 → 3.2.0

package/dist/surface/tools/harness-plan.d.ts

@@ -0,0 +1,76 @@
+/**
+ * What a drive is FOR, decided before it starts and read out of `.reticle` rather than the app.
+ *
+ * The driver used to open its eyes on a page and pick whatever looked interesting. That makes every
+ * run start from zero: it re-drives journeys that are already saved, and it has no idea which
+ * declared intent nobody has ever tested. Both are the same missing input — the project's own
+ * record of what it claims to do and what has been proved about it.
+ *
+ * `.reticle` already holds that. `buildDomainModel` reads `.reticle/flows/` and
+ * `.reticle/contract.json` and answers with every saved flow, the consequence that MUST hold for
+ * each one, and the GAPS: signals and testids the app DECLARED that no flow asserts. So the plan is
+ * derivable with no browser, no model and no source code — which is the order this product argues
+ * for everywhere else and did not follow here.
+ *
+ * Two kinds of step, and the split is the whole economics:
+ *
+ *   REPLAY  a journey that is already recorded. Deterministic, no model in the loop, a few hundred
+ *           tokens. Anything already covered belongs here and must never be re-driven.
+ *   DRIVE   a gap. A model is worth paying for exactly where nothing is proved yet.
+ *
+ * Nothing here calls a model. The plan is the deterministic half, and the model's only job is to
+ * choose among steps somebody already decided were worth taking.
+ */
+import type { DomainModel } from '../../judgement/domain/domain-model.js';
+export declare const PlanStepKind: {
+    /** Already recorded: replay it deterministically instead of paying a model to rediscover it. */
+    readonly REPLAY: "replay";
+    /** Declared but never proved: this is what a drive is actually for. */
+    readonly DRIVE: "drive";
+};
+export type PlanStepKind = (typeof PlanStepKind)[keyof typeof PlanStepKind];
+export interface PlanStep {
+    kind: PlanStepKind;
+    /** The flow to replay, or a short label for the gap to cover. */
+    target: string;
+    /**
+     * WHY this step is in the plan, in the project's own words.
+     *
+     * For a replay it is the consequence that must hold — the flow's `mustHold`, which is the thing
+     * that stops being true when the feature breaks. For a drive it is the declared intent nobody has
+     * tested. Carried because the model choosing between steps should be reading intent, not a list
+     * of names it has no way to rank.
+     */
+    why: string;
+}
+export interface HarnessPlan {
+    steps: readonly PlanStep[];
+    /** One line an agent or a human can read, derived rather than narrated. */
+    summary: string;
+    /**
+     * The app's OWN vocabulary: the signals it declared in its capabilities, untested ones first.
+     *
+     * Carried out of `.reticle` for the same reason the steps are, and then used for something the
+     * plan itself never does. A drive declares what it expects BEFORE it acts, and a declaration can
+     * only be saved into the flow if it names something: `signal "order:placed"` records, a bare
+     * "some signal fires" does not, and a flow that records nothing replays green whatever the
+     * feature does. These are the names that make the difference.
+     */
+    vocabulary: readonly string[];
+}
+/**
+ * Build the plan.
+ *
+ * Replays come first, always. They are the cheap half and they establish what is still true before
+ * any model is paid to explore what is not yet known — and a regression found by a replay is found
+ * for a few hundred tokens rather than a few hundred thousand.
+ */
+export declare function buildHarnessPlan(domain: DomainModel): HarnessPlan;
+/**
+ * The plan as the model reads it.
+ *
+ * Intent first and names second, because a model ranking "what next" against a list of identifiers
+ * is guessing, and ranking against what the project says each one is FOR is not. The kind is stated
+ * so it can prefer finishing the cheap deterministic half before spending itself on the rest.
+ */
+export declare function planAsText(plan: HarnessPlan): string;

package/dist/surface/tools/harness-plan.js

@@ -0,0 +1,156 @@
+/**
+ * What a drive is FOR, decided before it starts and read out of `.reticle` rather than the app.
+ *
+ * The driver used to open its eyes on a page and pick whatever looked interesting. That makes every
+ * run start from zero: it re-drives journeys that are already saved, and it has no idea which
+ * declared intent nobody has ever tested. Both are the same missing input — the project's own
+ * record of what it claims to do and what has been proved about it.
+ *
+ * `.reticle` already holds that. `buildDomainModel` reads `.reticle/flows/` and
+ * `.reticle/contract.json` and answers with every saved flow, the consequence that MUST hold for
+ * each one, and the GAPS: signals and testids the app DECLARED that no flow asserts. So the plan is
+ * derivable with no browser, no model and no source code — which is the order this product argues
+ * for everywhere else and did not follow here.
+ *
+ * Two kinds of step, and the split is the whole economics:
+ *
+ *   REPLAY  a journey that is already recorded. Deterministic, no model in the loop, a few hundred
+ *           tokens. Anything already covered belongs here and must never be re-driven.
+ *   DRIVE   a gap. A model is worth paying for exactly where nothing is proved yet.
+ *
+ * Nothing here calls a model. The plan is the deterministic half, and the model's only job is to
+ * choose among steps somebody already decided were worth taking.
+ */
+export const PlanStepKind = {
+    /** Already recorded: replay it deterministically instead of paying a model to rediscover it. */
+    REPLAY: 'replay',
+    /** Declared but never proved: this is what a drive is actually for. */
+    DRIVE: 'drive',
+};
+/**
+ * How many untested declarations become drive steps.
+ *
+ * A contract can declare hundreds of testids, and a plan longer than the step budget is not a plan,
+ * it is a list. Capped so the drive spends its budget on the front of a ranked queue rather than
+ * spreading itself across everything and finishing none of it.
+ */
+const MAX_DRIVE_STEPS = 12;
+/**
+ * How many recorded journeys become replay steps.
+ *
+ * A project with seventy-four flows produced a seventy-four-step plan, which went into the tool
+ * result AND the standing instruction — thousands of tokens spent, every turn, listing work the
+ * drive had no budget to do. The whole argument for reading `.reticle` first is spending less, and
+ * an uncapped plan spends more.
+ *
+ * `reticle_domain` caps its own per-flow detail at 25 for the same measured reason. Ranked before
+ * cutting, so what survives is what is worth replaying first rather than whatever was listed first.
+ */
+const MAX_REPLAY_STEPS = 15;
+/** Signals first: a declared signal is a stronger statement of intent than a testid. */
+function driveSteps(domain) {
+    const steps = [];
+    for (const signal of domain.gaps.declaredUntestedSignals) {
+        steps.push({
+            kind: PlanStepKind.DRIVE,
+            target: signal,
+            why: `the app declares the signal "${signal}" and no saved flow asserts it`,
+        });
+    }
+    for (const testid of domain.gaps.declaredUntestedTestids) {
+        steps.push({
+            kind: PlanStepKind.DRIVE,
+            target: testid,
+            why: `the app declares the control "${testid}" and no saved flow exercises it`,
+        });
+    }
+    return steps.slice(0, MAX_DRIVE_STEPS);
+}
+/**
+ * Replay steps, worst-risk first when there is run history to rank by.
+ *
+ * A flow that asserts nothing is listed too, and says so: replaying it proves very little, and the
+ * honest plan admits that rather than counting it as coverage.
+ */
+function replaySteps(domain) {
+    const byName = new Map(domain.flows.map((flow) => [flow.name, flow]));
+    const ordered = 0 === domain.riskRanked.length
+        ? domain.flows.map((flow) => flow.name)
+        : [
+            ...domain.riskRanked,
+            ...domain.flows.map((f) => f.name).filter((name) => !domain.riskRanked.includes(name)),
+        ];
+    /*
+     * Flows that assert a real consequence come first, whatever the run history says.
+     *
+     * A flow with no `mustHold` passes as long as its steps still run, so replaying one proves close
+     * to nothing — and when the plan has to be cut, proving nothing is the first thing to give up.
+     */
+    const ranked = [
+        ...ordered.filter((name) => byName.get(name)?.mustHold !== undefined),
+        ...ordered.filter((name) => byName.get(name)?.mustHold === undefined),
+    ];
+    const steps = [];
+    for (const name of ranked) {
+        const flow = byName.get(name);
+        if (flow === undefined)
+            continue;
+        steps.push({
+            kind: PlanStepKind.REPLAY,
+            target: name,
+            why: flow.mustHold === undefined
+                ? `already recorded, but it asserts no consequence — replaying it proves only that the steps still run`
+                : `already recorded; it must still hold: ${flow.mustHold}`,
+        });
+    }
+    return steps.slice(0, MAX_REPLAY_STEPS);
+}
+/**
+ * Build the plan.
+ *
+ * Replays come first, always. They are the cheap half and they establish what is still true before
+ * any model is paid to explore what is not yet known — and a regression found by a replay is found
+ * for a few hundred tokens rather than a few hundred thousand.
+ */
+export function buildHarnessPlan(domain) {
+    const replays = replaySteps(domain);
+    const drives = driveSteps(domain);
+    const steps = [...replays, ...drives];
+    // Counted over EVERYTHING, then listed up to the cap — the same split `reticle_domain` uses, so a
+    // capped listing never quietly becomes a smaller analysis.
+    const totalRecorded = domain.flows.length;
+    const totalGaps = domain.gaps.declaredUntestedSignals.length + domain.gaps.declaredUntestedTestids.length;
+    const omitted = totalRecorded - replays.length + (totalGaps - drives.length);
+    /*
+     * Untested declarations first: a signal no flow asserts is exactly the one a drive should be
+     * claiming, and it is the same ranking the drive steps above already use.
+     *
+     * Then the signals saved flows ALREADY assert, which is not redundant and not a nicety. Most apps
+     * declare no capabilities at all -- the production dashboard this was measured on has no
+     * `contract.json` -- so a vocabulary built only from declarations is empty for exactly the
+     * projects that most need one. A signal a saved flow asserts is better evidence than a
+     * declaration anyway: it is a name the app has actually been observed to fire.
+     */
+    const vocabulary = [
+        ...domain.gaps.declaredUntestedSignals,
+        ...domain.declared.signals,
+        ...domain.flows.flatMap((flow) => flow.signals),
+    ].filter((name, index, all) => 0 < name.length && all.indexOf(name) === index);
+    const summary = 0 === steps.length
+        ? 'Nothing is recorded and nothing is declared: there is no plan to follow, so drive the app to find out what it does.'
+        : `${String(totalRecorded)} recorded journey(s) and ${String(totalGaps)} untested declaration(s); the plan lists the ${String(steps.length)} worth doing first${0 === omitted ? '' : `, omitting ${String(omitted)}`}.`;
+    return { steps, summary, vocabulary };
+}
+/**
+ * The plan as the model reads it.
+ *
+ * Intent first and names second, because a model ranking "what next" against a list of identifiers
+ * is guessing, and ranking against what the project says each one is FOR is not. The kind is stated
+ * so it can prefer finishing the cheap deterministic half before spending itself on the rest.
+ */
+export function planAsText(plan) {
+    if (0 === plan.steps.length)
+        return 'PLAN: none — nothing recorded, nothing declared.';
+    const lines = plan.steps.map((step, index) => ` ${String(index + 1)}. [${step.kind}] ${step.target} — ${step.why}`);
+    return `PLAN (from .reticle, not from the source):\n${lines.join('\n')}`;
+}

package/dist/surface/tools/harness-toolset.js

@@ -23,7 +23,18 @@ import { withTimeout } from '../../features/harness/with-timeout.js';
  * only through a discovery hop — and a hop the model has to take on every journey is a hop it will
  * sometimes skip, which silently turns the cheap path off.
  */
-const HARNESS_EXTRA_TOOLS = [ReticleTool.RECORD, ReticleTool.FLOW_SAVE];
+/**
+ * Beyond the default surface, the three tools a drive cannot do its job without.
+ *
+ * RECORD and FLOW_SAVE are how a drive keeps what it drove. FLOW_REPLAY is how it avoids driving
+ * the same thing twice — it was absent, so a driver handed a plan full of already-recorded journeys
+ * had no way to run one, and every run paid a model to rediscover what was on disk.
+ */
+const HARNESS_EXTRA_TOOLS = [
+    ReticleTool.RECORD,
+    ReticleTool.FLOW_SAVE,
+    ReticleTool.FLOW_REPLAY,
+];
 /**
  * The one deliberate subtraction.
  *

package/dist/surface/tools/invoke-tool.js

@@ -14,10 +14,11 @@ import { resultIsError } from '../mcp/faults/mcp-is-error.js';
 import { verificationOf } from '../../telemetry/verification-of.js';
 import { emitBugFoundHook, emitVerdictHook } from '../../hooks/hook-emit.js';
 import { reportOnboardingStep } from '../../telemetry/onboarding-funnel.js';
-import { noteFirstVerdict, noteOnboardingFirst } from '../../telemetry/onboarding-firsts.js';
+import { noteActed, noteFirstVerdict, noteOnboardingFirst } from '../../telemetry/onboarding-firsts.js';
+import { withHarnessDrive } from '../../telemetry/harness-drive.js';
 import { OnboardingPhase, OnboardingStepStatus } from '@reticlehq/core/telemetry';
 import { asString } from '@reticlehq/core';
-import { sessionIdFromArgs, spentRefFromArgs } from './tools-helpers.js';
+import { SESSION_ID_ARG, sessionIdFromArgs, spentRefFromArgs } from './tools-helpers.js';
 import { EnvelopeKey } from './tool-kit.js';
 import { ReticleTool } from '@reticlehq/core';
 import { takeFeedbackPrompt } from './feedback-tools.js';
@@ -152,6 +153,17 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     // when NO session exists — "nothing ever connected" is feedback we especially want.
     ReticleTool.FEEDBACK,
 ]);
+/**
+ * The merged action that hands the drive to a model inside the daemon.
+ *
+ * Derived from the member tool's own name rather than spelled again: the merge dispatches on
+ * `action`, and `reticle_verify` plus `explore` IS `reticle_verify_explore`. A literal here would be
+ * a third spelling of one name, and the one that silently stops matching when the action is renamed.
+ */
+const HARNESS_DRIVE_ACTION = ReticleTool.VERIFY_EXPLORE.slice(`${ReticleTool.VERIFY}_`.length);
+function isHarnessDrive(toolName, args) {
+    return ReticleTool.VERIFY === toolName && HARNESS_DRIVE_ACTION === args['action'];
+}
 function isPlainObject(value) {
     return 'object' === typeof value && value !== null && !Array.isArray(value);
 }
@@ -299,6 +311,34 @@ function firstOversizedArg(args) {
     }
     return undefined;
 }
+/**
+ * The args the handler is dispatched with, pinned to the session THIS call resolved.
+ *
+ * `runTool` resolves the session once and then attributes the whole call to it: the pool lease it
+ * refreshes, the health envelope it splices, the tab a ref is recorded as minted in, the project
+ * ledger the call lands in, the session a verdict is reported under. The handler was then handed
+ * the caller's args untouched, so a call that named no `sessionId` resolved a SECOND time — and a
+ * tab that connects in between can win auto-selection on its fresher heartbeat. The action goes to
+ * one tab and the answer describes another, which is a verdict about a page that was never driven
+ * and reads exactly like a correct one (#983).
+ *
+ * The wrong-tab ref guard is the sharpest case: it is asked whether the ref belongs to the tab
+ * resolution picked, so its permission is only sound if that is also the tab the handler drives.
+ *
+ * A COPY, never a write into the caller's object. `reticle_run`, the merged families and the
+ * programmatic invoker all pass the same record on, and a dispatch decision leaking back into it
+ * would outlive this call.
+ *
+ * Only a GUESSED session is pinned. An explicit id — including one lifted off a sequence step — is
+ * passed through exactly as written, so whether a stale id refuses or rebinds stays the resolver's
+ * decision; and a tool no session was resolved for (disk-only tools, or nothing connected) is left
+ * unscoped, so it answers as it always did.
+ */
+function pinnedArgs(args, explicitSessionId, session) {
+    if (explicitSessionId !== undefined || session === undefined)
+        return args;
+    return { ...args, [SESSION_ID_ARG]: session.id };
+}
 export async function runTool(tool, deps, args) {
     // Both dispatch paths (MCP + programmatic) pass through here — the one place "which tool is mostly
     // used" can be counted. This used to EMIT an event per call; it now increments an in-process counter
@@ -313,7 +353,7 @@ export async function runTool(tool, deps, args) {
     noteToolCall();
     // The ONBOARD firsts, at the chokepoint every call already passes through — so a second dispatch
     // path cannot quietly stop reporting them the way an extra listener would.
-    noteOnboardingFirst(tool.name, args);
+    noteOnboardingFirst(tool.name);
     // The impact record needs the project's own `.reticle` root, and this is the first place every
     // call knows it. Idempotent: the first root wins for the daemon's lifetime.
     initImpact({ reticleRoot: deps.reticleRoot });
@@ -343,8 +383,13 @@ export async function runTool(tool, deps, args) {
     }
     // An ACTION is what gets abandoned. Counted here, against verifications, so "the agent drove the
     // page and then wandered off" becomes a number instead of an impression.
-    if (ACTION_TOOLS.has(tool.name))
+    if (ACTION_TOOLS.has(tool.name)) {
         getSessionMetrics().recordAction();
+        // The two funnel rungs this branch is the authority on: the first action of the run, and the
+        // fact that this install has been driven at all. Reported from the set that already decides
+        // what "drove the page" means, so a fourth driving tool inherits both.
+        noteActed(args);
+    }
     const settleTiming = getSessionMetrics().startToolCall(tool.name, args);
     const startedAt = Date.now();
     const rawSessionId = sessionIdFromArgs(args);
@@ -430,12 +475,27 @@ export async function runTool(tool, deps, args) {
     const leaseId = session?.id ?? rawSessionId;
     if (leaseId !== undefined)
         deps.pool?.touch(leaseId);
+    // One identity for the whole call: the handler drives the session everything above is attributed
+    // to, rather than resolving again against a registry that can have changed underneath it.
+    const dispatchArgs = pinnedArgs(args, rawSessionId, session);
     let raw;
     try {
         // The one dispatch point every tool call passes through, so it is where the trace's root span
         // belongs: with RETICLE_TRACE on, every stage that runs underneath inherits this call's id and
         // nests under it. Free when off — see trace.ts.
-        raw = await span('tool.handler', { tool: tool.name, session: session?.id }, () => tool.handler(deps, args));
+        // `dispatchArgs`, not `args`: an inferred session is pinned into the arguments before the
+        // handler sees them, so a tool that resolves the session a second time cannot land on a
+        // different one than the dispatcher chose.
+        const call = () => span('tool.handler', { tool: tool.name, session: session?.id }, () => tool.handler(deps, dispatchArgs));
+        // A drive we run on the user's behalf, marked for its whole span so the verdicts it produces
+        // underneath are distinguishable from the ones the user's own agent earned.
+        //
+        // The outer call emits no verdict of its own, and that is the honest answer rather than a gap:
+        // it drives and records, it adjudicates nothing, and its result carries no verified/pass field
+        // to read. Deriving one from how far the drive got would be inventing a verdict nobody reached.
+        // What was missing was never an event here — it was that a session driven BY US read exactly
+        // like one the agent earned, which is what the span fixes.
+        raw = await (isHarnessDrive(tool.name, args) ? withHarnessDrive(call) : call());
     }
     catch (error) {
         // The commonest refusal shape by far, and the one nothing could see: the message is built, handed

package/dist/surface/tools/live-call-text.d.ts

@@ -15,5 +15,11 @@ export declare function liveCallText(text: string, advertised: ReadonlySet<strin
  * was corrected and the result became unreadable, which is a worse trade than the advice was worth.
  *
  * Values, not keys: a key is a contract with the caller and nothing in a key is advice.
+ *
+ * And not every value is advice either. A field that carries a tool's IDENTITY is an answer to
+ * "which one", not a suggestion about what to call — rewriting it destroys the thing the caller
+ * asked for. `reticle_tools { names: ["reticle_act_sequence"] }` sets `name` to the name it was
+ * asked about, and this rewrote it to `reticle_act`, so a batch query came back with entries the
+ * caller could no longer match to their questions. See `IDENTITY_KEYS`.
  */
 export declare function liveCallValues(value: unknown, advertised: ReadonlySet<string>): unknown;

package/dist/surface/tools/live-call-text.js

@@ -123,12 +123,37 @@ export function liveCallText(text, advertised) {
             continue;
         out = out.replace(pattern, instead);
     }
-    return out.replace(TOOL_TOKEN, (name) => {
+    /**
+     * A sentence explaining where a name WENT keeps that name, even though it is unreachable.
+     *
+     * These messages open with their own subject — "reticle_act_sequence was merged into reticle_act",
+     * "reticle_refresh no longer exists" — and the rewrite is precisely a rule for replacing
+     * unreachable names, so it replaced the subject too. Asking about `reticle_act_sequence` answered
+     * "reticle_act no longer exists", which is false: `reticle_act` is a tool, and the one thing the
+     * reader needed to know was which name had moved.
+     *
+     * Only the leading token, and only in front of those two phrases. Every other mention in the same
+     * sentence — including the tool to call INSTEAD — is still rewritten, which is the whole job.
+     */
+    const explainsItsSubject = /^(reticle_[a-z_]+)(?= (?:was merged into|no longer exists))/.exec(out);
+    const subject = explainsItsSubject?.[1];
+    return out.replace(TOOL_TOKEN, (name, offset) => {
+        if (name === subject && 0 === offset)
+            return name;
         if (advertised.has(name))
             return name;
         return replacementFor(name, advertised) ?? name;
     });
 }
+/**
+ * Keys whose STRING value names a thing rather than advising a call.
+ *
+ * `name` is what the caller asked about and has to match their question against; `tool` is the
+ * already-resolved answer to "call this instead", so redirecting it a second time can only move it
+ * away from the answer. Deliberately two names and not a pattern: every other string in a result is
+ * prose, and prose is exactly what the rewrite is for.
+ */
+const IDENTITY_KEYS = new Set(['name', 'tool']);
 /**
  * The same rewrite, applied to a result's STRING VALUES instead of to its encoded form.
  *
@@ -140,6 +165,12 @@ export function liveCallText(text, advertised) {
  * was corrected and the result became unreadable, which is a worse trade than the advice was worth.
  *
  * Values, not keys: a key is a contract with the caller and nothing in a key is advice.
+ *
+ * And not every value is advice either. A field that carries a tool's IDENTITY is an answer to
+ * "which one", not a suggestion about what to call — rewriting it destroys the thing the caller
+ * asked for. `reticle_tools { names: ["reticle_act_sequence"] }` sets `name` to the name it was
+ * asked about, and this rewrote it to `reticle_act`, so a batch query came back with entries the
+ * caller could no longer match to their questions. See `IDENTITY_KEYS`.
  */
 export function liveCallValues(value, advertised) {
     if ('string' === typeof value)
@@ -149,7 +180,10 @@ export function liveCallValues(value, advertised) {
     if (null !== value && 'object' === typeof value) {
         const out = {};
         for (const [key, each] of Object.entries(value)) {
-            out[key] = liveCallValues(each, advertised);
+            out[key] =
+                IDENTITY_KEYS.has(key) && 'string' === typeof each
+                    ? each
+                    : liveCallValues(each, advertised);
         }
         return out;
     }

package/dist/surface/tools/observe-tools.js

@@ -19,6 +19,7 @@ import { applyEventBudget, costHint, withSizeCost, DEFAULT_OBSERVE_EVENT_LIMIT,
 import { annotateStarvedFailure, healthEnvelope, bufferEnvelope, } from '../../portal/session/session-health.js';
 import { assertsDerivedIpcStatus, DERIVED_IPC_STATUS_ADVICE, isPresenceOnlyAssertion, PRESENCE_ONLY_ADVICE, } from './assert/assert-grade.js';
 import { assertVerdict } from './assert/assert-verdict.js';
+import { followLostObservation } from './act/act-observation.js';
 import { withGapNovelty } from './gap-novelty.js';
 import { assertionSource } from './assert/assert-source.js';
 import { isChangeUndeclared } from '@reticlehq/engine/evidence/undeclared-change.js';
@@ -208,6 +209,10 @@ export const OBSERVE_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('The tab disconnected mid-wait, so this was never observed — the verdict is UNKNOWN, not a failure of the app.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('The session that answered, when a full-document navigation replaced the one this was asked of. Absent when the original session survived.'),
             inconclusive: z
                 .string()
                 .optional()
@@ -236,7 +241,7 @@ export const OBSERVE_TOOLS = [
         handler: async (deps, args) => {
             const waitBudget = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
             // Spend the budget waiting for the APP as well as for the predicate. See resolve-within.
-            const session = await resolveSessionWithin(deps.sessions, asString(args['sessionId']), waitBudget, WALL_CLOCK);
+            let session = await resolveSessionWithin(deps.sessions, asString(args['sessionId']), waitBudget, WALL_CLOCK);
             // `until` is act_and_wait's name for this — see alias-args.ts.
             const predicate = parsePredicate(aliasParam(args, 'predicate', ['until'])['predicate']);
             // Refused up front rather than waited out: a body clause this session cannot answer would
@@ -245,8 +250,22 @@ export const OBSERVE_TOOLS = [
             if (bodyRefusal !== undefined)
                 throw new Error(bodyRefusal);
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
-            const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
-            const verdict = await waitForPredicate(session, predicate, waitBudget, since);
+            let since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
+            // See the note on the assert handler below: a wait cut off by a full-document navigation is
+            // followed to the document that took over, rather than graded as a lost observation there.
+            const predicateStarted = session.elapsed();
+            const followed = await followLostObservation({
+                sessions: deps.sessions,
+                session,
+                verdict: await waitForPredicate(session, predicate, waitBudget, since),
+                timeout: waitBudget,
+                predicateStarted,
+                reevaluate: (next, budget) => waitForPredicate(next, predicate, budget, 0),
+            });
+            if (followed.followed)
+                since = 0;
+            session = followed.session;
+            const verdict = followed.verdict;
             // match reticle_assert — wrap with control + session health (throttle matters most while blocking)
             // and the buffer envelope, so a verdict reached over an evicted window says so.
             return withControl(session, {
@@ -255,6 +274,7 @@ export const OBSERVE_TOOLS = [
                 // `lastActSourceOnFailure` — an assert used to be blamed on the previous act's file:line.
                 ...annotateStarvedFailure(session, verdict),
                 ...assertionSource(session, predicate, verdict),
+                ...(followed.followed ? { sessionId: session.id } : {}),
                 ...healthEnvelope(session),
                 ...bufferEnvelope(session),
             });
@@ -271,7 +291,7 @@ export const OBSERVE_TOOLS = [
             // is the most common thing an agent wants to assert. A field report reached us from an agent
             // that guessed `urlContains` on route (net's spelling) and got unrecognized_keys.
             'Predicate to evaluate. Kinds: { signal, name|dataMatches|count } ' +
-                '{ net, urlContains|method|status|count|bodyContains|requestBodyContains|requestBodyMatches } ' +
+                '{ net, urlContains|method|status|count|bodyMatches|bodyContains|requestBodyContains|requestBodyMatches } ' +
                 '{ state, path|equals } { route, pathname (exact) | contains (path+query+hash) } ' +
                 '{ element, testid|role|text } { text } { console, level|contains|absent } { animation, name } ' +
                 '{ settled } — combine with { allOf | anyOf | not }. Prefer a signal/net/state consequence ' +
@@ -294,6 +314,10 @@ export const OBSERVE_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('The tab disconnected mid-wait, so this was never observed — the verdict is UNKNOWN, not a failure of the app.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('The session that answered, when a full-document navigation replaced the one this was asked of. Absent when the original session survived.'),
             inconclusive: z
                 .string()
                 .optional()
@@ -338,7 +362,7 @@ export const OBSERVE_TOOLS = [
         handler: async (deps, args) => {
             const timeout = asNumber(args['timeout_ms']) ?? 0;
             // Spend the budget waiting for the APP as well as for the predicate. See resolve-within.
-            const session = await resolveSessionWithin(deps.sessions, asString(args['sessionId']), timeout, WALL_CLOCK);
+            let session = await resolveSessionWithin(deps.sessions, asString(args['sessionId']), timeout, WALL_CLOCK);
             // `until` is act_and_wait's name for this — see alias-args.ts.
             const predicate = parsePredicate(aliasParam(args, 'predicate', ['until'])['predicate']);
             // Refused up front rather than waited out: a body clause this session cannot answer would
@@ -347,13 +371,34 @@ export const OBSERVE_TOOLS = [
             if (bodyRefusal !== undefined)
                 throw new Error(bodyRefusal);
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
-            const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
+            let since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
             // Declared BEFORE the verdict, so the undeclared-change read below finds it open and stays
             // quiet on THIS verdict rather than on the next one. Discharged after that read.
             const intentId = await linkInlineIntent(deps, asString(args['sessionId']), asString(args['intent']), PredicateKind.SETTLED === predicate.kind ? undefined : predicate);
-            const verdict = timeout > 0
-                ? await waitForPredicate(session, predicate, timeout, since)
-                : await evaluatePredicate(session, predicate, since);
+            // A full-document navigation tears the in-page SDK down mid-wait, and the predicate finishes
+            // `observationLost` against a channel that no longer exists. `act_and_wait` has followed the
+            // document that took over since the MPA drive was fixed; this path did not, so an assertion
+            // straddling a navigation came back "Reticle could not tell" while the answer was sitting on
+            // the successor — reported four times from the field, every one of them proving `yes` on the
+            // UNCHANGED predicate after a manual reconnect. Re-asking is not fabricating: the consequence
+            // is evaluated on a live document, and where there is no unique successor to follow,
+            // `followLostObservation` refuses to guess and the honest lost verdict stands.
+            const predicateStarted = session.elapsed();
+            const followed = await followLostObservation({
+                sessions: deps.sessions,
+                session,
+                verdict: timeout > 0
+                    ? await waitForPredicate(session, predicate, timeout, since)
+                    : await evaluatePredicate(session, predicate, since),
+                timeout,
+                predicateStarted,
+                reevaluate: (next, budget) => waitForPredicate(next, predicate, budget, 0),
+            });
+            // The successor's buffer is its own: the departed session's cursor means nothing there.
+            if (followed.followed)
+                since = 0;
+            session = followed.session;
+            const verdict = followed.verdict;
             // A GREEN presence-only assertion is the dangerous case (a wrong element can fake it) — nudge
             // toward a consequence. Never on a failing verdict (moot) or when a signal/net is asserted.
             // Two nudges, both only on a GREEN verdict (a failing one is moot): a presence-only assertion
@@ -396,6 +441,7 @@ export const OBSERVE_TOOLS = [
             return withControl(session, {
                 ...decision,
                 ...annotateStarvedFailure(session, verdict),
+                ...(followed.followed ? { sessionId: session.id } : {}),
                 ...(contradictions.length > 0 ? { contradictions } : {}),
                 // What the app did not tell Reticle, on the same rule the act path uses.
                 // Remedy once per session, facts every time. Applied HERE rather than inside

package/dist/surface/tools/read/query-windowed.d.ts

@@ -11,7 +11,7 @@
  * is not advertised on the default surface, so the agent that needed it could not see it and had no
  * way to learn it existed. A capability reachable only by already knowing about it is not reachable.
  *
- * The SCROLLING half lives in `portal/input/scrolling-find.ts`, because it drives the page and this
+ * The SCROLLING half lives in `portal/input/scroll-find.ts`, because it drives the page and this
  * directory must not reach into `input/` — doing so completed a mutual pair, and two directories
  * that need each other cannot be read, moved or tested apart. Shaping an answer and scrolling a list
  * are different jobs anyway; the guard made that visible before it was a habit.

package/dist/surface/tools/read/query-windowed.js

@@ -11,7 +11,7 @@
  * is not advertised on the default surface, so the agent that needed it could not see it and had no
  * way to learn it existed. A capability reachable only by already knowing about it is not reachable.
  *
- * The SCROLLING half lives in `portal/input/scrolling-find.ts`, because it drives the page and this
+ * The SCROLLING half lives in `portal/input/scroll-find.ts`, because it drives the page and this
  * directory must not reach into `input/` — doing so completed a mutual pair, and two directories
  * that need each other cannot be read, moved or tested apart. Shaping an answer and scrolling a list
  * are different jobs anyway; the guard made that visible before it was a habit.

package/dist/surface/tools/read-tools.js

@@ -14,8 +14,7 @@ import { diffLines } from '../../memory/project/baselines.js';
 import { selectPath, capDepth, projectComponentState } from '../../portal/session/state-select.js';
 import { costHint } from '../../portal/session/output-budget.js';
 import { buildReactionReport, summarizeReaction } from '@reticlehq/engine/question/reaction.js';
-import { asNumber, asString } from '@reticlehq/core';
-import { parseInteractive } from './tools-helpers.js';
+import { asNumber, asString, parseInteractive } from '@reticlehq/core';
 import { sessionIdShape, commandOrThrow, snapshotTree } from './tool-kit.js';
 import { bufferEnvelope } from '../../portal/session/session-health.js';
 import { routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';