@reticlehq/server 3.7.0 → 3.8.1

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

@@ -11,10 +11,10 @@
  */
 import { z } from 'zod';
 import { timeoutMsSchema } from './args/numeric-bounds.js';
-import { compileSequenceStep, pathOf } from '../../language/flows/replay.js';
+import { compileSequenceStep, pathOf, wroteSince } from '../../language/flows/replay.js';
 import { DEFAULT_SEQUENCE_STEP_TIMEOUT_MS } from '../../language/flows/flow-step-runners.js';
 import { sequenceStepArgs } from './act/act-preflight.js';
-import { REPLAY_PROGRAM_VERSION, ReticleTool, Verified, VerifiedReason, } from '@reticlehq/core';
+import { REPLAY_PROGRAM_VERSION, ReticleTool, Verified, VerifiedReason, checkIntent, } from '@reticlehq/core';
 import { healthEnvelope } from '../../portal/session/session-health.js';
 import { pausedShortCircuit, pausedOutputShape, withControl, } from '../../portal/session/control-envelope.js';
 import { asRecord, isAbsenceDerived, isAdvisory } from '@reticlehq/core';
@@ -26,7 +26,7 @@ import { takeStepShot } from '../../features/visual/step-shots.js';
 import { actCommand } from './act-tools.js';
 import { PredicateSchema, waitForPredicate, } from '@reticlehq/engine/question/predicate/predicate.js';
 import { DeviationMode, gradeSequence, JOURNEY_RECORDING, offerToKeep, } from './act/sequence-grade.js';
-import { stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
+import { stepEffect, appScope } from '@reticlehq/engine/evidence/step-effect.js';
 // resolveActTarget moved out of act-tools into its own module on this branch; #706 was written
 // against the older layout where act-tools re-exported it.
 import { resolveActTarget } from './act/act-target.js';
@@ -34,6 +34,7 @@ import { gradeOfPredicate } from './assert/assert-grade.js';
 import { describeWaitTarget } from '@reticlehq/engine/evidence/unsettled.js';
 import { sourceOf } from './tools-helpers.js';
 import { confirmedByDeclaration } from './act/act-danger.js';
+import { unreachableTargetNote } from './act/act-observation.js';
 /**
  * The step's effect record, best-effort.
  *
@@ -43,9 +44,11 @@ import { confirmedByDeclaration } from './act/act-danger.js';
  * INSIDE the step loop, be caught as a step failure, and abort the rest of a journey that was
  * running perfectly. The drive is the product; the description of it is not.
  */
-function effectOf(session, since) {
+function effectOf(session, since, expect) {
     try {
-        return stepEffect(session.eventsSince(since), { since, until: session.elapsed() });
+        // A failure the step declared is its expected result, as it is for `act_and_wait`'s `until`.
+        const declared = PredicateSchema.safeParse(expect);
+        return stepEffect(session.eventsSince(since), { since, until: session.elapsed() }, { ...appScope(session), ...(declared.success ? { declared: [declared.data] } : {}) });
     }
     catch {
         return {};
@@ -58,12 +61,19 @@ function stepVerdictEffect(check) {
             ? { verified: Verified.NO, reason: VerifiedReason.CONTRADICTED }
             : { verified: Verified.YES, reason: undefined }
         : check.undecided
-            ? { verified: Verified.UNKNOWN, reason: VerifiedReason.OBSERVATION_LOST }
+            ? {
+                verified: Verified.UNKNOWN,
+                reason: true === check.unreachable
+                    ? VerifiedReason.INCONCLUSIVE
+                    : VerifiedReason.OBSERVATION_LOST,
+            }
             : { verified: Verified.NO, reason: VerifiedReason.ASSERTION_FAILED };
     const source = sourceOf(check.source);
     return {
         claim: describeWaitTarget(check.expect),
         verified,
+        // A step's sentence: the step names no intent of its own, so it is built from its expect.
+        ...checkIntent(check.expect, check),
         ...(source === undefined ? {} : { source: `${source.file}:${String(source.line)}` }),
         ...(check.expected === undefined ? {} : { expected: check.expected }),
         ...(check.observed === undefined ? {} : { observed: check.observed }),
@@ -112,7 +122,7 @@ export const ACT_SEQUENCE_TOOL = {
     description: "Drive a WHOLE journey in ONE round-trip, with NO snapshot first. Name each step's element by {testid} | {label} | {role,name} | {text} in `target` and Reticle resolves it AT THE MOMENT THAT STEP RUNS — so a control that does not exist yet (a modal an earlier step opens, a row it creates) is still addressable, and waits up to timeout_ms to appear. This is the fast path: snapshot -> act -> snapshot -> act costs a model turn per step and is the slowest thing an agent can do. Give each step an `expect` and the sequence stops at the first one that does not hold, returning the un-run `tail` verbatim so you re-plan only the failure. Returns per-step effects[] (see reticle_act).",
     inputSchema: {
         steps: z
-            .array(z.record(z.unknown()))
+            .array(z.record(z.string(), z.unknown()))
             .describe('Ordered list of { ref | target, action, args?, expect? } objects. Each step is equivalent to one reticle_act call, and takes its arguments either way: `{ ref, action: "fill", value: "…" }` flat, as reticle_act does, or nested as `args: { value }`. Give `ref` from a snapshot/query, or `target` ({ testid } | { label } | { role, name } | { text }) to resolve in this call. Put confirmDangerous:true in a destructive step args object. `expect` is the same predicate shape as reticle_act_and_wait `until`, and it is what makes a step PROVE something: a step without one is driven, not verified, and the result says so. Naming the consequence is also FASTER — a named consequence is detected the instant it fires, where waiting for the page to settle can only conclude by waiting for silence.'),
         // A plain number, not boolean|number: a zod union serialises to a JSON-Schema `anyOf` that
         // cost 174 B on a surface re-sent every turn, against 81 B of headroom. One spelling is also
@@ -153,14 +163,14 @@ export const ACT_SEQUENCE_TOOL = {
         /** How many steps declared a consequence, of how many were driven. Never averaged away. */
         coverage: z.object({ declared: z.number(), total: z.number() }).optional(),
         /** Steps never run, verbatim, so a caller re-plans the failure rather than the whole journey. */
-        tail: z.array(z.record(z.unknown())).optional(),
+        tail: z.array(z.record(z.string(), z.unknown())).optional(),
         /**
          * Each step carries the same effect record a REPLAYED step carries: `window` (the
          * `reticle_observe { since, until }` drill address), `digest` (what the app did, as counts) and
          * `contradictions` (channels that disagree, present even when the step passed). Declared here
          * because an undeclared field is stripped from structuredContent and would be silently lost.
          */
-        steps: z.array(z.record(z.unknown())).optional(),
+        steps: z.array(z.record(z.string(), z.unknown())).optional(),
         result: z.unknown().optional(),
         session: z
             .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
@@ -274,7 +284,7 @@ export const ACT_SEQUENCE_TOOL = {
                      */
                     const describe = () => ({
                         ...describeStepResult(step, asRecord(outcome.result)),
-                        ...effectOf(session, stepSince),
+                        ...effectOf(session, stepSince, step['expect']),
                     });
                     const deciding = (step) => (step.contradictions ?? [])
                         .map((c) => c.kind)
@@ -287,12 +297,15 @@ export const ACT_SEQUENCE_TOOL = {
                      * satisfy step four's assertion, which is a false green built out of correct parts.
                      */
                     const parsed = PredicateSchema.safeParse(step['expect']);
+                    // A click no person could have made decides nothing, whatever followed it.
+                    const unreachable = unreachableTargetNote(outcome.result);
                     if (!parsed.success) {
                         const described = describe();
                         const contradicted = deciding(described);
                         expectations.push({
                             declared: false,
                             ...(0 === contradicted.length ? {} : { contradicted }),
+                            ...(unreachable === undefined ? {} : { undecided: unreachable }),
                         });
                         await pushStep(described);
                     }
@@ -304,29 +317,35 @@ export const ACT_SEQUENCE_TOOL = {
                         const described = describe();
                         const contradicted = deciding(described);
                         const disagreement = 0 === contradicted.length ? {} : { contradicted };
-                        const held = true === verdict.pass;
+                        const held = true === verdict.pass && unreachable === undefined;
                         // A tab that went away (an external checkout page) or a predicate that could not be
                         // read decided nothing: unknown, never a miss blamed on the app.
-                        const undecided = !held && (true === verdict.observationLost || verdict.inconclusive !== undefined);
+                        const undecided = unreachable !== undefined ||
+                            (!held && (true === verdict.observationLost || verdict.inconclusive !== undefined));
                         // One check per declared step, journaled as act_and_wait journals its own, so the
                         // session's result, its run file and the dashboard all count it. See sequence-journal.ts.
                         journalStep(session, { step: i, expect: step['expect'] }, stepVerdictEffect({
                             expect: parsed.data,
                             held,
                             undecided,
+                            ...(unreachable === undefined ? {} : { unreachable: true }),
                             contradicted,
                             expected: verdict.expected,
                             observed: held ? undefined : (verdict.observed ?? verdict.failureReason),
                             source: asRecord(outcome.result)['source'],
+                            evidence: verdict.evidence,
+                            assertion: verdict.assertion,
                         }));
                         expectations.push({
                             declared: true,
                             held,
                             ...(undecided
                                 ? {
-                                    undecided: true === verdict.observationLost
-                                        ? `${verdict.failureReason ?? 'the observation was lost'} (the page left)`
-                                        : (verdict.failureReason ?? 'the predicate could not be read'),
+                                    undecided: unreachable !== undefined
+                                        ? unreachable
+                                        : true === verdict.observationLost
+                                            ? `${verdict.failureReason ?? 'the observation was lost'} (the page left)`
+                                            : (verdict.failureReason ?? 'the predicate could not be read'),
                                 }
                                 : {}),
                             ...disagreement,
@@ -386,19 +405,29 @@ export const ACT_SEQUENCE_TOOL = {
             // in the ambient tape. A stalled plan keeps only the prefix whose steps actually ran.
             let journey;
             if (completed > 0) {
-                // A sub-step keeps its `expect` only if it held — same rule as act_and_wait, so a flow
-                // never replays an expectation that was never once observed to hold.
-                const proved = inputSteps.slice(0, completed).map((raw, i) => {
-                    const step = asRecord(raw);
+                // On the ambient tape a sub-step keeps its `expect` only if it held — same rule as
+                // act_and_wait, so an auto-saved flow never replays a claim that was never once observed to
+                // hold. A recording somebody opened keeps every claim they declared: dropping a refuted one
+                // there saved a flow that replayed green on the very defect it had caught.
+                const ran = inputSteps.slice(0, completed).map(asRecord);
+                const proved = ran.map((step, i) => {
                     const { expect: _expect, ...rest } = step;
                     return true === expectations[i]?.held ? step : rest;
                 });
-                const recorded = compileSequenceStep({ ...args, steps: proved }, {
-                    count: completed,
-                    steps: stepResults.slice(0, completed),
-                });
+                const compiled = (steps) => {
+                    const step = compileSequenceStep({ ...args, steps }, { count: completed, steps: stepResults.slice(0, completed) });
+                    // The journey sent a write request: saved `writes`, so a replay does not repeat it unasked.
+                    if (wroteSince(session, since))
+                        step.writes = true;
+                    return step;
+                };
+                const recorded = compiled(proved);
                 journey = recorded;
-                deps.recordings.capture(pageBefore === undefined ? recorded : { ...recorded, page: pageBefore }, undefined, session.id);
+                const onPage = (step) => pageBefore === undefined ? step : { ...step, page: pageBefore };
+                // Every step was on Reticle's own panel: nothing of the app's journey to record.
+                const onApp = asRecord(recorded.args)['steps'];
+                if (Array.isArray(onApp) && 0 < onApp.length)
+                    deps.recordings.capture(onPage(compiled(ran)), undefined, session.id, onPage(recorded));
                 deps.recordings.markEnded(pathOf(session.url), session.id);
             }
             /*

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

@@ -3,9 +3,8 @@ import { type ToolDef, type ToolDeps } from './tool-kit.js';
 /**
  * Single dispatch point for every ACT and ACT_SEQUENCE command.
  *
- * This is the seam the reviewer asked for: instead of wiring rewriteUploadArgs at three separate
- * call sites (reticle_act, reticle_act_and_wait, reticle_act_sequence) we intercept once here,
- * which also covers flow-replay, crawl, and any future dispatch site that goes through this helper.
+ * reticle_act, act_and_wait and act_sequence rewrite uploads here, once. The path resolves against
+ * the session's project, not the daemon's folder, so a worktree uploads its own fixture (#1769).
  *
  * captureAct is called AFTER this, so the flow-recording captures the pre-rewrite args (the path
  * the agent actually wrote) rather than the base64 blob — replay would otherwise send 750 KiB of

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

@@ -13,9 +13,9 @@ import { aliasParam } from './args/alias-args.js';
 import { resolveSessionWithin } from '../../portal/session/timing/resolve-within.js';
 import { WALL_CLOCK } from '../../portal/session/timing/wall-clock.js';
 import { timeoutMsSchema } from './args/numeric-bounds.js';
-import { captureAct, captureVerdictedAct, pathOf } from '../../language/flows/replay.js';
+import { captureAct, captureVerdictedAct, pathOf, wroteSince } from '../../language/flows/replay.js';
 import { durableArg, durableOutput, reloadAndRecheck, withDurability } from './act/durable.js';
-import { ActionType, ActionWarning, ReticleCommand, CaptureLoss, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, Verified, VerifiedReason, PredicateKind, } from '@reticlehq/core';
+import { ActionType, ActionWarning, ReticleCommand, CaptureLoss, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, Verified, VerifiedReason, PredicateKind, checkIntent, } from '@reticlehq/core';
 import { leanActResult, mutatedWithin } from './act/act-view.js';
 import { ReticleTool } from '@reticlehq/core';
 import { buildReactionReport, summarizeReaction } from '@reticlehq/engine/question/reaction.js';
@@ -25,7 +25,7 @@ import { causalSummary } from '../../judgement/capsule/causal-summary.js';
 import { findContradictions } from '@reticlehq/engine/disagreement/contradictions.js';
 import { crashedRuleNotes } from '@reticlehq/engine/disagreement/contradiction-folds.js';
 import { gapsForAction } from '@reticlehq/engine/evidence/instrumentation-gaps.js';
-import { withGapNovelty } from './gap-novelty.js';
+import { engineBlindSpotsOutput, withGapNovelty } from './gap-novelty.js';
 import { noteSessionGaps } from '@reticlehq/engine/evidence/gap-ledger.js';
 import { isChangeUndeclared } from '@reticlehq/engine/evidence/undeclared-change.js';
 import { intentDebt, ledgerFor } from '../../memory/intent/open-intents.js';
@@ -37,16 +37,15 @@ import { inFlightRequestLabels, repeatedRequestLabels } from './act/settle-in-fl
 import { finishAfterMatch } from './act/after-match.js';
 import { noteProved } from './act/proved-controls.js';
 import { decideVerified } from '@reticlehq/engine/evidence/verified.js';
-import { honestyForVerdict } from '@reticlehq/engine/evidence/honesty.js';
+import { buildHonestyBlock, honestyForVerdict } from '@reticlehq/engine/evidence/honesty.js';
 import { declaredExpectations, declaresBodyIndependentChannel, } from '@reticlehq/engine/question/declared.js';
 import { describeWaitTarget, namedNetIsInFlight } from '@reticlehq/engine/evidence/unsettled.js';
 import { saveFailedAssertCapsule } from './act-capsule.js';
 import { blastRadius, buildDivergenceCapsule, wireCapsule } from '../../judgement/capsule/capsule.js';
 import { predicateToExpectedLinks } from '@reticlehq/engine/question/predicate/predicate-to-links.js';
-import { buildHonestyBlock } from '@reticlehq/engine/evidence/honesty.js';
 import { absenceBlindSpotNote, buildCoverageStatement, blindSpotsFromState, transportGapNote, Coverage, impeachesCapture, } from '@reticlehq/engine/evidence/blind-spots.js';
 import { acceptedWriteLabels } from '@reticlehq/engine/evidence/accepted-write.js';
-import { unreadWriteLabels } from '@reticlehq/engine/evidence/unread-outcome.js';
+import { unreadWriteLabels, unreadWriteReason } from '@reticlehq/engine/evidence/unread-outcome.js';
 import { evaluatePredicate, waitForPredicate, provenExpectedLinks, PredicateSchema, } from '@reticlehq/engine/question/predicate/predicate.js';
 import { sessionVerdictFacts } from '../../portal/session/session-verdict-facts.js';
 import { currentOf, healthEnvelope, refuseIfThrottled } from '../../portal/session/session-health.js';
@@ -55,16 +54,17 @@ import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { sourceOf } from './tools-helpers.js';
 import { confirmedByDeclaration } from './act/act-danger.js';
 import { dispatchAct, preflightAct } from './act/act-preflight.js';
-import { checkNet, disabledTargetNote, followLostObservation } from './act/act-observation.js';
+import { actTargetNote, checkNet, followLostObservation } from './act/act-observation.js';
 import { intentArg, sessionIdShape } from './tool-kit.js';
 import { verdictIntentGap } from '@reticlehq/engine/evidence/verdict-intent-gap.js';
 import { asActionType, gradeOf } from './act/act-helpers.js';
 import { resolveActTarget } from './act/act-target.js';
 import { screenRequestFindings, withAdvisories } from './act/screen-request.js';
 import { tryRealInput, rewriteUploadArgs, HOVER_NEEDS_POINTER_MSG } from './real-input-attempt.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
 import { gradeOfPredicate } from './assert/assert-grade.js';
 import { readAlreadyTrue } from './act/already-true.js';
-import { noteSourceSeen } from '../../portal/session/recorded-gaps.js';
+import { engineBlindSpotsField, noteSourceSeen } from '../../portal/session/recorded-gaps.js';
 /**
  * The action vocabulary, derived from ActionType — never retyped: a hand-copied list once omitted
  * blur, upload and drag. The schema refuses an unknown action before any session is resolved.
@@ -74,32 +74,32 @@ const actionTypeEnum = z.enum(ACTION_TYPE_VALUES);
 /**
  * Single dispatch point for every ACT and ACT_SEQUENCE command.
  *
- * This is the seam the reviewer asked for: instead of wiring rewriteUploadArgs at three separate
- * call sites (reticle_act, reticle_act_and_wait, reticle_act_sequence) we intercept once here,
- * which also covers flow-replay, crawl, and any future dispatch site that goes through this helper.
+ * reticle_act, act_and_wait and act_sequence rewrite uploads here, once. The path resolves against
+ * the session's project, not the daemon's folder, so a worktree uploads its own fixture (#1769).
  *
  * captureAct is called AFTER this, so the flow-recording captures the pre-rewrite args (the path
  * the agent actually wrote) rather than the base64 blob — replay would otherwise send 750 KiB of
  * base64 to the browser as if it were an inline content call.
  */
 export async function actCommand(deps, session, actArgs, timeoutMs) {
-    const rewritten = await rewriteUploadArgs(deps, 'string' === typeof actArgs['action'] ? actArgs['action'] : '', asRecord(actArgs['args']));
+    const rewritten = await rewriteUploadArgs({ fs: deps.fs, reticleRoot: sessionRoot(deps, session.id) }, 'string' === typeof actArgs['action'] ? actArgs['action'] : '', asRecord(actArgs['args']));
     // Sequence and act_and_wait dispatch through here without the ACT handler's tryRealInput.
     // A synthetic hover reports dispatched/settled while CSS :hover never applies — drive a real
-    // pointer when one is available, otherwise refuse rather than lie.
-    if (ActionType.HOVER === actArgs['action']) {
+    // pointer when one is available, otherwise refuse rather than lie. A press on a lease takes its
+    // real keyboard, as reticle_act does: a synthetic Tab moves no focus.
+    const hover = ActionType.HOVER === actArgs['action'];
+    if (hover || (ActionType.PRESS === actArgs['action'] && deps.realInput === undefined)) {
         const ref = asString(actArgs['ref']);
-        if (ref === undefined)
+        if (hover && ref === undefined)
             throw new Error(HOVER_NEEDS_POINTER_MSG);
-        const real = await tryRealInput(deps, session, ref, ActionType.HOVER, actArgs);
-        if (real.result === undefined)
+        const action = hover ? ActionType.HOVER : ActionType.PRESS;
+        const real = await tryRealInput(deps, session, ref ?? '', action, actArgs);
+        if (hover && real.result === undefined)
             throw new Error(HOVER_NEEDS_POINTER_MSG);
-        return {
-            kind: 'command_result',
-            id: 'hover',
-            ok: true,
-            result: { dispatched: true, settled: real.settled, ...asRecord(real.result) },
-        };
+        if (real.result !== undefined) {
+            const result = { dispatched: true, settled: real.settled, ...asRecord(real.result) };
+            return { kind: 'command_result', id: action, ok: true, result };
+        }
     }
     const bridgeArgs = { ...actArgs, args: rewritten };
     // What the acted element shows (test id, source) is noted in `Session.command`, Harness acts too.
@@ -109,19 +109,19 @@ export const ACT_TOOLS = [
     {
         name: ReticleTool.ACT,
         example: { ref: 'e42', action: 'fill', args: { value: 'hello' } },
-        description: 'Act WITHOUT checking the result — if the action is supposed to cause something, use reticle_act_and_wait { until } instead and get the verdict in the same call. This tool returns immediately with a `since` cursor; observe the reaction yourself with reticle_observe. Use it for actions with no observable consequence to assert (focus, hover, scrollIntoView, a fill you are about to submit). One action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. Carries effect:{dispatched,targetMatched,visible,enabled,focusMoved,valueChanged,domMutatedWithin,occluded,occludedBy,scrolledIntoView} to tell "action missed" from "app didn\'t react"; dispatched=landed, settled=a real frame flushed, and a settle timeout never fails the tool. Fields at their uninformative default are OMITTED so a clean action collapses to its consequence: an absent dispatched/targetMatched/visible/enabled means true, an absent occluded/scrolledIntoView/valueChanged/defaultPrevented means false, an absent focusMoved/occludedBy means null. occluded=true means the click point is covered by another element (a real user could not click it) — synthetic dispatch still delivered the event; scrolledIntoView=true means an off-viewport target was scrolled in first. effect.alreadyAtValue=true (check/uncheck only) means the box already read as the requested state, so NOTHING was dispatched and the app was never told — the DOM property is not evidence the application holds that value, so assert the app\'s own state (a signal, a request, a derived control), not the box. inputMode is "real" (native CDP, no synthetic effect block) or "synthetic"; clicks default to the occlusion-honest synthetic path even when CDP is configured — pass args.native:true to force a trusted native click (file pickers, clipboard). args.holdMs keeps the pointer DOWN for that long between mousedown and mouseup — the only way to drive a hold-to-confirm control (hold-to-delete, hold-to-record, long-press); effect.heldMs reports the hold actually achieved, which a throttled background tab can stretch. args.confirmDangerous is a permission gate and NOT a duration: it allows a destructive control, it does not hold one. inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): node_modules/@reticlehq/server/docs/usage.md §18.',
+        description: 'Act WITHOUT checking the result — if the action is supposed to cause something, use reticle_act_and_wait { until } instead and get the verdict in the same call. This tool returns immediately with a `since` cursor; observe the reaction yourself with reticle_observe. Use it for actions with no observable consequence to assert (focus, hover, scrollIntoView, a fill you are about to submit). One action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. Carries effect:{dispatched,targetMatched,visible,enabled,focusMoved,valueChanged,domMutatedWithin,occluded,occludedBy,scrolledIntoView} to tell "action missed" from "app didn\'t react"; dispatched=landed, settled=a real frame flushed, and a settle timeout never fails the tool. Fields at their uninformative default are OMITTED so a clean action collapses to its consequence: an absent dispatched/targetMatched/visible/enabled means true, an absent occluded/scrolledIntoView/valueChanged/defaultPrevented means false, an absent focusMoved/occludedBy means null. occluded=true means the click point is covered by another element (a real user could not click it) — synthetic dispatch still delivered the event; scrolledIntoView=true means an off-viewport target was scrolled in first. effect.alreadyAtValue=true (check/uncheck only) means the box already read as the requested state, so NOTHING was dispatched and the app was never told — the DOM property is not evidence the application holds that value, so assert the app\'s own state (a signal, a request, a derived control), not the box. inputMode is "real" (native CDP, no synthetic effect block) or "synthetic"; clicks default to the occlusion-honest synthetic path even when CDP is configured — pass args.native:true to force a trusted native click (file pickers, clipboard). args.holdMs keeps the pointer DOWN for that long between mousedown and mouseup — the only way to drive a hold-to-confirm control (hold-to-delete, hold-to-record, long-press); effect.heldMs reports the hold actually achieved, which a throttled background tab can stretch. args.confirmDangerous is a permission gate and NOT a duration: it allows a destructive control, it does not hold one. inputModeReason explains any real→synthetic choice so it is never silent. On a leased tab a press uses the real keyboard: Tab moves focus, and a press with a ref focuses that element first, so Enter or Space presses it as a person would. Full model (real-input, throttled tabs, `reticle drive`): node_modules/@reticlehq/server/docs/usage.md §18.',
         inputSchema: {
             ref: z
                 .string()
                 .optional()
                 .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions. Give this OR \`target\`. A press of Escape, Tab, or a modifier shortcut (Cmd+K) is a document key and needs neither.`),
             target: z
-                .record(z.unknown())
+                .record(z.string(), z.unknown())
                 .optional()
                 .describe('Find the element and act on it in ONE call, instead of a reticle_query round trip first: { testid } | { text } | { role, name } | { label }. Refuses if it matches more than one, rather than guessing.'),
             action: actionTypeEnum.describe('Action to perform.'),
             args: z
-                .record(z.unknown())
+                .record(z.string(), z.unknown())
                 .optional()
                 .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt — a Cmd+K), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer or the key DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration. For press: { keys: ["Control","k"] } holds several keys down TOGETHER (pressed in order, released in reverse) and { code } names the physical key — both stay on the in-page dispatcher, the only path that can express them. For upload: { path } is a path on disk (absolute or relative to the project root; the daemon reads the file and delivers real bytes to the file picker — this is the way to verify document-ingestion flows); or { name, content?, type? } to supply inline bytes directly.'),
             refuseWhenThrottled: z
@@ -224,7 +224,7 @@ export const ACT_TOOLS = [
                 // Keep what only this call measured, so the observe that judges this window can ask whether
                 // anything happened INSIDE the target — the one fact that separates a dead control from a
                 // page that was merely busy with something else.
-                session.lastAct.markActed(since, action, mutatedWithin(r), asString(args['ref']));
+                session.lastAct.markActed(since, action, mutatedWithin(r), targetRef.ref);
                 return withControl(session, {
                     since,
                     inputMode: InputMode.SYNTHETIC,
@@ -264,12 +264,12 @@ export const ACT_TOOLS = [
                 .optional()
                 .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions. Give this OR \`target\`. A press of Escape, Tab, or a modifier shortcut (Cmd+K) is a document key and needs neither.`),
             target: z
-                .record(z.unknown())
+                .record(z.string(), z.unknown())
                 .optional()
                 .describe('Find the element and act on it in ONE call, instead of a reticle_query round trip first: { testid } | { text } | { role, name } | { label }. Refuses if it matches more than one, rather than guessing.'),
             action: actionTypeEnum.describe('Action to perform.'),
             args: z
-                .record(z.unknown())
+                .record(z.string(), z.unknown())
                 .optional()
                 .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { confirmDangerous: true } for a potentially destructive control. For upload: { path } is a path on disk (absolute or relative to project root; daemon reads real bytes) or { name, content?, type? } for inline bytes.'),
             predicate: PredicateSchema.optional().describe('Alias for `until`.'),
@@ -289,6 +289,7 @@ export const ACT_TOOLS = [
             durable: durableOutput,
             effect: z
                 .unknown()
+                .optional()
                 .describe('The reticle_act result (dispatched, settled, inputMode, etc.).'),
             verdict: z.object({
                 pass: z.boolean(),
@@ -316,9 +317,11 @@ export const ACT_TOOLS = [
             }),
             trace: z
                 .unknown()
+                .optional()
                 .describe('Reaction digest: { window_ms, summary } of what the app did (DOM/network/route/console/signal counts). The full per-event timeline is one reticle_observe { since } away.'),
             summary: z
                 .unknown()
+                .optional()
                 .describe('Bounded causal summary: net {total,errors,headline}, consoleErrors, statePathsChanged, storageKeysChanged, stateDiffs [{path,from,to}], storageDiffs [{key,from,to}], route, signals, layoutShift, longTasks — real before→after diffs (capped), not just readings. THIS IS THE ANSWER TO "what did that click do": console, network, storage and state for this action are all here, so do NOT follow an act with reticle_console + reticle_network + reticle_state to find out — call them only to go deeper into something this block already pointed at. Every list is length-capped so the verdict can never be the field a client truncates; `elided` says which lists lost entries and how many. `stateUnwatched: true` means NO subscribable store is registered, so an empty stateDiffs means unwatched, NOT unchanged — no state conclusion is available until one is registered.'),
             // Promoted out of `effect` on RED only — the file:line the failure came from, the first thing a
             // repair wants. Undeclared, it was stripped on the validating profile exactly like the structured
@@ -351,8 +354,10 @@ export const ACT_TOOLS = [
                 .array(z.unknown())
                 .optional()
                 .describe('What the APP did not tell Reticle, and the one change that would fix it — each entry is { kind, missing, cost, fix, source?, ref? }. Reported ONLY where an absence made THIS verdict weaker (a red that cannot name a file:line, a state assertion with no registered store, a DOM change no signal announced, a route change nothing signalled); never a survey of the page, so an entry is always work worth doing now. OMITTED when the app told Reticle everything it needed. Applying `fix` makes every later verdict on this app stronger, not just this one.'),
+            engineBlindSpots: engineBlindSpotsOutput,
             honesty: z
                 .unknown()
+                .optional()
                 .describe('The verdict trust block { grade, attribution, coverage, integrity, envelope? } — a green never looks stronger than this. Gate on grade ≥ net AND integrity.clean. Fields that were not measured are OMITTED rather than reported as zero, so treat an absent `envelope` as "not sampled", never as a failure.'),
             since: z
                 .number()
@@ -451,7 +456,7 @@ export const ACT_TOOLS = [
                     // Dispatched — now this act owns the cursor and the effect. Marking its OWN measurement
                     // also stops the spread below from inheriting an earlier reticle_act's action and
                     // mutation count.
-                    session.lastAct.markActed(since, asString(args['action']), mutatedWithin(asRecord(actResult.result)), asString(args['ref']));
+                    session.lastAct.markActed(since, asString(args['action']), mutatedWithin(asRecord(actResult.result)), resolved.ref);
                 }
                 // Honesty: floor the predicate at this act's cursor so a stale buffered event can't satisfy it.
                 const predicateStarted = session.elapsed();
@@ -504,17 +509,12 @@ export const ACT_TOOLS = [
                     ? undefined
                     : buildDivergenceCapsule(links, windowEvents, bufferLost);
                 /*
-                 * The blast radius travels on a GREEN too, which is the only verdict where it is news.
-                 *
-                 * On a red the capsule already carries it and the fault is the headline. On a green nothing
-                 * carried it at all — and "the consequence I declared held, AND this action also posted
-                 * somewhere I never mentioned" is exactly the finding a passing verdict buries. A click that
-                 * works and also fires a DELETE is a green that did extra damage.
+                 * The blast radius goes on a GREEN too. On a red the capsule carries it. On a green, a click
+                 * that works and also sends a DELETE did extra damage, and no other field shows that.
+                 * It is attached only when it is not empty, because its presence is the signal. The full
+                 * capsule stays red-only: its divergence walk and causal summary answer a red's question.
                  *
-                 * One pass over a window already in hand, and only attached when it is non-empty: a field
-                 * that is always present teaches a reader to skim it, and the whole value here is that its
-                 * presence is the signal. The full capsule stays red-only — the divergence walk and the
-                 * causal summary are the expensive halves and answer a question a green does not have.
+                 * One pass over a window that is already in hand.
                  */
                 const greenRadius = verdict.pass ? blastRadius(links, windowEvents) : [];
                 // Grade from what the verdict PROVED, not what it declared. A green anyOf holds on one branch, so
@@ -644,8 +644,8 @@ export const ACT_TOOLS = [
                 });
                 const outcomeUnread = unreadWriteLabels(windowEvents);
                 const stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
-                // A click on a disabled control cannot cause anything: a miss there is not the app's.
-                const inconclusive = verdict.inconclusive ?? disabledTargetNote(verdict.pass, actResult?.result);
+                // A click on a disabled control cannot cause anything, nor one no person could make.
+                const inconclusive = verdict.inconclusive ?? actTargetNote(verdict.pass, actResult?.result);
                 const { decision, durable } = await withDurability(args['durable'], until, decideVerified({
                     pass: verdict.pass,
                     // Threaded rather than looked up: decideVerified is pure and has no session.
@@ -673,7 +673,9 @@ export const ACT_TOOLS = [
                     honesty,
                     contradictions,
                     ...(0 === outcomePending.length ? {} : { outcomePending }),
-                    ...(outcomeUnread.length > 0 ? { outcomeUnread } : {}),
+                    ...(outcomeUnread.length > 0
+                        ? { outcomeUnread, outcomeUnreadReason: unreadWriteReason(windowEvents) }
+                        : {}),
                     // `settled` is genuinely optional: a wait that declared no predicate never measured it, and
                     // passing `false` there would report "never settled" about something never asked to settle.
                     ...(settledOutcome === undefined ? {} : { settled: settledOutcome }),
@@ -752,6 +754,7 @@ export const ACT_TOOLS = [
                 verdictEffect = {
                     claim: describeWaitTarget(until),
                     verified: decision.verified,
+                    ...checkIntent(until, verdict, asString(args['intent'])),
                     ...(actedSourceLabel === undefined ? {} : { source: actedSourceLabel }),
                     ...checkWords(verdict),
                     // TRUE here, and false on the `assert` path, and the difference is the point. This tool
@@ -796,19 +799,18 @@ export const ACT_TOOLS = [
                     // where an absence made this very verdict weaker — never as a survey of the page.
                     /*
                      * …and, on a pass, whether anybody said what this verdict was FOR.
-                     *
                      * Intent capture was reachable and unasked-for: the argument sits on this very tool, and
                      * the only nudge lived on `flow_save` — which a build-mode agent may never reach. An
                      * optional capability nobody is told about is one nobody uses, measured on `bodies` this
                      * same week.
                      */
-                    // Remedy once per session, facts every time — see gap-novelty.ts. `no-source-mapping`
-                    // shipped 11 identical copies of its fix text in one measured drive.
+                    // Remedy once per session, facts every time: see gap-novelty.ts for the measurement.
                     ...(gaps.length > 0 || intentGap !== undefined
                         ? {
                             instrumentationGaps: withGapNovelty(session.id, intentGap === undefined ? gaps : [...gaps, intentGap]),
                         }
                         : {}),
+                    ...engineBlindSpotsField(session.id, until, args['intent'], openIntents),
                     // Cross-channel disagreement, reported WITH the action that caused it.
                     //
                     // This is the one finding here a human structurally cannot make — they watch one channel,
@@ -832,7 +834,7 @@ export const ACT_TOOLS = [
             }
             finally {
                 if (dispatched !== undefined)
-                    captureVerdictedAct(deps.recordings, args, dispatched.result, routeBeforeWait, recordedVerdict, session.id);
+                    captureVerdictedAct(deps.recordings, args, dispatched.result, routeBeforeWait, recordedVerdict, 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/agent/compact-envelope.d.ts

@@ -75,6 +75,6 @@ export declare function shapeForAgent(tool: string, args: Record<string, unknown
  */
 export declare function withCompactEnvelope<T extends {
     name: string;
-    inputSchema: z.ZodRawShape;
-    outputSchema?: z.ZodRawShape;
+    inputSchema: Record<string, z.ZodType>;
+    outputSchema?: Record<string, z.ZodType>;
 }>(tools: T[]): T[];

package/dist/surface/tools/agent/for-the-agent.js

@@ -7,15 +7,53 @@
  * which was already shaped. Everything here runs AFTER the verdict was decided and after telemetry
  * read the full result; none of it can change a verdict.
  */
-import { ReticleTool } from '@reticlehq/core';
+import { existsSync, readFileSync } from 'node:fs';
+import { AgentRules, ReticleTool } from '@reticlehq/core';
 import { addAppNote, readAppNotes } from './app-notes.js';
 import { shapeForAgent, wantsFull } from './compact-envelope.js';
 import { learnFromVerdict } from './app-notes-learning.js';
 import { reteachFor } from './reteach.js';
 import { staleBuildNotice } from './build-staleness.js';
 import { PRIMER_POINTER, foldNotices } from './notices.js';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 import { keychainNoticeOnce, projectReader } from '../../../command/cli/doctor/doctor-signing-line.js';
+const GIT_DIR = '.git';
+/** A file's text, or empty when it cannot be read: a pointer is never worth a failed answer. */
+function textOf(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/** Whether `dir`, or a folder above it up to the repository root, has a rules file with the section. */
+function rulesSectionAbove(dir) {
+    for (let at = dir;; at = dirname(at)) {
+        for (const file of AgentRules.FILES) {
+            if (textOf(join(at, file)).includes(AgentRules.BEGIN)) {
+                return true;
+            }
+        }
+        if (existsSync(join(at, GIT_DIR)) || dirname(at) === at) {
+            return false;
+        }
+    }
+}
+/** Read once per agent session: the pointer is said once, on the first answer. */
+const sectionByAttach = new Map();
+/**
+ * Only where `init` wrote the section. In an unwired project the pointer named a file that did not
+ * exist, so the agent was sent to read nothing.
+ */
+function primerPointerFor(attach, project) {
+    let has = sectionByAttach.get(attach);
+    if (has === undefined) {
+        has = project !== undefined && rulesSectionAbove(project);
+        sectionByAttach.set(attach, has);
+    }
+    return has ? [PRIMER_POINTER] : [];
+}
 const isRecord = (value) => 'object' === typeof value && null !== value && !Array.isArray(value);
 export function forTheAgent(answer) {
     const { name, args, attach, root } = answer;
@@ -37,7 +75,7 @@ export function forTheAgent(answer) {
     return foldNotices(shaped, attach, answer.fold, [
         ...(stale === undefined ? [] : [stale]),
         ...(keychain === undefined ? [] : [keychain]),
-        PRIMER_POINTER,
+        ...primerPointerFor(attach, project),
         ...notes,
         ...reteachFor(attach, name, args, shaped),
     ]);

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

@@ -10,7 +10,7 @@
  *
  * Pure: no IO, no clock.
  */
-import { compareSourceClauses, isConsequenceKind, isPresenceKind, PredicateKind, } from '@reticlehq/core';
+import { compareSourceClauses, ElementState, isConsequenceKind, isPresenceKind, PredicateKind, } from '@reticlehq/core';
 import { HonestyGrade, strongerGrade, weakerGrade } from '@reticlehq/engine/evidence/honesty.js';
 export const PRESENCE_ONLY_ADVICE = 'This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion (or allOf it with one) so green means the feature actually worked.';
 function walk(predicate, negated = false) {
@@ -43,7 +43,7 @@ function walk(predicate, negated = false) {
     };
 }
 /**
- * An element predicate that checks the element's CONTENT, not merely that it is there.
+ * An element predicate that checks its content or state, not merely that it is there.
  *
  * The presence nudge exists because "a locator healed to the wrong element, or a stale render, can
  * satisfy this while the feature is broken". That is exactly true of `{ element, role, name }` and
@@ -58,7 +58,12 @@ function walk(predicate, negated = false) {
 function assertsElementContent(predicate) {
     if (predicate.kind !== PredicateKind.ELEMENT)
         return false;
-    return predicate.query?.value !== undefined || predicate.query?.text !== undefined;
+    return (predicate.query?.value !== undefined ||
+        predicate.query?.text !== undefined ||
+        (predicate.state !== undefined &&
+            predicate.state !== ElementState.PRESENT &&
+            predicate.state !== ElementState.VISIBLE &&
+            predicate.state !== ElementState.HIDDEN));
 }
 /**
  * True when the predicate asserts ONLY element/text presence with no signal/net consequence anywhere