@reticlehq/server 3.1.0 → 3.3.0

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

@@ -7,7 +7,7 @@ import { z } from 'zod';
 import { aliasParam } from './args/alias-args.js';
 import { CONSOLE_ATTACH_NOTE, CONSOLE_LEVELS, ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind, Verified, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
-import { countSchema, cursorSchema, httpStatusSchema, timeoutMsSchema, windowMsSchema, } from './args/numeric-bounds.js';
+import { countSchema, cursorSchema, httpStatusSchema, timeoutMsSchema, waitForTimeoutMsSchema, resumeAfter, MAX_BLOCKING_WAIT_MS, windowMsSchema, } from './args/numeric-bounds.js';
 import { buildReactionReport } from '@reticlehq/engine/question/reaction.js';
 import { findContradictions } from '@reticlehq/engine/disagreement/contradictions.js';
 import { evaluatePredicate, waitForPredicate, PredicateSchema, } from '@reticlehq/engine/question/predicate/predicate.js';
@@ -16,9 +16,10 @@ import { WALL_CLOCK } from '../../portal/session/timing/wall-clock.js';
 import { parsePredicate } from '@reticlehq/engine/question/predicate/predicate-parse.js';
 import { matchNet, matchConsole, isConsoleEvent, eventMatchesFilters, netEmptyHint, consoleEmptyHint, reconcileNet, projectNetCall, projectConsoleLog, withoutUrlRaw, } from '@reticlehq/engine/window/event-filters.js';
 import { applyEventBudget, costHint, withSizeCost, DEFAULT_OBSERVE_EVENT_LIMIT, DEFAULT_QUERY_LIMIT, } from '../../portal/session/output-budget.js';
-import { annotateStarvedFailure, healthEnvelope, bufferEnvelope, } from '../../portal/session/session-health.js';
+import { annotateStarvedFailure, currentOf, 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';
@@ -171,6 +172,7 @@ export const OBSERVE_TOOLS = [
                 currentDocumentId: session.currentDocumentId,
                 currentEditEpoch: session.currentEditEpoch,
                 appOrigin: session.url,
+                background: session.background,
                 ...(judgingTheAct ? { ...session.lastAct.effect(), actionSince: actCursor } : {}),
             });
             // carry session health — a throttled tab means the observed timeline may be incomplete.
@@ -192,15 +194,19 @@ export const OBSERVE_TOOLS = [
             predicate: PredicateSchema.optional().describe('Predicate to wait for: { signal }, { net }, { element }, { kind: "net", ok: false } (assert on the OUTCOME — the honest field for IPC, which has no status code), { kind: "state", store, path, equals } (assert a registered store\'s value directly — the source of truth no DOM read can reach; equals takes a literal or { $gte | $contains | $length } pattern), { kind: "settled", quietMs } (deterministic network + DOM idle — prefer this over a fixed sleep), or a combination via allOf/anyOf.'),
             // Same concept, the neighbouring tool's name. See alias-args.ts.
             until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
-            timeout_ms: timeoutMsSchema
+            timeout_ms: waitForTimeoutMsSchema
                 .optional()
-                .describe('Maximum wait in milliseconds. Default: 4000. Capped at 55000: your MCP client aborts the request before a longer wait can return, so a bound above this would be advertised and not deliverable. To outlast it, poll — several short waits, each of which returns a verdict.'),
+                .describe(`Maximum wait in milliseconds. Default: 4000, up to 600000. One call waits at most ${String(MAX_BLOCKING_WAIT_MS)} ms, because your MCP client aborts a longer request; past that it returns resume_ms, and you call again with timeout_ms: resume_ms and the same since to keep waiting.`),
             since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior reticle_act — scopes the wait to events after that act.'),
             ...sessionIdShape,
         },
         outputSchema: {
+            resume_ms: z
+                .number()
+                .optional()
+                .describe('Present when this call stopped at the per-call limit before the predicate was seen. Call again with timeout_ms set to this, the same predicate and the same since, to keep waiting.'),
             pass: z.boolean(),
             evidence: z.unknown().optional(),
             failureReason: z.string().optional(),
@@ -208,6 +214,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()
@@ -234,9 +244,11 @@ export const OBSERVE_TOOLS = [
                 .describe('Where the code behind this verdict lives, as `file:line`. For an element/text assertion it is the matched element itself; for a FAILING signal/net/state assertion — which has no element to point at — it is the control last acted on, where the handler that should have fired lives. OMITTED when neither is known: this tool never borrows an unrelated location.'),
         },
         handler: async (deps, args) => {
-            const waitBudget = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
+            const requestedMs = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
+            // One call never blocks past what the client allows; the rest comes back as resume_ms.
+            const waitBudget = Math.min(requestedMs, MAX_BLOCKING_WAIT_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 +257,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 +281,8 @@ 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 } : {}),
+                ...((resume) => (resume === undefined ? {} : { resume_ms: resume }))(resumeAfter(requestedMs, waitBudget, verdict)),
                 ...healthEnvelope(session),
                 ...bufferEnvelope(session),
             });
@@ -271,7 +299,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 +322,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 +370,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 +379,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 +449,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
@@ -408,7 +462,7 @@ export const OBSERVE_TOOLS = [
                 ...coverage,
                 // The SAME pointer the journal keeps, not a second lookup — one verdict, one file:line.
                 ...(verdictEffect.source === undefined ? {} : { source: verdictEffect.source }),
-                ...healthEnvelope(session),
+                ...healthEnvelope(currentOf(deps.sessions, session)),
                 ...bufferEnvelope(session),
             });
         },

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';

package/dist/surface/tools/real-input-attempt.d.ts

@@ -22,11 +22,6 @@
 import { ActionType, InputModeReason } from '@reticlehq/core';
 import type { Session } from '../../portal/session/session.js';
 import { type ToolDeps } from './tool-kit.js';
-/**
- * Expand a leading `~` against the caller's home directory. Absolute and relative paths pass
- * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
- */
-export declare function expandUserPath(rawPath: string, home: string): string;
 /**
  * If the action is `upload` AND the inner args carry `path`, read the file from disk and rewrite
  * the args to `{ content, name, type, __base64: true }` before the ACT command reaches the browser.

package/dist/surface/tools/real-input-attempt.js

@@ -99,7 +99,7 @@ const UPLOAD_MAX_BYTES = Math.floor((TRANSPORT_LIMITS.MAX_MESSAGE_BYTES / (4 / 3
  * Expand a leading `~` against the caller's home directory. Absolute and relative paths pass
  * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
  */
-export function expandUserPath(rawPath, home) {
+function expandUserPath(rawPath, home) {
     if ('~' === rawPath)
         return home;
     if (rawPath.startsWith('~/') || rawPath.startsWith('~\\'))

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

@@ -5,7 +5,7 @@
  * without a circular import — `tools.ts` assembles the groups and re-exports `ToolDef`/`ToolDeps`.
  */
 import { z } from 'zod';
-import { ReticleCommand } from '@reticlehq/core';
+import { type ProjectId, ReticleCommand } from '@reticlehq/core';
 import type { SessionManager } from '../../portal/session/session-manager.js';
 import type { RealInputProvider } from '../../portal/input/real-input.js';
 import type { BaselineStore } from '../../memory/project/baselines.js';
@@ -33,6 +33,21 @@ export interface ToolDeps<Ext = unknown> {
     recordings: RecordingStore;
     /** on-disk anchored-flow store (.reticle/flows/). */
     flows: FlowStore;
+    /**
+     * The credential this machine already holds for the linked project, if it is linked.
+     *
+     * INJECTED rather than read here. `reticle link` files a project-scoped key in
+     * `~/.reticle/credentials.json`, and the harness needs it so that somebody who has signed in and
+     * linked is not also asked to export a key by hand. Resolving it inside the tool surface would
+     * make `tools` reach into `memory/cloud`, which the directory guard refused — and it was right
+     * to: this is a port, and the daemon already resolves exactly this for cloud sync.
+     *
+     * Absent ⇒ nothing is linked, or the caller is an embedder with no filesystem. Never an error.
+     */
+    linkedCloud?: () => Promise<{
+        url: string;
+        apiKey: string;
+    } | null>;
     /** structured annotations accumulating for the live recording. */
     annotations: AnnotationStore;
     /**
@@ -65,7 +80,7 @@ export interface ToolDeps<Ext = unknown> {
      * embedding this engine may not have a filesystem to search. Absent ⇒ `reticleRoot`, which is
      * exactly today's behaviour.
      */
-    artifactRootFor?: (projectId: string | undefined) => ArtifactRoot;
+    artifactRootFor?: (projectId: ProjectId | undefined) => ArtifactRoot;
     /**
      * A verification run just landed — wake cloud sync instead of waiting for its next tick.
      *
@@ -85,7 +100,7 @@ export interface ToolDeps<Ext = unknown> {
      * test construction of ToolDeps predates it. Absence means "cannot tell", which must never be
      * treated as a mismatch.
      */
-    projectId?: string;
+    projectId?: ProjectId;
     /** injected clock for the contract's generatedAt stamp. */
     now: () => number;
     /**
@@ -207,6 +222,11 @@ export declare const EnvelopeKey: {
     readonly VERIFY_NEXT: "verify_next";
     /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
     readonly FEEDBACK_INVITE: "feedback_invite";
+    /**
+     * The same moment, for the HUMAN: a call with the founder, or an email through `identify`. The
+     * agent is told to offer it and never to book or submit anything itself.
+     */
+    readonly TALK_TO_US: "talk_to_us";
     /** 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. */

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

@@ -28,7 +28,7 @@ export const intentArg = z
     'BAD: "P1 step 5", "drive 2 of 2", "same as before the fix", "the board renders cleanly" — these name a session, ' +
     'a step number or nothing checkable, and the person reading them later has none of that context. ' +
     'This is shared memory: it is pooled per project and later agents read it back to avoid re-deriving what you just established. ' +
-    'Recorded in .reticle/intent.json, the same ledger reticle_intent writes, and marked proved by this verdict if it passes.');
+    'Recorded in .reticle/intent/, the same ledger reticle_intent writes, and marked proved by this verdict if it passes.');
 export const sessionIdShape = {
     sessionId: z
         .string()
@@ -75,6 +75,11 @@ export const EnvelopeKey = {
     VERIFY_NEXT: 'verify_next',
     /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
     FEEDBACK_INVITE: 'feedback_invite',
+    /**
+     * The same moment, for the HUMAN: a call with the founder, or an email through `identify`. The
+     * agent is told to offer it and never to book or submit anything itself.
+     */
+    TALK_TO_US: 'talk_to_us',
     /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
     VERSION_SKEW: 'version_skew',
     /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */

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

@@ -395,11 +395,23 @@ export function describeToolSurface(active, requested) {
 export function defaultAdvertisedNames() {
     const surface = resolveToolSurface();
     const names = [...filterToolNames(surface)];
-    // `reticle_run` is real only where the surface keeps a dispatch hatch. The merged surface ships
-    // the catalogue without one, and naming a hatch that is not there is the same defect one level in.
-    return TOOL_SURFACE.MERGED === surface
-        ? [...names, ReticleTool.TOOLS]
-        : [...names, ReticleTool.TOOLS, ReticleTool.RUN];
+    /*
+     * Both meta tools, on every surface, because that is what the MCP actually advertises.
+     *
+     * This used to withhold `reticle_run` from the merged surface, reasoning that "naming a hatch
+     * that is not there is the same defect one level in". The reasoning is sound and the premise was
+     * false: `buildDynamicTools` returns `[reticle_tools, reticle_run]` unconditionally and
+     * `advertisedTools` appends both to every surface, so the hatch has always been there. Measured
+     * against a live daemon on the default surface: `reticle_run` is advertised, and
+     * `reticle_run { tool: "reticle_lease" }` reaches `reticle_lease`.
+     *
+     * Two functions answering one question, and this was the one the MCP never called. It is read by
+     * `server-instructions`, which gates "Everything else is one hop: reticle_tools lists it,
+     * reticle_run calls it" on this list - so agents were told the hatch was absent from a surface
+     * carrying it, and six recovery messages were later rewritten to match the lie.
+     * `advertised-names-are-real.test.ts` now pins this to `advertisedTools` itself.
+     */
+    return [...names, ReticleTool.TOOLS, ReticleTool.RUN];
 }
 /** The advertised NAME set for a surface, without needing the tool table. */
 function filterToolNames(surface) {

package/dist/surface/tools/tools-helpers.d.ts

@@ -1,10 +1,12 @@
 /** Small pure helpers shared by the MCP tool handlers. */
-interface InteractiveItem {
-    ref: string;
-    desc: string;
-}
-/** Parse interactive elements (with refs) out of a snapshot tree for exploration. */
-export declare function parseInteractive(tree: string): InteractiveItem[];
+/**
+ * The argument a call names a tab with.
+ *
+ * A named constant because dispatch now WRITES this key as well as reading it — see `runTool`,
+ * which pins the session it resolved into the args the handler is given — and a key spelled at both
+ * ends of that can drift without anything saying so.
+ */
+export declare const SESSION_ID_ARG = "sessionId";
 /**
  * The session this call is aimed at: a top-level `sessionId`, or the same key on sequence steps.
  *
@@ -36,4 +38,3 @@ export declare function sourceOf(value: unknown): {
     line: number;
     column?: number;
 } | undefined;
-export {};

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

@@ -1,15 +1,13 @@
 import { asRecord, asString } from '@reticlehq/core';
-/** Parse interactive elements (with refs) out of a snapshot tree for exploration. */
-export function parseInteractive(tree) {
-    const items = [];
-    for (const line of tree.split('\n')) {
-        const match = /\(ref=(e\d+)\)/.exec(line);
-        if (match !== null) {
-            items.push({ ref: match[1] ?? '', desc: line.replace(/\s*\(ref=e\d+\)/, '').trim() });
-        }
-    }
-    return items;
-}
+/** Small pure helpers shared by the MCP tool handlers. */
+/**
+ * The argument a call names a tab with.
+ *
+ * A named constant because dispatch now WRITES this key as well as reading it — see `runTool`,
+ * which pins the session it resolved into the args the handler is given — and a key spelled at both
+ * ends of that can drift without anything saying so.
+ */
+export const SESSION_ID_ARG = 'sessionId';
 /**
  * The session this call is aimed at: a top-level `sessionId`, or the same key on sequence steps.
  *
@@ -21,7 +19,7 @@ export function parseInteractive(tree) {
  * Mixed step ids refuse rather than pick: two named tabs is a guess we will not make.
  */
 export function sessionIdFromArgs(args) {
-    const top = asString(args['sessionId']);
+    const top = asString(args[SESSION_ID_ARG]);
     if (top !== undefined)
         return top;
     const steps = args['steps'];
@@ -29,7 +27,7 @@ export function sessionIdFromArgs(args) {
         return undefined;
     let found;
     for (const raw of steps) {
-        const id = asString(asRecord(raw)['sessionId']);
+        const id = asString(asRecord(raw)[SESSION_ID_ARG]);
         if (id === undefined)
             continue;
         if (found !== undefined && found !== id) {