@reticlehq/server 3.4.0 → 3.6.0

package/dist/surface/mcp/shared-params.js

@@ -22,14 +22,14 @@
 /** The short form left in the per-turn schema. Must still make sense with no instructions at all. */
 export const SHARED_PARAM_SHORT = {
     sessionId: 'Target a specific tab. Omit unless you mean one — see instructions.',
-    since: 'Cursor from a prior reticle_act/reticle_observe.',
+    since: 'Cursor from a prior act/observe, or a git ref.',
     limit: 'Cap descriptors to the first N.',
 };
 /** The full text, sent once at initialize. Everything trimmed above is restated here. */
 export const SHARED_PARAM_GUIDANCE = 'Arguments that mean the same thing on every tool: `sessionId` — omit unless you mean a specific ' +
     'tab; Reticle scopes to your project, prefers the active one, and refuses rather than guesses when ' +
     'ambiguous. `since` — a cursor from a prior act/observe, bounding an observation to what came ' +
-    'after it. `limit` — caps returned descriptors, cutting tokens on broad queries.';
+    'after it, or a git ref when verifying a change. `limit` — caps returned descriptors, cutting tokens on broad queries.';
 /** Is this a parameter whose guidance now lives in the instructions block? */
 export function isSharedParam(name) {
     return Object.hasOwn(SHARED_PARAM_SHORT, name);

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

@@ -59,6 +59,14 @@ export interface ArrivalScope {
      * "the app redirected the newly arrived document somewhere else."
      */
     navigatedFrom: string;
+    /**
+     * The DOCUMENT the session was on when the navigation was dispatched.
+     *
+     * A navigation to the page already shown replaces the document without changing the URL, so the
+     * old document is still the connected one until the replacement reports (#1320). Only a different
+     * document identity proves the replacement; `undefined` on both sides proves nothing and waits.
+     */
+    navigatedFromDocumentId?: string;
     /** Sessions already on the target before dispatch cannot prove this navigation arrived. */
     priorIds: ReadonlySet<string>;
 }

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

@@ -42,6 +42,21 @@ function samePage(a, b) {
         return false;
     }
 }
+/**
+ * Same origin and path, different fragment: the browser changes the URL WITHOUT replacing the
+ * document. There is no replacement to wait for on this path, so it must not be treated as a
+ * same-page navigation (#1320).
+ */
+function sameDocumentFragmentChange(a, b) {
+    if (!samePage(a, b))
+        return false;
+    try {
+        return new URL(a).hash !== new URL(b).hash;
+    }
+    catch {
+        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,
@@ -70,13 +85,39 @@ export function idsAtTarget(sessions, target) {
     }
     return ids;
 }
+/**
+ * Whether `current` is a different document from the one the navigation was dispatched on.
+ *
+ * A new Session object under the same id is not enough: the SDK also reopens its socket in place,
+ * and that replaces the Session while the page stays exactly where it was. What a real unload
+ * changes is the document id — the one sampled before dispatch (`navigatedFromDocumentId`) against
+ * the one the live session is reporting (`currentDocumentId`). Either side not having reported one
+ * yet is "cannot tell", which is never reported as a new document.
+ */
+function documentUnloaded(scope, current) {
+    const before = scope.navigatedFromDocumentId;
+    const after = current.currentDocumentId;
+    return before !== undefined && after !== undefined && before !== after;
+}
 function findArrival(sessions, target, scope, currentSession) {
     let arrived = null;
-    for (const s of sessions.all()) {
+    // One snapshot for the whole look, so "is the driven session still connected?" and "has a
+    // replacement reported?" are answered from the same moment.
+    const snapshot = sessions.all();
+    const drivenPresent = snapshot.some((s) => s.id === currentSession.id);
+    // Navigating to the page already shown replaces its document without moving the URL, so the
+    // OLD document is still the connected one at the first looks; its presence there is not
+    // arrival until the replacement reports a different document identity (#1320). A fragment-only
+    // change keeps the document, so it is an arrival as soon as the URL matches.
+    const replacesDocument = samePage(scope.navigatedFrom, target) &&
+        !sameDocumentFragmentChange(scope.navigatedFrom, target);
+    for (const s of snapshot) {
         // The currently tracked document gets priority because it is the strongest
         // evidence of where this navigation went.
         if (s.id === currentSession.id) {
             if (samePage(s.url, target)) {
+                if (replacesDocument && s.currentDocumentId === scope.navigatedFromDocumentId)
+                    continue;
                 return { sessionId: s.id };
             }
             // Intermediate routes are not necessarily redirects. Keep polling so
@@ -87,6 +128,12 @@ function findArrival(sessions, target, scope, currentSession) {
         // navigation arrived.
         if (scope.priorIds.has(s.id))
             continue;
+        // While the replaced document is still connected, a DIFFERENT session at the target is an
+        // unrelated arrival (a second tab, a neighbour app): the replacement this navigation waits
+        // for has not reported yet, and letting the newcomer stand in would confirm too early and
+        // name the wrong session (#1320).
+        if (replacesDocument && drivenPresent)
+            continue;
         if (samePage(s.url, target)) {
             if (null === arrived)
                 arrived = { sessionId: s.id };
@@ -122,7 +169,11 @@ export async function awaitArrival(sessions, target, scope, timeoutMs = ARRIVAL_
     // landed when the target was never observed.
     const current = sessions.get(scope.navigatedSession.id);
     if (current !== undefined) {
-        if (!samePage(current.url, scope.navigatedFrom) && !samePage(current.url, target)) {
+        // Sitting on `navigatedFrom` means two different things: a tab that has not moved, or a page
+        // that unloaded and came back here (an auth guard bouncing `/checkout` to `/login` while the
+        // tab started on `/login`). Only a document that is provably new tells them apart.
+        if (!samePage(current.url, target) &&
+            (!samePage(current.url, scope.navigatedFrom) || documentUnloaded(scope, current))) {
             return {
                 sessionId: current.id,
                 landedOn: current.url,
@@ -131,6 +182,9 @@ export async function awaitArrival(sessions, target, scope, timeoutMs = ARRIVAL_
         return null;
     }
     const successor = await awaitDocumentSuccessor(sessions, scope.navigatedSession, 0, clock);
+    // A successor under another id is only "unique at the origin", which a tab opened by someone else
+    // after the driven one went away satisfies equally. On the starting page that guess cannot be told
+    // from a redirect, so it is not reported as one.
     if (successor !== null &&
         !samePage(successor.url, target) &&
         !samePage(successor.url, scope.navigatedFrom)) {

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

@@ -27,7 +27,26 @@
  *   - still in flight when the budget genuinely runs out → `unsettled`, as before, but now an honest
  *     limit instead of an early exit.
  */
-import { EventType, NetInitiator, isDevToolingUrl, isForeignTraffic } from '@reticlehq/core';
+import { EventType, NetInitiator, isDevToolingUrl, isForeignTraffic, urlForMatch, } from '@reticlehq/core';
+/**
+ * What a URL is matched against, as opposed to what is shown.
+ *
+ * Redaction runs at emit time and rewrites a sensitive path segment in place: `/verify/refresh-token`
+ * becomes `/verify/[REDACTED]`, and the original survives only in `urlRaw`. A project that DECLARED
+ * `/verify/refresh-token` in `.reticle.json` `background` is matched with `String.includes`, so
+ * classifying on the displayed URL silently put the endpoint back into the in-flight count and held
+ * the settle window open — the exact defect this file exists to prevent, reached through the one
+ * field the classifier did not consult.
+ *
+ * The same division every other URL comparison in the product already uses (`urlContains`, `netCall`):
+ * match against `urlForMatch`, DISCLOSE `url`. The transcript keeps the redacted spelling.
+ */
+const matchUrlOf = (data) => {
+    // `urlForMatch` answers with the empty string when the event carries no URL at all, and every
+    // classifier below takes `undefined` to mean "nothing to judge". Fails OPEN either way.
+    const url = urlForMatch(data);
+    return 0 === url.length ? undefined : url;
+};
 /**
  * The dev toolchain talking about ITSELF is not the app finishing its work.
  *
@@ -36,7 +55,7 @@ import { EventType, NetInitiator, isDevToolingUrl, isForeignTraffic } from '@ret
  * deliberately disabled control — no state change, no storage change, zero application requests —
  * was graded on the strength of a Next webpack hot-update the same payload printed as ignored.
  */
-const isDevTooling = (data) => isDevToolingUrl('string' === typeof data['url'] ? data['url'] : undefined);
+const isDevTooling = (data) => isDevToolingUrl(matchUrlOf(data));
 /**
  * Somebody else's host is not the app finishing its work.
  *
@@ -55,12 +74,15 @@ const isDevTooling = (data) => isDevToolingUrl('string' === typeof data['url'] ?
  * SAME-ORIGIN background traffic is never guessed: nothing in a URL separates the app's telemetry
  * from the app's work. It is excluded only when the project DECLARED it (`background`).
  */
-const isForeign = (data, appOrigin, background) => isForeignTraffic('string' === typeof data['url'] ? data['url'] : undefined, appOrigin, background);
+const isForeign = (data, appOrigin, background) => isForeignTraffic(matchUrlOf(data), appOrigin, background);
 /**
  * A departure records where the browser was SENT, not a request whose result we will see — the
  * response is delivered to a document this session does not live into. It can never be matched by a
  * NET_REQUEST, so counting it as outstanding would mean no page containing an outbound link or a
  * download button ever settles again. See `NetInitiator.NAVIGATION`.
+ *
+ * The `settled` predicate asks the same question in `evalSettled`; it spells it against this same
+ * constant rather than against a string, which is what keeps the two answers one vocabulary.
  */
 const isDeparture = (data) => data['initiator'] === NetInitiator.NAVIGATION;
 /** How often to re-read the buffer. Short enough to return promptly, long enough not to spin. */

package/dist/surface/tools/act-sequence-tool.js

@@ -303,8 +303,8 @@ export const ACT_SEQUENCE_TOOL = {
                     count: inputSteps.length,
                     steps: stepResults,
                 });
-                deps.recordings.capture(pageBefore === undefined ? recorded : { ...recorded, page: pageBefore });
-                deps.recordings.markEnded(pathOf(session.url));
+                deps.recordings.capture(pageBefore === undefined ? recorded : { ...recorded, page: pageBefore }, undefined, session.id);
+                deps.recordings.markEnded(pathOf(session.url), session.id);
             }
             /*
              * The grade, and the coverage it is never allowed to hide.

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

@@ -22,6 +22,7 @@ import { intentDebt, openSessionIntents } from '../../memory/intent/open-intents
 import { dischargeInlineIntent, inlineVerdictId, linkInlineIntent, } from '../../memory/intent/inline-intent.js';
 import { declaresState } from '@reticlehq/engine/question/predicate/predicate-asks.js';
 import { isStateUnwatched } from '@reticlehq/engine/evidence/blind-spots.js';
+import { hiddenMatchNote } from '@reticlehq/engine/evidence/already-true.js';
 import { inFlightRequestLabels, repeatedRequestLabels } from './act/settle-in-flight.js';
 import { finishAfterMatch } from './act/after-match.js';
 import { noteProved } from './act/proved-controls.js';
@@ -62,8 +63,8 @@ import { readAlreadyTrue } from './act/already-true.js';
 /**
  * The action vocabulary, derived from ActionType — never retyped.
  *
- * The description used to list thirteen actions while ActionType had seventeen: blur, upload, drag
- * and webmcp were real, callable, and undocumented, because a hand-copied list drifts the moment
+ * The description used to omit callable actions such as blur, upload and drag,
+ * because a hand-copied list drifts the moment
  * someone adds an arm. Deriving both the schema and the prose from the enum makes that impossible.
  *
  * The handler already refused an unknown action with a good message; the schema now refuses it
@@ -124,7 +125,7 @@ export const ACT_TOOLS = [
             args: z
                 .record(z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt — a Cmd+K), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration. For upload: { path } is a path on disk (absolute or relative to the project root; the daemon reads the file and delivers real bytes to the file picker — this is the way to verify document-ingestion flows); or { name, content?, type? } to supply inline bytes directly.'),
+                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt — a Cmd+K), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer or the key DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration. For press: { keys: ["Control","k"] } holds several keys down TOGETHER (pressed in order, released in reverse) and { code } names the physical key — both stay on the in-page dispatcher, the only path that can express them. For upload: { path } is a path on disk (absolute or relative to the project root; the daemon reads the file and delivers real bytes to the file picker — this is the way to verify document-ingestion flows); or { name, content?, type? } to supply inline bytes directly.'),
             refuseWhenThrottled: z
                 .boolean()
                 .optional()
@@ -193,7 +194,7 @@ export const ACT_TOOLS = [
                 // drive native pointer input when a provider is available; otherwise fall back.
                 const real = await tryRealInput(deps, session, ref, action, args);
                 if (real.result !== undefined) {
-                    captureAct(deps.recordings, args, real.result, routeBefore);
+                    captureAct(deps.recordings, args, real.result, routeBefore, session.id);
                     settledOutcome = real.settled ?? undefined;
                     // Native input reports no synthetic effect block, so nothing measured in-target: undefined
                     // (the weaker empty-window test), never a fabricated zero.
@@ -217,7 +218,7 @@ export const ACT_TOOLS = [
                 });
                 if (!result.ok)
                     throw new Error(result.error ?? 'act failed');
-                captureAct(deps.recordings, args, result.result, routeBefore);
+                captureAct(deps.recordings, args, result.result, routeBefore, session.id);
                 // lift dispatch/settle status to the envelope (a settle timeout is NOT a failure).
                 const r = asRecord(result.result);
                 if ('boolean' === typeof r['settled'])
@@ -240,7 +241,7 @@ export const ACT_TOOLS = [
                 });
             }
             finally {
-                deps.recordings.markEnded(pathOf(session.url));
+                deps.recordings.markEnded(pathOf(session.url), session.id);
                 // Close the window on every exit (settle or throw), recording the action + settle outcome.
                 session.finishAction(undefined, settledOutcome, true === settledOutcome ? session.elapsed() - since : undefined);
             }
@@ -524,6 +525,8 @@ export const ACT_TOOLS = [
                 const spots = blindSpotsFromState(session.blindSpots(), session.runtime);
                 const coverage = buildCoverageStatement(spots);
                 const absenceBlindSpot = absenceBlindSpotNote(until, spots);
+                // A green resting on hidden matches says the node exists, not that it shows (#1408).
+                const hiddenMatch = hiddenMatchNote(until, verdict.evidence);
                 // Nothing subscribed ⇒ the state channel is dark, and the summary must say so rather than
                 // report an empty diff list that reads like a fact about the app. See CausalSummary.
                 const stateUnwatched = isStateUnwatched(spots);
@@ -569,6 +572,10 @@ export const ACT_TOOLS = [
                     ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
                     losses,
                 });
+                // A refuted expectation must not ride into a regression flow cut from the ambient tape; it is
+                // kept as the capsule below instead. See RecordingStore.unassertLast.
+                if (!verdict.pass && actResult !== null)
+                    deps.recordings.unassertLast();
                 const capsuleSaved = await saveFailedAssertCapsule({
                     deps,
                     verdict,
@@ -606,6 +613,7 @@ export const ACT_TOOLS = [
                     prior,
                     actionSince: since,
                     expectedFailures: declared.netFailures,
+                    namedNetUrls: declared.netUrls,
                     // A consequence that was already true before the action proves nothing about it, so it is
                     // not evidence the destination rendered either — `alreadyTrue` decides that, once.
                     renderProved: verdict.pass && !alreadyTrue && declared.rendersContent,
@@ -617,7 +625,14 @@ export const ACT_TOOLS = [
                 });
                 // The single field an agent reads. Everything below it is the evidence it was derived from;
                 // this is the only one that has to be interpreted, and now it interprets itself.
-                const outcomePending = acceptedWriteLabels(windowEvents);
+                // Same routing as the assert path (#1120), fed by the links this verdict PROVED. On red,
+                // `gradedLinks` is the declared surface (every anyOf branch), which must not exempt a 202
+                // the verdict never rested on — so only a green passes it through.
+                const outcomePending = acceptedWriteLabels(windowEvents, {
+                    appUrl: session.url,
+                    background: session.background,
+                    asserted: verdict.pass ? gradedLinks : [],
+                });
                 const outcomeUnread = unreadWriteLabels(windowEvents);
                 const stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
                 const { decision, durable } = await withDurability(args['durable'], until, decideVerified({
@@ -643,6 +658,7 @@ export const ACT_TOOLS = [
                         ? { observationLost: true, lastUrl: session.url }
                         : {}),
                     ...(absenceBlindSpot === undefined ? {} : { absenceBlindSpot }),
+                    ...(hiddenMatch === undefined ? {} : { hiddenMatch }),
                     honesty,
                     contradictions,
                     ...(0 === outcomePending.length ? {} : { outcomePending }),
@@ -802,8 +818,8 @@ export const ACT_TOOLS = [
             }
             finally {
                 if (dispatched !== undefined)
-                    captureVerdictedAct(deps.recordings, args, dispatched.result, routeBeforeWait, recordedVerdict);
-                deps.recordings.markEnded(pathOf(currentOf(deps.sessions, session).url));
+                    captureVerdictedAct(deps.recordings, args, dispatched.result, routeBeforeWait, recordedVerdict, session.id);
+                deps.recordings.markEnded(pathOf(currentOf(deps.sessions, session).url), session.id);
                 acted.finishAction(verdictEffect, settledOutcome, true === settledOutcome ? acted.elapsed() - actedSince : undefined);
             }
         },

package/dist/surface/tools/assert/assert-verdict.d.ts

@@ -1,5 +1,5 @@
 import type { InstrumentationGap, JournalVerdictEffect } from '@reticlehq/core/artifacts';
-import type { Predicate } from '@reticlehq/engine/question/predicate/predicate.js';
+import { type Predicate } from '@reticlehq/engine/question/predicate/predicate.js';
 import type { Session } from '../../../portal/session/session.js';
 import { type Contradiction } from '@reticlehq/engine/disagreement/contradictions.js';
 /**

package/dist/surface/tools/assert/assert-verdict.js

@@ -4,12 +4,14 @@ import { gapsForAction } from '@reticlehq/engine/evidence/instrumentation-gaps.j
 import { noteSessionGaps } from '@reticlehq/engine/evidence/gap-ledger.js';
 import { declaresState } from '@reticlehq/engine/question/predicate/predicate-asks.js';
 import { isStateUnwatched } from '@reticlehq/engine/evidence/blind-spots.js';
+import { hiddenMatchNote } from '@reticlehq/engine/evidence/already-true.js';
+import { provenExpectedLinks, } from '@reticlehq/engine/question/predicate/predicate.js';
 import { findContradictions, } from '@reticlehq/engine/disagreement/contradictions.js';
 import { crashedRuleNotes } from '@reticlehq/engine/disagreement/contradiction-folds.js';
 import { declaredExpectations, declaresBodyIndependentChannel, } from '@reticlehq/engine/question/declared.js';
 import { absenceBlindSpotNote, blindSpotsFromState, buildCoverageStatement, restsOnCompleteWindow, Coverage, impeachesCapture, transportGapNote, } from '@reticlehq/engine/evidence/blind-spots.js';
 import { buildHonestyBlock } from '@reticlehq/engine/evidence/honesty.js';
-import { acceptedWriteLabels } from '@reticlehq/engine/evidence/accepted-write.js';
+import { acceptedWriteLabels, hasAcceptedWrite, } from '@reticlehq/engine/evidence/accepted-write.js';
 import { unreadWriteLabels } from '@reticlehq/engine/evidence/unread-outcome.js';
 import { decideVerified } from '@reticlehq/engine/evidence/verified.js';
 import { describeWaitTarget, namedNetIsInFlight } from '@reticlehq/engine/evidence/unsettled.js';
@@ -58,6 +60,8 @@ changeUndeclared) {
     const spots = blindSpotsFromState(session.blindSpots(), session.runtime);
     const statement = buildCoverageStatement(spots);
     const absenceBlindSpot = absenceBlindSpotNote(predicate, spots);
+    // A green resting on hidden matches says the node exists, not that it shows (#1408).
+    const hiddenMatch = hiddenMatchNote(predicate, evidence);
     // Omitted entirely when coverage is full, so an intact page pays nothing and the field's PRESENCE
     // is the warning.
     const coverage = Coverage.PARTIAL === statement.coverage
@@ -115,7 +119,17 @@ changeUndeclared) {
     // A consumer rule that crashed belongs here too: the engine ran with fewer rules than it claims,
     // so part of what happened may simply not have been looked for.
     const impeachingNotes = [impeaching.note, gap, ...crashedRuleNotes()].filter((n) => n !== undefined);
-    const outcomePending = acceptedWriteLabels(windowEvents);
+    // Which 202s are still the claim's outcome to wait for (#1120). The proven links decide the
+    // exemption, so a 200 branch of an `anyOf` cannot exempt the 202 that also fired; and the walk
+    // only runs when a 202 is actually waiting, because that is the only case it can change.
+    const assertedAccepts = pass && hasAcceptedWrite(windowEvents)
+        ? await provenExpectedLinks(session, predicate, since)
+        : [];
+    const outcomePending = acceptedWriteLabels(windowEvents, {
+        appUrl: session.url,
+        background: session.background,
+        asserted: assertedAccepts,
+    });
     const outcomeUnread = unreadWriteLabels(windowEvents);
     const stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
     const effectiveInconclusive = inconclusive ?? (!pass ? session.preconditionFailure?.() : undefined);
@@ -160,6 +174,7 @@ changeUndeclared) {
         ...(effectiveInconclusive === undefined ? {} : { inconclusive: effectiveInconclusive }),
         ...(true === observationLost ? { observationLost: true, lastUrl: session.url } : {}),
         ...(absenceBlindSpot === undefined ? {} : { absenceBlindSpot }),
+        ...(hiddenMatch === undefined ? {} : { hiddenMatch }),
         ...(namedNetIsInFlight(predicate, stillInFlight) ? { namedRequestInFlight: true } : {}),
         honesty: buildHonestyBlock({
             grade: gradeOfPredicate(predicate),

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

@@ -96,6 +96,10 @@ export const BROWSER_TOOLS = [
             // which reads whatever is at the target afterwards, cannot tell the two apart on its own.
             const target = absoluteTarget(url, session.url);
             const priorIds = idsAtTarget(deps.sessions, target);
+            // The document the tab is on NOW. Sampled before dispatch because the replacement can
+            // connect while the NAVIGATE reply is still pending, and reading it after the await would
+            // record the replacement as the starting document (#1320).
+            const navigatedFromDocumentId = session.currentDocumentId;
             session.beginAction(ReticleTool.NAVIGATE, { url });
             // Same floor as the reload path above, for the same reason: going to a new URL replaces the
             // document just as thoroughly. `beginAction` attributes events to this action; it does not move
@@ -112,9 +116,12 @@ export const BROWSER_TOOLS = [
                 const arrival = true === result.ok
                     ? await awaitArrival(deps.sessions, target, {
                         // Keep the original Session object and URL so arrival detection can distinguish
-                        // an in-progress navigation from a document that arrived somewhere else.
+                        // an in-progress navigation from a document that arrived somewhere else. The
+                        // document identity lets a same-URL navigation wait for its replacement instead
+                        // of confirming the document it is about to destroy (#1320).
                         navigatedSession: session,
                         navigatedFrom: session.url,
+                        ...(navigatedFromDocumentId === undefined ? {} : { navigatedFromDocumentId }),
                         priorIds,
                     }, timeoutMs)
                     : null;

package/dist/surface/tools/chat-drives.d.ts

@@ -0,0 +1,26 @@
+import type { SessionInfo } from '../../portal/session/session-info.js';
+import { LinkCapability, type PresenterTone } from '@reticlehq/core';
+import type { ToolDeps } from './tool-kit.js';
+import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
+/** What this daemon does for the platform's chat. Each one is listed only once it is built. */
+export declare const CHAT_CAPABILITIES: readonly LinkCapability[];
+/** The slice of the session manager this needs. */
+export interface ChatDriveSessions {
+    list(): SessionInfo[];
+    count(): number;
+    get(id: string): {
+        autoEnd(text: string, tone: PresenterTone): void;
+        pushNarration(text: string): void;
+    } | undefined;
+}
+export interface ChatDriveCloud {
+    /** The platform and key a tab's own project is linked with, or undefined when it is not. */
+    sessionCloud: (sessionId: string) => Promise<{
+        url: string;
+        apiKey: string;
+    } | undefined>;
+    version: string;
+}
+export declare function startChatDrives(deps: ToolDeps, sessions: ChatDriveSessions, fs: FileSystemPort, cloud: ChatDriveCloud, log: (line: string) => void): {
+    stop: () => void;
+};

package/dist/surface/tools/chat-drives.js

@@ -0,0 +1,165 @@
+/**
+ * The daemon's side of the platform chat: the apps it reports, and the drives it takes.
+ *
+ * Out of `index.ts`, which only calls this and hands it the cloud credentials (the tool surface does
+ * not reach `memory/cloud`; see `withLinkedCredential`): both halves share the same view of which tab is which
+ * app, and keeping them together is what stops a drive attached to one app landing in another that
+ * happens to be on the same port. See `local-apps.ts` and `remote-drive.ts` for each half.
+ */
+import { basename, join } from 'node:path';
+import { homedir, hostname } from 'node:os';
+import { LinkCapability, ReticleTool, asRecord } from '@reticlehq/core';
+import { prepareDrive } from '../../features/harness/platform/drive-target.js';
+import { reticleToolset } from './harness-toolset.js';
+import { projectDirFor } from '../../memory/project/session-root.js';
+import { driveFrame } from '../../features/visual/visual-tools.js';
+import { LEASE_ACQUIRE_TOOL } from './lease-tools.js';
+import { REMOTE_DRIVE_JPEG_QUALITY, endDrivenTab, pickOwnDriveSession, startRemoteDrives, } from '../../features/harness/platform/remote-drive.js';
+import { appKeyOf, appsByPlatform, machineOf, mayOpen, NOT_AN_APP_ADDRESS, nameFromProjectId, pickAppTab, startAppReports, } from '../../features/harness/platform/local-apps.js';
+import { serverOptionsFromEnv } from '../../features/harness/platform/server-driver.js';
+import { driveForChat } from './explore-tools.js';
+import { withLinkedCredential } from './harness-explore.js';
+import { runTool } from './invoke-tool.js';
+/** Why a platform drive with no tab of its own runs no tool. */
+const NO_DRIVEN_TAB = 'No tab was picked for this drive, so no tool runs.';
+/** What this daemon does for the platform's chat. Each one is listed only once it is built. */
+export const CHAT_CAPABILITIES = [
+    LinkCapability.DRIVE_SPEC,
+    LinkCapability.TARGET_TAB,
+    LinkCapability.TARGET_HEADLESS,
+    LinkCapability.TARGET_HEADED,
+    LinkCapability.HUD,
+    LinkCapability.TOOL_SESSION,
+    LinkCapability.FRAMES,
+];
+/** A project's own name: its package's, else its id's, else its folder's. */
+const nameOf = async (fs, dir, projectId) => {
+    try {
+        const name = JSON.parse(await fs.readFile(join(dir, 'package.json')))
+            .name;
+        if ('string' === typeof name && 0 < name.length)
+            return name;
+    }
+    catch {
+        // No package, or not JSON: the folder names it.
+    }
+    // Not mapped to a checkout (the daemon's shared `unmatched` directory): the id the SDK stamped.
+    if (undefined !== projectId)
+        return nameFromProjectId(projectId);
+    return basename(dir) || dir;
+};
+export function startChatDrives(deps, sessions, fs, cloud, log) {
+    const env = process.env;
+    const machine = machineOf(hostname(), homedir());
+    const sessionCloud = cloud.sessionCloud;
+    const sessionKey = async (id) => (await sessionCloud(id))?.apiKey;
+    // ponytail: a tab whose project resolves to nothing counts as the daemon's own project here, as it
+    // does for flows and runs; a per-tab "unresolved" app is the upgrade if that ever misleads.
+    const appOf = (id) => {
+        try {
+            const projectId = sessions.list().find((tab) => tab.sessionId === id)?.projectId;
+            return appKeyOf(machine.id, projectDirFor(deps, id), projectId);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // Opened headless, like `reticle drive <url>`, through runTool so it is counted like any call.
+    const openable = (url) => {
+        if (!mayOpen(url, sessions.list().map((tab) => tab.url)))
+            throw new Error(NOT_AN_APP_ADDRESS);
+    };
+    const open = async (url) => {
+        openable(url);
+        await runTool(LEASE_ACQUIRE_TOOL, deps, { url });
+    };
+    const pick = (goal, key, app) => undefined === app
+        ? pickOwnDriveSession(sessions.list(), goal, key, sessionKey)
+        : pickAppTab(app, goal, () => sessions.list(), appOf, open).then(async (id) => 
+        // The app the platform named must be one this credential's project owns.
+        'string' === typeof id && (await sessionKey(id)) !== key ? null : id);
+    const drives = startRemoteDrives({
+        env: () => withLinkedCredential(deps, env),
+        connected: () => 0 < sessions.count(),
+        pick,
+        // The spec's target and HUD, applied through the same counted tools an agent would call.
+        prepare: ({ goal, apiKey, app, spec }) => prepareDrive(spec, app?.url ?? undefined, {
+            pickTab: () => pick(goal, apiKey, app),
+            open: async (url, headed, hud) => {
+                openable(url);
+                const lease = asRecord(await runTool(LEASE_ACQUIRE_TOOL, deps, {
+                    url,
+                    ...(headed ? { headed } : {}),
+                    ...(hud === undefined ? {} : { hud }),
+                }));
+                const id = lease['sessionId'];
+                if ('string' !== typeof id)
+                    throw new Error(`could not open ${url}`);
+                return id;
+            },
+            tuneHud: async (sessionId, hud) => {
+                await reticleToolset(deps, { sessionId }).invoke(ReticleTool.SESSION_TUNE, { hud });
+            },
+            sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        }),
+        // A platform drive: Reticle's own tools on the driven tab, and nothing else. Locked, so a call
+        // naming another tab still lands on this one; with no tab picked, nothing runs at all.
+        session: (sessionId) => {
+            if (sessionId === undefined)
+                return { invoke: () => Promise.reject(new Error(NO_DRIVEN_TAB)) };
+            const tools = reticleToolset(deps, { sessionId, locked: true });
+            return { tools: tools.tools, invoke: (tool, args) => tools.invoke(tool, args) };
+        },
+        drive: async (goal, sessionId) => {
+            const url = sessions.list().find((tab) => tab.sessionId === sessionId)?.url;
+            const outcome = await driveForChat(deps, goal, sessionId);
+            return url === undefined ? outcome : { ...outcome, url };
+        },
+        // The leased tab, or a desktop window's own capture. A web tab only the SDK reaches has no camera.
+        frame: (sessionId) => sessionId === undefined
+            ? Promise.resolve(undefined)
+            : driveFrame(deps, sessionId, REMOTE_DRIVE_JPEG_QUALITY),
+        settle: (id, outcome) => endDrivenTab(id === undefined ? undefined : sessions.get(id), outcome),
+        log,
+    });
+    const reports = startAppReports({
+        machine,
+        version: cloud.version,
+        capabilities: CHAT_CAPABILITIES,
+        apps: async () => appsByPlatform(sessions.list(), serverOptionsFromEnv(await withLinkedCredential(deps, env)), machine.id, async (tab) => {
+            const dir = projectDirFor(deps, tab.sessionId);
+            const platform = await sessionCloud(tab.sessionId);
+            return {
+                dir,
+                name: await nameOf(fs, dir, tab.projectId),
+                ...(undefined === platform
+                    ? {}
+                    : { platform: { url: platform.url.replace(/\/+$/, ''), apiKey: platform.apiKey } }),
+            };
+        }),
+        open,
+        drivePending: (platform) => void drives.tick(platform),
+        // What the platform wants the person told: in the daemon's log, and on the HUD of each open tab
+        // of that project, so somebody who never reads the log still sees "update Reticle".
+        notify: (notice, platform) => {
+            const line = `${notice.text}${notice.url === undefined ? '' : ` ${notice.url}`}`;
+            log(`reticle: from the platform: ${line}`);
+            void (async () => {
+                for (const tab of sessions.list()) {
+                    const key = await sessionKey(tab.sessionId).catch(() => undefined);
+                    if (key === platform.apiKey)
+                        sessions.get(tab.sessionId)?.pushNarration(line);
+                }
+            })();
+        },
+        log,
+    });
+    // Once now, so the chat sees this machine's apps as soon as the daemon is up.
+    void reports.tick();
+    return {
+        stop: () => {
+            drives.stop();
+            reports.stop();
+        },
+    };
+}