@reticlehq/server 3.5.0 → 3.7.0

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

@@ -1,3 +1,13 @@
+/**
+ * Action tools — reticle_act and reticle_act_and_wait. Split out of tools.ts to keep that file under
+ * the line cap and assembled back into the tool list there via ...ACT_TOOLS; the native-input attempt
+ * itself lives in real-input-attempt.ts for the same reason.
+ *
+ * `reticle_act_sequence` is a sibling file and is assembled by `tools.ts` directly. It used to be
+ * re-exported through this list, which made a cycle out of nothing: that file needs `actCommand` from
+ * here, and a registry is the right place to collect a definition from.
+ */
+import { checkWords, runIdOfCall } from '../../judgement/runs/drive-run.js';
 import { z } from 'zod';
 import { aliasParam } from './args/alias-args.js';
 import { resolveSessionWithin } from '../../portal/session/timing/resolve-within.js';
@@ -18,10 +28,11 @@ import { gapsForAction } from '@reticlehq/engine/evidence/instrumentation-gaps.j
 import { 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, openSessionIntents } from '../../memory/intent/open-intents.js';
+import { intentDebt, ledgerFor } from '../../memory/intent/open-intents.js';
 import { dischargeInlineIntent, inlineVerdictId, linkInlineIntent, } from '../../memory/intent/inline-intent.js';
 import { declaresState } from '@reticlehq/engine/question/predicate/predicate-asks.js';
 import { isStateUnwatched } from '@reticlehq/engine/evidence/blind-spots.js';
+import { hiddenMatchNote } from '@reticlehq/engine/evidence/already-true.js';
 import { inFlightRequestLabels, repeatedRequestLabels } from './act/settle-in-flight.js';
 import { finishAfterMatch } from './act/after-match.js';
 import { noteProved } from './act/proved-controls.js';
@@ -42,32 +53,21 @@ import { currentOf, healthEnvelope, refuseIfThrottled } from '../../portal/sessi
 import { pausedShortCircuit, pausedOutputShape, withControl, PAUSED_NO_VERDICT, } from '../../portal/session/control-envelope.js';
 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 { followLostObservation } from './act/act-observation.js';
+import { checkNet, disabledTargetNote, 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 { gradeOfPredicate } from './assert/assert-grade.js';
 import { readAlreadyTrue } from './act/already-true.js';
+import { noteSourceSeen } from '../../portal/session/recorded-gaps.js';
 /**
- * Narrow the wire's `action` to a real ActionType, or undefined.
- *
- * It used to be `asString(args['action']) ?? ''`, so an unknown or missing action became the empty
- * string and travelled on — reaching the browser as a command it could not perform, and reported back
- * as a generic failure rather than "that is not an action". Validate at the boundary, per the project's
- * unknown-plus-narrowing rule, so a typo is rejected where it can still be explained.
- */
-/**
- * The action vocabulary, derived from ActionType — never retyped.
- *
- * The description used to omit callable actions such as blur, upload and drag,
- * because a hand-copied list drifts the moment
- * someone adds an arm. Deriving both the schema and the prose from the enum makes that impossible.
- *
- * The handler already refused an unknown action with a good message; the schema now refuses it
- * one layer earlier, before any session is resolved or any work is done.
+ * 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.
  */
 const ACTION_TYPE_VALUES = Object.values(ActionType);
 const actionTypeEnum = z.enum(ACTION_TYPE_VALUES);
@@ -102,9 +102,8 @@ export async function actCommand(deps, session, actArgs, timeoutMs) {
         };
     }
     const bridgeArgs = { ...actArgs, args: rewritten };
-    return timeoutMs !== undefined
-        ? session.command(ReticleCommand.ACT, bridgeArgs, timeoutMs)
-        : session.command(ReticleCommand.ACT, bridgeArgs);
+    // What the acted element shows (test id, source) is noted in `Session.command`, Harness acts too.
+    return session.command(ReticleCommand.ACT, bridgeArgs, timeoutMs);
 }
 export const ACT_TOOLS = [
     {
@@ -124,7 +123,7 @@ export const ACT_TOOLS = [
             args: z
                 .record(z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt — a Cmd+K), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration. For upload: { path } is a path on disk (absolute or relative to the project root; the daemon reads the file and delivers real bytes to the file picker — this is the way to verify document-ingestion flows); or { name, content?, type? } to supply inline bytes directly.'),
+                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt — a Cmd+K), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer or the key DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration. For press: { keys: ["Control","k"] } holds several keys down TOGETHER (pressed in order, released in reverse) and { code } names the physical key — both stay on the in-page dispatcher, the only path that can express them. For upload: { path } is a path on disk (absolute or relative to the project root; the daemon reads the file and delivers real bytes to the file picker — this is the way to verify document-ingestion flows); or { name, content?, type? } to supply inline bytes directly.'),
             refuseWhenThrottled: z
                 .boolean()
                 .optional()
@@ -193,7 +192,7 @@ export const ACT_TOOLS = [
                 // drive native pointer input when a provider is available; otherwise fall back.
                 const real = await tryRealInput(deps, session, ref, action, args);
                 if (real.result !== undefined) {
-                    captureAct(deps.recordings, args, real.result, routeBefore);
+                    captureAct(deps.recordings, args, real.result, routeBefore, session.id);
                     settledOutcome = real.settled ?? undefined;
                     // Native input reports no synthetic effect block, so nothing measured in-target: undefined
                     // (the weaker empty-window test), never a fabricated zero.
@@ -217,7 +216,7 @@ export const ACT_TOOLS = [
                 });
                 if (!result.ok)
                     throw new Error(result.error ?? 'act failed');
-                captureAct(deps.recordings, args, result.result, routeBefore);
+                captureAct(deps.recordings, args, result.result, routeBefore, session.id);
                 // lift dispatch/settle status to the envelope (a settle timeout is NOT a failure).
                 const r = asRecord(result.result);
                 if ('boolean' === typeof r['settled'])
@@ -240,7 +239,7 @@ export const ACT_TOOLS = [
                 });
             }
             finally {
-                deps.recordings.markEnded(pathOf(session.url));
+                deps.recordings.markEnded(pathOf(session.url), session.id);
                 // Close the window on every exit (settle or throw), recording the action + settle outcome.
                 session.finishAction(undefined, settledOutcome, true === settledOutcome ? session.elapsed() - since : undefined);
             }
@@ -312,6 +311,8 @@ export const ACT_TOOLS = [
                 observed: z.string().optional(),
                 expected: z.string().optional(),
                 assertion: z.string().optional(),
+                caseOnlyMiss: z.boolean().optional(),
+                wouldHold: z.string().optional(),
             }),
             trace: z
                 .unknown()
@@ -387,7 +388,9 @@ export const ACT_TOOLS = [
             // Omitting `until` waits for the page to settle (idle) — the deterministic default vs a sleep.
             // `predicate` is what reticle_assert / reticle_wait_for call this — see alias-args.ts.
             const withUntil = aliasParam(args, 'until', ['predicate']);
-            const until = withUntil['until'] !== undefined
+            // Declared: the consequence is named, which also confirms a named dangerous control.
+            const untilNamed = withUntil['until'] !== undefined;
+            const until = untilNamed
                 ? parsePredicate(withUntil['until'])
                 : { kind: PredicateKind.SETTLED };
             // BEFORE the action. A body clause this session cannot answer would fail whatever the app
@@ -400,6 +403,8 @@ export const ACT_TOOLS = [
             // the undeclared-change gap silent on THIS verdict rather than the next one: it reads the
             // ledger below and finds something open. The discharge comes after that read.
             const intentId = await linkInlineIntent(deps, asString(args['sessionId']), asString(args['intent']), PredicateKind.SETTLED === until.kind ? undefined : until);
+            // Bound while the session is live: the action may take the tab off the app's origin.
+            const readLedger = ledgerFor(deps, asString(args['sessionId']));
             // Everything refusable without touching the page — see act-preflight.ts.
             preflightAct(asRecord(args['args']), until);
             // Resolve `target` to a ref BEFORE the action window opens, so the lookup is not attributed to
@@ -437,7 +442,7 @@ export const ACT_TOOLS = [
                 const actResult = await dispatchAct(() => actCommand(deps, session, {
                     ref: resolved.ref,
                     action: args['action'],
-                    args: args['args'] ?? {},
+                    args: confirmedByDeclaration(asRecord(args['args']), args['target'], untilNamed),
                 }));
                 if (actResult !== null) {
                     if (!actResult.ok)
@@ -478,13 +483,13 @@ export const ACT_TOOLS = [
                 const r = asRecord(actResult?.result);
                 if ('boolean' === typeof r['settled'])
                     settledOutcome = r['settled'];
-                // Where the acted element is written. Captured at act time alongside the anchor, so it is
-                // available even when the action unmounted its own target.
+                // Where the acted element is written, captured at act time even if the action unmounted it.
                 const actedSource = sourceOf(r['source']);
-                // Remembered on the session so a LATER assertion can name a file even when its failure has no
-                // element to point at — a signal that never fired, a request that was never made.
+                // Remembered so a LATER assertion can name a file with no element to point at, and so the
+                // app's coverage counts source mapping as seen.
                 const actedSourceLabel = actedSource === undefined ? undefined : `${actedSource.file}:${String(actedSource.line)}`;
                 session.lastAct.markSource(actedSourceLabel);
+                noteSourceSeen(session, actedSourceLabel);
                 const windowEvents = session.eventsSince(since);
                 const trace = summarizeReaction(buildReactionReport(windowEvents, session.elapsed() - since));
                 // The bounded Tier-1 causal summary — net/console/state/storage diffs the trace's counts miss.
@@ -522,15 +527,21 @@ export const ACT_TOOLS = [
                 // Coverage: cross-origin frames / other blind spots the SDK reported during this window mean the
                 // verdict didn't see everything — say so, never imply full coverage.
                 const spots = blindSpotsFromState(session.blindSpots(), session.runtime);
-                const coverage = buildCoverageStatement(spots);
+                // The window's own counts, so sampling before it is not described as this window's (#1414).
+                const windowSpots = blindSpotsFromState(session.blindSpots(since), session.runtime);
+                const coverage = buildCoverageStatement(spots, windowSpots);
                 const absenceBlindSpot = absenceBlindSpotNote(until, spots);
+                // A green resting on hidden matches says the node exists, not that it shows (#1408).
+                const hiddenMatch = hiddenMatchNote(until, verdict.evidence);
                 // Nothing subscribed ⇒ the state channel is dark, and the summary must say so rather than
                 // report an empty diff list that reads like a fact about the app. See CausalSummary.
                 const stateUnwatched = isStateUnwatched(spots);
                 // Only a spot that IMPEACHES the capture belongs in integrity — see impeachesCapture. A
                 // structural boundary (virtualized rows, a cross-origin frame) is reported as coverage and
                 // must not downgrade a verdict about what WAS observed.
-                const impeaching = buildCoverageStatement(spots.filter((s) => impeachesCapture(s.kind)));
+                const impeaching = buildCoverageStatement(
+                // The WINDOW's blind spots: sampling before it is a coverage fact, not this verdict's gap (#1414).
+                windowSpots.filter((s) => impeachesCapture(s.kind)));
                 // Same rule as reticle_assert: a browser-side transport gap means part of this window was
                 // never seen, which is what `blindSpots` exists to say. `truncated` above covers the SERVER
                 // ring buffer evicting; this covers the BROWSER queue overflowing, and they are not the same
@@ -569,6 +580,10 @@ export const ACT_TOOLS = [
                     ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
                     losses,
                 });
+                // A refuted expectation must not ride into a regression flow cut from the ambient tape; it is
+                // kept as the capsule below instead. See RecordingStore.unassertLast.
+                if (!verdict.pass && actResult !== null)
+                    deps.recordings.unassertLast();
                 const capsuleSaved = await saveFailedAssertCapsule({
                     deps,
                     verdict,
@@ -606,6 +621,8 @@ export const ACT_TOOLS = [
                     prior,
                     actionSince: since,
                     expectedFailures: declared.netFailures,
+                    namedNetUrls: declared.netUrls,
+                    repeatableNetUrls: declared.repeatableNetUrls,
                     // A consequence that was already true before the action proves nothing about it, so it is
                     // not evidence the destination rendered either — `alreadyTrue` decides that, once.
                     renderProved: verdict.pass && !alreadyTrue && declared.rendersContent,
@@ -617,9 +634,18 @@ export const ACT_TOOLS = [
                 });
                 // The single field an agent reads. Everything below it is the evidence it was derived from;
                 // this is the only one that has to be interpreted, and now it interprets itself.
-                const outcomePending = acceptedWriteLabels(windowEvents);
+                // Same routing as the assert path (#1120), fed by the links this verdict PROVED. On red,
+                // `gradedLinks` is the declared surface (every anyOf branch), which must not exempt a 202
+                // the verdict never rested on — so only a green passes it through.
+                const outcomePending = acceptedWriteLabels(windowEvents, {
+                    appUrl: session.url,
+                    background: session.background,
+                    asserted: verdict.pass ? gradedLinks : [],
+                });
                 const outcomeUnread = unreadWriteLabels(windowEvents);
                 const stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
+                // 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);
                 const { decision, durable } = await withDurability(args['durable'], until, decideVerified({
                     pass: verdict.pass,
                     // Threaded rather than looked up: decideVerified is pure and has no session.
@@ -635,7 +661,7 @@ export const ACT_TOOLS = [
                     ...(alreadyTrue ? { alreadyTrue } : {}),
                     ...(alreadyTrueHiddenMatch ? { alreadyTrueHiddenMatch } : {}),
                     // An assertion nobody could evaluate must not be reported as one the app failed.
-                    ...(verdict.inconclusive === undefined ? {} : { inconclusive: verdict.inconclusive }),
+                    ...(inconclusive === undefined ? {} : { inconclusive }),
                     // Nor must one nobody could OBSERVE. This is the act path, so it is the one that produced
                     // the measured false red: a reload mid-wait, graded assertion_failed at the clicked
                     // component's own file and line.
@@ -643,6 +669,7 @@ export const ACT_TOOLS = [
                         ? { observationLost: true, lastUrl: session.url }
                         : {}),
                     ...(absenceBlindSpot === undefined ? {} : { absenceBlindSpot }),
+                    ...(hiddenMatch === undefined ? {} : { hiddenMatch }),
                     honesty,
                     contradictions,
                     ...(0 === outcomePending.length ? {} : { outcomePending }),
@@ -674,7 +701,7 @@ export const ACT_TOOLS = [
                 // Read ONCE and used twice: `changeUndeclared` asks whether the ledger is empty, and the
                 // undischarged-intent gap asks how much it still holds. Two reads would be two chances for
                 // them to disagree about the same file.
-                const openIntents = await openSessionIntents(deps, asString(args['sessionId']));
+                const openIntents = await readLedger();
                 const changeUndeclared = await isChangeUndeclared(session.currentEditEpoch, () => Promise.resolve(openIntents));
                 const intentGap = verdictIntentGap({
                     verified: decision.verified,
@@ -716,6 +743,7 @@ export const ACT_TOOLS = [
                         verdictId: inlineVerdictId(ReticleTool.ACT_AND_WAIT, deps.now()),
                         grade,
                         at: deps.now(),
+                        runId: runIdOfCall(session.id), // the run it lands in: linked by id, never by time
                     }, 
                     // Where the acted element is written, so the record can name a file somebody would open
                     // to change the thing it describes.
@@ -725,14 +753,15 @@ export const ACT_TOOLS = [
                     claim: describeWaitTarget(until),
                     verified: decision.verified,
                     ...(actedSourceLabel === undefined ? {} : { source: actedSourceLabel }),
+                    ...checkWords(verdict),
                     // TRUE here, and false on the `assert` path, and the difference is the point. This tool
                     // takes `until` BEFORE it acts: the consequence is named in advance and can then only be
                     // met or missed. A claim written after the fact can be shaped to fit whatever happened,
                     // which is why the two are recorded apart rather than assumed alike.
                     declaredBeforeActing: true,
+                    ...checkNet(verdict, windowEvents), // the calls that explain a miss, or the one that held
                     grade: gradeOfPredicate(until),
-                    // What the declared consequence READ. The run fold has only the journal, so a kind absent
-                    // here was being invented there as `element`. Same field, same reason, on the assert path.
+                    // What the declared consequence READ: a kind absent here was invented by the run fold.
                     kind: until.kind,
                     // The deciding clause, kept — and it was NOT, on this path, the commonest one. `unknown`
                     // alone cannot tell an outcome that has not arrived from a capture that could not be
@@ -789,7 +818,8 @@ export const ACT_TOOLS = [
                     // whole point is catching what NOBODY suspected. It now travels with the action, so an
                     // agent cannot miss it by not asking. Omitted entirely when clean, so a healthy action
                     // pays nothing.
-                    ...(contradictions.length > 0 ? { contradictions } : {}),
+                    // + the opt-in, advisory screen/request check, appended AFTER the verdict (act/screen-request.ts).
+                    ...withAdvisories(contradictions, await screenRequestFindings(session, windowEvents)),
                     ...(durable === undefined ? {} : { durable }),
                     honesty: honestyForVerdict(String(decision.verified), honesty),
                     // Without its summary: it is byte-identical to `summary` two fields up. See wireCapsule.
@@ -802,8 +832,8 @@ export const ACT_TOOLS = [
             }
             finally {
                 if (dispatched !== undefined)
-                    captureVerdictedAct(deps.recordings, args, dispatched.result, routeBeforeWait, recordedVerdict);
-                deps.recordings.markEnded(pathOf(currentOf(deps.sessions, session).url));
+                    captureVerdictedAct(deps.recordings, args, dispatched.result, routeBeforeWait, recordedVerdict, session.id);
+                deps.recordings.markEnded(pathOf(currentOf(deps.sessions, session).url), session.id);
                 acted.finishAction(verdictEffect, settledOutcome, true === settledOutcome ? acted.elapsed() - actedSince : undefined);
             }
         },

package/dist/surface/tools/agent/app-notes-learning.d.ts

@@ -0,0 +1,7 @@
+/** Tests only. */
+export declare function resetAppNoteLearning(): void;
+/**
+ * Read one verdict result. Returns a CONFIRMED note to persist, if this call confirmed one.
+ * `session` is the agent session (MCP connection); undefined does nothing.
+ */
+export declare function learnFromVerdict(session: string | undefined, args: Record<string, unknown>, result: unknown): string | undefined;

package/dist/surface/tools/agent/app-notes-learning.js

@@ -0,0 +1,80 @@
+/**
+ * Learning an app note from a corrected failure. Pure: the dispatcher does the disk write.
+ *
+ * A failed verdict whose diagnosis names the fix — the text is there in another case, the name is on
+ * a control with another role — is a CANDIDATE. It becomes a note only when a later passing verdict
+ * in the same agent session used that fix. So a note records what worked, never what was guessed.
+ *
+ * Nothing here can change a verdict: it reads results after they are decided, and its only output
+ * is a sentence. See app-notes.ts.
+ */
+import { Verified, asRecord } from '@reticlehq/core';
+const MAX_PENDING = 10;
+const pendingBySession = new Map();
+/** Tests only. */
+export function resetAppNoteLearning() {
+    pendingBySession.clear();
+}
+/** The verdict block, wherever this tool keeps it (nested on act_and_wait, spread on assert). */
+function verdictOf(result) {
+    return 'object' === typeof result['verdict'] && null !== result['verdict']
+        ? asRecord(result['verdict'])
+        : result;
+}
+function candidatesIn(result) {
+    const verdict = verdictOf(result);
+    const evidence = asRecord(verdict['evidence']);
+    const out = [];
+    const shown = evidence['caseMiss'];
+    if (true === verdict['caseOnlyMiss'] && 'string' === typeof shown && shown.length > 0) {
+        out.push({
+            usedWhen: [JSON.stringify(shown).slice(1, -1), '"ignoreCase":true'],
+            note: `this app writes "${shown}" — match that case exactly, or use ignoreCase: true where case does not matter`,
+        });
+    }
+    const nearest = evidence['nearestByName'];
+    if (Array.isArray(nearest) && nearest.length > 0) {
+        const first = asRecord(nearest[0]);
+        const name = first['name'];
+        const role = first['role'];
+        if ('string' === typeof name && name.length > 0) {
+            const kind = 'string' === typeof role && role.length > 0 ? `a ${role}` : 'an element with no role';
+            out.push({
+                usedWhen: [
+                    `"label":"${name}"`,
+                    ...('string' === typeof role && role.length > 0 ? [`"role":"${role}"`] : []),
+                ],
+                note: `"${name}" is ${kind} here — target it by { label: "${name}" }, not by a guessed role`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Read one verdict result. Returns a CONFIRMED note to persist, if this call confirmed one.
+ * `session` is the agent session (MCP connection); undefined does nothing.
+ */
+export function learnFromVerdict(session, args, result) {
+    if (session === undefined || 'object' !== typeof result || null === result)
+        return undefined;
+    const r = result;
+    if (Verified.NO === r['verified']) {
+        const found = candidatesIn(r);
+        if (found.length > 0) {
+            const pending = pendingBySession.get(session) ?? [];
+            pendingBySession.set(session, [...pending, ...found].slice(-MAX_PENDING));
+        }
+        return undefined;
+    }
+    if (Verified.YES !== r['verified'])
+        return undefined;
+    const pending = pendingBySession.get(session);
+    if (pending === undefined || 0 === pending.length)
+        return undefined;
+    const written = JSON.stringify(args);
+    const used = pending.find((c) => c.usedWhen.some((needle) => written.includes(needle)));
+    if (used === undefined)
+        return undefined;
+    pendingBySession.set(session, pending.filter((c) => c !== used));
+    return used.note;
+}

package/dist/surface/tools/agent/app-notes.d.ts

@@ -0,0 +1,4 @@
+/** The notes for the project at `root` (its `.reticle` directory). Never throws. */
+export declare function readAppNotes(root: string): string[];
+/** Add a confirmed note; true when it was new. Never throws: a note is never why a call fails. */
+export declare function addAppNote(root: string, note: string): boolean;

package/dist/surface/tools/agent/app-notes.js

@@ -0,0 +1,48 @@
+/**
+ * App notes: what an agent learned about TARGETING this app, kept for the next session.
+ *
+ * "The composer is a contenteditable labelled 'Ask a question'", "this app writes 'Trial' capitalised"
+ * — facts an agent pays one failed verdict to learn, and the next agent on the same app pays again.
+ * A note is written only after it was CONFIRMED (a later verdict that used it passed), so a guess
+ * never becomes lore.
+ *
+ * Hints, never evidence. Nothing that decides a verdict reads this file; it is surfaced to the agent
+ * in its first notices and in `reticle_context`, and an agent may use it to aim a check, never to
+ * pass one. Local to `.reticle/` (checked in with the project, so a team shares it through git).
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+/** Most notes kept: the oldest drop first. A notebook, not a database. */
+const MAX_NOTES = 30;
+function pathOf(root) {
+    return join(root, ReticleDir.APP_NOTES_FILE);
+}
+/** The notes for the project at `root` (its `.reticle` directory). Never throws. */
+export function readAppNotes(root) {
+    try {
+        const path = pathOf(root);
+        if (!existsSync(path))
+            return [];
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        const notes = 'object' === typeof parsed && null !== parsed ? parsed.notes : [];
+        return Array.isArray(notes) ? notes.filter((n) => 'string' === typeof n) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Add a confirmed note; true when it was new. Never throws: a note is never why a call fails. */
+export function addAppNote(root, note) {
+    try {
+        const notes = readAppNotes(root);
+        if (notes.includes(note) || !existsSync(root))
+            return false;
+        const kept = [...notes, note].slice(-MAX_NOTES);
+        writeFileSync(pathOf(root), `${JSON.stringify({ notes: kept }, null, 2)}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/surface/tools/agent/build-staleness.d.ts

@@ -0,0 +1,7 @@
+export declare const STALE_BUILD_NOTICE = "Reticle's code on disk changed after this daemon started, so it is still running the old build. Restart it (`npx @reticlehq/server restart`) and retry before trusting a fix to Reticle itself.";
+/** Newest `.js` mtime under `dir`, or 0 when it cannot be read. */
+export declare function newestJsMtime(dir: string): number;
+/** A watcher over one directory, started now. Exported for tests; the daemon uses the default. */
+export declare function buildWatcher(dir: string, clock: () => number): (now?: number) => string | undefined;
+/** The running daemon's watcher, started when this module is first loaded (daemon start). */
+export declare const staleBuildNotice: (now?: number) => string | undefined;

package/dist/surface/tools/agent/build-staleness.js

@@ -0,0 +1,62 @@
+/**
+ * "The daemon is running an older build than the one on disk."
+ *
+ * A daemon loads its code once. Rebuild Reticle (or update it in place) while one is running and
+ * every tool keeps answering from the old code — measured as most of a lost afternoon: fixes that
+ * "did not work" because the process serving them predated them. Nothing said so.
+ *
+ * So the newest `.js` mtime under this package's `dist` is read when the daemon starts, and again
+ * (at most every CHECK_EVERY_MS, on a tool call) to say once, in notices, that a restart is needed.
+ * A fact about the process, never about the app: no verdict reads it.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** How often the walk may run. A few hundred stats, so cheap, but not on every call. */
+const CHECK_EVERY_MS = 30_000;
+export const STALE_BUILD_NOTICE = "Reticle's code on disk changed after this daemon started, so it is still running the old build. Restart it (`npx @reticlehq/server restart`) and retry before trusting a fix to Reticle itself.";
+/** `dist/` of this package: this file sits at dist/surface/tools/agent/. */
+const DIST_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+/** Newest `.js` mtime under `dir`, or 0 when it cannot be read. */
+export function newestJsMtime(dir) {
+    let newest = 0;
+    const walk = (at) => {
+        let entries;
+        try {
+            entries = readdirSync(at, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(at, entry.name);
+            if (entry.isDirectory())
+                walk(path);
+            else if (entry.name.endsWith('.js')) {
+                try {
+                    newest = Math.max(newest, statSync(path).mtimeMs);
+                }
+                catch {
+                    /* removed mid-walk: a build in progress, read again next time */
+                }
+            }
+        }
+    };
+    walk(dir);
+    return newest;
+}
+/** A watcher over one directory, started now. Exported for tests; the daemon uses the default. */
+export function buildWatcher(dir, clock) {
+    const atStart = newestJsMtime(dir);
+    let checkedAt = clock();
+    let stale = false;
+    return (now = clock()) => {
+        if (!stale && now - checkedAt >= CHECK_EVERY_MS) {
+            checkedAt = now;
+            stale = atStart > 0 && newestJsMtime(dir) > atStart;
+        }
+        return stale ? STALE_BUILD_NOTICE : undefined;
+    };
+}
+/** The running daemon's watcher, started when this module is first loaded (daemon start). */
+export const staleBuildNotice = buildWatcher(DIST_ROOT, () => Date.now());

package/dist/surface/tools/agent/compact-envelope.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The compact envelope: what a verdict result carries by default, and what waits behind
+ * `detail: "full"`.
+ *
+ * The rule (plan: "the middle ground — what a result carries"): answer the question, include what
+ * decides the next move, and give a cursor for the rest. A click on a cache-backed page used to
+ * return several thousand tokens, most of it store snapshots and counters, and the verdict was a
+ * field among them. Compaction never touches a decisive key — `verified`, `because`, the verdict's
+ * expected/observed/evidence, contradictions, capture integrity, failed requests, console errors,
+ * the acted element's source — and `compact-envelope.contract.test.ts` fails the build if it ever
+ * does. What it drops is redundant (identity fields the agent sent), restated (counts the `changed`
+ * line already says) or always one `reticle_observe { since }` away.
+ *
+ * It works by DROPPING named keys, never by allow-listing: a field added to a result later survives
+ * compaction until somebody decides it should not. The accurate direction to fail in.
+ *
+ * Applied once, at the dispatch chokepoint, to an agent's own calls. The Harness and the HUD read
+ * the full result; so does telemetry, which runs before this.
+ */
+import { z } from 'zod';
+/** The argument that asks for today's full envelope. */
+export declare const DETAIL_ARG = "detail";
+export declare const Detail: {
+    readonly COMPACT: "compact";
+    readonly FULL: "full";
+};
+export type Detail = (typeof Detail)[keyof typeof Detail];
+/**
+ * The A/B control: `RETICLE_RESULT_DETAIL=full` makes every agent call answer as if it had passed
+ * `detail: "full"`, so the agent-loop benchmark can run compact against full on the same build with
+ * nothing else different — the measurement CLAUDE.md requires beside any token optimisation.
+ */
+export declare const RESULT_DETAIL_ENV = "RETICLE_RESULT_DETAIL";
+/**
+ * Did this call (or the daemon's environment) ask for the full envelope AND nothing else — no
+ * notices, no re-teach? Only an explicit ask: the A/B control arm, and an agent that said so.
+ */
+export declare function wantsFull(args: Record<string, unknown>): boolean;
+/**
+ * Did this call (or the daemon) ask for the compact envelope? Compaction is opt-in: in the
+ * agent-loop A/B the compact arm saved little per task and missed one failure the full arm caught,
+ * and a token saving ships only beside a correctness measurement that is at least as good.
+ */
+export declare function wantsCompact(args: Record<string, unknown>): boolean;
+/** The tools whose results are compacted. Each one's full shape stays one argument away. */
+export declare const COMPACTED_TOOLS: ReadonlySet<string>;
+/** Short enough for the per-turn surface; the reasoning lives in this file and the instructions. */
+export declare const DETAIL_ARG_DESCRIPTION = "\"compact\" keeps only the deciding fields.";
+/** Where the aliases a predicate was normalised from are named. */
+export declare const NORMALIZED_KEY = "normalized";
+/** The key the one-line "what changed" summary travels under. */
+export declare const CHANGED_KEY = "changed";
+/** Evidence with transport detail removed, recursively, keeping every deciding field. */
+export declare function trimEvidence(value: unknown, depth?: number): unknown;
+/**
+ * One line naming what moved: the route, the requests, the MEANINGFUL state paths (cache
+ * bookkeeping is already filtered out upstream), storage keys, fields and signals.
+ */
+export declare function changedLine(summary: Record<string, unknown>): string | undefined;
+/** One verdict result (act_and_wait, assert, wait_for), compacted. Idempotent. */
+export declare function compactVerdict(result: Record<string, unknown>): Record<string, unknown>;
+/** A sequence result, compacted per step. Idempotent. */
+export declare function compactSequence(result: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The result as an agent receives it: full unless it asked for `detail: "compact"`.
+ *
+ * `agentCall` is the dispatcher's own judgement (an MCP connection, not the Harness or the HUD).
+ */
+export declare function shapeForAgent(tool: string, args: Record<string, unknown>, result: unknown, agentCall: boolean): unknown;
+/**
+ * The compacted tools, with `detail` accepted and the compact-only keys declared.
+ *
+ * Declared because a schema-strict client validates `structuredContent` against `outputSchema` and
+ * drops what is not there: `changed`, `ref` and `source` would be built and silently thrown away.
+ */
+export declare function withCompactEnvelope<T extends {
+    name: string;
+    inputSchema: z.ZodRawShape;
+    outputSchema?: z.ZodRawShape;
+}>(tools: T[]): T[];