@reticlehq/server 3.8.2 → 3.9.0

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

@@ -8,6 +8,8 @@
  * rest of the budget the caller already granted is spent here, in three steps, each deciding
  * nothing on its own.
  */
+import { hiddenMatchNote } from '@reticlehq/engine/evidence/already-true.js';
+import { evaluatePredicate, } from '@reticlehq/engine/question/predicate/predicate.js';
 import { waitForInFlight } from './settle-in-flight.js';
 import { waitForReaction } from './react-grace.js';
 import { revertedAfterMatch } from './durable.js';
@@ -28,3 +30,34 @@ export async function finishAfterMatch(session, until, since, baselines, remaini
     // 3. Then ask whether what held still holds — see revertedAfterMatch.
     return revertedAfterMatch(session, until, since, baselines);
 }
+/**
+ * How long a match that holds only on hidden nodes gets to show. An entrance fade or a toast mounted
+ * at opacity 0 reads hidden for its first frame, and the wait matched on that frame. A node hidden
+ * by design pays this once, on a verdict that is `unknown` either way.
+ */
+const SHOWN_GRACE_MS = 1000;
+/** Poll cadence — the same as the reaction grace. */
+const SHOWN_POLL_MS = 50;
+/**
+ * A green that rests only on hidden matches, read again until a match shows, for at most
+ * SHOWN_GRACE_MS. Returns the reading that shows one, or `verdict` unchanged. Nothing is predicted:
+ * the verdict is judged on what the page painted, and a node that stays hidden stays `hidden_match`.
+ */
+export async function awaitShownMatch(session, until, since, baselines, verdict, remaining) {
+    if (!verdict.pass || hiddenMatchNote(until, verdict.evidence) === undefined) {
+        return verdict;
+    }
+    // Counted in reads, not read off the session clock, so a clock that does not move still ends it.
+    const reads = Math.floor(Math.min(SHOWN_GRACE_MS, remaining()) / SHOWN_POLL_MS);
+    for (let read = 0; read < reads; read += 1) {
+        await new Promise((resolve) => setTimeout(resolve, SHOWN_POLL_MS));
+        const now = await evaluatePredicate(session, until, since, true, baselines);
+        if (!now.pass) {
+            return verdict;
+        }
+        if (hiddenMatchNote(until, now.evidence) === undefined) {
+            return now;
+        }
+    }
+    return verdict;
+}

package/dist/surface/tools/act/resolve-target.d.ts

@@ -9,6 +9,8 @@ export type TargetResolution = {
     readonly kind: 'error';
     readonly message: string;
 };
+/** The words before the nearest-target list in a no_match refusal. The repeat hint reads after it. */
+export declare const NEAREST_TARGETS_LEAD = " The nearest targets on the page, most similar first: ";
 /**
  * Turn a target QUERY into the single ref an action can be performed on.
  *

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

@@ -1,4 +1,5 @@
-import { asRecord, ElementState } from '@reticlehq/core';
+import * as z from 'zod';
+import { asRecord, ElementState, NearestTargetSchema } from '@reticlehq/core';
 /**
  * Roles that usually name the control an agent meant, ahead of a wrapping `generic` that
  * happened to inherit the same accessible name (header CTA vs empty-state CTA).
@@ -17,8 +18,9 @@ const ROLE_RANK = {
     searchbox: 10,
 };
 function roleRank(role) {
-    if ('string' !== typeof role)
+    if ('string' !== typeof role) {
         return 100;
+    }
     return ROLE_RANK[role] ?? 50;
 }
 function statesOf(c) {
@@ -35,8 +37,9 @@ function inViewport(c) {
  */
 function compareCandidates(a, b) {
     const viewport = Number(inViewport(b)) - Number(inViewport(a));
-    if (0 !== viewport)
+    if (0 !== viewport) {
         return viewport;
+    }
     return roleRank(a.role) - roleRank(b.role);
 }
 /**
@@ -50,14 +53,18 @@ function formatCandidate(c, anyInViewport) {
     const ref = 'string' === typeof c.ref ? c.ref : '?';
     const visible = false !== c.visible;
     let where;
-    if (!visible)
+    if (!visible) {
         where = 'hidden';
-    else if (inViewport(c))
+    }
+    else if (inViewport(c)) {
         where = 'in-viewport';
-    else if (anyInViewport)
+    }
+    else if (anyInViewport) {
         where = 'off-screen';
-    else
+    }
+    else {
         where = 'visible';
+    }
     const head = name.length > 0 ? `${ref} (${role} "${name}"` : `${ref} (${role}`;
     return `${head}; ${where})`;
 }
@@ -76,6 +83,25 @@ function nearNamesClause(hint) {
         'Use that name, or — when the name carries a part that changes, like a time — target it by ' +
         '`testid` or by `text` (a contained match).');
 }
+const NearestTargetsSchema = z.array(NearestTargetSchema).min(1);
+/** The words before the nearest-target list in a no_match refusal. The repeat hint reads after it. */
+export const NEAREST_TARGETS_LEAD = ' The nearest targets on the page, most similar first: ';
+/**
+ * The browser's `nearest` hint as a sentence: the targets most like the one asked for, with refs,
+ * so the retry is one call and not a snapshot loop. Empty when there is no list. It is advice
+ * only: the action stays refused, and nothing here picks a target.
+ */
+function nearestClause(hint) {
+    const parsed = NearestTargetsSchema.safeParse(asRecord(hint)['nearest']);
+    if (!parsed.success) {
+        return '';
+    }
+    const listed = parsed.data
+        .map((t) => `${t.ref} (${t.role} "${t.name}${true === t.nameTruncated ? '…' : ''}")`)
+        .join(', ');
+    return (`${NEAREST_TARGETS_LEAD}${listed}. If one of them is the ` +
+        'element you meant, pass its ref as `ref`.');
+}
 /**
  * Turn a target QUERY into the single ref an action can be performed on.
  *
@@ -104,7 +130,8 @@ export function resolveTargetRef(candidates, hint) {
         return {
             kind: 'error',
             message: 'target matched no element. Nothing was acted on and no verdict is possible — ' +
-                nearNamesClause(hint),
+                nearNamesClause(hint) +
+                nearestClause(hint),
         };
     }
     if (usable.length > 1) {

package/dist/surface/tools/act/sequence-grade.d.ts

@@ -14,7 +14,7 @@
  * is verified FOR THOSE THREE and silent about nine, and `because` says so — reporting it as "25%
  * verified" would be the arithmetic that hides the nine.
  */
-import { Verified } from '@reticlehq/core';
+import { Verified, VerifiedReason } from '@reticlehq/core';
 /**
  * What to do when a step's declared consequence does not hold.
  *
@@ -49,6 +49,8 @@ export interface StepExpectation {
 }
 export interface SequenceGrade {
     verified: Verified;
+    /** The deciding clause, from core's list, so a sequence verdict is counted by reason like any other. */
+    reason: VerifiedReason;
     /** Steps that declared a consequence. */
     declared: number;
     total: number;

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

@@ -14,7 +14,7 @@
  * is verified FOR THOSE THREE and silent about nine, and `because` says so — reporting it as "25%
  * verified" would be the arithmetic that hides the nine.
  */
-import { Verified } from '@reticlehq/core';
+import { Verified, VerifiedReason } from '@reticlehq/core';
 /**
  * What to do when a step's declared consequence does not hold.
  *
@@ -36,6 +36,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
         const observed = missed.observed ?? 'nothing that matched';
         return {
             verified: Verified.NO,
+            reason: VerifiedReason.ASSERTION_FAILED,
             declared,
             total,
             because: `a declared consequence did not hold — observed ${observed}`,
@@ -47,6 +48,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
         const kinds = (steps[contradictedAt]?.contradicted ?? []).join(', ');
         return {
             verified: Verified.NO,
+            reason: VerifiedReason.CONTRADICTED,
             declared,
             total,
             because: `step ${String(contradictedAt + 1)}: channels disagree about this action (${kinds}) even though it went on`,
@@ -57,6 +59,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
     if (unjudged !== undefined)
         return {
             verified: Verified.UNKNOWN,
+            reason: VerifiedReason.INCONCLUSIVE,
             declared,
             total,
             because: `a step could not be judged — ${unjudged.undecided ?? ''}`,
@@ -77,6 +80,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
     if (0 === declared) {
         return {
             verified: Verified.UNKNOWN,
+            reason: VerifiedReason.NOTHING_DECLARED,
             declared,
             total,
             because: 0 === total
@@ -95,6 +99,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
     if (steps.length < total) {
         return {
             verified: Verified.UNKNOWN,
+            reason: VerifiedReason.EVIDENCE_INCOMPLETE,
             declared,
             total,
             because: `only ${String(steps.length)} of ${String(total)} steps ran, so the journey never reached its end`,
@@ -103,6 +108,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
     if (true !== steps.at(-1)?.declared) {
         return {
             verified: Verified.UNKNOWN,
+            reason: VerifiedReason.EVIDENCE_INCOMPLETE,
             declared,
             total,
             because: `the last step, where the journey ends, declared nothing — give it an \`expect\` naming the end state (${String(declared)} of ${String(total)} steps declared one)`,
@@ -110,6 +116,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
     }
     return {
         verified: Verified.YES,
+        reason: VerifiedReason.PROVED,
         declared,
         total,
         because: declared === total

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

@@ -153,6 +153,8 @@ export const ACT_SEQUENCE_TOOL = {
         stopped_at: z.number().optional(),
         /** THE field to gate on: "yes" | "no" | "unknown" — see `because`. */
         verified: z.string().optional(),
+        /** The deciding clause of `verified`, from the same list as every other verdict. */
+        verifiedReason: z.string().optional(),
         because: z.string().optional(),
         /**
          * Present only when the plan PROVED something — see `offerToKeep`. A plan that declared nothing
@@ -464,6 +466,7 @@ export const ACT_SEQUENCE_TOOL = {
                 ...(stalledAt !== undefined ? { stalled_at: stalledAt } : {}),
                 ...(stoppedAt !== undefined ? { stopped_at: stoppedAt } : {}),
                 verified: grade.verified,
+                verifiedReason: grade.reason,
                 because: grade.because,
                 // Offered at the one moment the compiled program is in hand and free to keep.
                 ...(() => {

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

@@ -34,7 +34,7 @@ import { declaresState } from '@reticlehq/engine/question/predicate/predicate-as
 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 { awaitShownMatch, finishAfterMatch } from './act/after-match.js';
 import { noteProved } from './act/proved-controls.js';
 import { decideVerified } from '@reticlehq/engine/evidence/verified.js';
 import { buildHonestyBlock, honestyForVerdict } from '@reticlehq/engine/evidence/honesty.js';
@@ -432,9 +432,10 @@ export const ACT_TOOLS = [
             const { alreadyTrue, alreadyTrueHiddenMatch, alreadyTrueEvidence, baselines } = await readAlreadyTrue(session, until, since);
             // Same as the ACT handler: the route this step RAN on, before the action can move the app.
             const routeBeforeWait = pathOf(session.url);
-            // Recorded in `finally`, once the verdict is known — see captureVerdictedAct.
+            // Recorded in `finally`, once the verdict is known — see captureVerdictedAct. `held`: the
+            // action made the declared claim hold.
             let dispatched;
-            let recordedVerdict;
+            let held = false;
             try {
                 // actCommand is the single interception point for upload+path rewrite.
                 //
@@ -484,6 +485,7 @@ export const ACT_TOOLS = [
                     const reverted = await finishAfterMatch(session, until, since, baselines, left);
                     if (reverted !== undefined)
                         verdict = { pass: false, failureReason: reverted, observed: reverted };
+                    verdict = await awaitShownMatch(session, until, since, baselines, verdict, left);
                 }
                 const r = asRecord(actResult?.result);
                 if ('boolean' === typeof r['settled'])
@@ -580,10 +582,9 @@ 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();
+                // A refuted or already-true claim stays off the ambient tape (the capsule below keeps a
+                // refuted one). See captureVerdictedAct.
+                held = verdict.pass && !alreadyTrue;
                 const capsuleSaved = await saveFailedAssertCapsule({
                     deps,
                     verdict,
@@ -690,8 +691,7 @@ export const ACT_TOOLS = [
                     },
                     ...(namedNetIsInFlight(until, stillInFlight) ? { namedRequestInFlight: true } : {}),
                 }), (part) => reloadAndRecheck(deps, session, part, timeout));
-                recordedVerdict = String(decision.verified);
-                noteProved(session, recordedVerdict, actResult?.result);
+                noteProved(session, String(decision.verified), actResult?.result);
                 // Computed once: the verdict block reports it, and the instrumentation gaps are a second
                 // reading of the same evidence rather than a new observation.
                 const actionSummary = causalSummary(windowEvents, {
@@ -834,7 +834,7 @@ export const ACT_TOOLS = [
             }
             finally {
                 if (dispatched !== undefined)
-                    captureVerdictedAct(deps.recordings, args, dispatched.result, routeBeforeWait, recordedVerdict, session.id, wroteSince(acted, actedSince));
+                    captureVerdictedAct(deps.recordings, args, dispatched.result, routeBeforeWait, held, session.id, wroteSince(acted, actedSince));
                 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.js

@@ -20,6 +20,28 @@ import { gradeOfPredicate } from './assert-grade.js';
 import { assertSource, stampedSourceIn } from './assert-source.js';
 import { VerdictAttribution, verdictAttributionOf } from '@reticlehq/core';
 import { noteSourceSeen } from '../../../portal/session/recorded-gaps.js';
+import { sdkBehindNote } from '../../../portal/session/session-info.js';
+// Unanchored: the engine prefixes the reason with "the page did not answer:".
+const COMMAND_TIMEOUT = /command '[^']*' timed out after (\d+)ms/;
+/**
+ * The cause and the one fix for a read that came back `unknown`, in place of a bare fact (#1990).
+ * A page whose SDK is behind this daemon may not serve `match` at all, so the fix is the same
+ * SDK-behind sentence the listing shows. On a current page the read ran out of the assertion's own
+ * budget, and the fix is more of it.
+ */
+function diagnoseTimeout(reason, session) {
+    const behind = sdkBehindNote(session);
+    if (behind !== undefined) {
+        return `${reason} ${behind}`;
+    }
+    const granted = COMMAND_TIMEOUT.exec(reason)?.[1];
+    if (granted === undefined) {
+        return reason;
+    }
+    return (`${reason} This read was bounded by what the assertion's budget had left ` +
+        `(${granted}ms): the budget ran out while the page was still working. ` +
+        'Give the assertion more time with `timeout_ms`.');
+}
 /**
  * The honesty verdict for a plain `reticle_assert`.
  *
@@ -138,7 +160,12 @@ changeUndeclared) {
     });
     const outcomeUnread = unreadWriteLabels(windowEvents);
     const stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
-    const effectiveInconclusive = inconclusive ?? (!pass ? session.preconditionFailure?.() : undefined);
+    const rawInconclusive = inconclusive ?? (!pass ? session.preconditionFailure?.() : undefined);
+    // A timed-out page read is the one `unknown` whose cause and fix are knowable here (#1990).
+    let effectiveInconclusive = rawInconclusive;
+    if (rawInconclusive !== undefined && COMMAND_TIMEOUT.test(rawInconclusive)) {
+        effectiveInconclusive = diagnoseTimeout(rawInconclusive, session);
+    }
     /**
      * Does a green here rest on the window having been COMPLETE?
      *

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

@@ -1,10 +1,10 @@
-import { carryReticleIdentity } from './lease-tools.js';
+import { carryReticleIdentity, LEASE_ACQUIRE_TOOL } from './lease-tools.js';
 import { z } from 'zod';
 import { navigateResult } from './act/navigation/navigate-result.js';
 import { absoluteTarget, awaitArrival, idsOpenAtDispatch, ARRIVAL_TIMEOUT_MS, } from './act/navigation/navigate-arrival.js';
 import { reloadResult } from './act/navigation/reload-result.js';
 import { waitForReconnect, RELOAD_RECONNECT_TIMEOUT_MS, } from '../../portal/session/session-reconnect.js';
-import { ReticleCommand } from '@reticlehq/core';
+import { NO_SESSION_CONNECTED_ERROR, ReticleCommand, SESSION_STARTED_NOTE, SessionStartedVia, relativeUrlNoSession, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { sessionIdShape, commandOrThrow } from './tool-kit.js';
@@ -17,8 +17,9 @@ const MSG_LEASE_WITHOUT_SDK = 'This page has no Reticle SDK, so only browser-lev
 async function navigateLease(deps, sessionId, url, args) {
     const timeoutMs = asNumber(args['timeout_ms']) ?? ARRIVAL_TIMEOUT_MS;
     const went = (await deps.pool?.gotoLease(sessionId, url, timeoutMs)) ?? false;
-    if (!went)
+    if (!went) {
         return { ok: false, url, reason: 'the leased page did not navigate' };
+    }
     const back = await waitForSession(deps, sessionId, timeoutMs);
     return back
         ? { ok: true, url, confirmed: true, sessionId }
@@ -28,19 +29,74 @@ async function navigateLease(deps, sessionId, url, args) {
 async function waitForSession(deps, sessionId, timeoutMs) {
     const start = deps.now();
     for (;;) {
-        if (deps.sessions.get(sessionId) !== undefined)
+        if (deps.sessions.get(sessionId) !== undefined) {
             return true;
-        if (deps.now() - start >= timeoutMs)
+        }
+        if (deps.now() - start >= timeoutMs) {
             return false;
+        }
         await new Promise((resolve) => setTimeout(resolve, LEASE_POLL_MS));
     }
 }
 const LEASE_POLL_MS = 100;
+/** `sessionStarted` on the result. See `SessionStarted` in core. */
+const SessionStartedSchema = z.object({
+    sessionId: z.string(),
+    via: z.nativeEnum(SessionStartedVia),
+    zeroInstall: z.boolean().optional(),
+});
+/** The origin a relative-URL refusal names when the project app cannot be found. */
+const EXAMPLE_ORIGIN = 'http://localhost:3000';
+function isHttpUrl(url) {
+    try {
+        const { protocol } = new URL(url);
+        return 'http:' === protocol || 'https:' === protocol;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * No session, and an absolute URL: open a lease on it through the lease tool itself, so the same
+ * owner, browser preflight and production rules apply as on an explicit `reticle_lease` acquire.
+ */
+async function startSessionOn(deps, url) {
+    const leased = (await LEASE_ACQUIRE_TOOL.handler(deps, { url }));
+    const sessionStarted = {
+        sessionId: leased.sessionId,
+        via: SessionStartedVia.LEASE,
+        ...(true === leased.zeroInstall ? { zeroInstall: true } : {}),
+    };
+    const note = leased.hint === undefined ? SESSION_STARTED_NOTE : `${SESSION_STARTED_NOTE} ${leased.hint}`;
+    return {
+        ok: true,
+        url,
+        confirmed: leased.ready,
+        sessionId: leased.sessionId,
+        sessionStarted,
+        note,
+    };
+}
+/**
+ * No session, and a relative URL: nothing names the app. Keep the no-session refusal (and its
+ * diagnosis), and add the absolute form of the same path.
+ */
+async function refuseRelativeWithoutSession(deps, path) {
+    let message = NO_SESSION_CONNECTED_ERROR;
+    try {
+        deps.sessions.resolve();
+    }
+    catch (err) {
+        message = err instanceof Error ? err.message : String(err);
+    }
+    const origin = (await deps.projectAppUrl?.().catch(() => undefined)) ?? EXAMPLE_ORIGIN;
+    throw new Error(`${message}${relativeUrlNoSession(path, origin)}`);
+}
 export const BROWSER_TOOLS = [
     {
         name: ReticleTool.NAVIGATE,
         example: { url: '/settings' },
-        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the old page cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect. `confirmed:true` with a `sessionId` means the requested page arrived and you can act immediately. `confirmed:false` with `landedOn` means the navigation arrived but the app landed at another URL, such as an authentication or route-guard redirect; use `landedOn` to understand where the browser actually ended up. `confirmed:false` without `landedOn` means the target was not observed within the wait window; a slow app may still be on its way, so increase `timeout_ms` when appropriate.',
+        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the old page cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect. `confirmed:true` with a `sessionId` means the requested page arrived and you can act immediately. `confirmed:false` with `landedOn` means the navigation arrived but the app landed at another URL, such as an authentication or route-guard redirect; use `landedOn` to understand where the browser actually ended up. `confirmed:false` without `landedOn` means the target was not observed within the wait window; a slow app may still be on its way, so increase `timeout_ms` when appropriate. With no session connected, an absolute URL opens a leased tab on it and the result carries `sessionStarted`.',
         inputSchema: {
             url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
             reload: z
@@ -74,6 +130,8 @@ export const BROWSER_TOOLS = [
              * of "Reticle stopped waiting" and "the page never came back" you are looking at.
              */
             waitedMs: z.number().optional(),
+            /** Present only when no session was connected and this call opened one on the URL. */
+            sessionStarted: SessionStartedSchema.optional(),
             note: z.string().optional(),
         },
         handler: async (deps, args) => {
@@ -110,8 +168,9 @@ export const BROWSER_TOOLS = [
                 return reloadResult(back, timeoutMs);
             }
             const requested = asString(args['url']);
-            if (requested === undefined || 0 === requested.length)
+            if (requested === undefined || 0 === requested.length) {
                 return { ok: false, reason: 'url required' };
+            }
             assertNotPaymentNavigation(requested);
             const named = asString(args['sessionId']);
             // A lease whose page has no SDK right now (it was navigated to an image, a PDF, another site):
@@ -123,6 +182,15 @@ export const BROWSER_TOOLS = [
                     return navigateLease(deps, named, carryReticleIdentity(leaseUrl, requested), args);
                 }
             }
+            // Nothing is connected at all, and the call named no tab. An absolute URL names the app, so
+            // open a lease on it instead of refusing. Several sessions, or one in another project, keep
+            // the refusal that resolve gives below: a lease there would guess.
+            if (named === undefined && 0 === deps.sessions.count()) {
+                if (isHttpUrl(requested)) {
+                    return startSessionOn(deps, requested);
+                }
+                return refuseRelativeWithoutSession(deps, requested);
+            }
             // Record navigate as an action. Its window is usually empty (the page unloads and the SDK
             // reconnects), but the action record itself — "navigated to X" — is the causal fact worth keeping.
             const session = deps.sessions.resolve(asString(args['sessionId']));

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { runTool } from './invoke-tool.js';
 import { buildErrorPayload, codedRefusalOf } from './error-recovery.js';
+import { withRepeatHint } from './repeat-hint.js';
 import { mergedNameRedirect, mergedNameMessage, retiredToolNames } from './merged-name-redirect.js';
 import { CATALOGUE_SUMMARY_LENGTH, firstSentence } from './first-sentence.js';
 import { takeVersionSkewOnto } from '../../command/version/version-nudge.js';
@@ -381,7 +382,7 @@ callable) {
                 // is reached through here: a stale ref, a paused session, a missing pairing token all came
                 // back as the agent's arguments being wrong, which is advice that spends the retry.
                 const message = error instanceof Error ? error.message : String(error);
-                const payload = buildErrorPayload(message, codedRefusalOf(error));
+                const payload = withRepeatHint(buildErrorPayload(message, codedRefusalOf(error)), error);
                 return { ...takeVersionSkewOnto(payload, deps.peerSkew), tool: name };
             }
         },

package/dist/surface/tools/empty-session-list.d.ts

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import { wiringConsent } from '../../portal/session/no-session-next-action.js';
 export { wiringConsent };
 import type { ToolDeps } from './tool-kit.js';
+/** The field that carries the next step for an unwired project. */
+export declare const NEXT_STEP_FIELD = "next_step";
 /** The fields only an empty list carries, declared so a schema-aware client does not strip them. */
 export declare const EMPTY_SESSION_LIST_OUTPUT: {
     why: z.ZodOptional<z.ZodString>;

package/dist/surface/tools/empty-session-list.js

@@ -32,6 +32,8 @@ const LEASABLE_ACTIONS = new Set([
     NoSessionAction.OPEN_APP,
 ]);
 const LOCALHOST = 'http://localhost';
+/** The field that carries the next step for an unwired project. */
+export const NEXT_STEP_FIELD = 'next_step';
 /** The fields only an empty list carries, declared so a schema-aware client does not strip them. */
 export const EMPTY_SESSION_LIST_OUTPUT = {
     why: z
@@ -51,7 +53,7 @@ export const EMPTY_SESSION_LIST_OUTPUT = {
         .string()
         .optional()
         .describe('Present ONLY when `sessions` is empty: a call with the founder for the person you are working with. Offer it; never act on it.'),
-    next_step: z
+    [NEXT_STEP_FIELD]: z
         .object({
         offered: z.nativeEnum(NextStepOffered),
         lease: z.string().optional(),
@@ -141,7 +143,7 @@ export function emptySessionList(deps, sessions) {
         sessions,
         ...(why === undefined ? {} : { why }),
         ...(next === undefined ? {} : { next_action: next }),
-        ...(nextStep === undefined ? {} : { next_step: nextStep }),
+        ...(nextStep === undefined ? {} : { [NEXT_STEP_FIELD]: nextStep }),
         ...(undefined === lastKnown ? {} : { lastKnown }),
         // Setup that never connects is where most people give up; it is the talk worth having.
         talk_to_us: DiscoveryInvite.AGENT,