@reticlehq/server 3.6.0 → 3.7.0

package/dist/surface/mcp/server-instructions.js

@@ -1,4 +1,4 @@
-import { ReticleTool } from '@reticlehq/core';
+import { ReticleTool, WRITING_RULE_SHORT } from '@reticlehq/core';
 import { SHARED_PARAM_GUIDANCE } from './shared-params.js';
 import { defaultAdvertisedNames } from '../tools/tool-surface.js';
 import { surfaceVocabulary, listOf } from './surface-vocabulary.js';
@@ -44,9 +44,9 @@ import { surfaceVocabulary, listOf } from './surface-vocabulary.js';
  */
 const verdictDiscipline = (v) => `Reticle verifies a running web app from the inside: go (${v.navigate}), look (${listOf(v.look, v.find)}), act and prove in one hop (${v.actAndWait}), observe (${listOf(v.observe, v.state, v.network, v.console)}), assert (${v.assert}). Verify a user-facing change against the real app before you call it done — \`npx @reticlehq/server gate --since <ref>\` fails unless a passing artifact covers every flow your edits affect — and never weaken a check to make it pass.
 
-Only ${v.act.length > 0 ? `${v.actAndWait}, ${v.assert} and ${v.act}{steps}` : `${v.actAndWait} and ${v.assert}`} produce a verdict. Everything else proves nothing; a drive without one has no result. Prefer ${v.actAndWait}({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. Only verified:"yes" is a pass; "unknown" (could not tell) and "no-fault" (nothing declared) are not proved. When a verdict catches what reading the code missed, say Reticle found it. Do a result's \`next\`.
+Only ${v.act.length > 0 ? `${v.actAndWait}, ${v.assert} and ${v.act}{steps}` : `${v.actAndWait} and ${v.assert}`} produce a verdict. Everything else proves nothing; a drive without one has no result. Prefer ${v.actAndWait}({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. Only verified:"yes" is a pass; "unknown" and "no-fault" (nothing declared) are not proved, never failed. When a verdict catches what reading the code missed, say Reticle found it. Do a result's \`next\`.
 
-Done is the journey's END proved, not its first step: drive each step your change touches and give the last an \`until\` naming the end state (\`durable: true\` if it must persist). A "yes" on it over a clean capture IS the answer — stop.
+Done is the journey's END proved, not its first step: drive each step your change touches and give the last an \`until\` naming the end state (\`durable: true\` if it must persist). A "yes" on it over a clean capture IS the answer — stop.${v.act.length > 0 ? ` Several steps? ONE ${v.act}{ steps: [{ target, action, expect }] } drives them all and stops at the first expect that fails; the last expect is the end state.` : ''}
 
 DIAGNOSING a bug? Read the source first — Reticle proves what the app DOES, not why. Drive to CONFIRM a fix, not to find one.`;
 /**
@@ -77,8 +77,15 @@ const replayFirst = (v) => {
     if (0 === v.replayChange.length)
         return '';
     const ask = v.affected.length > 0 ? `${v.affected} names the saved flows covering your edits; ` : '';
-    return `Changed code? Replay before you drive. ${ask}${v.replayChange} replays them for one verified + because — hundreds of tokens where driving the same journey costs tens of thousands. "yes": proved, stop. "no": names the step that broke. "unknown": NO saved flow covers it, so nothing was proved — drive it, and never report it as passing. What you drive by hand is saved as a flow automatically.`;
+    return `Changed code? Replay before you drive. ${ask}${v.replayChange} replays them for one verified + because — far cheaper than driving it again. "yes": proved, stop. "no": names the step that broke. "unknown": NO saved flow covers it, so nothing was proved — drive it, and never report it as passing. What you drive by hand is saved as a flow automatically.${driveOnce(v)}`;
 };
+/**
+ * A drive outlives a client's timeout, so its call answers with a run id instead of waiting for the
+ * end; an agent that retried instead of polling paid for a second drive.
+ */
+const driveOnce = (v) => 0 === v.explore.length
+    ? ''
+    : ` Drivers: you, or the Harness (${v.explore}; opt-in at 80% instrumentation): poll its runId; never start two.`;
 /**
  * The first move, for a project no app has ever connected to.
  *
@@ -90,12 +97,15 @@ const replayFirst = (v) => {
  * common way this step half-succeeds. Telling every agent to restart sent them to kill the server
  * `init` had just started.
  */
-const firstMoveFor = (v, appHere) => `FIRST: no app has ever connected to Reticle in this project, so nothing here can be verified yet. Having these tools is not the same as being set up — the tools reach a daemon, and the daemon has nothing to look at until the app itself is instrumented.
+// The lead is a snapshot, not a present fact: these instructions are sent ONCE, at the handshake, and
+// the app can connect a minute later. Stated as fact, it kept agents running setup while the session
+// list showed the app connected (#1362).
+const firstMoveFor = (v, appHere) => `FIRST: when this session started, no app had connected to Reticle in this project. Having these tools is not the same as being set up — the tools reach a daemon that has nothing to look at until the app is instrumented.
 
-Fix that first: call ${v.sessions}. Its first call wires the app (\`init\`, dev server, browser) and \`wired\` lists the files it changed; tell the user. If it answers \`run_init\`, run that command in the app's directory. A session listed there is the proof, and until one appears no other tool can tell you anything about this app.${appHere ? TELL_THE_USER : ''}`;
+Fix that first: call ${v.sessions}. Its first call wires the app (\`init\`, dev server, browser) and \`wired\` lists the files it changed; tell the user. If it answers \`run_init\`, run that command in the app's directory. A session on this project's app listed there is the proof; until one appears no other tool can tell you anything about this app.${appHere ? TELL_THE_USER : ''}`;
 const UNWIRED_LEAD_END = 'can tell you anything about this app.';
 // An agent never asked to verify anything never reads "fix that first"; this makes it raise wiring.
-const TELL_THE_USER = ' This directory holds a web app that is not wired yet: in your first reply, even if their request is unrelated, tell the user in one line and offer to wire it (the first session call does it). Do it only if they agree; if they decline, do not raise it again.';
+const TELL_THE_USER = ' If none is listed, this directory holds a web app that is not wired: in your first reply, even if their request is unrelated, tell the user in one line and offer to wire it (the first session call does it). Do it only if they agree; if they decline, do not raise it again.';
 /** The nudge set for the AGENT's directory: a shared daemon briefs from where IT started. */
 export function localizeInstructions(instructions, appHere) {
     const without = instructions.replace(TELL_THE_USER, '');
@@ -130,16 +140,14 @@ const reachFor = (v) => {
     // surface-vocabulary.ts. Where there is no cold tail, there is nothing to say about reaching it.
     if (v.coldTail.length > 0) {
         lines.push(`${v.coldTail} Two to know early: ${ReticleTool.RUN}({ tool: "${ReticleTool.CONTEXT}", args: {} }) returns what this run already established, after a compaction or handover, and ${ReticleTool.RUN}({ tool: "${ReticleTool.INTENT}", args: { action: "declare", ... } }) declares what a change was MEANT to do, so the verdict has something to check against other than itself.`);
+        // Measured: in 8 real agent runs asked to test an app, none read what Reticle already held
+        // first, and none could tell its user the credits or the Harness state.
+        lines.push(`Before testing, read what Reticle knows: ${ReticleTool.RUN}({ tool: "${ReticleTool.MEMORY}", args: {} })${v.yield.length > 0 ? ` and ${ReticleTool.SESSION} {action:"account"} (plan, credits, Harness)` : ''}.`);
     }
     return lines.join('\n\n');
 };
 /** The feedback ask. Constant: an agent that cannot get set up is the report we most need. */
-const feedbackAsk = (v) => `Feedback is first-class here, not a courtesy. Reticle is built FOR agents, so your experience is the only signal that decides what gets built or fixed — and it disappears when your context does. Send it with \`${v.feedback}\` the moment you notice, then carry on with your task:
-- Reticle broke, lied, or could not see something you needed (\`bug\` / \`gap\` / \`ambiguity\`).
-- You wished it could do something, or something works but costs too many calls (\`feature_request\` / \`improvement\`).
-- The install, the wiring, or the setup itself gave you trouble — including anything you had to work around by hand.
-
-Nothing is too minor, and a report costs one call. If the tools are unreachable (setup unfinished, daemon down), file the same report from the shell instead: \`reticle feedback --agent --kind <one of those kinds> "what happened"\`. Report defects in RETICLE — a bug you find in the app under test is Reticle working, and belongs in your answer to the user.`;
+const feedbackAsk = (v) => `Feedback is first-class here: once per session, when Reticle got in your way, send \`${v.feedback}\` and carry on — it broke, lied or missed something (\`bug\` / \`gap\` / \`ambiguity\`), cost too many calls or lacked something (\`improvement\` / \`feature_request\`), or the install, the wiring, or the setup gave you trouble. Tools unreachable? \`reticle feedback --agent --kind <kind> "what happened"\`. A bug in the app under test belongs in your answer to the user.`;
 /** The instructions this daemon should advertise, given what it knows about the project. */
 /**
  * Instructions are sent ONCE at initialize; the tool surface is re-sent every turn, and costs an
@@ -175,5 +183,5 @@ export function buildServerInstructions(state) {
         ? `${verdictDiscipline(v)}\n\n${reachFor(v)}\n\n${feedbackAsk(v)}`
         : `${firstMove}\n\n${verdictDiscipline(v)}\n\n${feedbackAsk(v)}`;
     const withReplay = replay.length > 0 ? `${base}\n\n${replay}` : base;
-    return `${withReplay}\n\n${SHARED_PARAM_GUIDANCE}`;
+    return `${withReplay}\n\n${SHARED_PARAM_GUIDANCE}\n\n${WRITING_RULE_SHORT}`;
 }

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

@@ -29,7 +29,7 @@ export const SHARED_PARAM_SHORT = {
 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, or a git ref when verifying a change. `limit` — caps returned descriptors, cutting tokens on broad queries.';
+    'after it, or a git ref when verifying a change. `limit` — caps returned descriptors.';
 /** 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/mcp/surface-vocabulary.d.ts

@@ -41,6 +41,8 @@ export interface SurfaceVocabulary {
     replayAll: string;
     /** Rebind a drifted locator, or empty when the surface cannot reach it. */
     heal: string;
+    /** Start or poll a Harness drive, or empty when the surface cannot reach it. */
+    explore: string;
 }
 /** Drop the empty slots, so a sentence never reads "look (), find ()". */
 export declare function listOf(...calls: readonly string[]): string;

package/dist/surface/mcp/surface-vocabulary.js

@@ -52,5 +52,6 @@ export function surfaceVocabulary(advertisedNames) {
         replayChange: call(ReticleTool.VERIFY_CHANGE, ReticleTool.VERIFY, 'change'),
         replayAll: call(ReticleTool.FLOW_REPLAY, ReticleTool.VERIFY, 'flows'),
         heal: advertised.has(ReticleTool.FLOW_HEAL) ? ReticleTool.FLOW_HEAL : '',
+        explore: call(ReticleTool.VERIFY_EXPLORE, ReticleTool.VERIFY, 'explore'),
     };
 }

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

@@ -0,0 +1,22 @@
+import type { ToolDef } from './tool-kit.js';
+/** What the agent is told to do next, in plain words: one step, the first one that applies. */
+export declare const ACCOUNT_NEXT: {
+    readonly SIGN_IN: "The user is not signed in to Reticle. Ask them to run `reticle connect` in the app folder: it signs them in and links this project. A new account gets 10 free credits.";
+    readonly LINK: "This project does not report to the dashboard yet. Ask the user to press \"Link this project\" on the Harness page of the HUD, or to run `reticle connect` in the app folder.";
+    readonly UNREACHABLE: "The Reticle platform did not answer, so credits and the Harness are not known now. Local checks still work.";
+    readonly NO_CREDITS: (said: string) => string;
+    readonly locked: (percent: number, missing: string) => string;
+    readonly OFF: "Reticle Harness is off for this project. The user can switch it on in the HUD (the Harness row at the foot of the Agent Log) or on the dashboard.";
+    readonly NO_PROVIDER: "The platform has no model provider set, so Reticle Harness cannot run now. Tell the user; it is not on their side.";
+    readonly ready: (typical: number | undefined, max: number | undefined) => string;
+};
+export interface AccountInput {
+    signedIn: boolean;
+    workspace?: string;
+    dashboardUrl?: string;
+    /** The platform's `/v1/model/config` answer; undefined when unlinked, null when it did not answer. */
+    platform: Record<string, unknown> | null | undefined;
+}
+/** The facts and the next step. Pure: the tool's I/O is in `readAccount`. */
+export declare function accountFacts(input: AccountInput): Record<string, unknown>;
+export declare const ACCOUNT_TOOLS: ToolDef[];

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

@@ -0,0 +1,157 @@
+/**
+ * Where the user stands with Reticle, for the coding agent: signed in or not, whether this project
+ * reports to the dashboard, the plan and credits left, whether Reticle Harness is on and unlocked,
+ * what a Harness run costs, and the one thing to do next.
+ *
+ * In 16 real Claude Code and Codex runs, no agent could answer "how many credits do I have" or "can
+ * the Harness run" from a tool: those facts lived only in the HUD and the dashboard. This reads the
+ * same sources they do (the HUD's snapshot for the account, the platform's model config for the
+ * plan, credits and gate), so the agent and the HUD cannot disagree.
+ */
+import { z } from 'zod';
+import { ReticleTool, asRecord, asString } from '@reticlehq/core';
+import { creditsUsageText } from '@reticlehq/core/hud';
+import { impactSnapshot } from '../../memory/impact/impact-recorder.js';
+import { readDashboardUrl } from '../../memory/project/sync-status.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { platformHeaders } from '../../features/harness/platform/server-driver.js';
+const CONFIG_PATH = '/v1/model/config';
+const CONFIG_TIMEOUT_MS = 3_000;
+const UNLOCK_PERCENT = 80;
+/** What the agent is told to do next, in plain words: one step, the first one that applies. */
+export const ACCOUNT_NEXT = {
+    SIGN_IN: 'The user is not signed in to Reticle. Ask them to run `reticle connect` in the app folder: it signs them in and links this project. A new account gets 10 free credits.',
+    LINK: 'This project does not report to the dashboard yet. Ask the user to press "Link this project" on the Harness page of the HUD, or to run `reticle connect` in the app folder.',
+    UNREACHABLE: 'The Reticle platform did not answer, so credits and the Harness are not known now. Local checks still work.',
+    NO_CREDITS: (said) => `${said} Reticle Harness cannot run until the user gets more credits on the dashboard's Plan and usage page.`,
+    locked: (percent, missing) => 
+    // The platform's own sentence already names the score and the gaps: said once, not twice.
+    `${0 < missing.length ? missing : `Setup score ${String(percent)}%: Reticle Harness needs ${String(UNLOCK_PERCENT)}%.`} Offer to close these gaps, then drive one flow to raise the score.`,
+    OFF: 'Reticle Harness is off for this project. The user can switch it on in the HUD (the Harness row at the foot of the Agent Log) or on the dashboard.',
+    NO_PROVIDER: 'The platform has no model provider set, so Reticle Harness cannot run now. Tell the user; it is not on their side.',
+    ready: (typical, max) => 'Reticle Harness is on and ready: reticle_verify { action: "explore", persona: "<the journey, with the text the page must show at the end in quotes>" }' +
+        (typical === undefined
+            ? '.'
+            : `. A run costs about ${String(typical)} credits${max === undefined ? '' : `, at most ${String(max)}`}.`),
+};
+const num = (v) => ('number' === typeof v ? v : undefined);
+const str = (v) => ('string' === typeof v ? v : undefined);
+/** The facts and the next step. Pure: the tool's I/O is in `readAccount`. */
+export function accountFacts(input) {
+    const base = {
+        signedIn: input.signedIn,
+        ...(input.workspace === undefined ? {} : { workspace: input.workspace }),
+        linked: input.platform !== undefined,
+        ...(input.dashboardUrl === undefined ? {} : { dashboardUrl: input.dashboardUrl }),
+    };
+    if (!input.signedIn)
+        return { ...base, next: ACCOUNT_NEXT.SIGN_IN };
+    if (input.platform === undefined)
+        return { ...base, next: ACCOUNT_NEXT.LINK };
+    if (null === input.platform)
+        return { ...base, next: ACCOUNT_NEXT.UNREACHABLE };
+    const p = input.platform;
+    const rawCredits = asRecord(p['credits']);
+    const used = num(rawCredits['used']);
+    const limit = num(rawCredits['limit']);
+    const plan = asRecord(p['plan']);
+    const daysLeft = num(plan['daysLeft']);
+    const kind = str(rawCredits['kind']);
+    const credits = used === undefined || limit === undefined
+        ? undefined
+        : {
+            used,
+            limit,
+            left: Math.max(0, limit - used),
+            ...(kind === undefined ? {} : { kind }),
+            said: creditsUsageText({
+                used,
+                limit,
+                ...('free' === kind || 'trial' === kind || 'paid' === kind ? { kind } : {}),
+                ...(daysLeft === undefined ? {} : { daysLeft }),
+            }),
+        };
+    const runCost = asRecord(p['harnessRunCredits']);
+    const typical = num(runCost['typical']);
+    const max = num(runCost['max']);
+    const lock = asRecord(p['harnessLock']);
+    const score = num(p['coverageScore']);
+    const percent = score === undefined ? undefined : Math.floor(score * 100 + 1e-9);
+    const unlocked = true === p['harnessUnlocked'];
+    const provider = str(p['provider']);
+    const providerReady = provider === undefined ? true : asRecord(p['available'])[provider] !== false;
+    const harness = {
+        on: true === p['harnessEnabled'],
+        unlocked,
+        ...(percent === undefined ? {} : { setupScore: percent }),
+        ...(str(lock['reason']) === undefined ? {} : { missing: str(lock['reason']) }),
+        ...(str(lock['prompt']) === undefined ? {} : { setupPrompt: str(lock['prompt']) }),
+        ...(typical === undefined
+            ? {}
+            : { runCredits: { typical, ...(max === undefined ? {} : { max }) } }),
+    };
+    const facts = {
+        ...base,
+        ...(0 === Object.keys(plan).length ? {} : { plan }),
+        ...(credits === undefined ? {} : { credits }),
+        harness,
+    };
+    const next = credits !== undefined && 0 === credits.left
+        ? ACCOUNT_NEXT.NO_CREDITS(credits.said)
+        : !unlocked
+            ? ACCOUNT_NEXT.locked(percent ?? 0, str(lock['reason']) ?? '')
+            : !providerReady
+                ? ACCOUNT_NEXT.NO_PROVIDER
+                : !harness.on
+                    ? ACCOUNT_NEXT.OFF
+                    : ACCOUNT_NEXT.ready(typical, max);
+    return { ...facts, next };
+}
+/** The platform's model config with this project's linked key; undefined unlinked, null on no answer. */
+async function platformConfig(deps) {
+    // The project's own link, not the environment: an agent asks about the project it is in.
+    const platform = (await deps.linkedCloud?.()) ?? null;
+    if (null === platform)
+        return undefined;
+    try {
+        const res = await fetch(`${platform.url.replace(/\/+$/, '')}${CONFIG_PATH}`, {
+            method: 'GET',
+            headers: platformHeaders(platform),
+            signal: AbortSignal.timeout(CONFIG_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        return asRecord(JSON.parse(await res.text()));
+    }
+    catch {
+        return null;
+    }
+}
+async function readAccount(deps, sessionId) {
+    let root;
+    try {
+        root = sessionRoot(deps, sessionId);
+    }
+    catch {
+        root = undefined; // no tab: the account still answers, without a project
+    }
+    const snapshot = impactSnapshot(root);
+    const account = snapshot?.account;
+    const dashboardUrl = root === undefined ? undefined : readDashboardUrl(root);
+    return accountFacts({
+        signedIn: true === account?.signedIn,
+        ...(account?.org === undefined ? {} : { workspace: account.org }),
+        ...(dashboardUrl === undefined ? {} : { dashboardUrl }),
+        platform: await platformConfig(deps),
+    });
+}
+export const ACCOUNT_TOOLS = [
+    {
+        name: ReticleTool.ACCOUNT,
+        description: 'Where the user stands with Reticle: signed in or not, whether this project reports to the dashboard, the plan and credits left, whether Reticle Harness is on and unlocked, the setup score and what is missing, what a Harness run costs, and the one thing to do next. Read it before you tell the user anything about credits, the plan or the Harness.',
+        inputSchema: {
+            sessionId: z.string().optional().describe('Target a specific tab. Omit unless you mean one.'),
+        },
+        handler: async (deps, args) => readAccount(deps, asString(args['sessionId'])),
+    },
+];

package/dist/surface/tools/act/act-danger.d.ts

@@ -18,3 +18,14 @@ export declare function assertDragNotDestructive(innerArgs: Record<string, unkno
 export declare const NATIVE_INPUT_UNSUPPORTED: string;
 /** Refuse rather than silently drop a native-input request the act-then-wait path cannot honour. */
 export declare function assertNativeInputSupported(innerArgs: Record<string, unknown>): void;
+/**
+ * The agent's own declaration counts as the confirmation, for that one control.
+ *
+ * `reticle_act_and_wait { target: { role: "button", name: "Place order" }, until }` names the
+ * control by the very words the guard flags AND names the consequence before acting: asking again
+ * for `confirmDangerous` cost a round trip per step on a shop's ordinary path and protected nothing.
+ * A `ref` or `testid` does not count — neither says what the control does, and a stale ref is
+ * exactly how the wrong button gets pressed. A Harness call never takes this path: its outward
+ * guard decides alone.
+ */
+export declare function confirmedByDeclaration(innerArgs: Record<string, unknown>, target: unknown, declared: boolean): Record<string, unknown>;

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

@@ -1,4 +1,5 @@
-import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, isDangerousActionText, } from '@reticlehq/core';
+import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, isDangerousActionText, outwardActionOf, outwardRefusal, } from '@reticlehq/core';
+import { currentDrivenBy, harnessOutwardAllowed } from '../../../hooks/driven-by.js';
 import { asRecord, asString } from '@reticlehq/core';
 /**
  * Refuse to drive a money-moving or destructive control by accident.
@@ -29,9 +30,21 @@ function descriptorRole(value) {
 function isDestructiveDescriptor(value) {
     return isDangerousActionText(descriptorText(value), descriptorRole(value));
 }
+/** A Harness call presses an outward control only when its journey asked (`harnessOutwardAllowed`). */
+function assertOutwardAllowed(...descriptors) {
+    const allowed = harnessOutwardAllowed();
+    if (allowed === undefined)
+        return;
+    for (const descriptor of descriptors) {
+        const kind = outwardActionOf(descriptorText(descriptor), descriptorRole(descriptor));
+        if (kind !== undefined && !allowed.includes(kind))
+            throw new Error(outwardRefusal(kind));
+    }
+}
 export function assertNotDestructive(action, innerArgs, inspected) {
     if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
         return;
+    assertOutwardAllowed(inspected);
     if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
     if (!isDestructiveDescriptor(inspected))
@@ -44,6 +57,7 @@ export function assertNotDestructive(action, innerArgs, inspected) {
  * option dragged onto Save is not a payment.
  */
 export function assertDragNotDestructive(innerArgs, from, to) {
+    assertOutwardAllowed(from, to);
     if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
     if (!isDestructiveDescriptor(from) && !isDestructiveDescriptor(to))
@@ -67,3 +81,26 @@ export function assertNativeInputSupported(innerArgs) {
     if (true === innerArgs[NATIVE_INPUT_ARG])
         throw new Error(NATIVE_INPUT_UNSUPPORTED);
 }
+/**
+ * The agent's own declaration counts as the confirmation, for that one control.
+ *
+ * `reticle_act_and_wait { target: { role: "button", name: "Place order" }, until }` names the
+ * control by the very words the guard flags AND names the consequence before acting: asking again
+ * for `confirmDangerous` cost a round trip per step on a shop's ordinary path and protected nothing.
+ * A `ref` or `testid` does not count — neither says what the control does, and a stale ref is
+ * exactly how the wrong button gets pressed. A Harness call never takes this path: its outward
+ * guard decides alone.
+ */
+export function confirmedByDeclaration(innerArgs, target, declared) {
+    if (!declared || true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
+        return innerArgs;
+    if (currentDrivenBy() !== undefined)
+        return innerArgs;
+    const named = asRecord(target);
+    // The words must themselves be the dangerous ones: naming "Continue" on a button whose form posts
+    // to /delete-account consents to nothing, and the guard still reads the whole control.
+    const words = ['name', 'text', 'label'].map((key) => asString(named[key]) ?? '').join(' ');
+    return isDangerousActionText(words, asString(named['role']))
+        ? { ...innerArgs, [DANGEROUS_ACTION_CONFIRM_ARG]: true }
+        : innerArgs;
+}

package/dist/surface/tools/act/act-observation.d.ts

@@ -10,6 +10,7 @@
  * used from the two points where observation can be lost: a write rejected at dispatch, and a wait
  * cut off mid-predicate.
  */
+import { type ReticleEvent } from '@reticlehq/core';
 import type { Session } from '../../../portal/session/session.js';
 import { type SuccessorRegistry } from '../../../portal/session/session-successor.js';
 import type { EvalResult } from '@reticlehq/engine/question/predicate/predicate-eval.js';
@@ -39,4 +40,36 @@ interface FollowedOutcome {
  * `awaitDocumentSuccessor` refuses to guess — a wrong follow drives somebody else's app.
  */
 export declare function followLostObservation(input: FollowSuccessor): Promise<FollowedOutcome>;
+/** Why a consequence that did not follow a click on a disabled control is not the app's failure. */
+export declare const DISABLED_TARGET_NOTE: string;
+/**
+ * The page reports `enabled: false` on an act whose target was disabled at dispatch. A missed
+ * consequence then says nothing about the app, so the verdict is undecided rather than "no".
+ */
+export declare function disabledTargetNote(pass: boolean, actResult: unknown): string | undefined;
+/**
+ * The requests of a failed check's window, as its record carries them: method, url, status and the
+ * start of the response body (redacted in the page before it was ever sent). Dev tooling is left out.
+ */
+/**
+ * The requests a check keeps: on a miss, the window's calls that explain it; on a held network check,
+ * the request that answered it, so a share page can name "a POST to /api/…", not "a request was seen".
+ */
+export declare function checkNet(verdict: {
+    pass: boolean;
+    evidence?: unknown;
+}, events: readonly ReticleEvent[]): {
+    net?: {
+        method: string;
+        url: string;
+        status?: number;
+        body?: string;
+    }[];
+};
+export declare function windowNet(events: readonly ReticleEvent[]): {
+    method: string;
+    url: string;
+    status?: number;
+    body?: string;
+}[];
 export {};

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

@@ -10,6 +10,7 @@
  * used from the two points where observation can be lost: a write rejected at dispatch, and a wait
  * cut off mid-predicate.
  */
+import { EventType, asRecord, asString, isDevToolingUrl } from '@reticlehq/core';
 import { awaitDocumentSuccessor, } from '../../../portal/session/session-successor.js';
 /**
  * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
@@ -34,3 +35,59 @@ export async function followLostObservation(input) {
         return { session: next, verdict, followed: true };
     return { session: next, verdict: await reevaluate(next, leftover), followed: true };
 }
+/** Why a consequence that did not follow a click on a disabled control is not the app's failure. */
+export const DISABLED_TARGET_NOTE = 'the control was disabled when it was acted on, so nothing a user could do there would have ' +
+    'caused the declared consequence. Check why it was disabled (an empty required field, a save ' +
+    'that already happened) before calling this a defect.';
+/**
+ * The page reports `enabled: false` on an act whose target was disabled at dispatch. A missed
+ * consequence then says nothing about the app, so the verdict is undecided rather than "no".
+ */
+export function disabledTargetNote(pass, actResult) {
+    if (pass)
+        return undefined;
+    return false === asRecord(actResult)['enabled'] ? DISABLED_TARGET_NOTE : undefined;
+}
+/** Calls quoted on a failed check, and how much of each response body. */
+const MAX_NET_CALLS = 5;
+const MAX_BODY_CHARS = 300;
+/**
+ * The requests of a failed check's window, as its record carries them: method, url, status and the
+ * start of the response body (redacted in the page before it was ever sent). Dev tooling is left out.
+ */
+/**
+ * The requests a check keeps: on a miss, the window's calls that explain it; on a held network check,
+ * the request that answered it, so a share page can name "a POST to /api/…", not "a request was seen".
+ */
+export function checkNet(verdict, events) {
+    if (!verdict.pass)
+        return { net: windowNet(events) };
+    const seen = asRecord(verdict.evidence);
+    const method = asString(seen['method']);
+    const url = asString(seen['url']);
+    if (method === undefined || url === undefined)
+        return {};
+    const status = seen['status'];
+    return { net: [{ method, url, ...('number' === typeof status ? { status } : {}) }] };
+}
+export function windowNet(events) {
+    const out = [];
+    for (const event of events) {
+        if (EventType.NET_REQUEST !== event.type)
+            continue;
+        const url = asString(event.data['url']);
+        if (url === undefined || isDevToolingUrl(url))
+            continue;
+        const status = event.data['status'];
+        const body = asString(event.data['responseBody']);
+        out.push({
+            method: (asString(event.data['method']) ?? 'GET').toUpperCase(),
+            url,
+            ...('number' === typeof status ? { status } : {}),
+            ...(body === undefined ? {} : { body: body.slice(0, MAX_BODY_CHARS) }),
+        });
+        if (MAX_NET_CALLS <= out.length)
+            break;
+    }
+    return out;
+}

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

@@ -11,7 +11,7 @@
  * outcome than "unknown".
  */
 import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate-schema.js';
-import { isGlobalPressCall } from '@reticlehq/core';
+import { SESSION_REF, isGlobalPressCall, unissuedRefRefusal } from '@reticlehq/core';
 import { SessionReplacedError } from '../../../portal/session/page-commands/pending-commands.js';
 import { assertNativeInputSupported } from './act-danger.js';
 import { unevaluablePredicateReason, vacuousPredicateReason, } from '@reticlehq/engine/question/predicate/predicate-precheck.js';
@@ -80,6 +80,19 @@ export function sequenceStepArgs(step) {
             flat[key] = value;
     }
     const nested = step['args'];
+    if ('string' === typeof nested) {
+        let parsed;
+        try {
+            parsed = JSON.parse(nested);
+        }
+        catch {
+            throw new Error(`step.args is a string that is not valid JSON — pass an object, not a string. Got: ${nested.slice(0, 120)}`);
+        }
+        if (null === parsed || 'object' !== typeof parsed || Array.isArray(parsed)) {
+            throw new Error(`step.args is a JSON string but not an object — pass an object, not ${null === parsed ? 'null' : typeof parsed}. Got: ${nested.slice(0, 120)}`);
+        }
+        return { ...flat, ...parsed };
+    }
     return { ...flat, ...(null !== nested && 'object' === typeof nested ? nested : {}) };
 }
 export function assertSequenceSteps(steps) {
@@ -113,8 +126,18 @@ export function assertSequenceSteps(steps) {
                 'Refused rather than dropped, because a step whose declaration was discarded reports ' +
                 'as a step that declared nothing. Nothing was acted on.');
         }
-        if ('string' === typeof step['ref'] && step['ref'].length > 0)
+        if ('string' === typeof step['args']) {
+            sequenceStepArgs(step);
+        }
+        if ('string' === typeof step['ref'] && step['ref'].length > 0) {
+            // The same shape check `resolveActTarget` makes, moved ahead of the first step: left there, a
+            // malformed ref in step three is only found after steps one and two have already acted.
+            if (!SESSION_REF.test(step['ref'])) {
+                throw new Error(`step ${String(i)}: ${unissuedRefRefusal(step['ref'])} ` +
+                    'Nothing was acted on — the whole sequence is refused so a bad step cannot leave the earlier ones half-applied.');
+            }
             return;
+        }
         if (step['target'] !== undefined)
             return;
         if (isGlobalPressCall(step))

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

@@ -7,7 +7,7 @@
  * dispatch out of the file that opens the window would have weakened a real invariant to satisfy a
  * line count. This resolves a TARGET and dispatches only QUERY, so that guard is untouched.
  */
-import { ReticleCommand, isGlobalPressCall } from '@reticlehq/core';
+import { ReticleCommand, SESSION_REF, isGlobalPressCall, unissuedRefRefusal, } from '@reticlehq/core';
 import { normalizeQueryArgs } from '../read/query-shape.js';
 import { resolveTargetRef } from './resolve-target.js';
 import { asRecord, asString, asNumber } from '@reticlehq/core';
@@ -49,8 +49,13 @@ export async function resolveActTarget(session, args,
  */
 appearanceMs) {
     const ref = asString(args['ref']);
-    if (ref !== undefined && ref.length > 0)
+    if (ref !== undefined && ref.length > 0) {
+        // Refused here, at the boundary, and never re-read as a `target`: guessing what an arbitrary
+        // string meant is the silent re-resolution the stale-ref refusal exists to prevent.
+        if (!SESSION_REF.test(ref))
+            return { kind: 'error', message: unissuedRefRefusal(ref) };
         return { kind: 'ref', ref };
+    }
     const target = args['target'];
     if (target === undefined) {
         if (isGlobalPressCall(args))
@@ -94,7 +99,7 @@ appearanceMs) {
         // One match, or an ambiguity: both are answered by the existing resolver, which already ranks
         // candidates inside its refusal so the next turn needs no snapshot.
         if ('wait' !== decision.do)
-            return resolveTargetRef(found);
+            return resolveTargetRef(found, asRecord(out.result)['hint']);
         await new Promise((resolve) => setTimeout(resolve, decision.waitMs));
     }
 }

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

@@ -29,4 +29,4 @@ export type TargetResolution = {
  * When several remain, they are ranked (in-viewport, then role) inside the refusal only — so the
  * agent can pass the top ref on the next turn without a snapshot. Ranking is never acted on here.
  */
-export declare function resolveTargetRef(candidates: readonly unknown[]): TargetResolution;
+export declare function resolveTargetRef(candidates: readonly unknown[], hint?: unknown): TargetResolution;

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

@@ -61,6 +61,21 @@ function formatCandidate(c, anyInViewport) {
     const head = name.length > 0 ? `${ref} (${role} "${name}"` : `${ref} (${role}`;
     return `${head}; ${where})`;
 }
+/**
+ * The names that role really has, when an exact role + name query just missed (the browser's
+ * `nameNearMiss` hint). Names are matched exactly, so one that carries a changing part — "billing
+ * Last run 1 minute ago" — is unreachable by name; `testid` or a `text` match is the durable way.
+ */
+function nearNamesClause(hint) {
+    const near = asRecord(hint)['nameNearMiss'];
+    const names = Array.isArray(near) ? near.filter((n) => 'string' === typeof n) : [];
+    if (0 === names.length) {
+        return 'widen the query, or take a reticle_snapshot to see what is actually on the page.';
+    }
+    return (`names are matched exactly, and that role is called ${names.map((n) => `"${n}"`).join(', ')}. ` +
+        '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).');
+}
 /**
  * Turn a target QUERY into the single ref an action can be performed on.
  *
@@ -81,15 +96,15 @@ function formatCandidate(c, anyInViewport) {
  * When several remain, they are ranked (in-viewport, then role) inside the refusal only — so the
  * agent can pass the top ref on the next turn without a snapshot. Ranking is never acted on here.
  */
-export function resolveTargetRef(candidates) {
+export function resolveTargetRef(candidates, hint) {
     const all = candidates.map((c) => asRecord(c));
     const visible = all.filter((c) => c.visible !== false);
     const usable = visible.length > 0 ? visible : all;
     if (0 === usable.length) {
         return {
             kind: 'error',
-            message: 'target matched no element. Nothing was acted on and no verdict is possible — widen the ' +
-                'query, or take a reticle_snapshot to see what is actually on the page.',
+            message: 'target matched no element. Nothing was acted on and no verdict is possible — ' +
+                nearNamesClause(hint),
         };
     }
     if (usable.length > 1) {